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 maintains the mapping between CVisualObject instances and their corresponding GPU-side RenderableProxy objects.

Key responsibilities:

• Initial compilation: translates the entire Scene into GPU structures

• Incremental updates: detects changes via dirty flags and recompiles only what’s needed

• Dynamic object support: detects newly added objects in the source Scene

• Resource management: owns all RenderableProxy instances and shader programs

• Rendering orchestration: delegates to CompiledViewport instances

Typical usage:

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

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

// Render loop:
while (running) {
  myObject->setColor(...);  // triggers dirty flag internally
  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

• Source viz objects may be modified from other threads (they use shared_mutex)

• The proxy will read from viz objects during compile/update (acquires read lock)

See also:

CompiledViewport, RenderableProxy, mrpt::viz::Scene

#include <mrpt/opengl/CompiledScene.h>

class CompiledScene
{
public:
    // typedefs

    typedef std::shared_ptr<CompiledScene> Ptr;

    // 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 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 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
std::runtime_error	if OpenGL context is not available

bool updateIfNeeded(CompilationStats* stats = nullptr)

Incrementally updates the compiled scene to match the source Scene.

This method:

1. Removes proxies for deleted source objects (via weak_ptr expiration)

2. Creates proxies for newly added objects in the source Scene

3. Updates GPU buffers for objects whose dirty flag is set

Much more efficient than full recompilation for animated/dynamic scenes.

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

The source Scene is re-queried each time to detect new objects.

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 hasPendingUpdates() const

Returns true if there are pending changes that need updating.

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.