Class CompiledScene

Class Documentation

class CompiledScene

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

Compilation and Updates

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.

Note

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

Note

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

Throws:

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.

Note

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

Note

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.

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.

Throws:

std::runtime_error – if viewport name not found

Configuration

inline 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.

inline bool getAutoUpdate() const

Returns current auto-update setting

Status Queries

inline 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

inline size_t getViewportCount() const

Number of viewports in the compiled scene

size_t getProxyCount() const

Number of total RenderableProxy objects (across all occurrences)

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

Returns the source Scene that was compiled.

Returns:

nullptr if not yet compiled

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

Access to compiled viewports

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

Access to a specific compiled viewport

inline ShaderProgramManager &shaderManager()

Access to the shader program manager

inline const ShaderProgramManager &shaderManager() const
inline const CompilationStats &lastStats() const

Access to last compilation statistics

Public Types

using Ptr = std::shared_ptr<CompiledScene>

Public Functions

CompiledScene()
~CompiledScene() = default
CompiledScene(const CompiledScene&) = delete
CompiledScene &operator=(const CompiledScene&) = delete
CompiledScene(CompiledScene&&) = delete
CompiledScene &operator=(CompiledScene&&) = delete