class mrpt::opengl::CompiledScene

Overview

A compiled, GPU-ready representation of a mrpt::viz::Scene.

This class bridges the gap between the abstract scene graph (mrpt::viz::Scene) and the actual OpenGL rendering. It keeps one node for each position of an object in the scene graph, holding the RenderableProxy instances of that object. The same object may appear at several positions (e.g. a model shared by several groups), each drawn with its own model matrix.

Key responsibilities:

Typical usage:

viz::Scene scene;
// ... populate scene with objects ...

opengl::CompiledScene compiled;
compiled.compile(scene);  // Initial compilation

// Render loop:
while (running) {
  myObject->setColor(...);  // increments its data version
  scene.insert(newObject);  // dynamically add objects
  compiled.updateIfNeeded(); // compiles new objects, updates changed ones
  compiled.render();
}

Thread safety:

  • All CompiledScene methods must be called from the OpenGL context thread

  • Properties of individual viz objects (pose, color, geometry…) may be modified from other threads, since they are protected by their own mutexes.

  • The structure of the scene graph (inserting or removing objects or viewports) must not change while compile(), updateIfNeeded() or render() run: callers must synchronize those changes with rendering (e.g. GUI windows provide a mutex for their scene).

See also:

CompiledViewport, RenderableProxy, mrpt::viz::Scene

#include <mrpt/opengl/CompiledScene.h>

class CompiledScene
{
public:
    // typedefs

    typedef std::shared_ptr<CompiledScene> Ptr;

    // structs

    struct Node;
    struct ParentState;
    struct ViewportEntry;

    // construction

    CompiledScene();
    CompiledScene(const CompiledScene&);
    CompiledScene(CompiledScene&&);

    // methods

    void compile(const mrpt::viz::Scene& scene, CompilationStats* stats = nullptr);
    bool updateIfNeeded(CompilationStats* stats = nullptr);
    void recompile();
    void clear();

    void render(
        int renderWidth = 0,
        int renderHeight = 0,
        int renderOffsetX = 0,
        int renderOffsetY = 0
        );

    void renderViewport(
        const std::string& viewportName,
        int renderWidth = 0,
        int renderHeight = 0,
        int renderOffsetX = 0,
        int renderOffsetY = 0
        );

    void setAutoUpdate(bool enable);
    bool getAutoUpdate() const;
    bool isCompiled() const;
    bool isCompiledFrom(const mrpt::viz::Scene& scene) const;
    bool hasPendingUpdates() const;
    size_t getViewportCount() const;
    size_t getProxyCount() const;
    const mrpt::viz::Scene* getSourceScene() const;
    const std::map<std::string, CompiledViewport::Ptr>& getViewports() const;
    CompiledViewport::Ptr getViewport(const std::string& name) const;
    ShaderProgramManager& shaderManager();
    const ShaderProgramManager& shaderManager() const;
    const CompilationStats& lastStats() const;
    CompiledScene& operator = (const CompiledScene&);
    CompiledScene& operator = (CompiledScene&&);
};

Methods

void compile(const mrpt::viz::Scene& scene, CompilationStats* stats = nullptr)

Performs initial compilation of the entire scene.

This creates RenderableProxy instances for all visible CVisualObject instances in the scene, uploads data to GPU, and prepares all necessary OpenGL state.

This must be called from a thread with an active OpenGL context.

Calling compile() multiple times will clear previous compilation and start fresh.

Parameters:

scene

The abstract scene to compile (reference kept internally)

stats

Optional pointer to receive compilation statistics

 
bool updateIfNeeded(CompilationStats* stats = nullptr)

Incrementally updates the compiled scene to match the source Scene: viewports added or removed, objects inserted or removed anywhere in the scene graph, and objects whose data, pose, scale or visibility changed.

This is called automatically by render() if auto-update is enabled.

Parameters:

stats

Optional pointer to receive update statistics

Returns:

true if any updates were performed, false if nothing changed

void recompile()

Forces a full recompilation of the entire scene.

Clears all existing proxies and recompiles from scratch. Use sparingly - updateIfNeeded() is usually sufficient.

void clear()

Clears all compiled data and GPU resources.

After calling this, you must call compile() again before rendering.

void render(
    int renderWidth = 0,
    int renderHeight = 0,
    int renderOffsetX = 0,
    int renderOffsetY = 0
    )

Renders all viewports in the compiled scene.

If auto-update is enabled (default), this automatically calls updateIfNeeded() before rendering.

Parameters:

renderWidth

Width of the render target in pixels

renderHeight

Height of the render target in pixels

renderOffsetX

X offset for viewport positioning

renderOffsetY

Y offset for viewport positioning

 
void renderViewport(
    const std::string& viewportName,
    int renderWidth = 0,
    int renderHeight = 0,
    int renderOffsetX = 0,
    int renderOffsetY = 0
    )

Renders a specific viewport by name.

Parameters:

std::runtime_error

if viewport name not found

 
void setAutoUpdate(bool enable)

Enable/disable automatic update before each render().

Default: true. When enabled, render() automatically calls updateIfNeeded() to ensure GPU state matches the scene.

Set to false if you want manual control over when updates happen.

bool getAutoUpdate() const

Returns current auto-update setting.

bool isCompiled() const

Returns true if the scene has been compiled at least once.

bool isCompiledFrom(const mrpt::viz::Scene& scene) const

Returns true if this was compiled from that scene object: the same instance, not another one that was later created at its memory address.

bool hasPendingUpdates() const

Returns true if any object of any scene changed since the last update, so the next updateIfNeeded() will check this scene for changes.

size_t getViewportCount() const

Number of viewports in the compiled scene.

size_t getProxyCount() const

Number of total RenderableProxy objects (across all occurrences)

const mrpt::viz::Scene* getSourceScene() const

Returns the source Scene that was compiled.

Returns:

nullptr if not yet compiled

const std::map<std::string, CompiledViewport::Ptr>& getViewports() const

Access to compiled viewports.

CompiledViewport::Ptr getViewport(const std::string& name) const

Access to a specific compiled viewport.

ShaderProgramManager& shaderManager()

Access to the shader program manager.

const CompilationStats& lastStats() const

Access to last compilation statistics.