Performance notes and the C++ API reference

Performance notes

rayrai is intended to stay single-threaded so it can be embedded in simulation, replay, and data-generation tools without adding renderer worker synchronization. The renderer keeps the main performance controls explicit:

• Disable shadows for high-throughput camera observations when shadows are not part of the desired output. Use RenderOverrides::doShadows = false or disable the light’s shadow map globally.

• Prefer addInstancedVisuals for repeated primitives or meshes. A single instanced visual renders many copies with one instance buffer instead of many separate visual objects.

• Opaque RaiSim single-body primitives are internally batched on non-shadowed color renders. This helps high-throughput observation rendering while keeping shadowed rendering on the conservative per-object path.

• TCP viewer scenes synthesize repeated articulated mesh visuals into internal InstancedVisuals batches when mesh path, scale, color policy, and color match. RemoteScene::tcpMeshBatchCount() and tcpMeshBatchMeshColorCount() expose diagnostics for this path.

• Use InstancedVisuals::setMaxRenderedInstances and PointCloud::setMaxRenderedPoints as simple LOD caps for debug overlays, particles, scans, or dense markers that do not need full density in every frame.

• Keep non-visible debug geometry outside the camera frustum when possible. rayrai performs coarse frustum culling for RaiSim objects, custom visuals, instanced visuals, and point clouds, so off-camera content is skipped before draw submission. Mesh-local bounds are used when available, so offset meshes, articulated links, deformables, and heightmaps cull and frame from their rendered bounds rather than only from the object origin.

• If the world topology is stable, repeated updateObjectLists() calls are cheap: rayrai refreshes appearances without rebuilding the object cache unless objects were added or removed.

• RGB/depth CPU readback supports an optional PBO-backed asynchronous path. The synchronous path remains the deterministic default for simple RL loops.

• Dynamic point clouds and instanced visuals support partial buffer updates for streaming changes.

• Deformable TCP streaming sends topology/indices only during initialization or topology changes; normal frames send vertex positions only.

Shader binary cache and multi-threaded prewarming

rayrai’s PBR shaders compile in 10-30 seconds on first run depending on the GL driver. v2.3.0 adds two features that eliminate that wait in production RL pipelines:

1. Persistent shader binary cache. Compiled GL programs are written to a per-driver cache directory and reloaded on subsequent runs.

2. Static prewarm helper for multi-threaded RL setups where many worker threads will each construct their own RayraiWindow — one thread can pre-compile every shader, then every worker thread reads from the cache.

Both are wired through the RayraiWindow constructor:

raisin::RayraiWindow viewer(
  world,
  /*width=*/1280, /*height=*/720,
  raisin::RayraiWindow::ThreadingMode::SingleThread,
  /*shaderCompileThreadCount=*/1,            // 1 = matches rayrai's default
  /*shaderBinaryCacheEnabled=*/true,         // on by default
  /*shaderBinaryCacheDirectory=*/"",          // empty → $HOME/.raisim/rayrai
  /*logShaderBinaryCache=*/false);

• shaderCompileThreadCount is passed to glMaxShaderCompilerThreadsARB and only takes effect on drivers that expose KHR/ARB_parallel_shader_compile. Raise it only when the host application is itself multi-threaded.

• shaderBinaryCacheEnabled = true (the default) writes program binaries under the cache directory keyed by GL vendor / renderer / version + GLSL source. On the next run, identical configurations are loaded directly, skipping the GLSL compile entirely.

• shaderBinaryCacheDirectory = "" uses $XDG_CACHE_HOME/raisim/rayrai (or $HOME/.raisim/rayrai on Linux/macOS).

• logShaderBinaryCache = true prints every hit/miss/store to stderr — useful for verifying the cache is actually being consulted.

Cache statistics (per process, across all Shader::compile calls):

auto s = raisin::Shader::binaryCacheStats();
std::printf("hits=%llu misses=%llu stores=%llu coordinated_waits=%llu\n",
            static_cast<unsigned long long>(s.hits),
            static_cast<unsigned long long>(s.misses),
            static_cast<unsigned long long>(s.stores),
            static_cast<unsigned long long>(s.coordinatedWaits));
raisin::Shader::resetBinaryCacheStats();  // scope a measurement window

Pre-warming for parallel RL can be done with the installed/source-tree rayrai_shader_prewarm utility, which creates an offscreen context and compiles every built-in shader into the persistent binary cache:

rayrai_shader_prewarm --cache-dir /tmp/rayrai-cache --compile-threads 4 --multi-thread
rayrai_shader_prewarm --log-cache

For an embedded application, spawn one background thread, give it its own offscreen GL context, call prewarmShadersForCurrentContext once. Worker threads that later construct their own RayraiWindow will find the heavy shaders already cached (or briefly block on a per-shader compile mutex if the warm-up is still in flight):

std::thread([]{
  SDL_Window* w = nullptr; SDL_GLContext gl = nullptr;
  raisin::RayraiWindow::createOffscreenGlContext(w, gl, "rayrai_prewarm");
  raisin::RayraiWindow::makeOffscreenContextCurrent(w, gl);
  raisin::RayraiWindow::prewarmShadersForCurrentContext(
    raisin::RayraiWindow::ThreadingMode::MultiThread);
  SDL_GL_MakeCurrent(nullptr, nullptr);
  SDL_GL_DeleteContext(gl);
  SDL_DestroyWindow(w);
}).detach();

Across the whole process, each shader’s GLSL→binary compile runs exactly once regardless of the number of worker threads.

When you only want to warm a specific subset:

// Names of every program registered with the running RayraiWindow.
auto names = viewer.linkedShaderNames();

// Compile the heaviest authored-content shader explicitly.
long long ms = viewer.compileShaderByName("pbrMeshHigh");
std::printf("pbrMeshHigh warmup: %lld ms\n", ms);

// Iterate every program, one per call. `done` flips true when all are
// linked; useful for spreading shader work across multiple frames.
bool done = false;
while (!done) {
  viewer.warmupNextShader(done);
}

For diagnostics on the cost of the lazy-compile pipeline (how long each program took on first use, how many are linked so far), call shaderWarmupDiagnostics().

Additional tips

• If you add/remove RaiSim objects after constructing the viewer, call RayraiWindow::updateObjectLists() so the renderer refreshes its cache.

• Use setShowCollisionBodies(true) for debug visualization of collision shapes.

• If you want rayrai overlays to use your ImGui font, pass it via setExternalFont.

API

Core types

class RayraiWindow

Offscreen renderer and visual scene manager for raisim.

RayraiWindow maintains an internal Camera, shader set, and a set of visual objects that can be rendered into an offscreen texture. It can render raisim world objects, custom visuals, point clouds, and coordinate frames.

Public Types

enum class ThreadingMode

Threading contract for the renderer.

SingleThread (the default) promises the application creates exactly one RayraiWindow per process and never spawns additional threads that touch rayrai state. In this mode no thread_local storage is used internally — caches sit in plain process-wide statics or on the window instance.

MultiThread is for RL / batch-render setups that spawn one RayraiWindow per worker thread, each with its own offscreen GL context. Internal caches that would otherwise need synchronization are kept per-thread via thread_local so workers cannot stomp on each other; shared resources (mesh import cache, texture cache) remain mutex-protected.

Mixing the two — for example, constructing several SingleThread windows on different threads — is unsupported.

Values:

enumerator SingleThread

enumerator MultiThread

Public Functions

RayraiWindow(std::shared_ptr<raisim::World> world, int width = 300, int height = 300, ThreadingMode threadingMode = ThreadingMode::SingleThread, unsigned int shaderCompileThreadCount = 1u, bool shaderBinaryCacheEnabled = true, std::string shaderBinaryCacheDirectory = std::string{}, bool logShaderBinaryCache = false)

Construct an offscreen renderer tied to a raisim world.

Parameters:

• world – Shared world pointer used for pulling object state.

• width – Initial render target width.

• height – Initial render target height.

• threadingMode – Concurrency contract — see ThreadingMode.

• shaderCompileThreadCount – Driver-side shader compile threads (passed to glMaxShaderCompilerThreadsARB). Defaults to 1 (single-threaded) to match rayrai’s overall single-threaded default; raise this only when the host application explicitly opts into multi-threading.

• shaderBinaryCacheEnabled – When true, compiled shader programs are persisted under shaderBinaryCacheDirectory and reused on next run, skipping driver compile entirely for unchanged GLSL/driver.

• shaderBinaryCacheDirectory – Explicit cache directory. Empty selects the default $HOME/.raisim/rayrai location.

• logShaderBinaryCache – When true, cache hits/misses/stores are logged to stderr — useful when verifying that the cache is actually being consulted.

RayraiWindow(raisim::World &world, int width = 300, int height = 300, ThreadingMode threadingMode = ThreadingMode::SingleThread, unsigned int shaderCompileThreadCount = 1u, bool shaderBinaryCacheEnabled = true, std::string shaderBinaryCacheDirectory = std::string{}, bool logShaderBinaryCache = false)

Construct an offscreen renderer tied to a raisim world.

Parameters:

• world – World reference used for pulling object state.

• width – Initial render target width.

• height – Initial render target height.

• threadingMode – Concurrency contract — see ThreadingMode.

• shaderCompileThreadCount – Driver-side shader compile threads (passed to glMaxShaderCompilerThreadsARB). Defaults to 1 (single-threaded) to match rayrai’s overall single-threaded default; raise this only when the host application explicitly opts into multi-threading.

• shaderBinaryCacheEnabled – When true, compiled shader programs are persisted under shaderBinaryCacheDirectory and reused on next run, skipping driver compile entirely for unchanged GLSL/driver.

• shaderBinaryCacheDirectory – Explicit cache directory. Empty selects the default $HOME/.raisim/rayrai location.

• logShaderBinaryCache – When true, cache hits/misses/stores are logged to stderr — useful when verifying that the cache is actually being consulted.

inline ThreadingMode threadingMode() const

Threading mode this renderer was constructed with.

void swapWorld(std::shared_ptr<raisim::World> world)

Reset this renderer to host a different raisim::World, reusing compiled shaders, textures, and render targets.

Pointers into the previous world become invalid the moment the caller destroys it, so this method drops every renderer-side handle that referenced those objects (objectList_, cachedWorldObjects_, render/shadow candidates, picking maps, and camera targets) and every visual added via addVisualXxx / addInstancedVisuals / addPointCloud / addCoordinateFrame. Additional lights, fog volumes, projected decals, irradiance volumes, and reflection probes are cleared so the caller’s scene-application step can repopulate them. Camera and render-quality settings are preserved.

size_t applyTextureFilteringQualityToLoadedTextures()

Apply current texture filtering quality to currently loaded RayRai visual textures.

Returns:

Number of texture ids updated.

void setAsyncMeshLoadingEnabled(bool enabled)

Enable or disable async mesh file import for future mesh visuals/world assets.

Async loading parses mesh files on a worker thread, skips drawing pending assets, and finalizes ready GPU resources on the render thread. Disable it when a caller needs mesh assets to be available immediately after addVisualMesh()/importVisualScene().

bool asyncMeshLoadingEnabled() const

True when future mesh file imports are started asynchronously.

size_t pollAsyncMeshLoads(size_t maxAssets = 1)

Finalize ready async mesh imports on the render thread.

Parameters:

maxAssets – Maximum number of assets to finalize.

Returns:

Number of assets finalized.

size_t pendingAsyncMeshLoadCount() const

Number of async mesh imports still waiting for CPU load or GPU finalization.

void resize(int newWidth, int newHeight)

Resize the internal camera render target.

Parameters:

• newWidth – New framebuffer width in pixels.

• newHeight – New framebuffer height in pixels.

void update(int w, int h, bool isHovering, int cX, int cY, bool shouldClick)

Render one frame into the internal camera’s offscreen texture.

Parameters:

• w – Target width.

• h – Target height.

• isHovering – Whether the mouse is over the render area (for input).

• cX – Cursor x position inside the render area.

• cY – Cursor y position inside the render area.

• shouldClick – Whether mouse click selection should be processed.

unsigned int getImageTexture() const

Return the GL texture id of the internal camera output.

Returns:

Texture id for the most recent rendered frame.

void setCameraFixedDistance(bool fixed)

Keep the camera distance constant when orbiting a target.

Parameters:

fixed – True to lock distance.

bool isCameraFixedDistance() const

True when the orbit distance is locked.

float cameraFixedDistance() const

Current locked orbit distance (metres).

void setCameraFixedTarget(bool fixed)

Keep the camera target fixed in world space.

Parameters:

fixed – True to lock the target position.

bool isCameraFixedTarget() const

True when the camera target is locked to a fixed point.

void setBackgroundColor(const glm::vec4 &color)

Set background clear color using legacy 0..255 RGBA channels.

Prefer setBackgroundColorRgb255() or setBackgroundColorLinear() in new code.

Parameters:

color – RGBA color where each channel is in [0, 255].

void setBackgroundColorRgb255(const glm::vec4 &color)

Set background clear color using 0..255 RGBA channels.

Parameters:

color – RGBA color where each channel is in [0, 255].

void setBackgroundColorLinear(const glm::vec4 &color)

Set background clear color using linear 0..1 RGBA channels.

Parameters:

color – Linear RGBA color where each channel is in [0, 1].

glm::vec4 getBackgroundColor() const

Get the current background clear color in 0..255 RGBA channels.

Mirrors setBackgroundColor*() so the value round-trips through serialization without a separate Camera lookup.

glm::vec4 getBackgroundColorLinear() const

Get the current background clear color in linear 0..1 RGBA channels.

inline void setEnvironmentBackground(unsigned int environmentMap, float exposure = 1.0f)

Render a cubemap behind the interactive viewer camera.

Parameters:

• environmentMap – Cubemap texture id, or 0 to disable the environment background.

• exposure – Multiplier applied while drawing the environment background.

inline unsigned int environmentBackgroundMap() const

Current interactive viewer environment background cubemap id, or 0 if disabled.

inline float environmentBackgroundExposure() const

Current interactive viewer environment background exposure multiplier.

inline void clearEnvironmentBackground()

Disable the interactive viewer environment background.

void setFogDensity(float density)

Set scene fog density used by the mesh shader.

Parameters:

density – Exponential fog density.

float getFogDensity() const

Get current fog density.

Returns:

Fog density value.

Camera &getCamera()

Access the internal camera for direct manipulation.

Returns:

Reference to the internal camera.

inline const Visuals *getTargetVisual() const

Get the currently selected target visual, if any.

Returns:

Pointer to the target visual or nullptr.

void setTargetVisual(Visuals *visual)

Set the target visual for camera tracking.

Parameters:

visual – Visual to target, or nullptr to clear.

void setShadowOrtho(float halfSize, float zNear, float zFar)

Set the directional shadow box (orthographic) parameters.

Parameters:

• halfSize – Half-size of the ortho box.

• zNear – Near plane.

• zFar – Far plane.

void setShadowCenterOffset(float meters)

Set the shadow center offset distance along the camera forward vector.

Parameters:

meters – Distance ahead of the camera.

void requestShadowUpdate()

Mark viewer shadow maps stale so they are rebuilt on the next viewer frame.

This is useful when RenderQualitySettings::updateShadowsEveryFrame is false and the application moves static-looking lights or scene geometry manually.

void setUpdateShadowsEveryFrame(bool enabled)

Runtime shortcut for RenderQualitySettings::updateShadowsEveryFrame.

Parameters:

enabled – True to refresh shadow maps every viewer frame, false to update on demand.

inline bool updateShadowsEveryFrame() const

True when viewer shadows are refreshed every frame.

inline float getShadowCenterOffset() const

Get the current shadow center offset distance.

Returns:

Distance ahead of the camera.

SupersampledCapture captureSupersampledRgba(const Camera &externalCam, int scale, const RenderOverrides &ov)

Render an explicit supersampled viewer capture and downsample to the input camera size.

This is intended for documentation screenshots. It is opt-in and uses an internal temporary camera, so it does not resize or otherwise mutate externalCam.

void renderWithExternalCamera(raisim::RGBCamera &sensorCam, Camera &externalCam, const RenderOverrides &ov)

Render using a raisim RGB camera and an external render camera.

Parameters:

• sensorCam – Raisim RGB camera providing projection parameters and pose.

• externalCam – Render camera to use for rendering.

• ov – Optional shader/toggle overrides.

void renderWithExternalCamera(raisim::DepthCamera &sensorCam, Camera &externalCam, const RenderOverrides &ov)

Render using a raisim depth camera and an external render camera.

Parameters:

• sensorCam – Raisim depth camera providing projection parameters and pose.

• externalCam – Render camera to use for rendering.

• ov – Optional shader/toggle overrides.

void renderWithExternalCamera(Camera &externalCam, const RenderOverrides &ov)

Render using an external render camera.

Parameters:

• externalCam – Render camera to use for rendering.

• ov – Optional shader/toggle overrides.

std::vector<RenderPassTiming> captureRenderPassTimings(Camera &externalCam, const RenderOverrides &ov)

Explicitly render once and return GPU elapsed-time measurements by pass.

This inserts blocking OpenGL timer queries and is intended for diagnostics and benchmarks only. Normal rendering does not issue timer queries.

std::vector<DebugPassCapture> captureDebugPasses(Camera &externalCam, const RenderOverrides &ov)

Capture the standard RayRai PBR/postprocess debug pass set for any scene.

The capture uses the caller-provided camera and render overrides, temporarily switches to Ultra quality, disables temporal history/upscaling for deterministic per-pass readback, and restores the previous quality settings and PBR debug environment afterward. Returned pixels are top-left ordered RGBA8 buffers so callers can write PNGs or analyze them without a RayRai image writer dependency.

DirectionalShadowCascadePlan planDirectionalShadowCascades(const Camera &camera) const

Compute stable directional-light cascade splits and light-space bounds for diagnostics.

This is CPU-only planning data. It does not allocate shadow maps or change the current single-map renderer; the returned values are intended for diagnostics, tests, and the future High/Ultra cascaded-shadow render path.

ShadowAtlasPlan planAdditionalShadowAtlas() const

Compute a deterministic tile plan for selected local-light shadow maps.

This is CPU-only planning data for the future local shadow atlas path. The current renderer still binds standalone depth textures/cubemaps; diagnostics expose this plan so atlas size, occupancy, point-light face count, and overflow are testable before the render path changes.

ShadowDebugOverlaySummary shadowDebugOverlaySummary() const

Build the CPU summary used by the optional in-view shadow debug overlay.

This does not render UI, allocate GL resources, or mutate settings. It is useful for tests, benchmarks, and applications that want to show their own shadow tuning panel.

unsigned int captureReflectionProbeCubemap(const glm::vec3 &position)

Capture a static local reflection probe into a cubemap.

This is a raster, load-time/manual operation. It renders six 90-degree faces from position and returns an OpenGL cubemap id with mipmaps. The caller owns the returned texture and may bind it to PBR materials through Visuals or Material.

Returns:

OpenGL cubemap id, or 0 on failure.

ReflectionProbe captureFilteredReflectionProbe(const glm::vec3 &position, float radius, float strength)

Capture a static local probe and generate irradiance, prefiltered specular, and BRDF maps.

This is an explicit bounded setup operation for High/Ultra. It does not update automatically after scene changes and does not affect Fast unless the caller uses the returned probe.

inline ReflectionProbe captureFilteredReflectionProbe(const CaptureFilteredReflectionProbeOptions &opts)

Options-struct overload; prefer this in new code.

inline ReflectionProbe captureFilteredReflectionProbeCached(const CaptureFilteredReflectionProbeOptions &opts)

Cached variant of the options-struct overload.

unsigned int captureReflectionProbeCubemapCached(const glm::vec3 &position, const ReflectionProbeCaptureSettings &settings)

Capture or reuse a cached static local reflection probe cubemap.

The cache is explicit and does not recapture automatically. The returned cubemap is owned by RayRai until clearReflectionProbeCache() or destruction. Applications should clear the cache after changing scene content that should be reflected in future probe captures.

ReflectionProbeDebugOverlaySummary reflectionProbeDebugOverlaySummary(const glm::vec3 &position) const

Build the CPU summary used by the optional in-view reflection probe overlay.

This is diagnostics-only: it does not capture probes, filter maps, allocate GL resources, or mutate probe selection state.

ReflectionProbePlacementSuggestion suggestReflectionProbePlacementFromSceneBounds() const

Suggest a static local reflection-probe placement from current scene bounds.

This is CPU-only and non-mutating. It does not capture or register a probe; callers can use the returned position/radius/box bounds with captureFilteredReflectionProbe() or a sidecar file after explicit approval. Halfspaces and heightmaps are ignored so infinite/default grounds do not dominate imported-room probe placement.

WeatherSkyEnvironment generateWeatherSkyEnvironment(int environmentFaceSize = 256, int irradianceFaceSize = 32, bool setVisibleBackground = true)

Generate a weather-driven sky/environment cubemap on demand.

This is intentionally explicit. Applications should call it at weather or time-of-day transition points, not every frame. When setVisibleBackground is true, the generated radiance cubemap is also installed as the visible environment background.

uint32_t pickWithExternalCamera(Camera &externalCam, int x, int y, Shader *pickingOverride = nullptr)

Run the picking pass and return object id at a pixel.

Parameters:

• externalCam – Render camera used for the picking pass.

• x – Pixel x coordinate in framebuffer space.

• y – Pixel y coordinate in framebuffer space.

• pickingOverride – Optional picking shader override.

Returns:

Encoded object id, or 0 if nothing is picked.

std::shared_ptr<PointCloud> addPointCloud(const std::string &name)

Create a named point cloud.

Parameters:

name – Unique name for the point cloud.

Returns:

Shared pointer to the point cloud instance.

void removePointCloud(const std::string &name)

Remove a point cloud by name.

Parameters:

name – Name of the point cloud to remove.

std::shared_ptr<CoordinateFrame> addCoordinateFrame(const std::string &name)

Create a named coordinate frame set.

Parameters:

name – Unique name for the coordinate frame set.

Returns:

Shared pointer to the coordinate frame instance.

void removeCoordinateFrame(const std::string &name)

Remove a coordinate frame set by name.

Parameters:

name – Name of the coordinate frame set to remove.

std::shared_ptr<Visuals> addVisualSphere(const std::string &name, double radius, float colorR = 1.f, float colorG = 1.f, float colorB = 1.f, float colorA = 1.f)

Add a visual sphere (not part of raisim::World).

Parameters:

• name – Visual name.

• radius – Sphere radius.

• colorR – Red channel.

• colorG – Green channel.

• colorB – Blue channel.

• colorA – Alpha channel.

Returns:

Shared pointer to the created visual.

inline std::shared_ptr<Visuals> addVisualSphere(const std::string &name, double radius, const glm::vec4 &color)

glm::vec4 color overload; prefer this in new code.

std::shared_ptr<Visuals> addVisualBox(const std::string &name, double xLength, double yLength, double zLength, float colorR = 1.f, float colorG = 1.f, float colorB = 1.f, float colorA = 1.f)

Add a visual box (not part of raisim::World).

Parameters:

• name – Visual name.

• xLength – Box size in X.

• yLength – Box size in Y.

• zLength – Box size in Z.

• colorR – Red channel.

• colorG – Green channel.

• colorB – Blue channel.

• colorA – Alpha channel.

Returns:

Shared pointer to the created visual.

inline std::shared_ptr<Visuals> addVisualBox(const std::string &name, double xLength, double yLength, double zLength, const glm::vec4 &color)

glm::vec4 color overload; prefer this in new code.

std::shared_ptr<Visuals> addVisualCylinder(const std::string &name, double radius, double height, float colorR = 1.f, float colorG = 1.f, float colorB = 1.f, float colorA = 1.f)

Add a visual cylinder (not part of raisim::World).

Parameters:

• name – Visual name.

• radius – Cylinder radius.

• height – Cylinder height.

• colorR – Red channel.

• colorG – Green channel.

• colorB – Blue channel.

• colorA – Alpha channel.

Returns:

Shared pointer to the created visual.

inline std::shared_ptr<Visuals> addVisualCylinder(const std::string &name, double radius, double height, const glm::vec4 &color)

glm::vec4 color overload; prefer this in new code.

std::shared_ptr<Visuals> addVisualCapsule(const std::string &name, double radius, double height, float colorR = 1.f, float colorG = 1.f, float colorB = 1.f, float colorA = 1.f)

Add a visual capsule (not part of raisim::World).

Parameters:

• name – Visual name.

• radius – Capsule radius.

• height – Capsule height.

• colorR – Red channel.

• colorG – Green channel.

• colorB – Blue channel.

• colorA – Alpha channel.

Returns:

Shared pointer to the created visual.

inline std::shared_ptr<Visuals> addVisualCapsule(const std::string &name, double radius, double height, const glm::vec4 &color)

glm::vec4 color overload; prefer this in new code.

std::shared_ptr<Visuals> addVisualMesh(const std::string &name, const std::string &meshFile, double scaleX = 1.0, double scaleY = 1.0, double scaleZ = 1.0, float colorR = 1.f, float colorG = 1.f, float colorB = 1.f, float colorA = 1.f)

Add a visual mesh (not part of raisim::World).

Parameters:

• name – Visual name.

• meshFile – Mesh file path.

• scaleX – Mesh scale in X.

• scaleY – Mesh scale in Y.

• scaleZ – Mesh scale in Z.

• colorR – Red channel.

• colorG – Green channel.

• colorB – Blue channel.

• colorA – Alpha channel.

Returns:

Shared pointer to the created visual.

inline std::shared_ptr<Visuals> addVisualMesh(const std::string &name, const std::string &meshFile, const glm::dvec3 &scale, const glm::vec4 &color = glm::vec4(1.f))

glm::vec3 scale + glm::vec4 color overload; prefer this in new code.

inline std::shared_ptr<Visuals> importVisualScene(const std::string &name, const std::string &sceneFile, const ImportVisualSceneOptions &opts)

Options-struct overload; prefer this in new code.

inline VisualMeshBuilder makeVisualMesh(std::string name, std::string meshFile)

Start a fluent build of an addVisualMesh visual. See VisualMeshBuilder.

std::shared_ptr<Visuals> addVisualPlane(const std::string &name, double width, double height, float colorR = 1.f, float colorG = 1.f, float colorB = 1.f, float colorA = 1.f)

Add a custom visual plane backed by the shared primitive plane mesh.

inline std::shared_ptr<Visuals> addVisualPlane(const std::string &name, double width, double height, const glm::vec4 &color)

glm::vec4 color overload; prefer this in new code.

std::shared_ptr<Visuals> addVisualCustomMesh(const std::string &name, const std::shared_ptr<std::vector<std::shared_ptr<OpenGLMesh>>> &meshes, const glm::vec4 &color = glm::vec4(1.f, 1.f, 1.f, 1.f))

Add a visual from custom OpenGL meshes.

Parameters:

• name – Visual name.

• meshes – Mesh list to render.

• color – Default color for non-textured meshes.

Returns:

Shared pointer to the created visual.

std::shared_ptr<Visuals> getVisualObject(const std::string &name)

Look up a visual by name.

Parameters:

name – Visual name.

Returns:

Shared pointer to the visual, or nullptr if not found.

void removeVisualObject(const std::string &name)

Remove a visual object by name.

Parameters:

name – Visual name to remove.

std::shared_ptr<InstancedVisuals> addInstancedVisuals(const std::string &name, raisim::Shape::Type type, const glm::vec3 &size, const glm::vec4 &color1, const glm::vec4 &color2, const std::string &meshFile = "")

Create instanced visuals for repeated shapes or meshes.

Parameters:

• name – Visual name.

• type – Shape type.

• size – Base size for the instances.

• color1 – Primary instance color.

• color2 – Secondary instance color.

• meshFile – Mesh file for mesh instances.

Returns:

Shared pointer to the created instanced visuals.

std::shared_ptr<InstancedVisuals> addInstancedVisuals(const std::string &name, const std::shared_ptr<std::vector<std::shared_ptr<OpenGLMesh>>> &meshes, const glm::vec3 &size, const glm::vec4 &color1, const glm::vec4 &color2)

Create instanced visuals from an already-created mesh list.

std::shared_ptr<InstancedVisuals> getInstancedVisuals(const std::string &name)

Look up instanced visuals by name.

Parameters:

name – Visual name.

Returns:

Shared pointer to the instanced visuals, or nullptr if not found.

void removeInstancedVisuals(const std::string &name)

Remove instanced visuals by name.

Parameters:

name – Visual name to remove.

std::shared_ptr<CameraFrustum> addCameraFrustum(const std::string &name, const glm::vec4 &color = glm::vec4(1.f, 1.f, 1.f, 1.f))

Create a camera frustum visualization.

Parameters:

• name – Visual name.

• color – Frustum color.

Returns:

Shared pointer to the frustum helper.

inline void setGroundPatternResourcePath(const std::string &path)

Set a tiled ground texture for halfspace visuals.

Parameters:

path – Path to the texture image.

inline std::string getGroundPatternResourcePath()

Get the current ground texture path.

Returns:

Ground texture path string.

void updateObjectLists()

Refresh internal lists of raisim objects.

inline const RaisimObject *debugObjectFor(raisim::Object *object) const

Return the cached draw wrapper for tests and diagnostics.

inline uint64_t debugSceneObjectCandidateRevision() const

Return the object candidate cache revision for tests and diagnostics.

void orthogonalViewSwitch()

Toggle between perspective and orthographic view.

void renderDepthPlaneDistance(raisim::DepthCamera &sensorCam, Camera &cam, Shader *depthPlaneOverride = nullptr)

Render a linear depth plane for a raisim depth camera.

Parameters:

• sensorCam – Raisim depth camera.

• cam – Render camera to use.

• depthPlaneOverride – Optional shader override.

void renderDepthPlaneDistance(Camera &cam, Shader *depthPlaneOverride = nullptr)

Render a linear depth plane with a given camera.

Parameters:

• cam – Render camera to use.

• depthPlaneOverride – Optional shader override.

inline unsigned int getDepthPlaneTexture() const

Get the linear depth texture id.

Returns:

OpenGL texture id for R32F linear depth.

void measureSpinningLidarSingleDrawGPU(raisim::SpinningLidar &lidar, const glm::dvec3 &sensorPosW, const glm::dmat3 &sensorRotW, const raisim::Object *objectToExclude = nullptr)

Render a single-draw incremental GPU LiDAR slice.

Renders the largest contiguous yaw span for this timestep using a spherical chunk shader.

Parameters:

• lidar – Raisim spinning lidar to update.

• sensorPosW – LiDAR position in world coordinates.

• sensorRotW – LiDAR orientation in world coordinates.

• objectToExclude – Optional object to exclude from rendering (e.g., the carrier).

inline Light &getLight()

Access the main scene light.

Returns:

Reference to the main light.

void addAdditionalLight(const AdditionalLight &light)

Add a non-shadow-casting light for visual quality.

Parameters:

light – Additional light. At most kMaxAdditionalLights are used.

void clearAdditionalLights()

Remove all non-shadow-casting additional lights.

inline size_t additionalLightCount() const

Return the current number of additional lights.

Returns:

Number of non-shadow-casting additional lights.

bool promoteDominantAdditionalLightToMainShadowCaster(bool preferSpotLights = true, bool removePromotedAdditionalLight = true)

Promote the dominant imported/local light to the single shadow-casting main light.

This is intended for authored glTF scenes that have a clear lamp/spot light. It keeps low-quality rendering fast because no additional shadow maps are created.

Parameters:

• preferSpotLights – Prefer spot lights over other light types when possible.

• removePromotedAdditionalLight – Remove the promoted light from the non-shadow list to avoid double-counting its direct contribution.

Returns:

True if a suitable light was promoted.

size_t importSceneLights(const std::string &sceneFile, float intensityScale = 1.0f)

Import authored scene lights from a mesh/scene file through Assimp.

Imported lights are appended as bounded, non-shadow-casting viewer lights. This is explicit so low-quality rendering does not pay for scene lights unless an application imports them.

Returns:

Number of lights appended, capped by kMaxAdditionalLights.

void setRenderQualityPreset(RenderQualityPreset preset)

Apply a named viewer-quality preset at runtime.

Parameters:

preset – Quality preset to apply.

inline RenderQualityPreset getRenderQualityPreset() const

Return the active named quality preset, or Custom after explicit settings.

void setRenderQualitySettings(const RenderQualitySettings &settings)

Apply explicit viewer-quality settings at runtime.

Parameters:

settings – Settings to apply.

inline const RenderQualitySettings &getRenderQualitySettings() const

Return the active explicit viewer-quality settings.

void printRenderDiagnostics(std::ostream &out = std::cout) const

Print active viewer-quality, light, shadow, and post-process diagnostics.

void writeRenderDiagnosticsJson(std::ostream &out, const SceneImportReport *importReport = nullptr) const

Write structured render diagnostics as JSON.

The JSON is intended for regression tests, issue reports, and imported-scene debugging. It contains render-quality settings, scene/resource counts, lights, shadow selection state, postprocess state, and an optional scene-import report.

std::string renderDiagnosticsJson(const SceneImportReport *importReport = nullptr) const

Return structured render diagnostics as a JSON string.

RenderPassAccounting estimateRenderPassAccounting() const

Return estimated render-pass accounting for the current quality settings.

This is an estimate-only diagnostic. It does not insert GPU timers or render any frame. Use captureRenderPassTimings() when exact blocking GPU timings are required.

TransparentDrawDebugView transparentDrawDebugView(size_t maxItems = 32) const

Return the transparent draw order that the viewer path should use for the current camera.

The result is diagnostic-only. It does not render and does not mutate instance buffers.

TransparentDrawDebugView transparentDrawDebugView(const Camera &camera, size_t maxItems = 32) const

Return transparent draw diagnostics for an explicit render camera.

ShaderWarmupDiagnostics shaderWarmupDiagnostics() const

Return startup shader compile/warmup diagnostics for built-in RayRai programs.

RayRai registers all built-in shader programs during construction and compiles optional shaders lazily on first use. This exposes the measured compile/link cost and linked program count so startup and first-use stalls can be tracked.

std::vector<std::string> linkedShaderNames() const

Names of every shader program currently linked, sorted alphabetically. Useful for diagnostics and for callers that want to record the “hot set” of shaders an application actually uses so a future run can pre-warm only those.

long long warmupNextShader(bool &done)

Compile one not-yet-compiled built-in shader program, if any.

Returns the number of milliseconds spent compiling (0 if no work was done). The output flag done is set to true when every registered program has been compiled at least once. Iterates all registered programs — most of which an application typically doesn’t use; prefer compileShaderByName to pre-warm just the heavy shaders your active scene actually exercises. Must be called on the thread that owns the GL context.

long long compileShaderByName(const std::string &name)

Compile a specific built-in shader by name if not already linked. Returns the milliseconds spent compiling (0 if already linked or unknown name). Lets the application warm just the shaders it knows will be needed — e.g. pbrMeshHigh is the dominant cost for content rendering (~15s alone) so pre-warming only that one already eliminates the visible “freeze” on first content frame without paying for unused shader variants. Must be called on the thread that owns the GL context.

MaterialTextureBudgetRecommendation recommendMaterialTextureBudget(size_t budgetBytes = 0) const

Build a non-mutating material texture memory fallback recommendation.

If budgetBytes is zero, a conservative preset-aware default is used. The recommendation only changes quality settings that reduce texture sampling/setup cost; it does not unload existing textures or alter sensor behavior.

void writeRenderDiagnosticsFiles(const std::filesystem::path &directory, const SceneImportReport *importReport = nullptr) const

Write structured diagnostics files, including uncapped mesh/material tables.

This is intended for explicit issue reports and offline analysis. The regular in-memory JSON remains capped so Fast/Balanced users do not accidentally pay for large debug payloads unless they request file export.

inline void setDOFEnabled(bool e)

Enable or disable depth of field post-processing.

Parameters:

e – True to enable.

inline void setDOFParams(float focusDist, float focusRange, float maxRadius)

Set depth of field parameters.

Parameters:

• focusDist – Focus distance in view space.

• focusRange – Focus range around the focus distance.

• maxRadius – Max blur radius in pixels.

inline void setShowCollisionBodies(bool show)

Toggle rendering of collision shapes for articulated systems.

Parameters:

show – True to render collision bodies.

inline bool getShowCollisionBodies() const

Return collision-body rendering state.

Returns:

True if collision bodies are shown.

void setExternalFont(ImFont *font)

Provide an ImGui font to use for the viewer overlay.

Parameters:

font – Pointer to an ImGui font.

inline ImFont *getExternalFont() const

Retrieve the external ImGui font pointer.

Returns:

Font pointer or nullptr.

inline void setHeightmapPatternResourcePath(const std::string &path)

Set a tiled albedo texture for all heightmaps.

Parameters:

path – Path to the texture image, or empty to clear.

inline void setHeightmapSplatLayer(const std::string &albedoPath, unsigned int controlTexId, float primaryUvScale, float secondaryUvScale, const glm::vec4 &controlBounds)

Configure a secondary terrain splat layer for heightmap meshes.

The PBR mesh shader blends albedoPath over the primary heightmap albedo using a single-channel control texture. Setting controlTexId to 0 or albedoPath empty disables splat blending.

Public Static Functions

static unsigned int loadTextureWithTiling(const char *path, bool useSrgbFormat = false)

Load an image file into an OpenGL texture with repeat tiling.

Parameters:

• path – Path to an image file supported by stb_image.

• useSrgbFormat – If true, RGB/RGBA textures are uploaded as sRGB color textures. Use true for albedo/emissive color maps and false for data maps such as normal, metallic-roughness, AO, depth, and masks.

Returns:

OpenGL texture id, or 0 on failure.

static unsigned int updateSingleChannelTexture(unsigned int existingTextureId, int width, int height, const unsigned char *data)

Create or update a single-channel R8 2D texture from raw pixel data.

Used for terrain splat control maps. Pass existingTextureId 0 to allocate a new texture, otherwise the existing texture is updated in place when the dimensions match. Returns the texture id (new or reused), or 0 on failure.

static unsigned int loadHdrEquirectangularCubemap(const char *path, int faceSize = 128, bool generateMipmaps = true)

Load a Radiance .hdr equirectangular environment into a cubemap texture.

This is intended for High/Ultra viewer PBR workflows. It does not allocate anything unless the application explicitly calls it.

Parameters:

• path – Path to a .hdr image supported by stb_image.

• faceSize – Cubemap face size in pixels.

• generateMipmaps – Whether to generate mip levels for roughness sampling.

Returns:

OpenGL cubemap id, or 0 on failure.

static unsigned int createHdrIrradianceCubemap(const char *path, int faceSize = 32, int sampleCount = 256)

Generate a diffuse irradiance cubemap from a Radiance .hdr equirectangular environment.

This is CPU-side cosine-hemisphere integration intended for High/Ultra PBR setup. Creation is explicit so Fast/Balanced RL rendering does not pay the cost.

Parameters:

• path – Path to a .hdr image supported by stb_image.

• faceSize – Irradiance cubemap face size in pixels.

• sampleCount – Number of hemisphere samples per texel.

Returns:

OpenGL cubemap id, or 0 on failure.

static unsigned int createHdrPrefilteredEnvironmentCubemap(const char *path, int faceSize = 128, int mipLevels = 5, int sampleCount = 256)

Generate a prefiltered specular environment cubemap from a Radiance .hdr equirectangular environment.

Mip level 0 is sharp and higher mip levels are GGX-prefiltered with increasing roughness. Use this as Material::prefilteredEnvironmentMap together with createSplitSumBrdfLut().

Parameters:

• path – Path to a .hdr image supported by stb_image.

• faceSize – Base cubemap face size in pixels.

• mipLevels – Number of mip levels to allocate and integrate.

• sampleCount – Number of GGX samples per texel.

Returns:

OpenGL cubemap id, or 0 on failure.

static unsigned int createSplitSumBrdfLut(int size = 256, int sampleCount = 512)

Create a numerically integrated split-sum BRDF LUT.

Use this as Material::brdfLut for High/Ultra PBR. Creation is explicit so Fast/Balance paths do not pay for it.

static void setTextureAnisotropy(unsigned int target, unsigned int textureId, float requestedLevel)

Apply anisotropic filtering to an existing 2D or cubemap texture if supported.

Parameters:

• target – Texture target such as GL_TEXTURE_2D or GL_TEXTURE_CUBE_MAP.

• textureId – OpenGL texture id.

• requestedLevel – Requested anisotropy level. Values <= 1 leave the texture unchanged.

static void setTextureFilteringQuality(unsigned int target, unsigned int textureId, float anisotropy, float mipLodBias)

Apply minification quality controls to an existing texture.

Positive mip LOD bias prefers blurrier mips and reduces distant texture shimmer. Negative values sharpen but can alias, so RayRai clamps the accepted range conservatively.

static void setDefaultTextureFilteringQuality(float anisotropy, float mipLodBias)

Set process-wide filtering defaults used by future loadTextureWithTiling() calls.

static void getDefaultTextureFilteringQuality(float &anisotropy, float &mipLodBias)

Read process-wide filtering defaults used by future loadTextureWithTiling() calls.

static void setTextureSamplerState(unsigned int target, unsigned int textureId, int wrapS, int wrapT, int minFilter, int magFilter)

Apply sampler wrap/filter state to an existing texture.

static inline unsigned int loadColorTextureWithTiling(const char *path)

Load an albedo/emissive color texture as sRGB.

Parameters:

path – Path to an image file supported by stb_image.

Returns:

OpenGL texture id, or 0 on failure.

static inline unsigned int loadDataTextureWithTiling(const char *path)

Load a data texture as linear values.

Parameters:

path – Path to an image file supported by stb_image.

Returns:

OpenGL texture id, or 0 on failure.

static void createOffscreenGlContext(SDL_Window *&window, SDL_GLContext &glContext, const char *title = "rayrai_offscreen")

Create a hidden SDL window and an offscreen OpenGL context.

Parameters:

• window – Output pointer for the created SDL window.

• glContext – Output handle for the OpenGL context.

• title – Window title for the hidden SDL window.

static void makeOffscreenContextCurrent(SDL_Window *window, SDL_GLContext glContext)

Make an existing offscreen context current and update glbinding.

Parameters:

• window – SDL window owning the OpenGL context.

• glContext – OpenGL context to make current.

static void prewarmShadersForCurrentContext(ThreadingMode threadingMode = ThreadingMode::MultiThread, std::string shaderBinaryCacheDirectory = std::string{})

Compile every built-in shader using the GL context currently bound to the calling thread, populating the on-disk binary cache.

Intended for parallel RL workflows: spawn a background thread that holds its own offscreen GL context, call this once, and worker threads that later construct RayraiWindow instances will find the heavy shaders already in the cache (or briefly block on the per-shader compile mutex for any program this thread is still finishing).

Net effect across a process: each shader’s GLSL→binary compile runs exactly once, regardless of how many worker threads concurrently construct RayraiWindows.

Pre-conditions: the caller’s thread has made a valid offscreen GL context current. Post-condition: the temporary RayraiWindow used for compilation is destroyed before this returns; the caller’s context is left current. The caller is responsible for the surrounding SDL_GL_MakeCurrent(nullptr) / SDL_GL_DeleteContext / thread join.

Parameters:

• threadingMode – Must match the mode used by the worker threads that will eventually construct their own RayraiWindows. Defaults to MultiThread since prewarming only makes sense when other threads will also render.

• shaderBinaryCacheDirectory – Optional explicit cache directory. Empty selects the default $HOME/.raisim/rayrai location.

static ReflectionProbeCaptureFrame reflectionProbeCaptureFrame(int face)

Return the capture camera frame used for a cubemap face.

The frame follows the same OpenGL cubemap convention used by environment-map sampling and CPU probe filtering. It is exposed so tests and tools can validate local reflection probe orientation without rendering a probe.

static inline ReflectionProbeSidecarLoadResult loadReflectionProbeSidecarResult(const std::string &sceneFile)

Struct-returning overload; prefer this in new code.

static RenderQualitySettings defaultRenderQualitySettings(RenderQualityPreset preset)

Return the default settings for a named preset.

Parameters:

preset – Preset to query.

static DynamicQualityRecommendation recommendDynamicQuality(const RenderQualitySettings &settings, RenderQualityPreset preset, const std::vector<RenderPassTiming> &timings)

Build a sensor-safe dynamic-quality recommendation from explicit GPU pass timings.

This does not mutate renderer state. It is intended for Fast/Balanced viewer loops that explicitly opt into adaptive render scale or static shadow updates after measuring GPU cost. High/Ultra recommendations preserve quality by default.

static RgbaLuminanceMetrics analyzeRgbaLuminance(const std::vector<unsigned char> &rgba, int width, int height)

Analyze display-space luminance and saturation from an RGBA8 capture.

This is intended for exposure/tone-map diagnostics and image regression tests. It does not render or read from OpenGL; callers pass already captured RGBA8 pixels.

static ExposureRecommendation recommendExposure(const RgbaLuminanceMetrics &metrics, double currentExposure = 1.0, double targetMedianLuminance = 0.45, double targetP95Luminance = 0.90, double minExposure = 0.125, double maxExposure = 8.0)

Build a bounded exposure recommendation from display-space luminance metrics.

This does not mutate renderer state. It is intended for explicit viewer calibration, quality-comparison reports, and offline screenshot tooling. Sensor renders should only apply the result if the caller explicitly opts into viewer-style postprocessing.

static double smoothExposure(double currentExposure, double targetExposure, double deltaSeconds, double brightenRate = 1.2, double darkenRate = 3.0, double minExposure = 0.125, double maxExposure = 8.0)

Smooth an explicitly chosen exposure target over time.

This helper is stateless and does not mutate renderer settings. Use a larger darken rate than brighten rate to adapt quickly away from clipping while avoiding flicker when lifting dark scenes.

static RgbaLuminanceHistogram analyzeRgbaLuminanceHistogram(const std::vector<unsigned char> &rgba, int width, int height, size_t binCount = 64)

Build a display-space luminance histogram from an RGBA8 capture.

This is a CPU diagnostics helper for exposure reports and regression artifacts. It does not render, read OpenGL state, or mutate color-management settings.

static std::vector<unsigned char> renderLuminanceHistogramRgba(const RgbaLuminanceHistogram &histogram, int width, int height)

Render a luminance histogram into a simple RGBA8 debug image.

The output is top-left row order. It is intended for reports and screenshots, not for the main frame path.

static std::vector<unsigned char> renderCloudDebugRgba(const RenderQualitySettings &settings, int width, int height)

Render procedural cloud diagnostics into a three-panel RGBA8 image.

The panels are coverage mask, projected shadow attenuation, and approximate cloud-lighting contribution. The CPU path mirrors the shader-side procedural cloud mask, so tests and showcase images can inspect the weather cloud path without screenshots alone.

static std::vector<unsigned char> renderRainDebugRgba(const RenderQualitySettings &settings, const WeatherDiagnostics &diagnostics, int width, int height)

Render rain/wet-material diagnostics into a four-panel RGBA8 image.

The panels are precipitation density, wet-surface mask, puddle mask, and material override strength. The CPU path uses the resolved weather diagnostics plus the same bounded wet/puddle/ripple model used by the PBR shader, so tests and showcase images can inspect the rain material path without relying on screenshots alone.

static std::vector<unsigned char> renderSnowDebugRgba(const RenderQualitySettings &settings, const WeatherDiagnostics &diagnostics, int width, int height)

Render snow-material diagnostics into a two-panel RGBA8 image.

The panels are accumulation mask and material override strength. The CPU path uses resolved weather diagnostics plus the same bounded snow accumulation model used by the PBR shader.

static std::vector<unsigned char> transformRgbaForOutput(const std::vector<unsigned char> &rgba, int width, int height, const RgbaOutputTransform &transform)

Apply a bounded CPU output transform to RGBA8 pixels for screenshots/reports.

This clamps RGB into displayable range and preserves alpha. It is intended for explicit PNG/screenshot tooling, not for simulation sensor outputs unless requested.

static RgbaCalibrationMetrics analyzeRgbaCalibrationPatches(const std::vector<unsigned char> &rgba, int width, int height, const std::vector<RgbaCalibrationPatch> &patches)

Measure color-calibration patches in display-space RGBA8 pixels.

Patch coordinates use top-left row order, matching RayRai PNG/debug buffers. This is an offline/report helper for calibration scenes and does not mutate renderer exposure, tone mapping, or sensor behavior.

static std::vector<unsigned char> renderCalibrationPatchReportRgba(const RgbaCalibrationMetrics &metrics, int width, int height)

Render a compact calibration error report image from patch metrics.

static RgbaCalibrationRecommendation recommendCalibrationOutputTransform(const RgbaCalibrationMetrics &metrics)

Build a bounded screenshot/report output transform from calibration patches.

Neutral patches drive exposure and white balance; saturated patches drive a conservative saturation correction. This returns a recommendation only and never mutates renderer state.

struct CaptureFilteredReflectionProbeOptions

Options bundle for captureFilteredReflectionProbe; replaces the three positional overloads with a single struct so callers do not have to remember which overload accepts which knob.

struct DebugPassCapture

Public Members

std::vector<unsigned char> rgba

RGBA8 pixels in top-left row order, ready for PNG writers.

struct DirectionalShadowCascade

struct DirectionalShadowCascadePlan

struct DynamicQualityRecommendation

struct EnvironmentSidecarSettings

struct ExposureRecommendation

struct ExternalFrameCache

struct ImportVisualSceneOptions

Options bundle for importVisualScene; collapses the seven trailing optional parameters from the flat-argument overload into a struct that is easier to read and to evolve without breaking call sites.

struct MaterialTextureBudgetRecommendation

struct ReflectionProbe

struct ReflectionProbeBlend

struct ReflectionProbeCaptureFrame

struct ReflectionProbeCaptureSettings

Explicit static reflection-probe capture settings.

Probe capture is never automatic. Applications call captureReflectionProbeCubemap() when they want a bounded real-time local reflection approximation.

struct ReflectionProbeDebugItem

struct ReflectionProbeDebugOverlaySummary

struct ReflectionProbeDebugView

struct ReflectionProbeFilterSettings

Explicit CPU filtering settings for captured local reflection probes.

Filtering is a load-time/manual Ultra operation. Fast/Balanced do not allocate or run this unless the application calls captureFilteredReflectionProbe().

struct ReflectionProbePlacementSuggestion

struct ReflectionProbeSidecarLoadResult

Result bundle for the struct-returning loadReflectionProbeSidecar overload.

Returned by value so callers do not have to thread &settings and &loadedSidecarPath out-parameters; the loadedSidecarPath is empty when no sidecar file was found.

struct ReflectionProbeSidecarProbe

struct ReflectionProbeSidecarSettings

struct RenderOverrides

Override shaders and rendering toggles when using external cameras.

Public Members

Shader *mesh

Mesh shader override (defaults to shaders_[“mesh”]).

Shader *pointcloud

Point cloud shader override (defaults to shaders_[“pointcloud”]).

Shader *picking

Picking shader override (defaults to shaders_[“picking”]).

Shader *post

Post-process shader override (defaults to shaders_[“post”]).

bool doShadows

Enable shadow passes.

bool drawCoordinateFrames

Draw coordinate frames.

bool drawPointClouds

Draw point clouds.

bool drawVisualizationObjects

Draw visualization-only custom visuals and instanced visuals.

bool drawWeatherEffects

Draw viewer-only weather effects such as precipitation particles.

bool skipGroundObjects

Skip halfspace and heightmap ground objects in scene-color rendering.

unsigned int environmentBackgroundMap

Optional cubemap rendered as a viewer background before scene geometry.

float environmentBackgroundExposure

Exposure applied to environmentBackgroundMap when rendered as background.

bool postProcess

Apply external-camera postprocessing after rendering.

bool allowViewerMsaa

Allow quality preset MSAA for this external render. Sensor overloads force this off.

bool allowTemporalAa

Allow quality preset temporal AA for this external render. Sensor overloads force this off.

bool allowViewerUpscale

Allow quality preset lower-resolution viewer rendering followed by upscale.

struct RenderPassAccounting

struct RenderPassTiming

struct RgbaCalibrationMetrics

struct RgbaCalibrationPatch

struct RgbaCalibrationPatchResult

struct RgbaCalibrationRecommendation

struct RgbaLuminanceHistogram

struct RgbaLuminanceMetrics

struct RgbaOutputTransform

struct SceneImportReport

struct ShaderWarmupDiagnostics

struct ShadowAtlasPlan

struct ShadowAtlasTile

struct ShadowDebugOverlaySummary

struct StaticSceneLayerCache

struct SupersampledCapture

struct TransparentDrawDebugView

struct TransparentDrawItem

class VisualMeshBuilder

Fluent builder for addVisualMesh.

Collects scale/position/orientation/material and flags up front; add() creates the visual via the corresponding addVisualMesh overload, then applies the deferred state via the existing setters and returns the shared_ptr<Visuals>. Setters on the returned visual still work for runtime mutations after creation.

Example:

auto v = renderer.makeVisualMesh("rusty", path)
  .scale({1.0, 1.0, 1.0})
  .position({0.0, 0.0, 0.5})
  .orientation(glm::angleAxis(0.4f, glm::vec3{0, 0, 1}))
  .twoSided(true)
  .pickable(true)
  .castsShadows(true)
  .material(rusty)
  .pbrEnvironment(env)
  .add();

Public Functions

std::shared_ptr<Visuals> add()

Create the visual, apply the deferred state, return the shared_ptr.

struct WeatherSidecarSettings

class Camera

Camera for offscreen rendering and interaction.

The camera owns its render targets (scene color/depth, post-process, linear depth, and picking). It can be driven by user input or by raisim sensor parameters.

Public Types

enum class ProjectionMode

Projection mode for view generation.

Values:

enumerator PERSPECTIVE

enumerator ORTHOGRAPHIC

enum class SensorStorageMode

Storage mode for extracting rendered images.

Values:

enumerator SENSOR_SETTER

enumerator CUSTOM_BUFFER

Public Functions

explicit Camera(glm::vec3 position = glm::vec3(5.0f, 4.0f, 5.0f), glm::vec3 up = glm::vec3(0.0f, 0.0f, 1.0f), float yaw = -135.0f, float pitch = -30.0f)

Construct a camera with a position, up vector, and yaw/pitch.

Parameters:

• position – Camera position in world coordinates.

• up – World up vector.

• yaw – Initial yaw angle in degrees.

• pitch – Initial pitch angle in degrees.

explicit Camera(raisim::RGBCamera &rgbCam)

Construct a camera from a raisim RGB camera (and allocate targets).

Parameters:

rgbCam – Raisim RGB camera to mirror.

explicit Camera(const raisim::RGBCamera &rgbCam)

Construct a camera from a const raisim RGB camera.

Parameters:

rgbCam – Raisim RGB camera to mirror.

explicit Camera(raisim::DepthCamera &depthCam)

Construct a camera from a raisim depth camera (and allocate targets).

Parameters:

depthCam – Raisim depth camera to mirror.

explicit Camera(const raisim::DepthCamera &depthCam)

Construct a camera from a const raisim depth camera.

Parameters:

depthCam – Raisim depth camera to mirror.

void update(bool processKeyboard = true)

Update camera orientation and handle input.

Parameters:

processKeyboard – If true, WASD and Space affect position.

glm::mat4 getViewMatrix() const

Get the view matrix for the current camera pose.

Returns:

View matrix in column-major GLM format.

glm::mat4 getProjectionMatrix() const

Get the projection matrix for the current camera state.

Returns:

Projection matrix in column-major GLM format.

void setProjectionJitterPixels(const glm::vec2 &jitterPixels)

Set subpixel projection jitter in pixels for temporal AA style viewer rendering.

inline void clearProjectionJitter()

Clear projection jitter.

inline glm::vec3 getPosition() const

Get the current camera position.

Returns:

Position in world coordinates.

void mouseDelta(float yawOffset, float pitchOffset)

Apply mouse delta to yaw/pitch or pan in orthographic mode.

Parameters:

• yawOffset – Delta yaw in degrees (screen-space delta).

• pitchOffset – Delta pitch in degrees (screen-space delta).

void moveForward(float steps)

Move forward/backward or zoom in orthographic mode.

Parameters:

steps – Positive moves forward/zooms in; negative moves back/zooms out.

void setCameraFixedDistance(bool fixed)

Lock camera distance while orbiting.

Parameters:

fixed – True to keep distance constant.

inline bool isCameraFixedDistance() const

True when the orbit distance is locked.

inline float cameraFixedDistance() const

Current locked orbit distance (metres).

void setCameraFixedTarget(bool fixed)

Lock the target position to a fixed point.

Parameters:

fixed – True to lock to the current target.

inline bool isCameraFixedTarget() const

True when the camera target is locked to a fixed point.

void setTargetObject(raisim::Object *target)

Set a raisim object to track as the camera target.

Parameters:

target – Raisim object to follow, or nullptr to clear.

void setProjectionMode(ProjectionMode mode)

Set projection mode.

Parameters:

mode – Projection mode (perspective or orthographic).

ProjectionMode getProjectionMode() const

Get the active projection mode.

Returns:

Current projection mode.

void setLensModel(const raisim::CameraLensModel &lens, double hFovRad)

Configure the camera lens model used for sensor rendering.

inline const raisim::CameraLensModel &getLensModel() const

Get the active sensor lens model.

inline bool isFisheyeLens() const

True when the camera is configured for OpenCV/ROS equidistant fisheye output.

void applyFisheyeRemap(Shader &fisheyeShader)

Resample scene color through the fisheye lens model.

glm::vec3 getTargetPosition() const

Get the current target position for orbiting.

Returns:

Target position in world coordinates.

void ensureRenderTargets(int width, int height)

Ensure render targets match the given size.

Parameters:

• width – Render target width.

• height – Render target height.

inline void resizeRenderTargets(int width, int height)

Resize render targets (alias for ensureRenderTargets).

Parameters:

• width – Render target width.

• height – Render target height.

void setSceneMsaaSamples(int samples)

Set scene-color MSAA samples for future scene FBO rendering.

Values <= 1 disable MSAA. The resolved color/depth are still written into the existing single-sample texture targets so postprocessing and readback APIs keep working.

inline int sceneMsaaSamples() const

Current scene-color MSAA sample count. 1 means disabled.

void resolveSceneFboIfNeeded(bool restoreFramebuffer = true)

Resolve the multisampled scene target into the regular color/depth textures.

void ensurePostRenderTarget()

Ensure the post-process render target exists.

void ensureLinearDepthRenderTarget()

Ensure the linear-depth render target exists.

void bindSceneFbo()

Bind the scene framebuffer for rendering.

void bindPostFbo()

Bind the post-process framebuffer for rendering.

void bindLinearDepthFbo()

Bind the linear-depth framebuffer for rendering.

inline int rtWidth() const

Current render target width.

Returns:

Width in pixels.

inline int rtHeight() const

Current render target height.

Returns:

Height in pixels.

void beginSceneFboAndClear(bool preserveState = true)

Bind scene FBO and clear with background color.

void postProcessDoF(Shader &postShader, bool fxaaEnabled = false, bool bloomEnabled = false, float bloomThreshold = 0.82f, float bloomStrength = 0.18f, float bloomRadius = 4.0f, float bloomKnee = 0.22f, int bloomQuality = 1, float bloomSourceClamp = 8.0f, float bloomAnamorphic = 0.0f, float bloomDirtStrength = 0.0f, float bloomDirtScale = 1.0f, unsigned int bloomDirtTexture = 0, int bloomBlendMode = 0, float bloomMix = 0.05f, const glm::vec3 &viewerWhiteBalance = glm::vec3(1.0f), float viewerSaturation = 1.0f, bool screenSpaceAoEnabled = false, float screenSpaceAoRadius = 2.0f, float screenSpaceAoStrength = 0.0f, float screenSpaceAoBias = 0.02f, int screenSpaceAoSamples = 12, float screenSpaceAoFalloff = 0.08f, bool screenSpaceAoRadiusWorldSpace = false, float screenSpaceAoMaxPixelRadius = 48.0f, bool screenSpaceAoGeometryAware = false, float contactAoRadius = 0.0f, float contactAoStrength = 0.0f, int contactAoSamples = 8, float contactAoFalloff = 0.05f, bool screenSpaceAoDenoiseEnabled = false, float screenSpaceAoDenoiseStrength = 0.0f, int screenSpaceAoDenoiseRadius = 1, float screenSpaceAoDenoiseDepthSigma = 0.035f, bool screenSpaceIndirectLightingEnabled = false, float screenSpaceIndirectLightingRadius = 3.0f, float screenSpaceIndirectLightingStrength = 0.0f, int screenSpaceIndirectLightingSamples = 12, float screenSpaceIndirectLightingFalloff = 0.22f, float screenSpaceIndirectLightingNormalRejection = 0.75f, float screenSpaceIndirectLightingSaturation = 1.0f, bool volumetricFogEnabled = false, float volumetricFogDensity = 0.0f, float volumetricFogNoiseScale = 6.0f, float volumetricFogNoiseStrength = 0.55f, const glm::vec3 &volumetricFogColor = glm::vec3(0.72f, 0.80f, 0.90f), float volumetricFogAnisotropy = 0.0f, float volumetricFogAnimationTimeSeconds = 0.0f, const glm::vec2 &volumetricFogWindDirection = glm::vec2(1.0f, 0.0f), float volumetricFogWindSpeed = 0.0f, float volumetricFogTurbulenceSpeed = 0.0f, bool volumetricLightingEnabled = false, float volumetricLightStrength = 0.0f, float volumetricLightDecay = 0.88f, int volumetricLightSamples = 16, const glm::vec2 &volumetricLightScreenPosition = glm::vec2(0.5f), const glm::vec3 &volumetricLightColor = glm::vec3(1.0f), int localFogVolumeCount = 0, const std::array<glm::vec4, 8> &localFogVolumeCenterRadius = {}, const std::array<glm::vec4, 8> &localFogVolumeColorDensity = {}, const std::array<glm::vec4, 8> &localFogVolumeParams = {}, int projectedDecalCount = 0, const std::array<glm::mat4, 8> &projectedDecalWorldToLocal = {}, const std::array<glm::vec4, 8> &projectedDecalColor = {}, const std::array<glm::vec4, 8> &projectedDecalParams = {}, const std::array<unsigned int, 8> &projectedDecalAlbedoMaps = {}, const std::array<unsigned int, 8> &projectedDecalEmissionMaps = {}, const std::array<unsigned int, 8> &projectedDecalNormalMaps = {}, const std::array<unsigned int, 8> &projectedDecalOrmMaps = {}, const std::array<glm::vec4, 8> &projectedDecalTextureParams = {}, const std::array<glm::vec4, 8> &projectedDecalSurfaceParams = {}, const std::array<glm::vec4, 8> &projectedDecalUvScaleOffset = {}, bool temporalAaEnabled = false, float temporalAaBlend = 0.08f, bool temporalAaReset = false, int postProcessDebugMode = 0, bool aerialPerspectiveEnabled = false, unsigned int apVolumeTex = 0, float apStrength = 1.0f, int viewerColorGradePreset = 0, float viewerColorGradeStrength = 1.0f, float viewerVignetteStrength = 0.0f, float viewerChromaticAberrationStrength = 0.0f, float viewerFilmGrainStrength = 0.0f, float viewerLensCharacterTime = 0.0f, bool lightShaftsEnabled = false, float lightShaftsStrength = 1.0f, float lightShaftsDecay = 0.965f, float lightShaftsDensity = 1.0f, const glm::vec2 &lightShaftsSunScreenPos = glm::vec2(0.5f, 0.5f), const glm::vec3 &lightShaftsTint = glm::vec3(1.0f), float lensFlareGhostStrength = 0.0f, float lensFlareStreakStrength = 0.0f, const glm::vec3 &lensFlareTint = glm::vec3(1.0f), bool contactShadowsEnabled = false, float contactShadowsLength = 0.12f, float contactShadowsStrength = 0.7f, float contactShadowsThickness = 0.08f, const glm::vec2 &contactShadowsSunScreenPos = glm::vec2(0.5f, 0.5f), const glm::vec3 &contactShadowsLightDirectionWorld = glm::vec3(0.0f, 0.0f, -1.0f), bool motionBlurEnabled = false, const glm::vec2 &motionBlurDirection = glm::vec2(0.0f), float motionBlurStrength = 0.0f, bool ssrEnabled = false, float ssrStrength = 0.0f, int ssrSteps = 24, float ssrMaxDistance = 6.0f, float ssrThickness = 0.35f, bool heatHazeEnabled = false, float heatHazeStrength = 0.0f, float heatHazeFrequency = 4.0f, float heatHazeSpeed = 1.0f, float heatHazeMaxY = 0.55f, bool zoomBlurEnabled = false, float zoomBlurStrength = 0.0f, const glm::vec2 &zoomBlurCenter = glm::vec2(0.5f), float zoomBlurInnerRadius = 0.15f, bool posterizeEnabled = false, int posterizeLevels = 4, bool starburstEnabled = false, float starburstStrength = 0.0f, int starburstSpikes = 6, float starburstAngleOffset = 0.0f, float starburstRadius = 0.35f, const glm::vec3 &starburstTint = glm::vec3(1.0f, 0.95f, 0.85f), bool lensDistortionEnabled = false, float lensDistortionStrength = 0.0f, const glm::vec2 &lensDistortionCenter = glm::vec2(0.5f), bool underwaterEnabled = false, const glm::vec3 &underwaterTint = glm::vec3(0.30f, 0.60f, 0.85f), float underwaterCausticStrength = 0.5f, float underwaterCausticScale = 1.0f, float underwaterDepthExtinction = 1.0f, bool pixelateEnabled = false, int pixelateBlockSize = 4, bool nightVisionEnabled = false, float nightVisionStrength = 0.0f, float nightVisionGain = 2.5f, bool ditherEnabled = false, float ditherStrength = 0.004f, bool thermalEnabled = false, float thermalStrength = 0.0f, float thermalGain = 1.5f, bool scanlineEnabled = false, float scanlineStrength = 0.3f, float scanlineFrequency = 360.0f, bool letterboxEnabled = false, float letterboxAspect = 2.35f, const glm::vec3 &letterboxColor = glm::vec3(0.0f))

Apply viewer post-processing.

Parameters:

• postShader – Shader configured for DoF, FXAA, and bloom.

• fxaaEnabled – True to apply FXAA even when DoF is disabled.

void resetTemporalHistory()

Reset the temporal postprocess history before the next temporal frame.

void updateAutoExposure(float targetKey, float speed, float minFactor, float maxFactor)

Sample mean scene-color luma and lerp the auto-exposure factor.

Generates mipmaps on the post-process color attachment, reads the smallest mip back to CPU, computes mean luma, then smooths autoExposureFactor_ toward targetKey / mean. Should be called once per frame, after post-process completes. The stored factor is then applied to the next frame’s pbrExposure.

inline float autoExposureFactor() const

Smoothed auto-exposure multiplier from the previous frame.

inline void resetAutoExposure()

Reset auto-exposure to identity (no compensation).

inline bool temporalHistoryValid() const

True if a temporal history texture is available for the current render target.

inline int temporalHistoryFrameCount() const

Number of post-process frames copied into temporal history since the last reset.

void ensurePickFramebuffer()

Ensure the picking framebuffer is created.

uint32_t readPickIdAt(int x, int y) const

Read the encoded pick id at a pixel coordinate.

Parameters:

• x – X coordinate in framebuffer space.

• y – Y coordinate in framebuffer space.

Returns:

Encoded object id.

inline unsigned int getPickFbo() const

Get the picking FBO id.

Returns:

OpenGL framebuffer id.

unsigned int getFinalTexture() const

Get the final texture to display (post or debug).

Returns:

Texture id for display.

inline unsigned int getSceneColorTex() const

Get the scene color texture id.

Returns:

Color texture id.

inline unsigned int getSceneDepthTex() const

Get the scene depth texture id.

Returns:

Depth texture id.

inline unsigned int getSceneFbo() const

Get the scene framebuffer id.

inline unsigned int getLinearDepthTexture() const

Get the linear depth texture id (R32F).

Returns:

Linear depth texture id.

std::vector<RenderTargetDiagnostics> renderTargetDiagnostics() const

Return a diagnostics-only snapshot of camera-owned render targets.

void getRawImage(raisim::RGBCamera &sensor, SensorStorageMode mode = SensorStorageMode::SENSOR_SETTER, char *customBuffer = nullptr, size_t customBufferSize = 0, bool flipVertical = true) const

Read the color buffer into a raisim RGB camera or custom buffer.

Parameters:

• sensor – Raisim RGB camera to fill when using SENSOR_SETTER.

• mode – Storage mode (sensor setter or custom buffer).

• customBuffer – Optional custom buffer for raw RGBA data.

• customBufferSize – Size of custom buffer in bytes.

• flipVertical – Whether to flip rows from GL origin to image origin.

void getRawImage(raisim::DepthCamera &sensor, SensorStorageMode mode = SensorStorageMode::SENSOR_SETTER, float *customBuffer = nullptr, size_t customBufferLength = 0, bool flipVertical = true) const

Read the linear depth buffer into a raisim depth camera or custom buffer.

Parameters:

• sensor – Raisim depth camera to fill when using SENSOR_SETTER.

• mode – Storage mode (sensor setter or custom buffer).

• customBuffer – Optional custom buffer for float depth values.

• customBufferLength – Length of custom buffer in floats.

• flipVertical – Whether to flip rows from GL origin to image origin.

void setAsyncReadbackEnabled(bool enabled, size_t ringSize = 3)

Configure optional PBO-backed readback helpers.

Sensor getRawImage() remains synchronous by default. The async helpers below return the most recent completed frame and therefore may lag by one or more frames.

inline void setBackgroundColor(const glm::vec4 &c)

Set the background clear color using legacy 0..255 RGBA channels.

Prefer setBackgroundColorRgb255() in new code to make the range explicit.

Parameters:

c – RGBA color where each channel is in [0, 255].

inline void setBackgroundColorRgb255(const glm::vec4 &c)

Set the background clear color using 0..255 RGBA channels.

Parameters:

c – RGBA color where each channel is in [0, 255].

inline void setBackgroundColorLinear(const glm::vec4 &c)

Set the background clear color using linear 0..1 RGBA channels.

Parameters:

c – Linear RGBA color where each channel is in [0, 1].

inline glm::vec4 getBackgroundColor() const

Get the background clear color.

Returns:

Legacy RGBA color in [0, 255].

inline glm::vec4 getBackgroundColorLinear() const

Get the background clear color in linear 0..1 channels.

Returns:

Linear RGBA color in [0, 1].

inline void setGamma(float g)

Set gamma correction value.

Parameters:

g – Gamma value.

inline float getGamma() const

Get gamma correction value.

Returns:

Gamma value.

inline void setDOFEnabled(bool e)

Enable or disable DoF.

Parameters:

e – True to enable.

inline bool getDOFEnabled() const

Get DoF enabled state.

Returns:

True if DoF is enabled.

inline void setDOFParams(float focusDist, float focusRange, float maxRadius)

Set DoF parameters.

Parameters:

• focusDist – Focus distance.

• focusRange – Focus range around focus distance.

• maxRadius – Max blur radius.

inline void setDebugShowPick(bool e)

Toggle rendering of the pick buffer for debugging.

Parameters:

e – True to show pick buffer.

inline bool isDebugShowingPick() const

Check if the pick buffer is shown for debugging.

Returns:

True if pick buffer is displayed.

Public Members

glm::vec3 position

Camera pose and view parameters (public for quick access).

Distances are in world units (typically metres). Angles in degrees unless the field name ends in Rad. nearPlane/farPlane and zNear/zFar are aliased pairs from earlier API revisions; prefer nearPlane/farPlane in new code (the duplicate aliases will be retired).

float pitch

Degrees.

float aspect

Horizontal / vertical.

float horizontalFovRad

Radians (45°).

float farPlane

Metres.

float orthoScale

Metres of vertical view extent in ortho mode.

float zFar

Metres. Legacy aliases — prefer nearPlane/farPlane.

raisim::Object *targetObject

Current target raisim object (if any).

Public Static Functions

static void unbindFbo()

Unbind any framebuffer (bind default).

struct RenderTargetDiagnostics

class RayraiGlobalAsset

A caching asset manager for 3D models and primitive meshes.

This class loads models on demand and keeps them in memory as long as they are being used. Once all references to a model are released, its memory can be reclaimed. It also owns reusable meshes for primitives such as cubes, spheres, cylinders, and capsules.

Public Functions

RayraiGlobalAsset()

Construct the asset cache and generate primitive meshes.

~RayraiGlobalAsset()

Destroy the asset cache.

std::shared_ptr<std::vector<std::shared_ptr<OpenGLMesh>>> getMeshes(const std::string &name)

Retrieves a model’s meshes by its asset name (usually file path).

Parameters:

name – The unique identifier for the asset, typically the file path.

Returns:

A shared_ptr to a vector of OpenGLMeshes. Returns nullptr if loading fails.

std::string canonicalMeshKey(const std::string &path) const

Resolve a mesh path to the canonical key used by getMeshes() / the LOD cache. Returns “” if the path cannot be canonicalized (does not exist, etc.).

std::shared_ptr<MeshLodChain> getCachedMeshLods(const std::string &canonicalKey) const

Look up a cached automatic-LOD chain. Returns nullptr on miss.

void cacheMeshLods(const std::string &canonicalKey, const std::shared_ptr<MeshLodChain> &chain)

Register an automatic-LOD chain for a canonical source-mesh key. The cache holds weak references, so the chain stays alive only while at least one caller (typically a Visuals) keeps the returned shared_ptr.

size_t pollAsyncLoads(size_t maxAssets = 1)

Finalize any async mesh imports whose CPU-side Assimp load has completed.

This must be called on the OpenGL/render thread because it creates textures, vertex buffers, and vertex array objects. Returns the number of assets finalized.

inline size_t pendingAsyncLoadCount() const

Number of mesh file imports that have not been finalized yet.

inline void setAsyncMeshLoadingEnabled(bool enabled)

Enable or disable async mesh file import for future getMeshes() calls.

inline bool asyncMeshLoadingEnabled() const

Check whether future mesh file imports start on a worker thread.

std::shared_ptr<std::vector<std::shared_ptr<OpenGLMesh>>> getCubeMesh()

Get a unit cube mesh.

Returns:

Shared mesh list for a cube.

std::shared_ptr<std::vector<std::shared_ptr<OpenGLMesh>>> getCylinderMesh()

Get a unit cylinder mesh.

Returns:

Shared mesh list for a cylinder.

std::shared_ptr<std::vector<std::shared_ptr<OpenGLMesh>>> getCapsuleMesh()

Get a unit capsule mesh.

Returns:

Shared mesh list for a capsule.

std::shared_ptr<std::vector<std::shared_ptr<OpenGLMesh>>> getSphereMesh()

Get a unit sphere mesh.

Returns:

Shared mesh list for a sphere.

std::shared_ptr<std::vector<std::shared_ptr<OpenGLMesh>>> getPlaneMesh()

Get a unit plane mesh.

Returns:

Shared mesh list for a plane.

void setDefaultPrimitivePbrEnabled(bool enabled)

Enable High/Ultra primitive PBR defaults for shared primitive assets.

inline bool defaultPrimitivePbrEnabled() const

True when shared primitive assets currently use the High/Ultra PBR path.

Public Static Functions

static void configureDefaultPrimitivePbrMaterial(const std::shared_ptr<std::vector<std::shared_ptr<OpenGLMesh>>> &meshes, bool enabled)

Configure the default material used by built-in primitive meshes.

The material remains a PBR material, but enabled controls whether it is allowed to enter the PBR pass or forced through the cheaper simple shader.

Visuals and geometry

class Visuals

Renderable visual object not owned by raisim::World.

Visuals encapsulate geometry, transform, and appearance for custom renderable shapes or meshes.

Public Functions

Visuals(raisim::Shape::Type type, const std::string &name, const std::shared_ptr<RayraiGlobalAsset> &assets, const std::string &meshFile = "")

Construct a visual from a built-in shape or mesh file.

Parameters:

• type – Raisim shape type to render.

• name – Visual name.

• assets – Global asset cache for primitive meshes.

• meshFile – Mesh file path when type is Mesh.

Visuals(const std::string &name, const std::shared_ptr<std::vector<std::shared_ptr<OpenGLMesh>>> &meshes)

Construct a visual from custom OpenGL meshes.

Parameters:

• name – Visual name.

• meshes – Mesh list to render.

void setSphereSize(double radius)

Set sphere radius (uniform scale).

Parameters:

radius – Sphere radius.

void setBoxSize(double x, double y, double z)

Set box dimensions.

Parameters:

• x – Box size in X.

• y – Box size in Y.

• z – Box size in Z.

void setCylinderSize(double radius, double height)

Set cylinder dimensions.

Parameters:

• radius – Cylinder radius.

• height – Cylinder height.

void setCapsuleSize(double radius, double height)

Set capsule dimensions.

Parameters:

• radius – Capsule radius.

• height – Capsule height.

void setMeshScale(double x, double y, double z)

Set mesh scale factors.

Parameters:

• x – Scale in X.

• y – Scale in Y.

• z – Scale in Z.

void setDefaultPrimitivePbrEnabled(bool enabled)

Toggle High/Ultra default PBR shading for built-in primitive meshes.

void configureGroundMaterial(bool reflective, float roughness, float metallic, bool proceduralChecker = false)

Configure this visual’s mesh material as a reflective/non-reflective ground, matching RaisimObject::configureGroundMaterial. Used for ground visuals created over the TCP path which don’t go through RaisimObject.

void setPosition(double x, double y, double z)

Set position from components.

Parameters:

• x – X position.

• y – Y position.

• z – Z position.

void setPosition(const glm::vec3 &pos)

Set position from a vector.

Parameters:

pos – Position vector.

void setOrientation(double w, double x, double y, double z)

Set orientation from wxyz quaternion.

Parameters:

• w – Quaternion w.

• x – Quaternion x.

• y – Quaternion y.

• z – Quaternion z.

void setOrientation(const glm::vec4 &ori)

Set orientation from wxyz quaternion vector.

Parameters:

ori – Quaternion (w, x, y, z).

void setColor(double r, double g, double b, double a)

Set object color from components.

Parameters:

• r – Linear red channel in [0, 1].

• g – Linear green channel in [0, 1].

• b – Linear blue channel in [0, 1].

• a – Alpha channel in [0, 1].

void setColor(const glm::vec4 &color)

Set object color from vector.

Parameters:

color – Linear RGBA color in [0, 1].

inline void setUseMeshColor(bool use)

Use mesh-provided colors instead of object color.

Parameters:

use – True to use mesh colors.

inline bool usesMeshColor() const

Check if mesh colors are used.

Returns:

True if mesh colors are used.

inline void setFlatShading(bool enabled)

Force flat shading for this visual.

Parameters:

enabled – True to use flat shading.

inline bool isFlatShading() const

Check if flat shading is forced.

Returns:

True if flat shading is used.

inline void setTwoSided(bool enabled)

Disable face culling while drawing this visual.

Parameters:

enabled – True to draw both sides of mesh triangles.

inline bool isTwoSided() const

Check if face culling is disabled for this visual.

Returns:

True if both sides are drawn.

inline void setPbrEnvironment(unsigned int environmentMap, unsigned int brdfLut = 0, float strength = 1.0f)

Apply an image-based lighting environment to all PBR submeshes.

inline void setPbrEnvironment(unsigned int environmentMap, unsigned int irradianceMap, unsigned int prefilteredEnvironmentMap, unsigned int brdfLut, float strength = 1.0f, bool boxProjection = false, const glm::vec3 &probePosition = glm::vec3(0.0f), const glm::vec3 &boxMin = glm::vec3(0.0f), const glm::vec3 &boxMax = glm::vec3(0.0f))

Apply split image-based lighting maps to all PBR submeshes.

This mirrors the real-time IBL layout used by engines such as Filament: a display/environment cubemap, diffuse irradiance, prefiltered specular radiance, and a split-sum BRDF LUT. Supplying the full set gives whole-scene imported visuals the same high-fidelity path used by hand-built PBR meshes.

inline void setPbrEnvironment(const PbrEnvironment &env)

Apply a PbrEnvironment bundle to all PBR submeshes.

Convenience overload that unpacks the four texture handles and the strength scalar from a single struct, eliminating the need for callers to juggle four raw GL ids in parallel.

inline void setCategory(VisualCategory category)

Set visual category for detection or filtering.

Parameters:

category – Category value.

inline void setDetectable(bool detectable)

Convenience helper to set detectability.

Parameters:

detectable – True to mark as detectable.

inline glm::vec3 getPosition() const

Get current position.

Returns:

Position vector.

inline glm::vec4 getOrientation() const

Get current orientation as a wxyz quaternion.

inline glm::vec3 getScale() const

Get current shape or mesh scale.

inline glm::vec4 getColor() const

Get current color.

Returns:

RGBA color.

inline VisualCategory getCategory() const

Get visual category.

Returns:

Category value.

inline bool isDetectable() const

Check if visual is marked detectable.

Returns:

True if detectable.

inline void setCastsShadows(bool castsShadows)

Enable or disable rendering this visual into shadow maps.

Large receiver-only helper surfaces can keep color rendering and shadow receiving while staying out of the shadow caster pass.

inline bool castsShadows() const

Check if this visual should cast shadows.

void setVisibilityRange(float begin, float end, float beginMargin = 0.0f, float endMargin = 0.0f, VisibilityRangeFadeMode fadeMode = VisibilityRangeFadeMode::Disabled)

Set renderer-side camera visibility range.

A zero begin/end disables that side of the range. Self fade uses the margins to alpha-fade this visual near the begin/end thresholds.

void setMaterialOverride(std::shared_ptr<Material> material)

Override the visual’s draw material with a shared instance.

Ownership. The same shared_ptr<Material> may be held by any number of other visuals — setMaterialOverride does not deep-copy. Mutating the pointed-to material from any holder is observed by every visual that shares it. If you want an in-place edit that affects only this visual, call the const Material& overload (which copies into a new shared instance) or grab a fresh copy via *materialOverride() and push it back through setMaterialOverride(Material{...}).

void setMaterialOverride(const Material &material)

Override the visual’s draw material with a private copy.

Copies material into a freshly allocated shared instance so later mutations affect only this visual. Prefer this overload when the material is going to be tweaked per-visual.

inline Material *mutableMaterialOverride()

Mutable accessor for the override material.

Honest companion to setMaterialOverride(std::shared_ptr<Material>): if the material is shared with other visuals, edits made through this pointer are visible on all of them.

bool isTransparent() const

Check if visual is translucent based on alpha.

Returns:

True if alpha < 1.0.

bool hasSpecialBlendMode() const

True when at least one mesh uses a non-standard transparent blend equation.

int renderPriority() const

Highest material render priority across the visual’s meshes.

inline bool isValid() const

Check if the visual has valid mesh data.

Returns:

True if valid.

inline const std::string &getName() const

Get the visual name used by the renderer.

float approximateRadius() const

Conservative radius around getPosition() for coarse culling.

bool approximateBounds(glm::vec3 &center, float &radius) const

Conservative world-space bounds for coarse culling.

Parameters:

• center – Output sphere center.

• radius – Output sphere radius.

Returns:

True if bounds are available.

bool hasTextures() const

Check if any mesh has textures bound.

Returns:

True if a mesh has textures.

void setAutomaticMeshLodEnabled(bool enabled)

Enable automatic mesh LOD generation/selection for mesh visuals.

This affects visuals created from addVisualMesh()/addVisualCustomMesh(). Built-in primitive shapes keep their fixed authored meshes.

inline bool automaticMeshLodEnabled() const

Check whether automatic mesh LOD is enabled for this visual.

size_t automaticMeshLodLevelCount() const

Number of available mesh LOD levels including the source mesh at level 0.

size_t automaticMeshLodTriangleCount(size_t level) const

Triangle count for one mesh LOD level. Level 0 is the source mesh.

float automaticMeshLodMaxUvClusterSpan(size_t level) const

Largest UV span collapsed into one generated LOD vertex for diagnostics.

size_t selectAutomaticMeshLodLevel(const glm::vec3 &viewPos, float verticalFovDeg, int viewportHeight) const

Select the mesh LOD level that would be used for a camera.

void draw(Shader &shader, OpenGLMesh::RenderMode mode = OpenGLMesh::RenderMode::All) const

Draw the visual using a shader.

Parameters:

shader – Shader to use for drawing.

inline void drawWithBoundShader(Shader &shader, OpenGLMesh::RenderMode mode = OpenGLMesh::RenderMode::All) const

Same as draw(); assumes the caller has already bound shader.

Currently equivalent to draw() because OpenGLMesh::draw also assumes the shader is bound. Kept as an API hook for callers that opt in via drawWithBoundShader.

void draw(Shader &shader, const glm::vec3 &viewPos, float verticalFovDeg, int viewportHeight, OpenGLMesh::RenderMode mode = OpenGLMesh::RenderMode::All) const

Draw the visual using camera-aware automatic mesh LOD.

void drawSorted(Shader &shader, const glm::vec3 &viewPos, OpenGLMesh::RenderMode mode = OpenGLMesh::RenderMode::All) const

Draw submeshes back-to-front relative to a camera position.

This is intended for transparent mesh visuals. It is more expensive than draw(), so rayrai only uses it on the transparent visual path.

uint64_t materialSortKey(OpenGLMesh::RenderMode mode) const

Compact key for sorting opaque visual draws by material/texture state.

void setMeshes(const std::shared_ptr<std::vector<std::shared_ptr<OpenGLMesh>>> &meshes)

Replace mesh data for this visual.

Parameters:

meshes – New mesh list to render.

bool updateSingleMeshVertices(const std::vector<Vertex> &vertices)

Update the first mesh’s vertex buffer while preserving its index buffer.

Parameters:

vertices – New vertex data for the existing mesh.

Returns:

True when a single mesh was present and updated.

size_t applyTextureFilteringQuality(float anisotropy, float mipLodBias) const

Apply sampler quality to all 2D material textures in this visual.

Returns:

Number of unique texture ids updated.

void collectMaterialTextureIds(std::vector<unsigned int> &textureIds) const

Append non-environment material texture ids used by this visual.

void accumulateGeometryDiagnostics(OpenGLMesh::GeometryDiagnostics &diagnostics, float tinyTriangleAreaThreshold) const

Accumulate CPU-side mesh geometry diagnostics for this visual.

void collectMeshDiagnostics(std::vector<OpenGLMesh::MeshDiagnostics> &diagnostics, float tinyTriangleAreaThreshold) const

Append per-mesh geometry/material diagnostics for this visual.

class InstancedVisuals

Public Functions

InstancedVisuals(raisim::Shape::Type type, const std::string &name, const glm::vec3 &size, const glm::vec4 &color1, const glm::vec4 &color2, const std::shared_ptr<RayraiGlobalAsset> &assets, const std::string &meshFile = "")

Construct an instanced visual for repeated shapes/meshes.

Parameters:

• type – Shape type to instance.

• name – Visual name.

• size – Base size for instances.

• color1 – Primary color.

• color2 – Secondary color.

• assets – Global asset cache for primitive meshes.

• meshFile – Mesh file path when type is Mesh.

InstancedVisuals(const std::string &name, const glm::vec3 &size, const glm::vec4 &color1, const glm::vec4 &color2, const std::shared_ptr<std::vector<std::shared_ptr<OpenGLMesh>>> &meshes)

Construct an instanced visual from an already-created mesh list.

inline size_t count() const

Get number of instances.

Returns:

Instance count.

void clearInstances()

Clear all instances.

void resize(size_t count)

Resize instance storage.

Parameters:

count – New instance count.

void addInstance(const glm::vec3 &pos, const glm::vec4 &ori, const glm::vec3 &scale, float colorWeight = 0.f)

Add a fully specified instance.

Parameters:

• pos – Position.

• ori – Orientation quaternion (wxyz).

• scale – Per-instance scale.

• colorWeight – Blend between color1 and color2.

void addInstance(const glm::vec3 &pos, const glm::vec4 &ori, float colorWeight = 0.f)

Add an instance with default scale.

Parameters:

• pos – Position.

• ori – Orientation quaternion (wxyz).

• colorWeight – Blend between color1 and color2.

void addInstance(const glm::vec3 &pos, float colorWeight = 0.f)

Add an instance at position with identity orientation.

Parameters:

• pos – Position.

• colorWeight – Blend between color1 and color2.

void setPosition(size_t id, const glm::vec3 &pos)

Update position of an instance.

Parameters:

• id – Instance index.

• pos – New position.

void setOrientation(size_t id, const glm::vec4 &ori)

Update orientation of an instance.

Parameters:

• id – Instance index.

• ori – Orientation quaternion (wxyz).

void setScale(size_t id, const glm::vec3 &scale)

Update scale of an instance.

Parameters:

• id – Instance index.

• scale – New scale.

void setColor(const glm::vec4 &color1, const glm::vec4 &color2)

Update the two base colors used for blending.

Parameters:

• color1 – Primary linear RGBA color in [0, 1].

• color2 – Secondary linear RGBA color in [0, 1].

inline void setUseMeshColor(bool use)

Use mesh-authored colors for mesh instances instead of instance colors.

inline bool usesMeshColor() const

Check whether mesh-authored colors are used for mesh instances.

void setDefaultPrimitivePbrEnabled(bool enabled)

Toggle High/Ultra default PBR shading for built-in primitive meshes.

void setColorWeight(size_t id, float weight)

Set per-instance blend weight.

Parameters:

• id – Instance index.

• weight – Blend weight (0..1).

inline void setCategory(VisualCategory category)

Set visual category for detection or filtering.

Parameters:

category – Category value.

inline void setDetectable(bool detectable)

Convenience helper to set detectability.

Parameters:

detectable – True to mark as detectable.

glm::vec3 getPosition(size_t id) const

Get instance position.

Parameters:

id – Instance index.

Returns:

Position vector.

glm::vec4 getOrientation(size_t id) const

Get instance orientation (wxyz).

Parameters:

id – Instance index.

Returns:

Quaternion vector.

glm::vec3 getScale(size_t id) const

Get instance scale.

Parameters:

id – Instance index.

Returns:

Scale vector.

float getColorWeight(size_t id) const

Get per-instance color blend weight.

inline const glm::vec4 &getColor1() const

Get primary color.

Returns:

Primary color.

inline const glm::vec4 &getColor2() const

Get secondary color.

Returns:

Secondary color.

inline VisualCategory getCategory() const

Get visual category.

Returns:

Category value.

inline bool isDetectable() const

Check if visuals are marked detectable.

Returns:

True if detectable.

bool isTransparent() const

Check if any color is translucent.

Returns:

True if alpha < 1.0 for any color.

bool hasSpecialBlendMode() const

True when at least one mesh uses a non-standard transparent blend equation.

int renderPriority() const

Highest material render priority across the instanced visual’s meshes.

void setCastsShadows(bool castsShadows)

Set whether this instanced visual casts shadows.

bool castsShadows() const

Check whether this instanced visual should cast shadows.

inline bool isValid() const

Check if meshes are valid.

Returns:

True if valid.

bool approximateBounds(glm::vec3 &center, float &radius) const

Conservative bounding sphere for all instances.

Parameters:

• center – Output center.

• radius – Output radius.

Returns:

True if there are instances to bound.

inline void setMaxRenderedInstances(size_t maxInstances)

Cap drawn instances for simple single-threaded LOD. 0 means draw all.

void setRenderedInstanceStride(size_t stride)

Set a stride for simple per-camera-independent LOD. 1 draws every instance.

void setProjectedLodPolicy(bool enabled, float minProjectedRadiusPixels = 2.0f, size_t maxStride = 8)

Enable camera-projected LOD for instanced visuals.

When enabled, the renderer increases the effective draw stride for far-away instances whose approximate per-instance radius projects below minProjectedRadiusPixels. The explicit rendered stride remains a lower bound, so user-requested LOD is preserved.

void setAutomaticMeshLodEnabled(bool enabled)

Enable automatic mesh LOD generation/selection for instanced mesh visuals.

inline bool automaticMeshLodEnabled() const

Check whether automatic mesh LOD is enabled for instanced mesh visuals.

size_t automaticMeshLodLevelCount() const

Number of available instanced mesh LOD levels including the source mesh.

inline size_t sourceMeshCountForDiagnostics() const

Source mesh count for renderer regressions and diagnostics.

inline bool instanceAttributesBoundForDiagnostics() const

Whether per-instance vertex attributes are bound to the current mesh VAOs.

size_t automaticMeshLodTriangleCount(size_t level) const

Triangle count for one instanced mesh LOD level. Level 0 is the source mesh.

float automaticMeshLodMaxUvClusterSpan(size_t level) const

Largest UV span collapsed into one generated LOD vertex for diagnostics.

size_t selectAutomaticMeshLodLevel(const glm::vec3 &viewPos, float verticalFovDeg, int viewportHeight) const

Select the instanced mesh LOD level that would be used for a camera.

void configureGrassPatch(float patchWidth, float patchDepth, float densityPerSquareMeter, size_t drawBudget, float maxDrawDistance, float lodFadeStartDistance, float lodFadeEndDistance, uint32_t seed, float bladeRootHeight = 0.0f, float bladeTipHeight = 1.0f, float windStrength = 1.0f, float stiffness = 0.35f, float flutterWeight = 0.15f)

Mark this instanced visual as a grass patch and configure bounded draw/wind metadata.

Instances are still authored through addInstance()/resize() so callers keep full control over density masks and scatter placement. This method wires the batch into the generic foliage wind shader path, projected LOD, and render diagnostics.

void setDoubleBufferedInstanceUploads(bool enabled)

Enable double-buffering for full instance-buffer uploads.

Dirty-range updates remain on the single-buffer subdata path. Double-buffering helps when full rebuilds are frequent, for example after sorting or projected LOD stride changes.

inline void setSortTransparentInstances(bool enabled)

Enable optional back-to-front CPU sorting for transparent instances.

This is disabled by default to keep RL visual workloads on the fast path.

size_t applyTextureFilteringQuality(float anisotropy, float mipLodBias) const

Apply sampler quality to all 2D material textures in the instanced mesh.

Returns:

Number of unique texture ids updated.

void collectMaterialTextureIds(std::vector<unsigned int> &textureIds) const

Append non-environment material texture ids used by this instanced visual.

void accumulateGeometryDiagnostics(OpenGLMesh::GeometryDiagnostics &diagnostics, float tinyTriangleAreaThreshold) const

Accumulate CPU-side mesh geometry diagnostics for this instanced visual.

void collectMeshDiagnostics(std::vector<OpenGLMesh::MeshDiagnostics> &diagnostics, float tinyTriangleAreaThreshold) const

Append per-mesh geometry/material diagnostics for this instanced visual.

void draw(Shader &shader)

Draw all instances using instanced rendering.

Parameters:

shader – Shader to use for drawing.

void draw(Shader &shader, const glm::vec3 &viewPos, float verticalFovDeg, int viewportHeight)

Draw all instances using camera-aware projected LOD.

struct GrassPatchDiagnostics

class OpenGLMesh

Simple OpenGL mesh with indexed geometry and optional textures.

Public Functions

OpenGLMesh(const std::vector<Vertex> &vertices, const std::vector<unsigned int> &indices, const std::vector<Texture> &textures = {}, const glm::vec4 &baseColor = glm::vec4(1.0f, 1.0f, 1.0f, 1.0f), PrimitiveTopology primitiveTopology = PrimitiveTopology::Triangles)

Construct a mesh and upload it to the GPU.

Parameters:

• vertices – Vertex array.

• indices – Index array.

• textures – Optional texture list.

• baseColor – Base color used when textures are absent.

void draw(const Shader &shader) const

Draw the mesh using the provided shader.

Parameters:

shader – Shader with expected texture uniforms.

void draw(const Shader &shader, RenderMode mode, const raisin::Material *materialOverride = nullptr) const

Draw the mesh if it matches the requested material render mode.

Parameters:

• shader – Shader with expected material uniforms.

• mode – Material filter for multi-pass rendering.

• materialOverride – Optional material to use instead of the mesh material.

void drawInstanced(const Shader &shader, int instanceCount) const

Draw the mesh with instancing.

Parameters:

• shader – Shader with expected texture uniforms.

• instanceCount – Number of instances to draw.

inline void drawWithBoundShader(const Shader &shader) const

Same as draw(), but assumes the caller has already bound shader. Currently equivalent to draw() (kept as an API hook for callers that used to pay a redundant shader bind cost; preserved for callers that opt in via OpenGLMesh::drawWithBoundShader).

inline void setPrimitiveTopology(PrimitiveTopology topology)

Set the OpenGL primitive topology used by this mesh.

inline PrimitiveTopology primitiveTopology() const

Get the OpenGL primitive topology used by this mesh.

inline void setLineWidth(float width)

Set GL line width for PrimitiveTopology::Lines meshes.

inline void setPointSize(float size)

Set GL point size for PrimitiveTopology::Points meshes.

bool usesPbrShading() const

True when this mesh should be rendered by the PBR shader.

uint64_t materialSortKey(RenderMode mode = RenderMode::All, const raisin::Material *materialOverride = nullptr) const

Compact key for ordering opaque draws by material/texture state.

void updateMesh(const std::vector<Vertex> &vertices, const std::vector<unsigned int> &indices)

Update mesh data on the GPU.

Parameters:

• vertices – New vertex data.

• indices – New index data.

void updateVertices(const std::vector<Vertex> &vertices)

Update only vertex data on the GPU, keeping the existing index buffer.

Parameters:

vertices – New vertex data.

void updateVertices(const std::vector<Vertex> &vertices, bool recomputeTangents)

Update only vertex data on the GPU, optionally preserving caller-provided tangents.

Parameters:

• vertices – New vertex data.

• recomputeTangents – True to rebuild tangents from the index buffer.

bool updateVertexRange(size_t firstVertex, const Vertex *vertices, size_t count)

Update a contiguous vertex range while preserving the index buffer.

void uploadVertices(const Vertex *vertices, size_t count)

Upload vertex data without copying it into the CPU-side mesh cache.

Parameters:

• vertices – Pointer to vertex data.

• count – Number of vertices.

size_t applyTextureFilteringQuality(float anisotropy, float mipLodBias) const

Apply sampler quality to all 2D textures owned by this mesh/material.

Returns:

Number of unique texture ids updated.

void collectMaterialTextureIds(std::vector<unsigned int> &textureIds) const

Append non-environment 2D material texture ids used by this mesh.

Environment/IBL maps are renderer resources and are reported separately by RayraiWindow diagnostics.

void accumulateGeometryDiagnostics(GeometryDiagnostics &diagnostics, float tinyTriangleAreaThreshold) const

Accumulate CPU-side triangle statistics for diagnostics.

void collectMeshDiagnostics(std::vector<MeshDiagnostics> &diagnostics, float tinyTriangleAreaThreshold) const

Append per-mesh geometry/material diagnostics for structured JSON output.

inline void invalidateMaterialCache() const

Refresh cached material-derived flags after direct material edits.

Public Members

std::vector<Vertex> vertices

Vertex list for the mesh.

std::vector<unsigned int> indices

Index list for the mesh.

std::vector<Texture> textures

List of textures associated with the mesh.

glm::vec4 baseColor

Base color used when textures are not present.

raisin::Material material

Material data used by the optional PBR path.

std::string debugSourceMeshName

Source mesh name and imported primitive counts used by optional diagnostics.

unsigned int VAO

OpenGL vertex array object handle.

struct GeometryDiagnostics

struct MeshDiagnostics

namespace assimp

Functions

bool isUsdModelFile(const std::string &path)

std::future<AsyncModelLoadResult> loadModelSceneAsync(const std::string &path)

std::shared_ptr<std::vector<std::shared_ptr<OpenGLMesh>>> finishImportedModelScene(AsyncModelLoadResult &imported)

std::shared_ptr<std::vector<std::shared_ptr<OpenGLMesh>>> loadModel(const std::string &path)

std::vector<AdditionalLight> loadSceneLights(const std::string &path, float intensityScale = 1.0f)

struct AsyncModelLoadResult

#include <AssimpMeshLoader.hpp>

struct FallbackMaterial

#include <AssimpMeshLoader.hpp>

Scene helpers

class PointCloud

Simple point cloud renderer.

Stores positions and colors and uploads them to the GPU when updated.

Public Functions

PointCloud()

Construct an empty point cloud.

~PointCloud()

Destroy the point cloud and release GPU resources.

inline void setCategory(VisualCategory category)

Set the visual category for detection or filtering.

Parameters:

category – Category value.

inline void setDetectable(bool detectable)

Convenience helper to set detectability.

Parameters:

detectable – True to mark as detectable.

inline VisualCategory getCategory() const

Get current visual category.

Returns:

Category value.

inline bool isDetectable() const

Check if point cloud is detectable.

Returns:

True if detectable.

void updatePointBuffer()

Upload point data to the GPU (or clear if empty).

void updatePointPositionsBuffer()

Streaming variant for point clouds whose colors stay unchanged. Updates bounds + position VBO only and reuses the initialized color buffer.

void updatePointRange(size_t begin, size_t count)

Upload a changed point range without reallocating the whole buffer when possible.

void draw(Camera &camera, Shader &shader)

Draw the point cloud.

Parameters:

• camera – Active camera (unused but kept for consistency).

• shader – Shader to use for drawing.

bool approximateBounds(glm::vec3 &center, float &radius) const

Conservative bounding sphere for all points.

inline void setMaxRenderedPoints(size_t maxPoints)

Cap drawn points for simple single-threaded LOD. 0 means draw all.

void setRenderedPointStride(size_t stride)

Draw every Nth point for cheap point-cloud LOD. 1 draws contiguous points.

inline void enable(bool enable)

Enable or disable rendering.

Parameters:

enable – True to enable.

inline void notifyDataChanged()

Bump the render revision after a direct mutation of positions or colors.

setCategory(), enable(), setMaxRenderedPoints() already bump the revision themselves; this method is for the public positions / colors vectors, which the setter pattern does not cover.

Public Members

std::vector<glm::vec3> positions

Point positions in world space.

std::vector<glm::vec4> colors

Per-point colors (must match positions size).

float pointSize

Rendered point size in pixels.

class CoordinateFrame

Render helper for visualizing multiple coordinate frames.

Public Functions

CoordinateFrame(std::shared_ptr<RayraiGlobalAsset> &asset)

Construct a coordinate frame visualizer.

Parameters:

asset – Shared asset cache for retrieving the axis mesh.

void draw(Shader &shader)

Draws all coordinate frames in the ‘poses’ vector.

Parameters:

shader – The shader program to use for rendering.

void draw(Shader &shader, const glm::mat4 &viewProjection, bool boundShader)

Variant that also frustum-culls poses against viewProjection and assumes the caller has already bound shader.

inline void enable(bool enable)

Enables or disables rendering of this coordinate frame set.

Parameters:

enable – True to enable, false to disable.

Public Members

std::vector<Pose> poses

List of poses to render.

double frameSize

Scale factor for axis length.

struct Pose

Pose definition for a single coordinate frame.

position is in world units (typically metres). quaternion is a glm unit quaternion using glm’s (w, x, y, z) component order.

class CameraFrustum

Visual helper that renders a camera frustum volume.

The frustum mesh is updated from either a rayrai Camera or a raisim DepthCamera and rendered using a Visuals instance.

Public Functions

CameraFrustum(std::shared_ptr<Visuals> visual, std::shared_ptr<OpenGLMesh> mesh)

Construct a frustum helper with a visual and mesh.

Parameters:

• visual – Visuals object used for rendering.

• mesh – OpenGL mesh representing the frustum volume.

void updateFromCamera(const Camera &camera)

Update frustum mesh from a rayrai camera.

Parameters:

camera – Source camera.

void updateFromDepthCamera(raisim::DepthCamera &depthCam)

Update frustum mesh from a raisim depth camera.

Parameters:

depthCam – Source depth camera.

void setColor(const glm::vec4 &color)

Set the frustum color.

Parameters:

color – RGBA color.

void setDetectable(bool detectable)

Set detectability flag on the frustum visual.

Parameters:

detectable – True to mark as detectable.

inline std::shared_ptr<Visuals> getVisual() const

Get the underlying Visuals object.

Returns:

Shared pointer to the visual.

enum class raisin::VisualCategory

Category tag for visuals and point clouds.

Values:

enumerator NotDetectable

enumerator Detectable

Rendering and materials

class Light

Simple light with optional shadow map support.

Supports directional and point lighting models and owns the shadow-map framebuffer used by the renderer.

Public Functions

inline Light()

Default constructor creates a directional light and shadow resources.

inline void setAsDirectional(const glm::vec3 &dir, const glm::vec3 &diffColor = {0.85f, 0.85f, 0.85f})

Configure as a directional light.

Parameters:

• dir – Direction pointing from the light toward the scene.

• diffColor – Diffuse color.

inline void setAsPoint(const glm::vec3 &pos, const glm::vec3 &diffColor = {0.85f, 0.85f, 0.85f})

Configure as a point light.

Parameters:

• pos – Light position.

• diffColor – Diffuse color.

inline void setSpotAngles(float innerDeg, float outerDeg)

Set the spotlight cone half-angles in degrees.

Convenience wrapper around the raw cosine fields. The inner cone is the fully-lit region; intensity falls off smoothly between innerDeg and outerDeg. Pass any values; they are clamped so that innerDeg <= outerDeg.

Parameters:

• innerDeg – Half-angle in degrees where falloff begins.

• outerDeg – Half-angle in degrees where light reaches zero.

inline void setRange(float rangeMeters)

Set point-light range in metres by computing reasonable attenuation.

Picks an inverse-quadratic falloff such that intensity drops to ~1% at the requested radius. Use this instead of writing constant/linear/ quadratic by hand. Sets radius to the requested value as a culling hint.

Parameters:

rangeMeters – Distance at which the light contribution becomes negligible.

bool ensureShadowFramebuffer()

Create or resize the shadow framebuffer and depth texture.

bool shadowPrePass()

Prepare for shadow depth rendering (bind FBO, set viewport).

bool pointShadowPrePassFace(int face)

Prepare one face of a point-light cubemap shadow render.

Parameters:

face – Cubemap face index in OpenGL order [0, 5].

void shadowPostPass()

Restore state after shadow rendering.

void setShadowResolution(int res)

Set shadow-map resolution.

Parameters:

res – Shadow map size in pixels.

inline void setShadowsEnabled(bool e)

Enable or disable shadow sampling.

Parameters:

e – True to enable shadows.

inline void setShadowParams(float bias, float strength, float pcfRadius)

Set shadow bias and filtering parameters.

Parameters:

• bias – Depth bias to reduce acne.

• strength – Shadow darkening strength.

• pcfRadius – PCF sampling radius.

inline void setShadowOrtho(float halfSize, float zNear, float zFar)

Configure orthographic shadow projection for directional lights.

Parameters:

• halfSize – Half-size of the ortho box.

• zNear – Near plane.

• zFar – Far plane.

inline void setShadowCenter(const glm::vec3 &center)

Set the center point used for directional shadow projection.

Parameters:

center – World-space center.

inline void setShadowPosition(const glm::vec3 &pos, bool enable = true)

Override the light position used for directional shadow projection.

Parameters:

• pos – World-space light position.

• enable – True to use the custom position, false to revert to auto position.

Public Members

LightType type

Active light type.

glm::vec3 ambient

Ambient, diffuse, and specular color terms.

glm::vec3 position

Light position (point lights only).

glm::vec3 direction

Light direction (directional lights only).

float constant

Attenuation parameters for point lights.

Standard inverse-quadratic falloff: intensity / (constant + linear*r + quadratic*r²) where r is in metres. Use setRange() for a more ergonomic alternative.

float spotInnerCos

Cosine of the inner spotlight cone half-angle (use setSpotAngles() to set in degrees).

float spotOuterCos

Cosine of the outer spotlight cone half-angle (use setSpotAngles() to set in degrees).

float radius

Light bound radius in metres; 0 = no clip.

glm::vec2 areaSize

Area-light extents in metres.

float temperatureKelvin

Kelvin.

float distanceFadeBegin

Metres from camera.

float distanceFadeShadow

Metres from camera.

float distanceFadeLength

Metres of fade band.

unsigned int shadowFbo_

Shadow framebuffer and depth texture identifiers.

class Material

A general-purpose material class supporting PBR, textured, and simple color models.

This class uses a unified PBR model. Simpler material types are emulated by setting PBR properties to default values (e.g., metallic=0, roughness=0.8 for a dielectric).

Public Types

enum class Type

Defines the user-facing type of material for easier configuration. The shader itself will always use the PBR rendering path.

Values:

enumerator SIMPLE_COLOR

Basic diffuse material with a solid color.

enumerator TEXTURED

A simple textured material (uses albedoMap).

enumerator PBR

Full PBR material with metallic/roughness properties.

enum class NormalMapConvention

Tangent-space normal-map convention.

Values:

enumerator OpenGL

+Y/green-up normal maps.

enumerator DirectX

-Y/green-down normal maps, common in Unreal assets.

enum class AlphaMode

glTF-style alpha handling for imported materials.

Values:

enumerator Opaque

enumerator Mask

enumerator Hash

enumerator Blend

enum class BlendMode

Godot-style transparent compositing mode.

Values:

enumerator Mix

enumerator Add

enumerator Subtract

enumerator Multiply

enumerator PremultipliedAlpha

enum class AlphaAntiAliasing

Godot-style alpha-edge smoothing for masked materials.

Values:

enumerator Off

enumerator AlphaToCoverage

enumerator AlphaToCoverageAndToOne

enum class DistanceFadeMode

Godot-style distance fade behavior.

Values:

enumerator Disabled

enumerator PixelAlpha

enumerator PixelDither

enumerator ObjectDither

enum class DiffuseMode

Godot-style direct diffuse BRDF mode.

Values:

enumerator Burley

enumerator Lambert

enumerator LambertWrap

enumerator Toon

enum class SpecularMode

Godot-style direct specular BRDF mode.

Values:

enumerator SchlickGgx

enumerator Toon

enumerator Disabled

enum class ShadingModel

Higher-level shading-model selection.

Collapses the three orthogonal DiffuseMode / SpecularMode / unlit controls that the underlying material exposes for fine-grained control into the small set of choices most callers actually want. Use setShadingModel() to write the corresponding low-level fields and shadingModel() to read back a best-effort classification.

Values:

enumerator Standard

Burley diffuse + GGX specular (default PBR look).

enumerator Lambert

Lambert diffuse + GGX specular (cheaper PBR).

enumerator Toon

Toon diffuse + Toon specular (stylized).

enumerator Unlit

Skip lighting entirely; emissive-style flat color.

enum class DetailBlendMode

Detail albedo compositing mode.

Values:

enumerator SoftMultiply

enumerator Mix

enumerator Add

enumerator Subtract

enumerator Multiply

enum class TextureChannel

Godot-style channel selector for scalar texture maps.

Values:

enumerator Red

enumerator Green

enumerator Blue

enumerator Alpha

enumerator Gray

enum class DepthState

Optional per-material OpenGL depth-state override.

Inherit keeps the current render-pass state, which is the default and preserves existing Fast/Ultra behavior. Enabled/Disabled are explicit material-level overrides for decals, overlays, special transparent surfaces, and authored inspection assets.

Values:

enumerator Inherit

enumerator Enabled

enumerator Disabled

enumerator Inverted

enum class StencilCompare

Godot-style stencil comparison operator.

Values:

enumerator Always

enumerator Less

enumerator Equal

enumerator LessOrEqual

enumerator Greater

enumerator NotEqual

enumerator GreaterOrEqual

enum class CullMode

Per-material face-culling mode.

Values:

enumerator Back

enumerator Front

enumerator Disabled

enum class TextureRepeatMode

Shader-side material texture repeat override.

Values:

enumerator Inherit

enumerator Repeat

enumerator Disabled

enumerator Mirror

enum class TextureFilter

Godot-style per-material texture filtering mode.

Inherit preserves the texture object’s current sampler state. The remaining modes explicitly apply nearest/linear and optional mipmap/anisotropic filtering.

Values:

enumerator Inherit

enumerator Nearest

enumerator Linear

enumerator NearestWithMipmaps

enumerator LinearWithMipmaps

enumerator NearestWithMipmapsAnisotropic

enumerator LinearWithMipmapsAnisotropic

enum class EmissionOperator

Godot-style emission texture compositing operator.

Values:

enumerator Add

enumerator Multiply

enum class BillboardMode

Camera-facing material billboard mode.

FixedZ is the z-up equivalent of Godot’s fixed-Y billboard mode.

Values:

enumerator Disabled

enumerator Enabled

enumerator FixedZ

enumerator Particles

enum class UvLayer

Detail/material secondary UV selector.

Values:

enumerator Uv1

enumerator Uv2

enum class FoliageType

Viewer-side foliage classification for wind deformation and diagnostics.

Values:

enumerator None

enumerator Grass

enumerator LeafCard

enumerator Bush

enumerator Branch

enumerator TreeTrunk

enumerator Crop

enumerator Vine

Public Functions

Material(std::string name = "DefaultMaterial")

Construct a new Material object.

Parameters:

name – A unique name for the material.

void applyTo(Shader &shader) const

Applies the material’s properties to a shader.

This method binds the necessary textures and sets all material-related uniforms on the provided shader before a draw call.

Parameters:

shader – The shader to which the properties will be applied.

inline void setShadingModel(ShadingModel model)

Write diffuseMode, specularMode, and unlit from a high-level model.

Helper for the common case where callers want “PBR/Lambert/Toon/Unlit” rather than picking a DiffuseMode + SpecularMode pair and remembering to clear the unlit flag.

inline ShadingModel shadingModel() const

Read back a best-effort high-level shading model classification.

Returns Unlit when the unlit flag is set, otherwise picks the closest Standard/Lambert/Toon based on the current diffuseMode / specularMode. Mixed combinations (e.g. Lambert+Toon) fall back to Lambert.

inline AlphaSettings alphaSettings() const

Bundle the three alpha-related enums into a single struct view.

The returned struct is a snapshot; round-trip it via setAlphaSettings() to write back into the underlying fields.

inline void setAlphaSettings(const AlphaSettings &s)

Write alphaMode, blendMode, alphaAntialiasing from one struct.

bool usesPbrShading() const

True when this material needs the PBR shader path.

bool canUseCorePbr() const

True when this material can be drawn by the compact core PBR shader without losing authored features.

bool requiresHighFidelityPbr() const

True when this material benefits from the high-fidelity PBR shader when that mode is enabled.

bool needsTransparentPass() const

True when this material must be sorted and rendered by the transparent pass.

inline bool hasDepthTestOverride() const

True when this material explicitly overrides the current depth-test state.

inline bool hasDepthWriteOverride() const

True when this material explicitly overrides the current depth-write state.

inline bool usesInvertedDepthTest() const

True when this material wants an inverted depth comparison.

inline bool hasStencilOverride() const

True when this material explicitly configures stencil state.

inline bool resolveDepthTest(bool passDefault) const

Resolve material depth-test override against a render-pass default.

inline bool resolveDepthWrite(bool passDefault) const

Resolve material depth-write override against a render-pass default.

inline bool usesTwoSidedLighting() const

True when back-facing fragments should use two-sided lighting.

Public Members

std::string name

Material name used for debugging or lookup.

Type type

Material type hint (PBR path is always used in shaders).

bool forceSimpleShading

Force this material through the simple mesh shader even when PBR fields are set.

glm::vec4 baseColorFactor

Base color factor (albedo tint).

This is the base color if no texture is used, or a tint factor otherwise.

bool useVertexColorAsAlbedo

Multiply base albedo and opacity by mesh vertex colors.

bool vertexColorIsSrgb

Decode vertex color RGB from sRGB before applying it as albedo.

float textureBlendFactor

Strength for blending textureBlendMap over the base albedo. The blend map alpha is the mask.

float metallicFactor

Metallic factor (0 for dielectric, 1 for metal).

float roughnessFactor

Roughness factor (0 smooth, 1 rough).

float ao

Ambient occlusion strength.

glm::vec3 emissiveFactor

Emissive color factor in linear RGB.

float iblStrength

Strength of the simple procedural image-based lighting approximation.

float environmentMapStrength

Blend amount for the optional environment cubemap.

bool environmentBoxProjection

Enable box-projected parallax correction for local reflection probes.

glm::vec3 environmentProbePosition

Local reflection probe capture position in world space.

glm::vec3 environmentBoxMin

World-space minimum corner of the box-projected reflection volume.

glm::vec3 environmentBoxMax

World-space maximum corner of the box-projected reflection volume.

float normalStrength

Strength of tangent-space normal-map perturbation.

float normalMapYScale

Tangent-space normal-map Y scale. Use -1 for DirectX-style normal maps.

float bentNormalStrength

Strength for bent-normal ambient/specular-occlusion direction.

NormalMapConvention normalMapConvention

Named normal-map convention. This is applied before normalMapYScale.

AlphaMode alphaMode

Material alpha mode. Masked and fully transparent texels discard before depth writes.

BlendMode blendMode

Transparent compositing mode used when the material is drawn in the transparent pass.

int renderPriority

Godot-style render priority. Higher priority transparent materials draw later.

std::shared_ptr<Material> nextPass

Optional Godot-style material pass rendered immediately after this material.

The renderer walks a small bounded chain of next passes. This is intended for outline shells, X-ray overlays, and other lightweight multi-pass material effects.

float alphaCutoff

Alpha cutoff used for masked materials.

float alphaHashScale

Alpha-hash noise scale. Higher values create finer dither.

AlphaAntiAliasing alphaAntialiasing

Smooth alpha-tested edges. The shader approximates coverage when MSAA is unavailable.

float alphaAntialiasingEdge

Width of the smoothed alpha-test edge.

DistanceFadeMode distanceFadeMode

Distance fade mode for Godot-style material fade-out.

float distanceFadeMin

Distance where fade-out starts.

float distanceFadeMax

Distance where fade-out reaches zero visibility.

bool proximityFadeEnabled

Fade transparent pixels as they approach already-rendered opaque geometry.

float proximityFadeDistance

View-space distance over which proximity fade reaches full opacity.

float aoStrength

Ambient-occlusion texture strength. 0 ignores the AO map, 1 uses it fully.

float aoLightAffect

Godot-style amount of ambient occlusion applied to direct lighting.

0 keeps AO on indirect/ambient light only, 1 also attenuates direct lights.

float emissiveStrength

Multiplier for emissive texture/factor contribution.

EmissionOperator emissionOperator

Combine emissiveFactor and emissiveMap by addition or multiplication.

float specularFactor

glTF-style dielectric specular strength multiplier.

glm::vec3 specularColorFactor

glTF-style dielectric specular color multiplier.

DiffuseMode diffuseMode

Direct diffuse BRDF selector. Lambert preserves RayRai’s legacy default.

SpecularMode specularMode

Direct specular BRDF selector.

float ior

Index of refraction used to derive dielectric F0.

float transmissionFactor

glTF-style transmission strength for thin glass/plastic approximation.

float refractionFactor

Godot-style screen refraction strength independent of physical transmission.

float volumeThicknessFactor

glTF-style volume thickness used for tinted transmission attenuation.

float volumeAttenuationDistance

Distance over which volume attenuation reaches the authored color.

glm::vec3 volumeAttenuationColor

Tinted volume attenuation color for thick glass approximation.

float subsurfaceScatteringStrength

Godot-style subsurface scattering strength.

glm::vec3 subsurfaceTransmittanceColor

Tint for subsurface transmittance through thin/soft materials.

float subsurfaceTransmittanceDepth

Approximate material depth used to damp subsurface transmittance.

float subsurfaceTransmittanceBoost

Extra gain for subsurface transmittance from back-facing light.

bool subsurfaceSkinMode

Use a Godot-style skin diffusion profile for subsurface transmittance.

glm::vec3 backlightColor

Additive backlight tint for thin materials.

TextureChannel metallicTextureChannel

Channel sampled from metallicMap.

TextureChannel roughnessTextureChannel

Channel sampled from roughnessMap.

TextureChannel aoTextureChannel

Channel sampled from aoMap.

TextureChannel refractionTextureChannel

Channel sampled from transmission/refraction map.

glm::vec4 uvScaleOffset

UV transform as scale.xy and offset.zw.

float uvRotation

UV rotation in radians.

glm::vec4 uv2ScaleOffset

Secondary UV transform as scale.xy and offset.zw.

float uv2Rotation

Secondary UV rotation in radians.

TextureRepeatMode textureRepeatMode

Shader-side repeat behavior for material texture coordinates.

TextureFilter textureFilter

Explicit sampler filtering mode for all 2D textures used by this material.

float textureFilterAnisotropy

Requested anisotropy level for anisotropic textureFilter modes.

bool albedoTextureForceSrgb

Decode albedo texture samples as sRGB in shader for linear-format authored maps.

bool albedoTextureMsdf

Interpret the albedo texture as a multi-channel signed-distance field.

float msdfPixelRange

Source-pixel distance range encoded by the albedo MSDF texture.

float msdfOutlineSize

Optional MSDF outline expansion in source pixels.

BillboardMode billboardMode

Rotate the rendered material geometry toward the active camera.

bool billboardKeepScale

Preserve the model scale when billboardMode is enabled.

int particlesAnimHFrames

Horizontal frame count for Godot-style particle atlas animation.

When billboardMode is Particles, UV1 is remapped into the selected atlas cell.

int particlesAnimVFrames

Vertical frame count for Godot-style particle atlas animation.

bool particlesAnimLoop

Wrap particle atlas frame progress instead of clamping at the last frame.

float particlesAnimFrameProgress

Normalized atlas animation progress. Godot sources this from INSTANCE_CUSTOM.z.

bool particleTrailsEnabled

Stretch particle billboards into renderer-side trail quads.

Godot’s particle trail render mode is driven by particle history buffers. RayRai exposes the renderer-side deformation directly so callers can author trail visuals without an engine particle system.

float particleTrailLength

Extra tail length in world/local units for particle trail billboards.

float particleTrailTaper

Tail width multiplier. Values below one taper the trail toward the end.

glm::vec3 particleTrailWorldDirection

Optional world-space trail direction. Zero uses the billboard’s local down axis.

bool fixedSize

Scale the material by camera depth so its apparent size stays stable.

float fixedSizeScale

Multiplier for fixed-size material scaling.

bool usePointSize

Render GL point primitives with an authored material point size.

float pointSize

Material point size in screen pixels for point primitive meshes.

bool useZClipScale

Apply Godot-style clip-space Z compression toward the near plane.

float zClipScale

Clip-space Z scale. Values below 1 pull the material toward the near plane.

bool useFovOverride

Override the apparent camera FOV for this material in degrees.

float fovOverrideDegrees

Vertical FOV used when useFovOverride is enabled.

bool triplanarEnabled

Project primary material textures from three axes instead of mesh UVs.

This matches Godot-style triplanar materials for terrain, rocks, walls, and procedural assets where ordinary UVs would stretch or create visible seams.

bool triplanarWorldSpace

Use world-space coordinates for triplanar projection. False uses local mesh space.

glm::vec3 triplanarScale

Triplanar projection scale along local/world XYZ.

glm::vec3 triplanarOffset

Triplanar projection offset along local/world XYZ.

float triplanarSharpness

Blend sharpness for triplanar axis weights. Godot clamps this to 0..150.

bool uv2TriplanarEnabled

Triplanar projection for textures that explicitly use secondary UVs.

bool uv2TriplanarWorldSpace

Use world-space coordinates for UV2 triplanar projection.

glm::vec3 uv2TriplanarScale

UV2 triplanar projection scale along local/world XYZ.

glm::vec3 uv2TriplanarOffset

UV2 triplanar projection offset along local/world XYZ.

float uv2TriplanarSharpness

UV2 triplanar blend sharpness.

std::array<UvTransform, static_cast<size_t>(TextureSlot::Count)> textureUvTransforms

Authored UV transforms per texture slot.

glTF KHR_texture_transform belongs to each textureInfo. The material-wide uvScaleOffset/uvRotation fields remain as fallback for legacy/simple paths.

float clearcoatFactor

Optional clearcoat layer strength.

float clearcoatRoughnessFactor

Optional clearcoat roughness.

float iridescenceFactor

Thin-film iridescence strength (0..1). Adds soap-bubble/oil-slick rainbow shift to the Fresnel highlight. Combine with iridescenceThickness to control which wavelengths constructively interfere.

float iridescenceThickness

Thin-film thickness in nm. Typical soap bubble ~400nm; oil film 200..600nm; insect wings ~300nm.

float sheenFactor

Optional cloth/fabric sheen strength.

glm::vec3 sheenColorFactor

Optional cloth/fabric sheen color.

float sheenRoughnessFactor

Optional cloth/fabric sheen roughness.

float anisotropyFactor

Optional anisotropic specular strength for brushed materials.

float anisotropyRotation

Tangent-frame anisotropy rotation in radians.

bool unlit

Render base color without scene lighting, for glTF KHR_materials_unlit.

bool proceduralGroundChecker

Use an analytically filtered world-space checker for default ground.

bool usePlanarReflection

Whether this material samples the renderer’s planar reflection texture.

float planarReflectionStrength

Blend strength for planar reflections on this material.

bool dontReceiveShadows

Godot-style flag that skips shadow attenuation on this material.

bool disableAmbientLight

Godot-style flag that disables ambient and image-based lighting.

bool disableFog

Godot-style flag that disables fog compositing for this material.

bool disableSpecularOcclusion

Godot-style flag that keeps ambient specular from being occluded.

bool shadowToOpacity

Godot-style flag that converts received shadow into material opacity.

bool doubleSided

Disable back-face culling for this material.

CullMode cullMode

Explicit material culling mode. Disabled matches Godot’s cull_disabled mode.

bool thinTwoSidedLighting

Use generic two-sided lighting for thin non-foliage surfaces.

This is separate from doubleSided: doubleSided controls culling, while this controls diffuse/back-light response for paper, curtains, decals-on-cards, and thin shells.

float thinBackDiffuseScale

Back-side diffuse contribution scale for generic thin-surface lighting.

float thinTransmissionStrength

Thin-surface backlight/transmission strength for non-foliage materials.

glm::vec3 thinTransmissionColor

Tint for generic thin-surface transmitted light.

FoliageType foliageType

Explicit foliage category. None disables foliage-specific rendering behavior.

float foliageWindStrength

Per-material wind response multiplier for viewer-side foliage animation.

float foliageRootHeight

Local-space height where foliage deformation starts. Vertices below this stay rooted.

float foliageTipHeight

Local-space height where foliage deformation reaches full strength.

float foliageStiffness

Per-material stiffness multiplier. Higher values reduce wind deformation.

float foliageFlutterWeight

High-frequency leaf/card flutter multiplier.

bool foliageTwoSidedLighting

Use foliage-specific two-sided diffuse lighting for thin leaves/cards.

float foliageTransmissionStrength

Thin-leaf backlight/transmission strength for viewer PBR foliage materials.

glm::vec3 foliageTransmissionColor

Tint for thin-leaf transmitted light.

bool foliageWeatherResponse

Allow weather wetness/snow load to alter foliage color, roughness, and wind damping.

float foliageWetResponse

Per-material rain/wetness response multiplier for foliage.

float foliageSnowResponse

Per-material snow accumulation/load response multiplier for foliage.

bool weatherAffectsWetness

Allow the runtime weather layer to darken/lower roughness for rain wetness.

bool weatherAffectsSnow

Allow the runtime weather layer to accumulate snow on this material.

float weatherPorosity

Relative porous weather response. 0 disables absorption; 1 is the default.

bool weatherPuddleEligible

Allow flat/up-facing areas of this material to receive procedural puddle masks.

bool weatherSnowEligible

Allow this material to receive snow accumulation after slope/opacity filtering.

float rimFactor

View-dependent rim-light strength, matching Godot-style material rim.

float rimTint

Blend between neutral rim light and rimColor/texture tint.

float rimPower

Rim falloff exponent. Higher values keep the rim closer to the silhouette.

glm::vec3 rimColor

Authored rim-light tint color.

bool growEnabled

Extrude vertices along their local normals before rendering this material.

float growAmount

Local-space grow extrusion distance.

float heightmapScale

Height-map parallax scale. Values follow Godot’s percent-style convention.

bool heightmapDeepParallax

Enable iterative parallax occlusion sampling instead of a single offset sample.

int heightmapMinLayers

Minimum layer count for deep parallax at near-facing views.

int heightmapMaxLayers

Maximum layer count for deep parallax at grazing views.

glm::vec2 heightmapFlip

Tangent/binormal direction flips for assets authored with inverted height-map axes.

bool heightmapInvert

Invert sampled height-map values before parallax displacement.

float detailAlbedoBlend

Blend amount for detail albedo texture.

UvLayer detailUvLayer

UV layer used by detail mask, detail albedo, and detail normal maps.

DetailBlendMode detailAlbedoBlendMode

Detail albedo compositing mode. SoftMultiply preserves RayRai’s legacy detail look.

float detailNormalStrength

Strength for detail tangent-space normal map.

bool aoUsesUv2

Sample the ambient-occlusion texture from secondary UVs.

bool emissiveUsesUv2

Sample the emissive texture from secondary UVs.

bool lightmapUsesUv2

Sample the baked lightmap texture from secondary UVs.

float lightmapStrength

Baked diffuse-indirect lightmap strength.

glm::vec3 lightmapTint

Optional tint/multiplier for baked lightmap texels.

bool decalDepthBias

Render after ordinary opaque surfaces with decal-style depth handling.

bool tinySurfaceDetail

Very small albedo-only imported surface detail such as book covers.

DepthState depthTest

Optional override for whether this material participates in depth testing.

DepthState depthWrite

Optional override for whether this material writes to the active depth buffer.

int stencilReference

Stencil reference value. Negative disables per-material stencil state.

bool stencilRead

Compare existing stencil values against stencilReference before drawing.

bool stencilWrite

Replace stencil values with stencilReference when depth and stencil tests pass.

bool stencilWriteDepthFail

Replace stencil values with stencilReference when the stencil test passes but depth fails.

StencilCompare stencilCompare

Stencil comparison operator used when stencilRead is enabled.

unsigned int stencilMask

Bit mask used for stencil reads and writes.

StencilEffectMode stencilEffectMode

Godot-style automatic stencil effect. Custom uses the raw stencil fields above.

glm::vec4 stencilEffectColor

Overlay color for automatic stencil outline and X-ray effects.

float stencilOutlineThickness

Normal-direction expansion used by stencil outline mode.

unsigned int albedoMap

Base color texture (OpenGL id, 0 if unused).

unsigned int textureBlendMap

Optional second base-color texture. RGB is the layer color, alpha is the blend mask.

unsigned int terrainSplatAlbedoMap

Optional secondary albedo layer used by terrain splat blending.

unsigned int terrainSplatControlMap

Optional control texture (R = primary-vs-secondary weight) for terrain splat blending.

float terrainSplatPrimaryUvScale

World-space UV tiling rate (1/metres) for the primary albedo layer.

float terrainSplatSecondaryUvScale

World-space UV tiling rate (1/metres) for the secondary albedo layer.

glm::vec4 terrainSplatControlBounds

Control-map bounds in world space (x, y, sizeX, sizeY) used to sample the splat control texture.

bool hasTerrainSplat

When true the splat blending path runs; false keeps the existing single-layer behaviour.

unsigned int normalMap

Tangent-space normal map (OpenGL id, 0 if unused).

unsigned int bentNormalMap

Optional bent normal map for ambient/specular occlusion direction.

unsigned int metallicMap

Metallic map (OpenGL id, 0 if unused).

unsigned int roughnessMap

Roughness map (OpenGL id, 0 if unused).

unsigned int metallicRoughnessMap

Combined glTF metallic-roughness map (G=roughness, B=metallic, 0 if unused).

unsigned int ormMap

Godot-style ORM map (R=ambient occlusion, G=roughness, B=metallic).

Uses the metallicRoughness UV transform because it shares the same sampler path in the PBR shader.

unsigned int aoMap

Ambient occlusion map (OpenGL id, 0 if unused).

unsigned int emissiveMap

Emissive color texture (OpenGL id, 0 if unused).

unsigned int clearcoatMap

Optional clearcoat intensity texture, red channel.

unsigned int clearcoatRoughnessMap

Optional clearcoat roughness texture, red channel.

unsigned int clearcoatNormalMap

Optional clearcoat tangent-space normal texture.

unsigned int sheenColorMap

Optional sheen color texture, RGB channels.

unsigned int sheenRoughnessMap

Optional sheen roughness texture.

unsigned int transmissionMap

Optional transmission texture, red channel.

unsigned int refractionMap

Optional screen refraction texture.

unsigned int thicknessMap

Optional volume thickness texture.

unsigned int subsurfaceMap

Optional subsurface scattering strength texture.

unsigned int subsurfaceTransmittanceMap

Optional subsurface transmittance color texture.

unsigned int backlightMap

Optional backlight color texture.

unsigned int anisotropyMap

Optional anisotropy texture.

Red and green encode the tangent-frame highlight direction. By default blue scales strength for glTF KHR_materials_anisotropy; enable anisotropyMapAlphaStrength for Godot-style flow maps that store strength in alpha.

unsigned int weatherMaskMap

Optional weather response mask. Red channel scales wetness, green channel scales snow.

unsigned int rimMap

Optional rim mask/tint texture. Red masks rim strength, green tints toward rimColor.

unsigned int heightMap

Optional height map for tangent-space parallax offset.

unsigned int detailMaskMap

Optional detail mask. Red channel controls detail albedo/normal blend.

unsigned int detailAlbedoMap

Optional detail albedo texture.

unsigned int detailNormalMap

Optional detail tangent-space normal texture.

unsigned int lightmapMap

Optional baked diffuse-indirect lightmap.

unsigned int environmentMap

Optional radiance/environment cubemap (OpenGL cubemap id, 0 if unused).

unsigned int irradianceMap

Optional diffuse irradiance cubemap for high-fidelity IBL.

unsigned int prefilteredEnvironmentMap

Optional prefiltered specular cubemap for high-fidelity IBL.

unsigned int brdfLut

Optional split-sum BRDF LUT texture for high-fidelity IBL.

std::string importReport

Human-readable import notes for debugging material differences.

Public Static Functions

static Material pbr(std::string name, const glm::vec4 &baseColor, float metallic = 0.0f, float roughness = 0.5f)

Build a metallic/roughness PBR material with sensible defaults.

Sets type = Type::PBR, the albedo tint, metallic, and roughness factors; leaves all texture slots empty. Provide an IBL environment separately via Visuals::setPbrEnvironment(...) if you want indirect lighting.

static Material unlitColor(std::string name, const glm::vec4 &color = glm::vec4(1.0f))

Build an unlit material that ignores scene lighting.

Useful for HUD elements, debug visuals, holograms, light-emitting decals. Named unlitColor rather than unlit to avoid colliding with the bool unlit data member.

static Material simpleColor(std::string name, const glm::vec4 &color)

Build a simple-color (non-PBR) material that responds to lighting.

Routes through the simple mesh shader. Cheaper than pbr() and appropriate for primitives that do not need metallic/roughness or IBL.

static Material foliage(std::string name, FoliageType foliageKind, const glm::vec4 &baseColor)

Build a foliage material with the given type and base color.

Configures wind/foliage behavior with engine defaults and enables two-sided lighting (foliage cards usually need it).

static Material defaultGround(std::string name = "GroundMaterial")

Build a neutral PBR ground material (mid-grey, rough, non-metallic).

Convenient default for the world’s ground plane / heightmap when no authored material is supplied.

static const std::array<TextureBindingInfo, 32> &textureBindingTable()

Stable material sampler binding table used by Material::applyTo().

static const TextureSlotInfo &textureSlotInfo(TextureSlot slot)

Look up metadata for a texture slot by enum.

Returns:

Metadata describing the slot. Count is invalid and returns a zeroed entry.

struct AlphaSettings

Grouped alpha-handling configuration.

Bundles the three orthogonal alpha-related enums that otherwise live as flat fields. The struct stores references back into the material’s own fields so writes are visible to the existing apply pipeline without an additional sync step.

struct FoliageSettings

Grouped foliage wind/weather authoring fields.

Wraps the ~12 foliage* fields scattered through the flat layout. Read with foliageSettings(), write back with setFoliageSettings().

struct ParallaxSettings

Grouped tangent-space heightmap / parallax controls.

Wraps the heightmap* fields. scale == 0 keeps parallax disabled regardless of deepParallax.

struct TextureBindingInfo

struct TextureSlotInfo

Static per-slot metadata for the TextureSlot enum.

Bundles the data that would otherwise live as parallel tables in Material.cpp: human-facing name, whether the slot carries sRGB color (so loaders pick the right internal format), and whether the slot is tracked in textureUvTransforms[] so callers can iterate slots without a hardcoded list.

struct UvTransform

struct RenderQualitySettings

Explicit runtime quality settings for viewer rendering.

The struct stores its fields as a flat layout for historical reasons (the shader-side uniform glue treats it as a memcpy-friendly POD). For authoring, new code should prefer the grouped sub-config accessors — shadows(), bloom(), depthOfField(), fog(), toneMapping(), temporalAa() — and the matching set*() writers. They mirror the intended grouping documented in review2.md §6 without breaking the 300+ existing call sites that touch the flat fields directly.

Use RenderQualitySettings::preset(RenderQualityPreset) to start from a known-good configuration.

Public Functions

inline ShadowsSettings shadows() const

Read a snapshot of the shadows sub-config from the flat fields.

inline void setShadows(const ShadowsSettings &s)

Write the shadows sub-config back into the flat fields.

Public Static Functions

static RenderQualitySettings preset(RenderQualityPreset p)

Build a RenderQualitySettings for the given preset.

Companion to the existing RenderQualityPreset enum so the type that names the presets can also produce them. Delegates to RayraiWindow::defaultRenderQualitySettings() defined in RayraiWindow.cpp.

struct BloomSettings

Bloom / glow controls.

struct DepthOfFieldSettings

Depth-of-field controls.

struct FogSettings

Distance / height / volumetric fog controls.

struct ShadowsSettings

Directional / additional / point shadow controls.

struct TemporalAaSettings

Temporal antialiasing controls.

struct ToneMappingSettings

Tone-mapping + color-grade controls.

struct RenderOverrides

Override shaders and rendering toggles when using external cameras.

Public Members

Shader *mesh

Mesh shader override (defaults to shaders_[“mesh”]).

Shader *pointcloud

Point cloud shader override (defaults to shaders_[“pointcloud”]).

Shader *picking

Picking shader override (defaults to shaders_[“picking”]).

Shader *post

Post-process shader override (defaults to shaders_[“post”]).

bool doShadows

Enable shadow passes.

bool drawCoordinateFrames

Draw coordinate frames.

bool drawPointClouds

Draw point clouds.

bool drawVisualizationObjects

Draw visualization-only custom visuals and instanced visuals.

bool drawWeatherEffects

Draw viewer-only weather effects such as precipitation particles.

bool skipGroundObjects

Skip halfspace and heightmap ground objects in scene-color rendering.

unsigned int environmentBackgroundMap

Optional cubemap rendered as a viewer background before scene geometry.

float environmentBackgroundExposure

Exposure applied to environmentBackgroundMap when rendered as background.

bool postProcess

Apply external-camera postprocessing after rendering.

bool allowViewerMsaa

Allow quality preset MSAA for this external render. Sensor overloads force this off.

bool allowTemporalAa

Allow quality preset temporal AA for this external render. Sensor overloads force this off.

bool allowViewerUpscale

Allow quality preset lower-resolution viewer rendering followed by upscale.

enum class raisin::RenderQualityPreset

Viewer-quality policy presets.

These presets affect interactive viewer rendering only. They do not change sensor world-object filtering or make sensor outputs include viewer-only visuals.

Values:

enumerator Fast

enumerator Balanced

enumerator High

enumerator Ultra

enumerator Custom

enum class raisin::ViewerColorMode

Values:

enumerator FastLinear

enumerator AcesApprox

enumerator UnrealPreviewApprox

enumerator FilmicApprox

enumerator AgXApprox

enum class raisin::ColorGradePreset

Values:

enumerator Neutral

enumerator Warm

enumerator Cool

enumerator Cinematic

enumerator Bleach

enum class raisin::PostProcessDebugMode

Values:

enumerator Final

enumerator BloomSource

enumerator AmbientOcclusion

enumerator AmbientOcclusionRaw

enumerator FogTransmittance

enumerator FogDensity

enumerator FogScattering

enumerator WorldNormal

enumerator DepthHeatmap

enumerator ScreenSpaceIndirectLighting

Weather, scene effects, and reflections

struct WeatherSettings

Weather state applied on top of the renderer.

Many fields overlap with RenderQualitySettings (fog density, wetness, volumetrics). The current contract is: WeatherSettings is the runtime source of truth for atmospheric state; when enabled = true, the renderer reads weather fields and ignores the corresponding RenderQualitySettings fields for that frame. When enabled = false, RenderQualitySettings applies. See review2.md §9.

Numeric fields are in metres, degrees, hours, or normalized [0,1] ranges as documented per-field.

Public Members

float timeOfDayHours

Hours, [0, 24).

float latitude

Degrees.

float longitude

Degrees.

float windSpeed

Metres / second.

float transitionSeconds

Seconds.

float cloudCoverage

Normalized [0, 1].

float cloudDensity

Normalized [0, 1].

float precipitationRate

Millimetres / hour, conceptual.

float rainOcclusionStrength

Normalized [0, 1].

float fogDensity

Exponential extinction; metres^-1.

float visibilityMeters

Metres.

float fogAnisotropy

Henyey-Greenstein g in [-1, 1].

float humidity

Normalized [0, 1].

float wetness

Normalized [0, 1].

float wetnessAccumulationRate

Per second.

float wetnessDryingRate

Per second.

enum class raisin::WeatherPreset

Values:

enumerator Clear

enumerator Hazy

enumerator Overcast

enumerator Fog

enumerator Rain

enumerator HeavyRain

enumerator Snow

enumerator Storm

enumerator NightClear

enumerator NightRain

enumerator Custom

struct LocalFogVolume

Public Members

float density

Signed density. Positive values add local fog; negative values carve clearer regions from global/local fog in a bounded postprocess approximation.

struct ProjectedDecal

struct IrradianceVolume

struct ReflectionProbe

struct ReflectionProbeCaptureSettings

Explicit static reflection-probe capture settings.

Probe capture is never automatic. Applications call captureReflectionProbeCubemap() when they want a bounded real-time local reflection approximation.

struct ReflectionProbeFilterSettings

Explicit CPU filtering settings for captured local reflection probes.

Filtering is a load-time/manual Ultra operation. Fast/Balanced do not allocate or run this unless the application calls captureFilteredReflectionProbe().

struct ReflectionProbeBlend

struct ReflectionProbePlacementSuggestion

Render quality, weather, capture, reflection-probe, and diagnostics helpers are exposed through raisin::RayraiWindow and the public headers included by rayrai/RayraiWindow.hpp. The sections above document the intended entry points and the fast-path boundaries for those APIs.

RaiSim integration

class RaisimObject

Render wrapper for a raisim::Object.

RaisimObject caches meshes and per-shape scales for a raisim object and exposes a draw method that respects appearance and collision-visual toggles.

Public Functions

explicit RaisimObject(raisim::Object *object, RayraiWindow *parent, std::shared_ptr<RayraiGlobalAsset> asset)

Construct a render wrapper for a raisim object.

Parameters:

• object – Raisim object to wrap.

• parent – Owning RayraiWindow (for shared assets/settings).

• asset – Asset cache to load primitive/mesh geometry.

void draw(Shader &shader, bool showCollisionBodies, OpenGLMesh::RenderMode mode = OpenGLMesh::RenderMode::All, uint64_t renderSerial = 0)

Draw the object using the provided shader.

Parameters:

• shader – Shader used for rendering.

• showCollisionBodies – True to render collision geometry when available.

bool hasPbrMeshes() const

True when any cached mesh needs the PBR shader.

bool hasTransparentMaterials() const

True when any cached mesh material must be rendered in the transparent pass.

bool hasSpecialBlendMode() const

True when any cached mesh uses a non-standard transparent blend equation.

int renderPriority() const

Highest material render priority across cached meshes.

bool isSelectable() const

Check if this object can be selected in the picker.

Returns:

True if selectable.

inline bool isValid() const

True when this wrapper still references a live raisim::Object.

RaisimObject does not own the underlying raisim object; if the world it came from is destroyed or the object removed, the cached pointer becomes dangling. Public mutators (updateAppearance, updateHeightMapVisual, configureGroundMaterial) early-return when isValid() is false so callers don’t have to track lifetime themselves. Clear the underlying pointer via invalidate() when the source object is removed.

inline void invalidate()

Mark this wrapper as no longer referencing a live raisim::Object.

Subsequent calls to mutators become no-ops. The owning RayraiWindow uses this when the world is reset or an object is removed.

bool updateAppearance()

Refresh appearance (color) from the underlying raisim object.

bool updateHeightMapVisual()

Refresh a heightmap object’s existing mesh vertices without rebuilding its mesh.

void configureGroundMaterial(bool reflective, float roughness, float metallic, bool proceduralChecker = false)

Configure ground and heightmap terrain materials. No-op for other objects.

inline void setHidden(const bool h)

Hide or show this object in rendering.

Parameters:

h – True to hide.

inline bool hidden() const

Check if object is hidden.

Returns:

True if hidden.

inline glm::vec4 getColor() const

Get object color used for rendering.

Returns:

RGBA color.

float approximateRadius(bool showCollisionBodies) const

Conservative radius around the raisim object position for coarse culling.

bool approximateBounds(bool showCollisionBodies, glm::vec3 &center, float &radius) const

Conservative world-space bounds for coarse culling.

The center is allowed to differ from the raisim object origin for offset meshes, articulated links, and deformables.

bool getPrimitiveBatchData(bool showCollisionBodies, glm::mat4 &model, raisim::Shape::Type &shape, glm::vec4 &color) const

Return transform/color data for simple single-body primitive batching.

Returns:

True when this object can be drawn by the internal primitive batch path.

void setDefaultPrimitivePbrEnabled(bool enabled)

Toggle High/Ultra default PBR shading for built-in primitive meshes.

void collectMaterialTextureIds(std::vector<unsigned int> &textureIds) const

Append non-environment material texture ids used by this object’s cached meshes.

void accumulateGeometryDiagnostics(OpenGLMesh::GeometryDiagnostics &diagnostics, float tinyTriangleAreaThreshold) const

Accumulate CPU-side mesh geometry diagnostics for this object.

void collectMeshDiagnostics(std::vector<OpenGLMesh::MeshDiagnostics> &diagnostics, float tinyTriangleAreaThreshold) const

Append per-mesh geometry/material diagnostics for this object.