DOCSEARCHbyAlgolia
Submit Docs

OGRE (Object-Oriented Graphics Rendering Engine)

repository·master·Indexed 26 days ago

https://github.com/ogrecave/ogre

A modular C++ rendering engine for high-performance 3D applications that abstracts low-level APIs including Vulkan, Direct3D, and OpenGL. Features include the DotScene XML-based scene format, the Portal-Connected-Zone Scene Manager (PCZSM) for zone and portal management, SPIR-V shader support via the GLSLang Plugin, and bindings for Python, C#, and Java.

Tokens
82.3K
Snippets
170
Records
524
Agent score
88%

What's inside OGRE

  1. RTSS Core Components Overview

    master

    The RTSS (Runtime Shader System) consists of several key components:

    • ShaderGenerator: The primary interface for requesting shader generation, controlling shading languages, and managing shader caching.
    • RenderState: The core component that aggregates SubRenderStates to form a shader. It exists at two levels: SGScheme (for a material scheme) and SGPass (for a specific pass).
    • SubRenderState (SRS): Isolated components that implement specific effects (e.g., SRS_TRANSFORM, SRS_TEXTURING, SRS_FOG). Combining these creates the final shader logic.
    • SubRenderStateFactory: Factories that produce specific SubRenderStates and can act as script readers/writers for specialized SRSs.

  2. Compositor Fundamentals

    master

    The Compositor framework allows you to define rendering pipelines (such as full-screen post-processing effects) via scripts. This is often more efficient than defining pipelines entirely in code.

    Key Concepts

    ConceptDescription
    CompositorA definition of a rendering pipeline that can be applied to a viewport.
    Compositor InstanceAn instance of a compositor applied to a specific viewport.
    Compositor ChainA sequence of one or more compositor instances on a single viewport, where each compositor takes the previous one's result as input.
    TargetAn Ogre::RenderTarget (the canvas). This can be the final output (e.g., Ogre::RenderWindow) or an intermediate render texture declared via the texture line in a script.
    Output TargetThe single final result of all operations. Its size and format are defined by the application, not the script.
    Target SectionA specific rendering pass within a Target. Declared using target or target_output lines. Internally referred to as Ogre::CompositionTargetPass.
    PassAn individual action within a Target Section, such as render_scene, render_quad, or clear.

    Workflow

    Compositing typically involves rendering the scene to a texture, then using that texture in a fragment program (via a render_quad pass) to perform operations like convolutions or color grading, eventually outputting to the final target.

  3. Understand the OGRE Core Architecture

    master

    OGRE is an object-oriented 3D graphics engine designed to be platform and API agnostic. It uses abstraction to hide the differences between various 3D APIs (like Direct3D or OpenGL) and operating systems.

    Core responsibilities are divided into three main subsystems:

    1. Scene Management: Handles the structure of the scene, camera views, and object placement using a declarative interface (e.g., defining where objects are and what materials they use rather than manual render states).
    2. Resource Management: Manages the lifecycle (loading, reuse, and unloading) of geometry, textures, fonts, and other assets.
    3. Rendering: Handles the low-level rendering pipeline, including buffers, render states, and pushing data to the 3D API.

    Extensibility is achieved through a plugin system, allowing developers to add new RenderSystems, SceneManagers, or resource loaders.

  4. Understand Ogre's Plugin Architecture

    master

    OGRE uses a plugin-based system to integrate third-party libraries for functionality like physics, input, and GUI.

    • Input: Managed via plugins like Simple DirectMedia Layer (SDL).
    • Geometry Loading: The AssimpCodec allows loading formats like .obj using the Assimp library.

    Best Practice for Distribution:

    • Development/Testing: Keep all plugins activated to experiment with different features.
    • Release Builds: Deactivate any plugins that are not strictly required by your application to optimize the environment.

  5. Understand Shadow Mapping in OGRE

    master

    Shadow mapping in OGRE works by taking a snapshot of the scene from the light's viewpoint and storing it in a floating-point depth buffer. This buffer is then used during camera rendering to determine if a point is visible to the light (lit) or obscured (shadowed).

    OGRE supports two primary techniques for rendering shadows into the final image:

    1. Modulative Technique: A cheaper, less accurate model that uniformly darkens shadowed regions. For example, specular highlights in shadow will appear as darkened specular highlights.
    2. Additive Light Masking: A more accurate technique that builds up contributions from each light in non-shadowed areas and adds them together to create the final image.

    To avoid shadow acne (z-fighting), it is important to use a depth buffer format with sufficient precision. In OGRE, you can specify the depth format (e.g., a 16-bit format) to manage this.

  7. Understand Ogre Scene Management Concepts

    master

    Building a scene in Ogre relies on three primary components:

    • Ogre::SceneManager: The central object that organizes the scene. It tracks the locations and attributes of all objects, manages cameras, and determines how to display them. Different types of SceneManagers exist for different partitioning schemes (e.g., Octree or portals).
    • Ogre::SceneNode: An abstract object that holds spatial information like location and orientation. SceneNodes are not visible themselves, but they act as attachment points. An object is only rendered when attached to a SceneNode. SceneNodes can be nested (parent-child relationships), where a child's position is relative to its parent.
    • Ogre::Entity: A renderable object represented by a 3D mesh. To display an Entity, you must attach it to a Ogre::SceneNode.

  8. Migrate to C++11 standard library types

    master

    OGRE 1.11 requires a C++11 conforming compiler (minimum gcc 4.8 or VS2013). Many core OGRE classes have been replaced by standard C++11 equivalents. When updating code, prefer these standard types:

    • Use std::shared_ptr instead of SharedPtr (though a wrapper exists for backward compatibility).
    • Use std::atomic instead of AtomicScalar.
    • Use std::unordered_map instead of OGRE_HashMap.
    • Use std::hash<string> instead of _StringHash.
    • Use std::thread for threading instead of the previous backport.
    • Use std::chrono for timer implementations.

  9. Define an image-based font texture

    master

    To use an existing font texture (e.g., a PNG with an alpha channel), use the image type in your .fontdef file. You must manually define the texture coordinates for every character using the glyph attribute.

    Attributes:

    • type image
    • source <filename>: The image file (PNG is recommended for alpha support).
    • glyph <character> <u1> <v1> <u2> <v2>: The texture coordinates for a specific character.
      • For ASCII, use the character itself.
      • For Unicode, use u followed by the decimal value (e.g., u0546).

  10. Write Cross-Platform Shaders with OgreUnifiedShader.h

    master

    To write a single shader file that works across GLSL, HLSL, and Metal, include OgreUnifiedShader.h and use its specific macros and syntax patterns.

    Required Changes for Unified Shaders:

    1. Add #include <OgreUnifiedShader.h> at the top.
    2. Use MAIN_PARAMETERS and MAIN_DECLARATION instead of void main().
    3. Use IN/OUT macros for non-uniform parameters passed to the main function.
    4. Wrap uniform parameters in the OGRE_UNIFORMS macro.
    5. Declare samplers using SAMPLER2D, SAMPLER3D, etc., instead of sampler2D.
    6. Use mtxFromRows / mtxFromCols for matrix construction.
    7. Use HLSL-style mul(matrix, vector) instead of * for matrix multiplication.
    8. Use vec2_splat(val) instead of vec2(val) for single-component constructors.
    9. Use f32vecN instead of highp vecN for full precision floats in fragment shaders.

    Example Conversion:

    Original GLSL:

    #version 120
uniform mat4 worldMatrix;
attribute vec4 vertex;
void main()
{
    gl_Position = worldMatrix * vertex;
}

    Cross-Platform Unified Version:

    OGRE_NATIVE_GLSL_VERSION_DIRECTIVE
#include <OgreUnifiedShader.h>

OGRE_UNIFORMS(
uniform mat4 worldMatrix;
)

MAIN_PARAMETERS
IN(vec4 vertex, POSITION)
MAIN_DECLARATION
{
    gl_Position = mul(worldMatrix, vertex);
}

  12. Split Milkshape animations into multiple sequences

    master

    You can split a single Milkshape animation sequence into multiple separate animations by providing a comma-separated text file. The file format should be: start_frame,end_frame,animation_name.

    Example file content:

    1,30,Walk
31,40,Wave
41,80,Run

    When using this method, the resulting animations can be accessed in OGRE via:

    • Skeleton::getAnimation("AnimationName")
    • Entity::getAnimationState("AnimationName")
    1,30,Walk
31,40,Wave
41,80,Run