raisin::RayraiWindow

class · #include <rayrai/RayraiWindow.hpp>

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.

Quick start

cpp

auto world = std::make_shared<raisim::World>();
world->addSphere(0.5, 1.0);

// A GL context must be current first, e.g.:
//   SDL_Window* win; SDL_GLContext ctx;
//   raisin::RayraiWindow::createOffscreenGlContext(win, ctx);
raisin::RayraiWindow renderer(world, 1280, 720);

// Add a free-standing visual using the glm::vec4 colour overload.
renderer.addVisualSphere("marker", 0.25, glm::vec4(1.0f, 0.0f, 0.0f, 1.0f));

// (Optional) IBL: one struct instead of four GL handles.
auto env = raisin::PbrEnvironment::loadFromHdrFile("studio.hdr");

// Drive the simulation and render one frame.
world->integrate();
renderer.update(1280, 720, false, 0, 0, false);
unsigned int textureId = renderer.getImageTexture();

Lifetime

The shared_ptr constructor stores the pointer, so the window shares ownership of the world and keeps it alive. The raisim::World& constructor wraps the reference in a non-owning shared_ptr; that world must outlive the window (or be replaced with swapWorld() before it is destroyed).

GL context

Construction, rendering, resource creation (textures, cubemaps, probes) and destruction issue OpenGL calls, so they must run on the thread that has this renderer's GL context current (see createOffscreenGlContext()). The pure-CPU helpers (e.g. analyzeRgbaLuminance(), recommendExposure(), loadReflectionProbeSidecar()) do not touch GL.

Error model

Named entities are strict: addVisual*(), addInstancedVisuals(), addPointCloud() and addCoordinateFrame() abort (RSFATAL) when the name is already in use, and getVisualObject(), getInstancedVisuals(), removeVisualObject(), removeInstancedVisuals(), removePointCloud() and removeCoordinateFrame() abort when it does not exist. Use findVisualObject() / findInstancedVisuals() for a lookup that returns nullptr instead. A few newer entry points throw std::invalid_argument instead of aborting; this is noted on each of them.

The texture and cubemap loaders (loadTextureWithTiling(), loadHdrEquirectangularCubemap(), ...) return 0 on failure.

Threading-mode mismatch at construction is fatal (RSFATAL).

Nested classes

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 ConservativeOcclusionCullingDiagnostics — Diagnostics: occlusion-culling counters of the last scene color pass (see conservativeOcclusionCullingDiagnostics()).
struct DebugPassCapture — One pass returned by captureDebugPasses().
struct DirectionalShadowCascade — One cascade of DirectionalShadowCascadePlan. Depths are view distances in metres.
struct DirectionalShadowCascadePlan — Result of planDirectionalShadowCascades().
struct DynamicQualityRecommendation — Result of recommendDynamicQuality(); GPU times are summed from the input timings by pass name.
struct EnvironmentBackgroundDiagnostics — How the last scene pass drew its environment background (see renderMeshes).
struct EnvironmentSidecarSettings — Contents of a .rayrai_environment.json sidecar (see loadEnvironmentSidecar()).
struct ExposureRecommendation — Result of recommendExposure(); the target/limit fields echo the inputs.
struct ExternalFrameCache — Internal: reuse key of the last externally rendered frame (see invalidateExternalFrameCache()).
struct FoliageRenderDiagnostics — Diagnostics: foliage and instanced-draw counters (see foliageRenderDiagnostics()).
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 — Result of recommendMaterialTextureBudget(). Byte counts are estimates from GL texture sizes.
struct ReflectionProbe — A captured local reflection probe (see captureFilteredReflectionProbe(), addReflectionProbe()).
struct ReflectionProbeBlend — Result of selectReflectionProbeBlend(): up to two probes and their normalized weights.
struct ReflectionProbeCaptureFrame — Camera basis used to render one reflection-probe cubemap face.
struct ReflectionProbeCaptureSettings — Explicit static reflection-probe capture settings.
struct ReflectionProbeDebugItem — Per-probe entry of ReflectionProbeDebugView.
struct ReflectionProbeDebugOverlaySummary — Result of reflectionProbeDebugOverlaySummary(); blend fields mirror ReflectionProbeBlend.
struct ReflectionProbeDebugView — Result of reflectionProbeDebugView().
struct ReflectionProbeFilterSettings — Explicit CPU filtering settings for captured local reflection probes.
struct ReflectionProbePlacementSuggestion — Result of suggestReflectionProbePlacementFromSceneBounds().
struct ReflectionProbeSidecarLoadResult — Result bundle for the struct-returning loadReflectionProbeSidecar overload.
struct ReflectionProbeSidecarProbe — One probe entry parsed from a .rayrai_probes.json sidecar (see loadReflectionProbeSidecar()).
struct ReflectionProbeSidecarSettings — Optional quality block of a reflection-probe sidecar; each hasX flag says whether X was present.
struct RenderOverrides — Override shaders and rendering toggles when using external cameras.
struct RenderPassAccounting — Estimated per-frame pass counts from estimateRenderPassAccounting() (no rendering involved).
struct RenderPassTiming — GPU time of one render pass (see captureRenderPassTimings()).
struct RgbaCalibrationMetrics — Result of analyzeRgbaCalibrationPatches(); averages cover valid patches only.
struct RgbaCalibrationPatch — A rectangular reference patch for analyzeRgbaCalibrationPatches().
struct RgbaCalibrationPatchResult — Per-patch measurement inside RgbaCalibrationMetrics.
struct RgbaCalibrationRecommendation — Result of recommendCalibrationOutputTransform().
struct RgbaLuminanceHistogram — Display-space luminance histogram returned by analyzeRgbaLuminanceHistogram().
struct RgbaLuminanceMetrics — Display-space luminance statistics returned by analyzeRgbaLuminance().
struct RgbaOutputTransform — CPU output transform for screenshots (see transformRgbaForOutput()).
struct SceneImportReport — What importVisualScene() loaded.
struct ShaderWarmupDiagnostics — Result of shaderWarmupDiagnostics().
struct ShadowAtlasPlan — Result of planAdditionalShadowAtlas().
struct ShadowAtlasTile — One tile of ShadowAtlasPlan. Pixel coordinates are in atlas texels.
struct ShadowCacheDiagnostics — Diagnostics: shadow-map caching counters (see shadowCacheDiagnostics()).
struct ShadowDebugOverlaySummary — Result of shadowDebugOverlaySummary(); combines settings, the current plans and last-frame state.
struct StaticSceneLayerCache — Internal: cached render of static scene content reused under dynamic objects.
struct SupersampledCapture — Result of captureSupersampledRgba().
class SynchronousMeshLoadingScope — Loads the mesh files requested while it lives synchronously, without finishing the other pending work.
struct TransparentDrawDebugView — Diagnostics: transparent rendering state and estimated overdraw (see transparentDrawDebugView()).
struct TransparentDrawItem — One transparent draw in TransparentDrawDebugView::backToFrontOrder.
class VisualMeshBuilder — Fluent builder for addVisualMesh.
struct WeatherSidecarSettings — Contents of a .rayrai_weather.json sidecar (see loadWeatherSidecar()).

Public types

Type and limit aliases

Re-exports of namespace-level rayrai types (RenderQuality.hpp, Weather.hpp, SceneEffects.hpp) so they can be spelled RayraiWindow::X. See the aliased type for its documentation.

AdditionalLight

cpp

using AdditionalLight = ::raisin::AdditionalLight

Alias of raisin::AdditionalLight (see addAdditionalLight()).

RenderQualityPreset

cpp

using RenderQualityPreset = ::raisin::RenderQualityPreset

Alias of raisin::RenderQualityPreset (see setRenderQualityPreset()).

ViewerColorMode

cpp

using ViewerColorMode = ::raisin::ViewerColorMode

Alias of raisin::ViewerColorMode.

ColorGradePreset

cpp

using ColorGradePreset = ::raisin::ColorGradePreset

Alias of raisin::ColorGradePreset.

GlowBlendMode

cpp

using GlowBlendMode = ::raisin::GlowBlendMode

Alias of raisin::GlowBlendMode (bloom composite mode).

ViewerUpscaleFilter

cpp

using ViewerUpscaleFilter = ::raisin::ViewerUpscaleFilter

Alias of raisin::ViewerUpscaleFilter.

PostProcessDebugMode

cpp

using PostProcessDebugMode = ::raisin::PostProcessDebugMode

Alias of raisin::PostProcessDebugMode.

PointShadowPolicy

cpp

using PointShadowPolicy = ::raisin::PointShadowPolicy

Alias of raisin::PointShadowPolicy.

RenderQualitySettings

cpp

using RenderQualitySettings = ::raisin::RenderQualitySettings

Alias of raisin::RenderQualitySettings (see setRenderQualitySettings()).

WeatherPreset

cpp

using WeatherPreset = ::raisin::WeatherPreset

Alias of raisin::WeatherPreset (see setWeatherPreset()).

WeatherQuality

cpp

using WeatherQuality = ::raisin::WeatherQuality

Alias of raisin::WeatherQuality.

LocalFogVolume

cpp

using LocalFogVolume = ::raisin::LocalFogVolume

Alias of raisin::LocalFogVolume (see addLocalFogVolume()).

WeatherSettings

cpp

using WeatherSettings = ::raisin::WeatherSettings

Alias of raisin::WeatherSettings (see setWeatherSettings()).

WeatherDiagnostics

cpp

using WeatherDiagnostics = ::raisin::WeatherDiagnostics

Alias of raisin::WeatherDiagnostics (see weatherDiagnostics()).

WeatherSkyEnvironment

cpp

using WeatherSkyEnvironment = ::raisin::WeatherSkyEnvironment

Alias of raisin::WeatherSkyEnvironment (see generateWeatherSkyEnvironment()).

ProjectedDecal

cpp

using ProjectedDecal = ::raisin::ProjectedDecal

Alias of raisin::ProjectedDecal (see addProjectedDecal()).

IrradianceVolume

cpp

using IrradianceVolume = ::raisin::IrradianceVolume

Alias of raisin::IrradianceVolume (see addIrradianceVolume()).

Weather

While WeatherSettings::enabled is true, the resolved weather is applied on top of the last settings passed to setRenderQualitySettings(): main light, ambient, sky, clouds and wet/snow materials are overwritten and fog is combined with the user values (see raisin::WeatherSettings). Disabling weather restores the user settings; getUserRenderQualitySettings() returns them meanwhile. Transitions and wetness advance only in updateWeather().

WeatherThunderCallback

cpp

using WeatherThunderCallback = std::function<void(const WeatherDiagnostics &)>

Callback invoked from updateWeather() once per new lightning event.

ThreadingMode

cpp

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. Render state is owned by the window or the calling thread.

MultiThread is for RL / batch-render setups that spawn one RayraiWindow per worker thread, each with its own offscreen GL context. State that would otherwise need synchronization is owned by the object it describes — a resolved uniform location by its Shader, GL context state by the renderer driving that context — rather than kept per-thread, so handing a context between threads does not strand it. Shared resources (immutable mesh templates and shader compilation) are coordinated. File textures and mutable material state are local to each worker/context.

This is instance confinement, not concurrent access to one window. Construct, render, read back, edit, and destroy a renderer on its owning worker with its GL context current. Do not integrate or mutate its World on another thread while rendering. Prefer an independent World per worker. Keep application supplied mutable materials, cameras, visuals and GPU objects worker-local. Create/destroy SDL windows on the main thread and hand their contexts to workers with makeOffscreenContextCurrent after detaching them on the main thread. All renderers in the process, including prewarmers, must use this mode.

What workers share and what they duplicate: immutable mesh geometry is shared between contexts in one GL share group, so a model imported by one worker costs no second vertex/index upload. Textures are not: rayrai retunes filtering and anisotropy on the texture object itself, per material and per render-quality preset, so a shared texture would let one worker's settings rewrite another's. Each worker therefore decodes and uploads its own copy of every image, and a textured model's geometry is not shared either. Lifting that needs filtering to move off the texture object onto GL sampler objects bound per texture unit.

Rendering draws a copy of the World's render state (a PhysicsSnapshot), never the World itself. A render call (update(), renderWithExternalCamera(), renderDepthPlaneDistance(), ...) first copies the bound World (updateObjectLists()); the shadow maps and the image then come from that copy. An application that steps or edits the World on another thread must keep that thread out of the copy, for example by holding the World's mutex (raisim::World is lockable) for the render call. Reading the image back into an application buffer (Camera::getRawImage() with SensorStorageMode::CUSTOM_BUFFER) does not read the World and can follow after the lock is released. For independent physics and camera threads, capture a PhysicsSnapshot on the physics thread immediately after integration, then applyPhysicsSnapshot() on the render thread: render calls then never read a World. Snapshot capture performs no GL work and must not wait for a render mutex. The overloads that take a raisim sensor and the GPU lidar read the live World, so they are refused while an applied snapshot is shown.

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

Enumerator	Value	Description
`SingleThread`	`0`	One renderer per process, driven from one thread (default).
`MultiThread`	`1`	One renderer per worker thread, each with its own GL context.

Constructors & destructor

RayraiWindow

cpp

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.

Requires a current OpenGL context on the calling thread (see createOffscreenGlContext()); built-in shaders are registered here and the viewer render targets are allocated lazily on first render.

A world built from a RaiSim Engine scene (World::getRscene(): a .rscene file, or a RaiSim XML world file that includes one) is shown with that scene: the constructor applies it (see RsceneVisuals.hpp for the render settings and the created visuals). Its meshes load like any others, asynchronously by default (see setAsyncMeshLoadingEnabled() and pendingAsyncMeshLoadCount()), and so does an HDR background: it appears once a decode worker has resampled it. Settings changed afterwards (camera, render quality) override the scene's. A scene rayrai cannot show, for example one with a missing texture, is a RaiSim fatal error.

Parameters

Parameter	Description
`world`	Shared world pointer used for pulling object state. The window keeps this `shared_ptr`, i.e. it shares ownership.
`width`	Initial render target width in pixels.
`height`	Initial render target height in pixels.
`threadingMode`	Concurrency contract — see ThreadingMode. Must match every other RayraiWindow in the process (`RSFATAL` otherwise).
`shaderCompileThreadCount`	Driver-side shader compile threads (passed to `glMaxShaderCompilerThreadsARB`); 0 is treated as 1. Defaults to 1 to match rayrai's overall single-threaded default; raise this only when the host application explicitly opts into multi-threading. This is a process-wide setting shared by all renderers.
`shaderBinaryCacheEnabled`	When true, compiled shader programs are persisted under `shaderBinaryCacheDirectory` and reused on next run, skipping driver compile entirely for unchanged GLSL/driver. Process-wide, like the two parameters below.
`shaderBinaryCacheDirectory`	Explicit cache directory. Empty selects the first writable per-user cache directory: `LOCALAPPDATA%/RaiSim/rayrai` on Windows, `$XDG_CACHE_HOME/raisim/rayrai`, `~/Library/Caches/raisim/rayrai` (macOS) or `~/.cache/raisim/rayrai`, then `~/.raisim/rayrai`, then the system temp directory.
`logShaderBinaryCache`	When true, cache hits/misses/stores are logged to stderr — useful when verifying that the cache is actually being consulted.

cpp

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 (non-owning).

Same as the shared_ptr overload, but world is wrapped with a no-op deleter: the caller keeps ownership and the world must outlive this window (or be replaced with swapWorld() first).

Parameters

Parameter	Description
`world`	World reference used for pulling object state.
`width`	Initial render target width in pixels.
`height`	Initial render target height in pixels.
`threadingMode`	Concurrency contract — see ThreadingMode.
`shaderCompileThreadCount`	Process-wide driver shader compile threads.
`shaderBinaryCacheEnabled`	Enable the process-wide shader binary cache.
`shaderBinaryCacheDirectory`	Explicit cache directory; empty selects the default per-user cache directory.
`logShaderBinaryCache`	Log cache hits/misses/stores to stderr.

~RayraiWindow

cpp

~RayraiWindow()

Releases GL resources owned by this renderer; call with its GL context current.

Public member functions

Weather

setWeatherSettings

cpp

void setWeatherSettings(const WeatherSettings &settings)

Apply weather settings immediately.

Values are clamped to their valid ranges, any running transition is cancelled, a generated weather sky environment is released, and the render quality settings are updated (see the group description).

Parameters

Parameter	Description
`settings`	New weather settings.

getWeatherSettings

cpp

const WeatherSettings &getWeatherSettings() const

Returns Current (clamped) weather settings; mid-transition this is the blended state.

setWeatherThunderCallback

cpp

void setWeatherThunderCallback(WeatherThunderCallback callback)

Called synchronously on the thread that calls updateWeather(), with the diagnostics of the frame in which a new lightning event started.

Parameters

Parameter	Description
`callback`	Callback to store.

setWeatherPreset

cpp

void setWeatherPreset(WeatherPreset preset)

Apply defaultWeatherSettings(preset) immediately.

Parameters

Parameter	Description
`preset`	Preset to apply.

transitionWeather

cpp

void transitionWeather(WeatherPreset preset, double transitionSeconds)

Blend from the current weather to a preset's defaults over time.

Parameters

Parameter	Description
`preset`	Target preset.
`transitionSeconds`	Duration; <= 0 applies the target immediately.

cpp

void transitionWeather(
    const WeatherSettings &target,
    double transitionSeconds)

Blend from the current weather to target over time.

The blend advances only in updateWeather().

Parameters

Parameter	Description
`target`	Target settings.
`transitionSeconds`	Duration in seconds; <= 0 applies the target immediately.

updateWeather

cpp

void updateWeather(double dt)

Advance weather transitions, wetness accumulation/drying and lightning.

Call once per frame from the render thread before rendering.

Parameters

Parameter	Description
`dt`	Elapsed time in seconds (negative values are treated as 0).

weatherDiagnostics

cpp

WeatherDiagnostics weatherDiagnostics() const

Resolved weather state (sun/moon, clouds, fog, precipitation, wetness, lightning). CPU only.

Returns Diagnostics for the current settings.

printWeatherDiagnostics

cpp

void printWeatherDiagnostics(std::ostream &out) const

Print weatherDiagnostics() in a human-readable multi-line form.

Parameters

Parameter	Description
`out`	Output stream.

generateWeatherSkyEnvironment

cpp

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. The previous generated environment is released first; the textures are owned by the renderer and are also released by clearWeatherSkyEnvironment() and setWeatherSettings(). Requires this renderer's GL context.

Parameters

Parameter	Description
`environmentFaceSize`	Radiance cubemap face size, clamped to [16, 2048].
`irradianceFaceSize`	Irradiance cubemap face size, clamped to [0, 256]; 0 skips it.
`setVisibleBackground`	Install the radiance map as the visible background.

Returns The generated environment (also available via weatherSkyEnvironment()).

clearWeatherSkyEnvironment

cpp

void clearWeatherSkyEnvironment()

Delete the generated weather sky textures; unsets the visible background if it was installed.

weatherSkyEnvironment

cpp

const WeatherSkyEnvironment &weatherSkyEnvironment() const

Returns Last generated weather sky environment (valid false when none).

Ground and heightmap terrain textures

Textures applied to every halfspace (ground) and heightmap in the world. The public texture ids are written by the setters below; prefer the setters over assigning the ids directly, since they also refresh texture filtering and the terrain materials. Loading requires a current GL context.

setHeightmapPatternResourcePath

cpp

void setHeightmapPatternResourcePath(const std::string &path)

Set a tiled albedo texture for all heightmaps.

Parameters

Parameter	Description
`path`	Path to the texture image, or empty to clear.

getHeightmapPatternResourcePath

cpp

std::string getHeightmapPatternResourcePath() const

Returns Path passed to setHeightmapPatternResourcePath(), empty when cleared.

setHeightmapNormalResourcePath

cpp

void setHeightmapNormalResourcePath(const std::string &path)

Set a tiled normal map (linear) for all heightmaps.

Parameters

Parameter	Description
`path`	Path to the texture image, or empty to clear.

getHeightmapNormalResourcePath

cpp

std::string getHeightmapNormalResourcePath() const

Returns Path passed to setHeightmapNormalResourcePath(), empty when cleared.

setHeightmapHeightResourcePath

cpp

void setHeightmapHeightResourcePath(const std::string &path)

Set a tiled height map (linear) used for parallax on all heightmaps.

Parameters

Parameter	Description
`path`	Path to the texture image, or empty to clear.

getHeightmapHeightResourcePath

cpp

std::string getHeightmapHeightResourcePath() const

Returns Path passed to setHeightmapHeightResourcePath(), empty when cleared.

setHeightmapTerrainMaterialParameters

cpp

void setHeightmapTerrainMaterialParameters(
    float normalStrength,
    float roughness,
    float parallaxScale,
    bool deepParallax=true)

Set heightmap terrain material parameters.

Parameters

Parameter	Description
`normalStrength`	Normal-map strength (default 1; negative acts as 0). Used only with a normal map.
`roughness`	PBR roughness (default 0.9), clamped to [0.04, 1] when applied.
`parallaxScale`	Parallax height scale (default 4). Used only with a height map.
`deepParallax`	Use layered (deep) parallax mapping. Used only with a height map.

getHeightmapTerrainNormalStrength

cpp

float getHeightmapTerrainNormalStrength() const

Returns Normal strength set by setHeightmapTerrainMaterialParameters().

getHeightmapTerrainRoughness

cpp

float getHeightmapTerrainRoughness() const

Returns Roughness set by setHeightmapTerrainMaterialParameters() (unclamped).

getHeightmapTerrainDeepParallax

cpp

bool getHeightmapTerrainDeepParallax() const

Returns Deep-parallax flag set by setHeightmapTerrainMaterialParameters().

getHeightmapTerrainParallaxScale

cpp

float getHeightmapTerrainParallaxScale() const

Returns Parallax scale set by setHeightmapTerrainMaterialParameters().

setHeightmapSplatLayer

cpp

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. Blending only happens when a primary albedo (setHeightmapPatternResourcePath()) is set as well.

Parameters

Parameter	Description
`albedoPath`	Secondary albedo image (sRGB); reloaded only when the path changes.
`controlTexId`	Single-channel control texture (e.g. from updateSingleChannelTexture()); its red channel is the secondary weight (0 = primary only, 1 = secondary only). Not owned. All coordinates below are world XY of the terrain as if it were unrotated (its translation applied, its orientation ignored), like raisim::HeightMap::getHeight(); for a rotated heightmap the layer therefore turns with the terrain.
`primaryUvScale`	Primary albedo tiling: UV = world XY * scale (default 0.25).
`secondaryUvScale`	Secondary albedo tiling: UV = world XY * scale (default 0.25).
`controlBounds`	World XY rectangle covered by the control texture as (minX, minY, sizeX, sizeY) in metres; outside it the edge value is used.

clearHeightmapSplatLayer

cpp

void clearHeightmapSplatLayer()

Disable splat blending and forget the secondary albedo (the control texture is not deleted).

getHeightmapSplatAlbedoId

cpp

unsigned int getHeightmapSplatAlbedoId() const

Returns Secondary splat albedo texture id, 0 when unset.

getHeightmapSplatControlId

cpp

unsigned int getHeightmapSplatControlId() const

Returns Splat control texture id, 0 when unset.

getHeightmapSplatPrimaryUvScale

cpp

float getHeightmapSplatPrimaryUvScale() const

Returns Primary albedo UV scale used with splatting.

getHeightmapSplatSecondaryUvScale

cpp

float getHeightmapSplatSecondaryUvScale() const

Returns Secondary albedo UV scale used with splatting.

getHeightmapSplatControlBounds

cpp

glm::vec4 getHeightmapSplatControlBounds() const

Returns Control texture bounds (minX, minY, sizeX, sizeY).

hasHeightmapTerrainTextures

cpp

bool hasHeightmapTerrainTextures() const

Returns True when a heightmap albedo, normal or height texture, or a splat layer, is set.

applyHeightmapTerrainTextures

cpp

void applyHeightmapTerrainTextures(OpenGLMesh &mesh) const

Give a heightmap mesh the terrain textures and material set above, as world heightmaps get them. The mesh's texture coordinates must tile every 4 m of world XY, like those of world heightmaps; the TCP viewer builds its heightmaps that way while terrain textures are set.

Parameters

Parameter	Description
`mesh`	Heightmap mesh; its textures and material are replaced.

Local fog volumes, projected decals and irradiance volumes

Scene-effect lists rendered by the PBR path. Each add*() copies and sanitizes its argument (e.g. clamps strengths and fades, orthonormalizes box orientations), silently ignores it once the matching kMax* limit is reached, and returns the list size afterwards. The lists are cleared by swapWorld(). See SceneEffects.hpp / Weather.hpp for the field meanings.

addLocalFogVolume

cpp

size_t addLocalFogVolume(const LocalFogVolume &volume)

Add a spherical local fog volume (density clamped to [-1, 1]; negative values clear fog).

Parameters

Parameter	Description
`volume`	Volume to add.

Returns Number of volumes afterwards (capped at kMaxLocalFogVolumes).

clearLocalFogVolumes

cpp

void clearLocalFogVolumes()

Remove all local fog volumes.

localFogVolumeCount

cpp

size_t localFogVolumeCount() const

Returns Number of local fog volumes.

localFogVolumes

cpp

const std::vector<LocalFogVolume> &localFogVolumes() const

Returns Current local fog volumes (sanitized copies).

addProjectedDecal

cpp

size_t addProjectedDecal(const ProjectedDecal &decal)

Add a projected (box) decal.

Parameters

Parameter	Description
`decal`	Decal to add.

Returns Number of decals afterwards (capped at kMaxProjectedDecals).

clearProjectedDecals

cpp

void clearProjectedDecals()

Remove all projected decals.

projectedDecalCount

cpp

size_t projectedDecalCount() const

Returns Number of projected decals.

projectedDecals

cpp

const std::vector<ProjectedDecal> &projectedDecals() const

Returns Current projected decals (sanitized copies).

addIrradianceVolume

cpp

size_t addIrradianceVolume(const IrradianceVolume &volume)

Add a box-shaped irradiance volume.

Parameters

Parameter	Description
`volume`	Volume to add.

Returns Number of volumes afterwards (capped at kMaxIrradianceVolumes).

clearIrradianceVolumes

cpp

void clearIrradianceVolumes()

Remove all irradiance volumes.

irradianceVolumeCount

cpp

size_t irradianceVolumeCount() const

Returns Number of irradiance volumes.

irradianceVolumes

cpp

const std::vector<IrradianceVolume> &irradianceVolumes() const

Returns Current irradiance volumes (sanitized copies).

Custom visuals

Render-only shapes that are not part of raisim::World. Names share one namespace (addVisual*(), importVisualScene(), addCameraFrustum()) and must be unique (RSFATAL otherwise). Sizes are in metres, colors are RGBA in [0, 1]. A new visual sits at the world origin with identity orientation; move it through the returned Visuals. The renderer keeps its own reference until removeVisualObject(), clearVisualizationObjects() or swapWorld().

addVisualSphere

cpp

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

Parameter	Description
`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.

cpp

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

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

Parameters

Parameter	Description
`name`	Visual name.
`radius`	Sphere radius.
`color`	RGBA color.

Returns Shared pointer to the created visual.

addVisualBox

cpp

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

Parameter	Description
`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.

cpp

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.

Parameters

Parameter	Description
`name`	Visual name.
`xLength`	Size in X.
`yLength`	Size in Y.
`zLength`	Size in Z.
`color`	RGBA color.

Returns Shared pointer to the created visual.

addVisualCylinder

cpp

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

Parameter	Description
`name`	Visual name.
`radius`	Cylinder radius.
`height`	Cylinder height (along the visual's local Z axis).
`colorR`	Red channel.
`colorG`	Green channel.
`colorB`	Blue channel.
`colorA`	Alpha channel.

Returns Shared pointer to the created visual.

cpp

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.

Parameters

Parameter	Description
`name`	Visual name.
`radius`	Cylinder radius.
`height`	Cylinder height.
`color`	RGBA color.

Returns Shared pointer to the created visual.

addVisualCapsule

cpp

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

Parameter	Description
`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.

cpp

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.

Parameters

Parameter	Description
`name`	Visual name.
`radius`	Capsule radius.
`height`	Capsule height.
`color`	RGBA color.

Returns Shared pointer to the created visual.

addVisualMesh

cpp

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

The file is imported through the renderer's asset manager. With async mesh loading enabled (the default) the visual is returned immediately and its geometry appears once pollAsyncMeshLoads() (called by every render) finalizes it.

Parameters

Parameter	Description
`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.

cpp

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.

Parameters

Parameter	Description
`name`	Visual name.
`meshFile`	Mesh file path.
`scale`	Per-axis scale.
`color`	RGBA color.

Returns Shared pointer to the created visual.

importVisualScene

cpp

std::shared_ptr<Visuals> importVisualScene(
    const std::string &name,
    const std::string &sceneFile,
    SceneImportReport *report=nullptr,
    bool importLights=true,
    float lightIntensityScale=1.0f,
    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)

Import a scene file as a mesh visual and, optionally, its authored lights.

Equivalent to addVisualMesh() plus importing the file's lights as additional lights (dropping those beyond kMaxAdditionalLights). When lights were imported and RenderQualitySettings::autoSelectImportedShadowLight is set with a non-zero shadowedLightBudget, the dominant one is promoted to the main shadow caster (promoteDominantAdditionalLightToMainShadowCaster()). Light-import errors are reported in SceneImportReport::notes, not thrown.

Parameters

Parameter	Description
`name`	Visual name (must be unique).
`sceneFile`	Scene/mesh file path.
`report` (out)	Optional import summary.
`importLights`	Import the file's lights.
`lightIntensityScale`	Multiplier applied to imported light intensities.
`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.

cpp

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

Options-struct overload; prefer this in new code.

Parameters

Parameter	Description
`name`	Visual name.
`sceneFile`	Scene/mesh file path.
`opts`	Import options.

Returns Shared pointer to the created visual.

threadingMode

cpp

ThreadingMode threadingMode() const

Threading mode this renderer was constructed with.

Returns The mode passed to the constructor.

swapWorld

cpp

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 (per-object draw wrappers, render/shadow candidate caches, picking ids, the target visual and camera targets) and every visual added via addVisualXxx / addInstancedVisuals / addPointCloud / addCoordinateFrame, plus tendon visuals. Additional lights, fog volumes, projected decals, irradiance volumes, and registered reflection probes are cleared so the caller's scene-application step can repopulate them (probe textures are not deleted). Camera and render-quality settings are preserved, apart from those a world scene set (see below).

The dropped visuals are kept alive (unreferenced by the renderer) until the end of the next update(), renderWithExternalCamera(), or depth-only render, so a scene applied again in between reuses their meshes, mesh LODs and foliage partitions instead of reading and processing every model again. Models whose files changed since they were read are read again (RayraiGlobalAsset::forgetChangedModelFiles()).

Like the constructor, it applies the new world's .rscene scene, if it has one. The previous world's scene is removed, including its background, sky and terrain textures, and the viewer settings it replaced come back: render quality and weather, background color, main light and terrain material. The camera stays where it is unless the new world's scene places it.

Parameters

Parameter	Description
`world`	New world; stored (shared ownership) like the constructor's.

loadSceneHdrCubemapCached

cpp

unsigned int loadSceneHdrCubemapCached(
    const std::string &path,
    int faceSize)

Load a scene HDR map once per path, file signature and face size. The viewer owns the texture until destruction; callers must not delete it. GL context required.

acquireSceneHdrCubemapCached

cpp

std::shared_ptr<const unsigned int> acquireSceneHdrCubemapCached(
    const std::string &path,
    int faceSize)

Acquire a scene HDR texture while it is installed in a background or visual. Unused scene entries are evicted; the viewer frees textures before context teardown.

applyTextureFilteringQualityToLoadedTextures

cpp

size_t applyTextureFilteringQualityToLoadedTextures()

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

Uses RenderQualitySettings::textureAnisotropy and textureMipLodBias and covers the ground texture, custom visuals and instanced visuals.

Returns Number of texture ids updated.

setAsyncMeshLoadingEnabled

cpp

void setAsyncMeshLoadingEnabled(bool enabled)

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

Async loading parses files and prepares base geometry and instanced LODs on workers. Pending instances are skipped; textures and incremental GPU uploads use the render thread. Disable it when a caller needs mesh assets to be available immediately after addVisualMesh()/importVisualScene(). Disabling it also finishes the meshes still loading before it returns, for example those of the world's scene that the constructor applied; call it with this window's GL context current. To load only the meshes requested next synchronously, use a SynchronousMeshLoadingScope instead. Enabled by default; USD files are always imported synchronously.

Parameters

Parameter	Description
`enabled`	True to import future mesh files asynchronously; false to load them synchronously and finish the pending ones.

asyncMeshLoadingEnabled

cpp

bool asyncMeshLoadingEnabled() const

True when future mesh file imports are started asynchronously.

Returns Current async-import flag.

pollAsyncMeshLoads

cpp

size_t pollAsyncMeshLoads(size_t maxAssets=1)

Finalize ready async mesh imports on the render thread.

Parameters

Parameter	Description
`maxAssets`	Maximum import/upload stages to advance (zero does no work). Instanced LOD preparation is also polled, with one submesh upload per batch. Requires the window's GL context: with another current, the pending uploads give their staging space back and this throws std::logic_error before any advances (as does a frame's poll in update()).

Returns Number of assets finalized.

pendingAsyncMeshLoadCount

cpp

size_t pendingAsyncMeshLoadCount() const

Pending imports plus instanced LOD jobs, including unfinished GPU uploads, and the HDR background of the world's scene while it loads.

Returns Number of pending jobs; 0 once everything has been finalized by pollAsyncMeshLoads().

debugAssets

cpp

RayraiGlobalAsset &debugAssets() const

The asset manager this renderer imports through.

Exposed so tests can inspect the meshes this renderer actually holds rather than re-deriving them through a second manager, which only agrees when the asset happens to be eligible for the process-wide GPU cache.

Returns Reference owned by this renderer, valid for its lifetime.

modelHandle

cpp

std::shared_ptr<const void> modelHandle(const std::string &meshFile) const

A strong reference to a model file this renderer has read.

The model caches reference models weakly, and instanced foliage keeps only the meshes it derives from its model, so a model can be released while the scene still uses it. An application that rebuilds its scene (swapWorld(), then the same visuals again) can hold these handles across the rebuild, so the models are reused instead of read and prepared again.

Parameters

Parameter	Description
`meshFile`	Model file path, as passed when the visual was added.

Returns The model, or nullptr when it was not read (it is not read here).

setKeyboardShortcutsEnabled

cpp

void setKeyboardShortcutsEnabled(bool enabled)

Whether this renderer reacts to global keyboard shortcuts.

The renderer's built-in shortcuts read SDL's keyboard state, which is one array for the whole process and carries no notion of which window has focus. A process running several renderers would otherwise see a key press act on all of them at once, so a multi-window application should leave this on only for the focused renderer. Defaults to true, which is the behaviour of a single-renderer application. Currently the only shortcut is B, which toggles the picking-buffer debug view. Camera movement keys are controlled separately by setKeyboardInputEnabled().

Parameters

Parameter	Description
`enabled`	False to ignore shortcut keys in this renderer.

keyboardShortcutsEnabled

cpp

bool keyboardShortcutsEnabled() const

Returns True when this renderer reacts to global keyboard shortcuts (default true).

pbrDebugOutputMode

cpp

int pbrDebugOutputMode() const

PBR debug output mode in force for this renderer.

The environment variable RAYRAI_PBR_DEBUG_OUTPUT sets it process-wide; captureDebugPasses overrides it for the frames it renders. The override belongs to this renderer: rewriting the process environment raced every other worker's getenv on the render path, and a thread-local override would follow whichever thread happened to drive the renderer.

Returns Active mode; 0 is normal shading.

setPbrDebugOutputMode

cpp

void setPbrDebugOutputMode(int mode)

Select a renderer-local material capture mode (0..31). -1 restores the process default. Changing the mode invalidates cached scene color.

Parameters

Parameter	Description
`mode`	Mode in [-1, 31]; throws std::invalid_argument otherwise.

resize

cpp

void resize(int newWidth, int newHeight)

Resize the internal camera render target.

Non-positive or unchanged sizes are ignored. update() calls this with its own size every frame, so explicit calls are only needed before rendering through other paths.

Parameters

Parameter	Description
`newWidth`	New framebuffer width in pixels.
`newHeight`	New framebuffer height in pixels.

update

cpp

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

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

The interactive viewer path: resizes the target to w x h, finalizes at most one pending async mesh import, syncs raisim objects, applies mouse and keyboard camera input, then renders shadows, the scene and post-processing. Read the result with getImageTexture(). Requires this renderer's GL context.

Parameters

Parameter	Description
`w`	Target width in pixels.
`h`	Target height in pixels.
`isHovering`	Whether the mouse is over the render area; mouse input is ignored otherwise.
`cX`	Cursor x position inside the render area, in pixels.
`cY`	Cursor y position inside the render area, in pixels.
`shouldClick`	Whether mouse click selection should be processed.

cancelViewportMouseDrag

cpp

void cancelViewportMouseDrag()

Stop an in-progress viewport mouse drag without changing button state.

setKeyboardInputEnabled

cpp

void setKeyboardInputEnabled(bool enabled)

Allow or block this renderer's WASD/Space camera movement.

Parameters

Parameter	Description
`enabled`	False to ignore the keyboard for this renderer.

The camera reads the process-wide SDL keyboard state, which is shared by every renderer in the process. A host that draws more than one view at a time (the TCP viewer's split panes) must therefore leave this on for just one of them, or a single key press walks every camera at once. Mouse input needs no such switch: it is already scoped by the hover flag passed to update().

keyboardInputEnabled

cpp

bool keyboardInputEnabled() const

Returns True when this renderer acts on camera keys (default true).

getImageTexture

cpp

unsigned int getImageTexture() const

Return the GL texture id of the internal camera output.

Returns Texture id for the most recent rendered frame, owned by the renderer (it can change after resize()).

setCameraFixedDistance

cpp

void setCameraFixedDistance(bool fixed)

Keep the camera distance constant when orbiting a target.

Parameters

Parameter	Description
`fixed`	True to lock distance.

isCameraFixedDistance

cpp

bool isCameraFixedDistance() const

True when the orbit distance is locked.

Returns Lock state.

cameraFixedDistance

cpp

float cameraFixedDistance() const

Current locked orbit distance (metres).

Returns Distance used while the orbit distance is locked.

setCameraFixedTarget

cpp

void setCameraFixedTarget(bool fixed)

Keep the camera target fixed in world space.

Parameters

Parameter	Description
`fixed`	True to lock the target position.

isCameraFixedTarget

cpp

bool isCameraFixedTarget() const

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

Returns Lock state.

setBackgroundColor

cpp

void setBackgroundColor(const glm::vec4 &color)

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

Parameters

Parameter	Description
`color`	RGBA color where each channel is in [0, 255].

Identical to setBackgroundColorRgb255(); prefer that name or setBackgroundColorLinear() in new code. Overwritten by setRenderQualitySettings()/setRenderQualityPreset().

setBackgroundColorRgb255

cpp

void setBackgroundColorRgb255(const glm::vec4 &color)

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

Parameters

Parameter	Description
`color`	RGBA color where each channel is in [0, 255].

setBackgroundColorLinear

cpp

void setBackgroundColorLinear(const glm::vec4 &color)

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

Parameters

Parameter	Description
`color`	Linear RGBA color where each channel is in [0, 1].

getBackgroundColor

cpp

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.

Returns RGBA color, each channel in [0, 255].

getBackgroundColorLinear

cpp

glm::vec4 getBackgroundColorLinear() const

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

Returns Linear RGBA color.

setEnvironmentBackground

cpp

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

Render a cubemap behind the interactive viewer camera.

Parameters

Parameter	Description
`environmentMap`	Cubemap texture id, or 0 to disable the environment background. Not owned: the caller keeps it alive while it is installed.
`exposure`	Multiplier applied while drawing the environment background.

setSceneEnvironmentBackground

cpp

void setSceneEnvironmentBackground(
    std::shared_ptr<const unsigned int> texture,
    float exposure=1.0f)

Install a background while retaining its scene HDR texture lease.

environmentBackgroundMap

cpp

unsigned int environmentBackgroundMap() const

Current interactive viewer environment background cubemap.

Returns Cubemap id, or 0 if disabled.

environmentBackgroundExposure

cpp

float environmentBackgroundExposure() const

Current interactive viewer environment background exposure.

Returns Exposure multiplier.

clearEnvironmentBackground

cpp

void clearEnvironmentBackground()

Disable the interactive viewer environment background.

setFogDensity

cpp

void setFogDensity(float density)

Set scene fog density used by the mesh shader.

Overwritten by setRenderQualitySettings() (RenderQualitySettings::fogDensity).

Parameters

Parameter	Description
`density`	Fog density in 1/m (default 0.01); negative values are clamped to 0.

getFogDensity

cpp

float getFogDensity() const

Get current fog density.

Returns Fog density value.

getCamera

cpp

Camera &getCamera()

Access the internal camera for direct manipulation. Targets are allocated on first render or explicit ensureRenderTargets().

Returns Reference to the internal camera.

getTargetVisual

cpp

const Visuals *getTargetVisual() const

Get the currently selected target visual, if any.

Returns Pointer to the target visual or nullptr.

cpp

Visuals *getTargetVisual()

Get the currently selected target visual, if any.

Returns Pointer to the target visual or nullptr.

setTargetVisual

cpp

void setTargetVisual(Visuals *visual)

Set the target visual for camera tracking.

A non-null visual locks the camera target and orbit distance onto it; nullptr unlocks both. The pointer is not owned; the target is dropped automatically when the visual is removed from this renderer.

Parameters

Parameter	Description
`visual`	Visual to target, or nullptr to clear.

pickTargetVisualAt

cpp

Visuals *pickTargetVisualAt(int x, int y)

Pick a custom visual at a pixel of the internal camera.

Runs a picking pass immediately (GL context required). Only visuals added through this renderer can be returned.

Parameters

Parameter	Description
`x`	Pixel x coordinate in the internal camera's framebuffer (top-left origin).
`y`	Pixel y coordinate, growing downward; out-of-range pixels pick nothing.

Returns Pointer to the picked visual (owned by the renderer) or nullptr.

setShadowOrtho

cpp

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

Set the directional shadow box (orthographic) parameters.

Defaults are 12.5, 0.1 and 55 m; overwritten by setRenderQualitySettings().

Parameters

Parameter	Description
`halfSize`	Half-size of the ortho box in metres.
`zNear`	Near plane in metres.
`zFar`	Far plane in metres.

setShadowCenterOffset

cpp

void setShadowCenterOffset(float meters)

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

Default 10 m; overwritten by setRenderQualitySettings().

Parameters

Parameter	Description
`meters`	Distance ahead of the camera.

requestShadowUpdate

cpp

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.

setUpdateShadowsEveryFrame

cpp

void setUpdateShadowsEveryFrame(bool enabled)

Runtime shortcut for RenderQualitySettings::updateShadowsEveryFrame.

Parameters

Parameter	Description
`enabled`	True to refresh shadow maps every viewer frame, false to update on demand.

updateShadowsEveryFrame

cpp

bool updateShadowsEveryFrame() const

True when viewer shadows are refreshed every frame.

Returns RenderQualitySettings::updateShadowsEveryFrame.

getShadowCenterOffset

cpp

float getShadowCenterOffset() const

Get the current shadow center offset distance.

Returns Distance ahead of the camera.

captureSupersampledRgba

cpp

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. Temporal AA and viewer upscaling are disabled for the capture.

Parameters

Parameter	Description
`externalCam`	Camera whose pose, projection and render-target size define the output.
`scale`	Supersampling factor per axis, clamped to [1, 4].
`ov`	Render overrides, as for renderWithExternalCamera().

Returns Downsampled RGBA8 image at the camera's render-target size.

renderWithExternalCamera

cpp

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

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

Only the sensor's world pose is copied into externalCam (see syncRaisimCameraPose(): sensor +X is the view direction, +Z is up); projection and resolution come from externalCam itself. Custom visuals, point clouds and coordinate frames are never drawn, MSAA/temporal AA/viewer upscaling are disabled, and weather effects follow WeatherSettings::affectSensors, regardless of ov.

Parameters

Parameter	Description
`sensorCam`	Raisim RGB camera providing the pose; its pose is updated.
`externalCam`	Render camera to use for rendering; receives the output.
`ov`	Shader/toggle overrides (see RenderOverrides).

cpp

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

Render using a raisim depth camera's pose and an external render camera.

Same as the RGB overload (pose only, sensor-safe overrides). This renders the color image; use renderDepthPlaneDistance() for linear depth.

Parameters

Parameter	Description
`sensorCam`	Raisim depth camera providing the pose; its pose is updated.
`externalCam`	Render camera to use for rendering; receives the output.
`ov`	Shader/toggle overrides (see RenderOverrides).

cpp

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

Render using an external render camera.

Renders into externalCam's own render targets (allocated on first use at its configured size); read the result from the camera, e.g. its final texture. Syncs raisim objects and finalizes at most one pending async mesh import first. When nothing that affects the image has changed since the last call with the same camera, the previous frame may be reused; call invalidateExternalFrameCache() after changes the renderer cannot see. Requires this renderer's GL context.

Parameters

Parameter	Description
`externalCam`	Render camera to use for rendering; receives the output.
`ov`	Shader/toggle overrides (see RenderOverrides). Throws std::invalid_argument when a custom `post` shader is combined with reprojected temporal AA.

invalidateExternalFrameCache

cpp

void invalidateExternalFrameCache()

Force the next viewer/external render to redraw instead of reusing a cached frame.

cpp

void invalidateExternalFrameCache(bool invalidateStaticSceneLayer)

Internal: not implemented (no definition is provided); use invalidateExternalFrameCache().

Parameters

Parameter	Description
`invalidateStaticSceneLayer`	Unused.

buildExternalFrameCacheKey

cpp

bool buildExternalFrameCacheKey(
    const Camera &externalCam,
    const RenderOverrides &ov,
    bool useTemporalAa,
    int sceneMsaaSamples,
    uint64_t &key,
    bool pointCloudsMustBeDetectable=false) const

Internal: compute the frame-cache key for an external render.

Parameters

Parameter	Description
`externalCam`	Camera to be rendered.
`ov`	Overrides to be used.
`useTemporalAa`	Whether temporal AA will run.
`sceneMsaaSamples`	Scene MSAA sample count.
`key` (out)	Resulting key.
`pointCloudsMustBeDetectable`	Only detectable point clouds contribute.

Returns False when the frame must not be cached.

captureRenderPassTimings

cpp

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. Viewer upscaling is disabled for the measurement; scenes with foliage are rendered a second time to time foliage sub-passes.

Parameters

Parameter	Description
`externalCam`	Camera to render with (receives the image).
`ov`	Render overrides.

Returns One entry per timed pass, in submission order.

captureViewerPassTimings

cpp

std::vector<RenderPassTiming> captureViewerPassTimings(
    int width,
    int height)

Blocking diagnostic renders of the native viewer, including non-detectable foliage. Call with a current GL context; timings exclude presentation/UI. Runs update() (twice with foliage) on the internal camera.

Parameters

Parameter	Description
`width`	Viewer width in pixels; must be positive (throws std::invalid_argument).
`height`	Viewer height in pixels; must be positive.

Returns One entry per timed pass.

conservativeOcclusionCullingDiagnostics

cpp

ConservativeOcclusionCullingDiagnostics conservativeOcclusionCullingDiagnostics() const

Returns Diagnostics: occlusion-culling counters of the last scene color pass.

foliageRenderDiagnostics

cpp

FoliageRenderDiagnostics foliageRenderDiagnostics() const

Returns Diagnostics: foliage/instanced draw counters of the last rendered frame.

environmentBackgroundDiagnostics

cpp

EnvironmentBackgroundDiagnostics environmentBackgroundDiagnostics() const

Returns Diagnostics: how the last scene pass drew the environment background.

shadowCacheDiagnostics

cpp

ShadowCacheDiagnostics shadowCacheDiagnostics() const

Returns Diagnostics: shadow-map caching counters of the last rendered frame.

captureDebugPasses

cpp

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 afterwards re-applies the previous quality settings through setRenderQualitySettings() and resets the renderer-local PBR debug mode to -1 (process default). Because it goes through setRenderQualitySettings(), application-added additional lights are cleared and the preset reads Custom afterwards (see setRenderQualitySettings()). Returned pixels are top-left ordered RGBA8 buffers so callers can write PNGs or analyze them without a RayRai image writer dependency.

Parameters

Parameter	Description
`externalCam`	Camera to render with; its size defines the capture size.
`ov`	Render overrides (temporal AA and upscaling are forced off).

Returns 25 passes (final, material channels, lighting terms, shadows, fog, AO, ...).

planDirectionalShadowCascades

cpp

DirectionalShadowCascadePlan planDirectionalShadowCascades(const Camera &camera) const

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

The shadow pass uses this same planner for the main directional light; calling it is CPU-only and does not allocate shadow maps or change renderer state. Cascades are enabled when RenderQualitySettings::directionalShadowCascadeCount is greater than 1.

Parameters

Parameter	Description
`camera`	Camera whose frustum is split.

Returns Cascade plan (see DirectionalShadowCascadePlan).

planAdditionalShadowAtlas

cpp

ShadowAtlasPlan planAdditionalShadowAtlas() const

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

The renderer uses this plan for its 2D additional-light shadow atlas (point lights keep standalone cubemaps unless the point-shadow policy says otherwise). Calling it is CPU-only; the result depends on the shadow lights selected by the last rendered frame.

Returns Atlas plan (see ShadowAtlasPlan).

shadowDebugOverlaySummary

cpp

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.

Returns Summary for the internal camera.

captureReflectionProbeCubemap

cpp

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 RGBA8 OpenGL cubemap id with mipmaps. The caller owns the returned texture and may bind it to PBR materials through Visuals or Material. Faces are rendered without post-processing. Requires this renderer's GL context.

Parameters

Parameter	Description
`position`	World-space capture position.

Returns OpenGL cubemap id, or 0 on failure.

cpp

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

Capture a static local reflection probe with explicit capture settings.

Parameters

Parameter	Description
`position`	World-space capture position.
`settings`	What to draw and at which resolution.

Returns Caller-owned OpenGL cubemap id, or 0 on failure.

captureFilteredReflectionProbe

cpp

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. Uses default capture settings and reflectionProbeFilterSettingsForCurrentQuality(), so with probe filtering disabled only the raw environment map is produced. All returned textures are owned by the caller. Pass the probe to addReflectionProbe() to make it selectable.

Parameters

Parameter	Description
`position`	World-space capture position.
`radius`	Influence radius in metres (negative values become 0 = unbounded).
`strength`	Probe strength (negative values become 0).

Returns The probe; map ids are 0 for maps that were skipped or failed.

cpp

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

Capture a static local probe and generate irradiance, prefiltered specular, and BRDF maps. Uses filter settings for the current quality.

Parameters

Parameter	Description
`position`	World-space capture position.
`radius`	Influence radius in metres.
`strength`	Probe strength.
`captureSettings`	What to draw and at which resolution.

Returns The probe; textures are owned by the caller.

cpp

ReflectionProbe captureFilteredReflectionProbe(
    const glm::vec3 &position,
    float radius,
    float strength,
    const ReflectionProbeCaptureSettings &captureSettings,
    const ReflectionProbeFilterSettings &filterSettings)

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

Parameters

Parameter	Description
`position`	World-space capture position.
`radius`	Influence radius in metres.
`strength`	Probe strength.
`captureSettings`	What to draw and at which resolution.
`filterSettings`	CPU filtering settings; zero sizes skip the corresponding map.

Returns The probe; textures are owned by the caller.

cpp

ReflectionProbe captureFilteredReflectionProbe(const CaptureFilteredReflectionProbeOptions &opts)

Options-struct overload; prefer this in new code.

Parameters

Parameter	Description
`opts`	Capture options.

Returns The probe; textures are owned by the caller.

captureFilteredReflectionProbeCached

cpp

ReflectionProbe captureFilteredReflectionProbeCached(const CaptureFilteredReflectionProbeOptions &opts)

Cached variant of the options-struct overload.

Parameters

Parameter	Description
`opts`	Capture options.

Returns The cached or newly captured probe; textures are owned by the renderer.

cpp

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

Cached captureFilteredReflectionProbe(); textures stay owned by the renderer.

Entries are keyed by all arguments and live until clearReflectionProbeCache().

Parameters

Parameter	Description
`position`	World-space capture position.
`radius`	Influence radius in metres.
`strength`	Probe strength.

Returns The cached or newly captured probe.

cpp

ReflectionProbe captureFilteredReflectionProbeCached(
    const glm::vec3 &position,
    float radius,
    float strength,
    const ReflectionProbeCaptureSettings &captureSettings)

Cached captureFilteredReflectionProbe(); textures stay owned by the renderer.

Parameters

Parameter	Description
`position`	World-space capture position.
`radius`	Influence radius in metres.
`strength`	Probe strength.
`captureSettings`	Capture settings.

Returns The cached or newly captured probe.

cpp

ReflectionProbe captureFilteredReflectionProbeCached(
    const glm::vec3 &position,
    float radius,
    float strength,
    const ReflectionProbeCaptureSettings &captureSettings,
    const ReflectionProbeFilterSettings &filterSettings)

Cached captureFilteredReflectionProbe(); textures stay owned by the renderer.

Parameters

Parameter	Description
`position`	World-space capture position.
`radius`	Influence radius in metres.
`strength`	Probe strength.
`captureSettings`	Capture settings.
`filterSettings`	Filter settings.

Returns The cached or newly captured probe.

captureReflectionProbeCubemapCached

cpp

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. Entries are keyed by position and settings.

Parameters

Parameter	Description
`position`	World-space capture position.
`settings`	Capture settings.

Returns Renderer-owned cubemap id, or 0 on failure (failures are not cached).

clearReflectionProbeCache

cpp

void clearReflectionProbeCache()

Delete every texture held by the probe caches and empty them. GL context required. Probes previously returned by the cached functions become dangling.

reflectionProbeCacheSize

cpp

size_t reflectionProbeCacheSize() const

Returns Number of entries in both probe caches.

applyReflectionProbeSidecarQualitySettings

cpp

bool applyReflectionProbeSidecarQualitySettings(const std::string &sceneFile)

Apply the quality block of a scene's reflection-probe sidecar.

Copies the provided probe selection/filter values into the current render quality settings via setRenderQualitySettings() (which has side effects, see there). Probes themselves are not captured.

Parameters

Parameter	Description
`sceneFile`	Scene/mesh file path, or the sidecar path itself.

Returns True when the sidecar provided at least one quality value.

applyEnvironmentSidecarSettings

cpp

bool applyEnvironmentSidecarSettings(const std::string &sceneFile)

Apply a scene's environment sidecar to the current render quality settings.

Present values are written into a copy of the current settings, which is then applied with setRenderQualitySettings() (see its side effects). A background map is loaded as a 512 px cubemap and installed with setEnvironmentBackground(). Requires this renderer's GL context.

Parameters

Parameter	Description
`sceneFile`	Scene/mesh file path, or the sidecar path itself.

Returns True when the sidecar provided at least one value.

applyWeatherSidecarSettings

cpp

bool applyWeatherSidecarSettings(const std::string &sceneFile)

Apply a scene's weather sidecar.

Calls setWeatherSettings() when weather data is present, and replaces all local fog volumes when the sidecar has local_fog_volumes.

Parameters

Parameter	Description
`sceneFile`	Scene/mesh file path, or the sidecar path itself.

Returns True when anything was applied.

reflectionProbeFilterSettingsForCurrentQuality

cpp

ReflectionProbeFilterSettings reflectionProbeFilterSettingsForCurrentQuality() const

Returns Probe filter settings derived from the current RenderQualitySettings (all zero when reflection-probe filtering is disabled).

addReflectionProbe

cpp

size_t addReflectionProbe(const ReflectionProbe &probe)

The probe is copied with radius/strength clamped to >= 0 and box projection disabled for degenerate boxes. Registered probes are not bound to visuals automatically, and the registry does not take ownership of the textures.

Parameters

Parameter	Description
`probe`	Probe to register; ignored when it has no environment, irradiance or prefiltered map.

Returns Number of registered probes afterwards.

clearReflectionProbes

cpp

void clearReflectionProbes()

Unregister every probe added with addReflectionProbe(); their textures stay with the caller.

selectReflectionProbeBlend

cpp

bool selectReflectionProbeBlend(
    const glm::vec3 &position,
    ReflectionProbeBlend &blend) const

Pick up to two registered probes influencing a position.

Weight per probe is strength * (1 - d / radius) inside a positive radius (0 outside), or strength / (1 + d) for radius 0, where d is the distance to the probe position, or to its box when box projection is valid. Probes at or below RenderQualitySettings::minReflectionProbeWeight are skipped; the second probe is used only when maxReflectionProbesPerSelection is 2.

Parameters

Parameter	Description
`position`	World-space query position.
`blend` (out)	Selected probes and normalized weights.

Returns True when at least one probe influences the position.

reflectionProbeDebugView

cpp

ReflectionProbeDebugView reflectionProbeDebugView(const glm::vec3 &position) const

Diagnostics: probe selection at a position plus per-probe weights.

Parameters

Parameter	Description
`position`	World-space query position.

Returns Debug view; CPU only.

reflectionProbeDebugOverlaySummary

cpp

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.

Parameters

Parameter	Description
`position`	World-space query position.

Returns Overlay summary.

suggestReflectionProbePlacementFromSceneBounds

cpp

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. Bounds are the union of approximate bounding spheres of raisim objects, custom visuals and instanced visuals.

Returns Suggestion; valid is false when there is nothing to bound.

applyNearestReflectionProbe

cpp

bool applyNearestReflectionProbe(
    Visuals &visual,
    const glm::vec3 &position) const

Bind the best registered reflection probe at position to a visual's PBR environment.

Uses the primary probe of selectReflectionProbeBlend() with the blend strength.

Parameters

Parameter	Description
`visual`	Visual to update.
`position`	World-space position used for selection (typically the visual's).

Returns False when no probe influences the position (the visual is left unchanged).

reflectionProbeCount

cpp

size_t reflectionProbeCount() const

Returns Number of probes registered with addReflectionProbe().

pickWithExternalCamera

cpp

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

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

Parameters

Parameter	Description
`externalCam`	Render camera used for the picking pass.
`x`	Pixel x coordinate in framebuffer space (top-left origin).
`y`	Pixel y coordinate in framebuffer space, growing downward.
`pickingOverride`	Optional picking shader override.

Returns Encoded object id (24-bit), or 0 if nothing is picked or the pixel is out of range.

addPointCloud

cpp

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

Create a named point cloud.

Parameters

Parameter	Description
`name`	Unique name for the point cloud; aborts (`RSFATAL`) if already used.

Returns Shared pointer to the point cloud; the renderer keeps its own reference until removePointCloud() / clearVisualizationObjects() / swapWorld().

removePointCloud

cpp

void removePointCloud(const std::string &name)

Remove a point cloud by name.

Parameters

Parameter	Description
`name`	Name of the point cloud to remove; aborts (`RSFATAL`) if unknown.

clearVisualizationObjects

cpp

void clearVisualizationObjects()

Remove all visual objects, instanced visuals, and point clouds.

Also drops automatically maintained tendon visuals and the target visual. Coordinate frames are kept.

addCoordinateFrame

cpp

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

Create a named coordinate frame set.

Parameters

Parameter	Description
`name`	Unique name for the coordinate frame set; aborts (`RSFATAL`) if already used.

Returns Shared pointer to the coordinate frame set (also held by the renderer).

removeCoordinateFrame

cpp

void removeCoordinateFrame(const std::string &name)

Remove a coordinate frame set by name.

Parameters

Parameter	Description
`name`	Name of the coordinate frame set to remove; aborts (`RSFATAL`) if unknown.

makeVisualMesh

cpp

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

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

Parameters

Parameter	Description
`name`	Visual name.
`meshFile`	Mesh file path.

Returns Builder bound to this renderer; call add() to create the visual.

addVisualPlane

cpp

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.

Flat-shaded; the unit plane lies in the local XY plane with a +Z normal and width / height scale it along local X / Y. Duplicate names are fatal.

Parameters

Parameter	Description
`name`	Visual name.
`width`	Size along local X.
`height`	Size along local Y.
`colorR`	Red channel.
`colorG`	Green channel.
`colorB`	Blue channel.
`colorA`	Alpha channel.

Returns Shared pointer to the created visual.

cpp

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.

Parameters

Parameter	Description
`name`	Visual name.
`width`	Size along local X.
`height`	Size along local Y.
`color`	RGBA color.

Returns Shared pointer to the created visual.

addVisualCustomMesh

cpp

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.

The mesh list is shared, not copied. Duplicate names are fatal.

Parameters

Parameter	Description
`name`	Visual name.
`meshes`	Mesh list to render.
`color`	Default color for non-textured meshes.

Returns Shared pointer to the created visual.

cpp

std::shared_ptr<Visuals> addVisualCustomMesh(
    const std::string &name,
    const std::shared_ptr<std::vector<std::shared_ptr<OpenGLMesh>>> &meshes,
    const glm::vec4 &color,
    bool automaticMeshLodEnabled)

addVisualCustomMesh() variant that can disable automatic mesh LOD (for already prepared terrain LODs).

Unlike the other overload this throws std::invalid_argument for a duplicate or empty name, a null/empty mesh list, or a null mesh.

Parameters

Parameter	Description
`name`	Visual name.
`meshes`	Mesh list to render (shared).
`color`	Default color for non-textured meshes.
`automaticMeshLodEnabled`	False to disable generic mesh simplification.

Returns Shared pointer to the created visual.

getVisualObject

cpp

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

Look up a visual by name.

Parameters

Parameter	Description
`name`	Visual name.

Returns Shared pointer to the visual. Aborts (RSFATAL) if not found; use findVisualObject() for a non-fatal lookup.

findVisualObject

cpp

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

Look up a custom visual by name without aborting.

Parameters

Parameter	Description
`name`	Visual name.

Returns The visual, or nullptr when it does not exist.

removeVisualObject

cpp

void removeVisualObject(const std::string &name)

Remove a visual object by name.

Clears the target visual if it was this one.

Parameters

Parameter	Description
`name`	Visual name to remove; aborts (`RSFATAL`) if unknown.

addInstancedVisuals

cpp

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.

Instances are added through the returned object; each instance color is a blend of color1 and color2 (see InstancedVisuals). Instanced names form their own namespace and must be unique (RSFATAL otherwise). Automatic mesh LOD is enabled.

Parameters

Parameter	Description
`name`	Visual name.
`type`	Shape type.
`size`	Base size for the instances.
`color1`	Primary instance color (linear RGBA).
`color2`	Secondary instance color (linear RGBA).
`meshFile`	Mesh file for mesh instances.

Returns Shared pointer to the created instanced visuals (also held by the renderer).

cpp

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,
    bool automaticMeshLodEnabled)

Create instanced visuals for repeated shapes or meshes.

Parameters

Parameter	Description
`name`	Visual name.
`type`	Shape type.
`size`	Base size.
`color1`	Primary color.
`color2`	Secondary color.
`meshFile`	Mesh file.
`automaticMeshLodEnabled`	False to disable automatic mesh simplification.

Returns Shared pointer to the created instanced visuals.

cpp

std::shared_ptr<InstancedVisuals> addInstancedVisuals(
    const std::string &name,
    const InstancedVisuals &prototype)

Create an empty cell batch sharing a ready prototype's prepared meshes (see InstancedVisuals::cloneWithoutInstances()).

Parameters

Parameter	Description
`name`	Batch name; throws std::invalid_argument if already used.
`prototype`	Fully prepared source batch.

Returns The new, empty batch.

cpp

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.

Parameters

Parameter	Description
`name`	Visual name (unique among instanced visuals).
`meshes`	Mesh list shared by all instances.
`size`	Base size for the instances.
`color1`	Primary instance color.
`color2`	Secondary instance color.

Returns Shared pointer to the created instanced visuals.

cpp

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,
    bool automaticMeshLodEnabled)

Mesh-list overload with explicit automatic-LOD control.

Parameters

Parameter	Description
`name`	Visual name.
`meshes`	Shared mesh list.
`size`	Base size.
`color1`	Primary color.
`color2`	Secondary color.
`automaticMeshLodEnabled`	False to disable automatic mesh simplification.

Returns Shared pointer to the created instanced visuals.

getInstancedVisuals

cpp

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

Look up instanced visuals by name.

Parameters

Parameter	Description
`name`	Visual name.

Returns Shared pointer to the instanced visuals. Aborts if not found.

findInstancedVisuals

cpp

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

Look up instanced visuals by name without aborting when absent.

Parameters

Parameter	Description
`name`	Visual name.

Returns The instanced visuals, or nullptr.

getTendonVisual

cpp

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

Automatically maintained spatial tendon drawing, available after scene sync. Returns nullptr for an unknown or fixed tendon. Width is a radius; color, enabled state and path changes are reflected on the next rendered frame.

Parameters

Parameter	Description
`name`	Tendon name.

Returns Renderer-maintained instanced visual, or nullptr.

removeInstancedVisuals

cpp

void removeInstancedVisuals(const std::string &name)

Remove instanced visuals by name.

Parameters

Parameter	Description
`name`	Visual name to remove; aborts (`RSFATAL`) if unknown.

addCameraFrustum

cpp

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.

Adds a line-mesh custom visual named name (remove it with removeVisualObject()); duplicate names are fatal.

Parameters

Parameter	Description
`name`	Visual name.
`color`	Frustum color.

Returns Shared pointer to the frustum helper used to update its shape and pose.

setGroundPatternResourcePath

cpp

void setGroundPatternResourcePath(const std::string &path)

Set a tiled ground texture for halfspace visuals.

Loaded with loadTextureWithTiling() (linear, not sRGB). GL context required.

Parameters

Parameter	Description
`path`	Path to the texture image.

getGroundPatternResourcePath

cpp

std::string getGroundPatternResourcePath()

Get the current ground texture path.

Returns Ground texture path string.

updateObjectLists

cpp

void updateObjectLists()

Copy the bound World's render state for the next renders.

Captures the World's objects, poses, appearance, terrain and deformable geometry, tendons and .rscene scene into a PhysicsSnapshot and applies it. Every render calls this automatically; renders draw the copy, not the World (see ThreadingMode for stepping the World on another thread). Does nothing while an applyPhysicsSnapshot() snapshot is shown. Requires a current GL context.

applyPhysicsSnapshot

cpp

void applyPhysicsSnapshot(std::shared_ptr<const PhysicsSnapshot> snapshot)

Show a physics snapshot instead of the bound World.

Capture with PhysicsSnapshotCapture immediately after integrate2() while the World is protected, publish the immutable snapshot to the render thread without holding a render mutex on the physics thread, and apply it on the render thread with its GL context current. Later renders draw it, including shadow maps, until the next applied snapshot or clearPhysicsSnapshot(); they never read a World. The snapshot can outlive removed physics objects. Scene files and materials must remain available.

Parameters

Parameter	Description
`snapshot`	Frame to show; must be non-null.

clearPhysicsSnapshot

cpp

void clearPhysicsSnapshot()

Show the bound World again: copies it now, as updateObjectLists() does, so protect it as for a render. Requires a current GL context.

setObjectHidden

cpp

void setObjectHidden(raisim::Object *object, bool hidden)

Change render visibility without removing an object's physics collision.

Parameters

Parameter	Description
`object`	Object in this renderer's world; throws std::invalid_argument when null or not part of the world.
`hidden`	True to stop drawing it.

debugObjectFor

cpp

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

Return the cached draw wrapper for tests and diagnostics.

Parameters

Parameter	Description
`object`	raisim object.

Returns Renderer-owned wrapper, or nullptr if the object has not been synced.

debugSceneObjectCandidateRevision

cpp

uint64_t debugSceneObjectCandidateRevision() const

Return the object candidate cache revision for tests and diagnostics.

Returns Counter value.

debugSceneVisualizationCandidateRebuilds

cpp

size_t debugSceneVisualizationCandidateRebuilds() const

Return visualization candidate cache rebuild count for tests and diagnostics.

Returns Counter value.

debugSceneVisualizationCandidateCacheHits

cpp

size_t debugSceneVisualizationCandidateCacheHits() const

Return visualization candidate cache hit count for tests and diagnostics.

Returns Counter value.

debugActiveAdditionalLightSelectionRevision

cpp

uint64_t debugActiveAdditionalLightSelectionRevision() const

Return active additional-light selection revision for tests and diagnostics.

Returns Counter value.

debugActiveAdditionalLightSelectionRebuilds

cpp

size_t debugActiveAdditionalLightSelectionRebuilds() const

Return active additional-light selection rebuild count for tests and diagnostics.

Returns Counter value.

debugActiveAdditionalLightSelectionCacheHits

cpp

size_t debugActiveAdditionalLightSelectionCacheHits() const

Return active additional-light selection cache hit count for tests and diagnostics.

Returns Counter value.

orthogonalViewSwitch

cpp

void orthogonalViewSwitch()

Step the viewer camera through axis-aligned orthographic views.

Switches the internal camera to orthographic projection and, on each call, moves it to the next of six views placed 2 m from the camera target on the +X, +Y, -X, -Y, +Z and -Z sides, looking at the target. It does not switch back to perspective; use getCamera().setProjectionMode() for that.

renderDepthPlaneDistance

cpp

void renderDepthPlaneDistance(
    raisim::DepthCamera &sensorCam,
    Camera &cam,
    Shader *depthPlaneOverride=nullptr,
    bool drawVisualizationObjects=false,
    bool visualizationObjectsMustBeDetectable=true)

Render a linear depth plane for a raisim depth camera.

Copies the sensor's pose into cam (as renderWithExternalCamera() does), then behaves like the Camera overload.

Parameters

Parameter	Description
`sensorCam`	Raisim depth camera; its pose is updated and copied.
`cam`	Render camera to use; receives the depth image.
`depthPlaneOverride`	Optional shader override.
`drawVisualizationObjects`	Include custom and instanced visuals.
`visualizationObjectsMustBeDetectable`	When true, include only visualization objects marked detectable; when false, include all visualization objects.

cpp

void renderDepthPlaneDistance(
    Camera &cam,
    Shader *depthPlaneOverride=nullptr,
    bool drawVisualizationObjects=false,
    bool visualizationObjectsMustBeDetectable=true)

Render a linear depth plane with a given camera.

Writes camera-plane depth into cam's R32F linear-depth target (read it with Camera::getLinearDepthTexture()); pixels with no geometry are 0. Weather, post-processing and point clouds are not involved. Requires this renderer's GL context.

Parameters

Parameter	Description
`cam`	Render camera to use; receives the depth image.
`depthPlaneOverride`	Optional shader override.
`drawVisualizationObjects`	Include custom and instanced visuals.
`visualizationObjectsMustBeDetectable`	When true, include only visualization objects marked detectable; when false, include all visualization objects.

getDepthPlaneTexture

cpp

unsigned int getDepthPlaneTexture() const

Get the internal viewer camera's linear depth texture id.

For an external camera passed to renderDepthPlaneDistance(), read that camera's Camera::getLinearDepthTexture() instead.

Returns OpenGL texture id for R32F linear depth (0 before it is allocated).

measureSpinningLidarSingleDrawGPU

cpp

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

Measure a spinning LiDAR on the GPU.

Advances the head with SpinningLidar::advanceSweep() (the sweep state is shared with SpinningLidar::update(), so the two can alternate) and casts the swept yaw columns against the world's collision bodies (World::getRayCastBodies()), stores the hits in the sensor frame with lidar.setScan() and stamps the world time. The scan reproduces SpinningLidar::update(): the same columns and point order, exact intersections with primitives, heightmaps and meshes, rays starting at rangeMin, and the sensor's own body ignored. Ranges agree to float precision (about 1e-5 of the range); a ray grazing a silhouette within that tolerance may differ. Requires this renderer's GL context.

Parameters

Parameter	Description
`lidar`	Raisim spinning lidar to update.
`sensorPosW`	LiDAR position in world coordinates.
`sensorRotW`	LiDAR orientation in world coordinates.
`objectToExclude`	Optional object whose bodies are all ignored (e.g. the carrier).

Exceptions

Exception	Description
`std::runtime_error`	if a GL resource cannot be created or the scene exceeds a GPU limit.

setLinearHdrRenderingEnabled

cpp

void setLinearHdrRenderingEnabled(bool enabled)

Keep scene radiance linear through MSAA, fog, bloom and DoF, then apply the selected exposure/tone curve/gamma in the existing post pass. Opt-in for compatibility. External captures with postProcess=false keep their legacy contract; internal reflection captures inherit the scene domain. Bloom thresholds are scene-linear radiance in this mode. Changing it resets temporal AA history.

Parameters

Parameter	Description
`enabled`	True to enable linear HDR rendering (default false).

linearHdrRenderingEnabled

cpp

bool linearHdrRenderingEnabled() const

Returns True when linear HDR rendering is enabled (see setLinearHdrRenderingEnabled()).

geometryRefractionDiagnostics

cpp

GeometryRefractionDiagnostics geometryRefractionDiagnostics() const

Returns Diagnostics: state of geometry (dielectric) refraction rendering; default-constructed when that path has never run. CPU only.

geometryRefractionSamplingStatistics

cpp

GeometryRefractionSamplingStatistics geometryRefractionSamplingStatistics() const

Explicit GPU readback; requires this renderer's GL context and may stall.

Returns Sampling statistics, default-constructed when the path has never run.

setSkyVisibilityGrid

cpp

void setSkyVisibilityGrid(
    const SkyVisibilityGrid &grid,
    float strength=1.0f,
    float edgeFadeMeters=2.0f)

Upload a static sky-visibility grid that attenuates environment lighting.

Call on the rendering thread with its GL context current; the data is copied into a texture. Only global environment lighting is attenuated; direct light, authored ambient, lightmaps and local irradiance volumes keep their own visibility. Replaces any previous grid.

Parameters

Parameter	Description
`grid`	Visibility grid; validated (throws std::invalid_argument).
`strength`	Attenuation strength in [0, 1] (throws std::invalid_argument otherwise).
`edgeFadeMeters`	Fade distance at the grid boundary in metres, >= 0.

clearSkyVisibilityGrid

cpp

void clearSkyVisibilityGrid()

Remove the sky-visibility grid.

setBakedIrradianceGrid

cpp

void setBakedIrradianceGrid(
    const BakedIrradianceGrid &grid,
    float strength=1.f,
    float edgeFadeMeters=2.f)

Upload a static baked-irradiance grid (scene-referred diffuse bounce).

Independent of environment sky fill. Upload/clear on the owning rendering GL context; disabled by default. Replaces any previous grid and resets temporal AA history.

Parameters

Parameter	Description
`grid`	Irradiance grid; validated (throws std::invalid_argument).
`strength`	Strength in [0, 4] (throws std::invalid_argument otherwise).
`edgeFadeMeters`	Fade distance at the grid boundary in metres, >= 0.

clearBakedIrradianceGrid

cpp

void clearBakedIrradianceGrid()

Remove the baked-irradiance grid.

getLight

cpp

Light &getLight()

Access the main scene light (the single main shadow caster).

Direct edits take effect on the next frame, but setRenderQualitySettings(), setRenderQualityPreset(), promoteDominantAdditionalLightToMainShadowCaster() and enabled weather overwrite parts of it. Call requestShadowUpdate() after moving it when shadows are not refreshed every frame.

Returns Reference to the main light, owned by the renderer.

addAdditionalLight

cpp

void addAdditionalLight(const AdditionalLight &light)

Add a light besides the main light.

The light is sanitized and copied. Additional lights with AdditionalLight::castsShadows set can receive shadow maps when shadows are enabled and RenderQualitySettings::shadowedLightBudget is greater than 1 (up to kMaxAdditionalShadowLights per frame); otherwise they only shade. Note that setRenderQualitySettings() / setRenderQualityPreset() clear all additional lights, so add lights after choosing the quality settings.

Parameters

Parameter	Description
`light`	Additional light. Ignored once kMaxAdditionalLights lights exist.

updateAdditionalLight

cpp

bool updateAdditionalLight(size_t index, const AdditionalLight &light)

Replace an existing additional light without forcing unrelated shadow maps dirty.

Parameters

Parameter	Description
`index`	Index in insertion order.
`light`	New light (sanitized and copied).

Returns True if the light existed and was replaced.

clearAdditionalLights

cpp

void clearAdditionalLights()

Remove all additional lights (including their shadow maps).

The main light is unaffected.

additionalLightCount

cpp

size_t additionalLightCount() const

Return the current number of additional lights.

Returns Number of additional lights (excluding the main light).

promoteDominantAdditionalLightToMainShadowCaster

cpp

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. Candidates must have AdditionalLight::castsShadows set and non-zero power; point lights are never promoted (they use cubemap shadows through the additional-light budget). The main light takes over the candidate's type, pose, color and attenuation, and its shadows are enabled.

Parameters

Parameter	Description
`preferSpotLights`	Prefer spot lights over other light types when possible.
`removePromotedAdditionalLight`	Remove the promoted light from the additional-light list to avoid double-counting its direct contribution.

Returns True if a suitable light was promoted.

importSceneLights

cpp

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 additional lights (see addAdditionalLight()). This is explicit so low-quality rendering does not pay for scene lights unless an application imports them. When any light was added and RenderQualitySettings::autoSelectImportedShadowLight is set with a non-zero shadowedLightBudget, the dominant one is promoted to the main shadow caster. Import errors are printed to stderr, not thrown.

Parameters

Parameter	Description
`sceneFile`	Scene/mesh file to read lights from.
`intensityScale`	Multiplier applied to imported light intensities.

Returns Number of lights appended, capped by kMaxAdditionalLights.

setRenderQualityPreset

cpp

void setRenderQualityPreset(RenderQualityPreset preset)

Apply a named viewer-quality preset at runtime.

Equivalent to setRenderQualitySettings(defaultRenderQualitySettings(preset)) followed by recording preset as the active preset; the same side effects apply.

Parameters

Parameter	Description
`preset`	Quality preset to apply.

getRenderQualityPreset

cpp

RenderQualityPreset getRenderQualityPreset() const

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

Returns Preset; Fast for a freshly constructed renderer.

setRenderQualitySettings

cpp

void setRenderQualitySettings(const RenderQualitySettings &settings)

Apply explicit viewer-quality settings at runtime.

Besides storing (and clamping) the settings, this re-derives renderer state from them: background color, fog density, gamma, depth of field, the main light (type reset to directional, direction, colors, shadow resolution and parameters), the shadow box and center offset, and texture filtering of loaded textures. It also clears all additional lights and, when RenderQualitySettings::addViewerFillLights is set, adds the built-in fill and rim lights. The active preset becomes Custom. With weather enabled the settings become the base that weather is applied on.

Parameters

Parameter	Description
`settings`	Settings to apply. Throws std::invalid_argument for an unknown temporal AA method, a non-finite jitter scale, a current weight outside [0.02, 1] or a sharpness outside [0, 1].

getRenderQualitySettings

cpp

const RenderQualitySettings &getRenderQualitySettings() const

Return the active explicit viewer-quality settings.

Returns Effective settings, including weather overrides and clamping.

getUserRenderQualitySettings

cpp

const RenderQualitySettings &getUserRenderQualitySettings() const

Returns Settings as last set by the user, i.e. without weather overrides while weather is enabled; otherwise the same as getRenderQualitySettings().

setDepthPrepassesEnabled

cpp

void setDepthPrepassesEnabled(bool opaque, bool foliageAlpha)

Toggle depth prepasses while preserving authored lights and materials.

Unlike setRenderQualitySettings() this does not reset lights; the preset becomes Custom.

Parameters

Parameter	Description
`opaque`	RenderQualitySettings::opaqueDepthPrepass.
`foliageAlpha`	RenderQualitySettings::foliageAlphaDepthPrepass.

setAdditionalLightContributionThreshold

cpp

void setAdditionalLightContributionThreshold(float threshold)

Set the total additional-light incident-radiance cutoff budget without resetting authored lights. Zero (default) keeps exact unlimited lighting. Invalid/negative values disable culling. This is not a final-pixel tolerance. The preset becomes Custom.

Parameters

Parameter	Description
`threshold`	RenderQualitySettings::additionalLightContributionThreshold.

setFoliageWindTimeSeconds

cpp

void setFoliageWindTimeSeconds(float seconds)

Set the global foliage wind animation clock without changing quality preset state.

Parameters

Parameter	Description
`seconds`	Clock value in seconds; negative or non-finite values become 0.

advanceFoliageWindTime

cpp

void advanceFoliageWindTime(float deltaSeconds)

Advance the global foliage wind animation clock.

Parameters

Parameter	Description
`deltaSeconds`	Elapsed seconds; non-positive or non-finite values are ignored. The clock wraps at 100000 s.

printRenderDiagnostics

cpp

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

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

Parameters

Parameter	Description
`out`	Output stream.

writeRenderDiagnosticsJson

cpp

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.

Parameters

Parameter	Description
`out`	Output stream.
`importReport`	Optional report to embed (not stored).

renderDiagnosticsJson

cpp

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

Return structured render diagnostics as a JSON string.

Parameters

Parameter	Description
`importReport`	Optional report to embed.

Returns Same JSON as writeRenderDiagnosticsJson().

estimateRenderPassAccounting

cpp

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.

Returns Estimated pass counts.

transparentDrawDebugView

cpp

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.

Parameters

Parameter	Description
`maxItems`	Maximum entries in backToFrontOrder; 0 returns all.

Returns Transparent draw diagnostics for the internal camera.

cpp

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

Return transparent draw diagnostics for an explicit render camera.

Parameters

Parameter	Description
`camera`	Camera used for sorting and the overdraw estimate.
`maxItems`	Maximum entries in backToFrontOrder; 0 returns all.

Returns Transparent draw diagnostics.

shaderWarmupDiagnostics

cpp

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.

Returns Warmup diagnostics (queries GL program state; GL context required).

linkedShaderNames

cpp

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.

Returns Sorted program names.

warmupNextShader

cpp

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.

Parameters

Parameter	Description
`done` (out)	Set to true when nothing was left to compile, false otherwise.

Returns Milliseconds spent compiling. Throws std::runtime_error when a shader fails.

compileShaderByName

cpp

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 (the high-fidelity PBR mesh program) is typically the dominant cost for content rendering, so pre-warming only that one avoids most of the visible "freeze" on the first content frame without paying for unused shader variants. Must be called on the thread that owns the GL context.

Parameters

Parameter	Description
`name`	Built-in program name (see linkedShaderNames()).

Returns Milliseconds spent compiling. Throws std::runtime_error when the shader fails.

recommendMaterialTextureBudget

cpp

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. Texture sizes are queried from GL, so call it with this renderer's GL context current.

Parameters

Parameter	Description
`budgetBytes`	Texture memory budget in bytes; 0 selects the preset default.

Returns Recommendation; apply recommendedSettings yourself if desired.

writeRenderDiagnosticsFiles

cpp

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.

Parameters

Parameter	Description
`directory`	Output directory, created if needed; files such as `render_diagnostics.json` and `mesh_diagnostics_full.json` are overwritten.
`importReport`	Optional report to embed.

setDOFEnabled

cpp

void setDOFEnabled(bool e)

Enable or disable depth of field post-processing.

Overwritten by setRenderQualitySettings() (depthOfFieldEnabled).

Parameters

Parameter	Description
`e`	True to enable.

setDOFParams

cpp

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

Set depth of field parameters.

Parameters

Parameter	Description
`focusDist`	Focus distance in view space.
`focusRange`	Focus range around the focus distance.
`maxRadius`	Max blur radius in pixels.

Overwritten by setRenderQualitySettings().

setShowCollisionBodies

cpp

void setShowCollisionBodies(bool show)

Toggle rendering of collision shapes for articulated systems.

Parameters

Parameter	Description
`show`	True to render collision bodies (default false).

getShowCollisionBodies

cpp

bool getShowCollisionBodies() const

Return collision-body rendering state.

Returns True if collision bodies are shown.

setExternalFont

cpp

void setExternalFont(ImFont *font)

Provide an ImGui font to use for the viewer overlay.

Also installed as ImGui's default font when an ImGui context exists.

Parameters

Parameter	Description
`font`	Pointer to an ImGui font (not owned).

getExternalFont

cpp

ImFont *getExternalFont() const

Retrieve the external ImGui font pointer.

Returns Font pointer or nullptr.

Static member functions

Weather

defaultWeatherSettings static

cpp

static WeatherSettings defaultWeatherSettings(WeatherPreset preset)

Default settings for a weather preset (CPU only).

Parameters

Parameter	Description
`preset`	Preset to expand.

Returns Settings with enabled = true, High quality, 13:00 local time.

loadTextureWithTiling static

cpp

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

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

Parameters

Parameter	Description
`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.

The texture gets GL_REPEAT wrapping, mipmaps, and the process-wide defaults from setDefaultTextureFilteringQuality(). Results are cached per thread and per GL context by (path, sRGB flag), so repeated calls return the same id; a failed load is cached as 0 too. Requires a current GL context.

updateSingleChannelTexture static

cpp

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 (and reallocated if the dimensions differ). New textures use linear filtering and clamp-to-edge wrapping. Requires a current GL context.

Parameters

Parameter	Description
`existingTextureId`	Texture to update, or 0 (or a deleted id) to create one.
`width`	Width in pixels; must be positive.
`height`	Height in pixels; must be positive.
`data`	`width * height` tightly packed bytes; must not be null.

Returns The texture id (new or reused), or 0 on invalid input.

loadHdrEquirectangularCubemap static

cpp

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

Parameter	Description
`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.

createHdrIrradianceCubemap static

cpp

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

Parameter	Description
`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.

createHdrPrefilteredEnvironmentCubemap static

cpp

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

Parameter	Description
`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.

createSplitSumBrdfLut static

cpp

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. The result is an RG16F texture (x = N.V, y = roughness).

Parameters

Parameter	Description
`size`	LUT width and height in texels.
`sampleCount`	GGX samples per texel.

Returns OpenGL texture id owned by the caller, or 0 if either argument is not positive.

setTextureAnisotropy static

cpp

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

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

Parameters

Parameter	Description
`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.

setTextureFilteringQuality static

cpp

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 bias to [-1, 2].

Parameters

Parameter	Description
`target`	Texture target such as GL_TEXTURE_2D.
`textureId`	OpenGL texture id; 0 is ignored.
`anisotropy`	Requested anisotropy, see setTextureAnisotropy().
`mipLodBias`	Mip LOD bias, clamped to [-1, 2].

setDefaultTextureFilteringQuality static

cpp

static void setDefaultTextureFilteringQuality(
    float anisotropy,
    float mipLodBias)

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

Parameters

Parameter	Description
`anisotropy`	Default anisotropy, clamped to [1, 16].
`mipLodBias`	Default mip LOD bias, clamped to [-1, 2].

getDefaultTextureFilteringQuality static

cpp

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

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

Parameters

Parameter	Description
`anisotropy` (out)	Default anisotropy.
`mipLodBias` (out)	Default mip LOD bias.

setTextureSamplerState static

cpp

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.

Parameters

Parameter	Description
`target`	Texture target such as GL_TEXTURE_2D.
`textureId`	OpenGL texture id; 0 is ignored.
`wrapS`	GL wrap mode for S (e.g. GL_REPEAT).
`wrapT`	GL wrap mode for T.
`minFilter`	GL minification filter.
`magFilter`	GL magnification filter.

loadColorTextureWithTiling static

cpp

static unsigned int loadColorTextureWithTiling(const char *path)

Load an albedo/emissive color texture as sRGB.

Parameters

Parameter	Description
`path`	Path to an image file supported by stb_image.

Returns OpenGL texture id, or 0 on failure.

loadDataTextureWithTiling static

cpp

static unsigned int loadDataTextureWithTiling(const char *path)

Load a data texture as linear values.

Parameters

Parameter	Description
`path`	Path to an image file supported by stb_image.

Returns OpenGL texture id, or 0 on failure.

createOffscreenGlContext static

cpp

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

Create a hidden SDL window and an offscreen OpenGL context.

If the calling thread already has a current SDL OpenGL context, the new context joins its share group. This lets worker renderers reuse immutable untextured mesh buffers while retaining context-local VAOs and render targets. With no current context, an independent root context is created. Initializes SDL video if needed and requests an OpenGL 4.3 core context, falling back to 3.3. The new context is left current on the calling thread. Aborts (RSFATAL) when the window or context cannot be created. The caller owns both handles (SDL_GL_DeleteContext / SDL_DestroyWindow).

Parameters

Parameter	Description
`window`	Output pointer for the created SDL window.
`glContext`	Output handle for the OpenGL context.
`title`	Window title for the hidden SDL window.

makeOffscreenContextCurrent static

cpp

static void makeOffscreenContextCurrent(
    SDL_Window *window,
    SDL_GLContext glContext)

Make an existing offscreen context current and update glbinding.

Also resets rayrai's per-context binding caches. Aborts (RSFATAL) on a null argument or when SDL cannot make the context current.

Parameters

Parameter	Description
`window`	SDL window owning the OpenGL context.
`glContext`	OpenGL context to make current.

detachOffscreenGlContext static

cpp

static void detachOffscreenGlContext(SDL_Window *window)

Detach the GL context currently bound to window on this thread.

createOffscreenGlContext leaves the context it made current on the calling thread, so a context created on the main thread has to be released before a worker can adopt it with makeOffscreenContextCurrent — a context is current on at most one thread at a time. Safe to call with no context current.

Parameters

Parameter	Description
`window`	SDL window whose context should be released; nullptr is a no-op.

prewarmShadersForCurrentContext static

cpp

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.

Side effect: the temporary renderer re-applies the process-wide shader settings (one compile thread, binary cache enabled at shaderBinaryCacheDirectory, cache logging off), like any constructor.

Parameters

Parameter	Description
`threadingMode`	Must match the mode used by the worker threads that will eventually construct their own `RayraiWindow`s. Defaults to `MultiThread` since prewarming only makes sense when other threads will also render.
`shaderBinaryCacheDirectory`	Optional explicit cache directory. Empty selects the default per-user cache directory (see the RayraiWindow constructor).

reflectionProbeCaptureFrame static

cpp

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.

Parameters

Parameter	Description
`face`	Face index in GL order (+X, -X, +Y, -Y, +Z, -Z), clamped to [0, 5].

Returns The face's camera basis.

loadReflectionProbeSidecar static

cpp

static std::vector<ReflectionProbeSidecarProbe> loadReflectionProbeSidecar(
    const std::string &sceneFile,
    ReflectionProbeSidecarSettings *settings=nullptr,
    std::string *loadedSidecarPath=nullptr)

Parse the reflection-probe sidecar that belongs to a scene file (CPU only).

Sidecar lookup (shared by all sidecar loaders): if sceneFile itself ends in .json it is used; otherwise <sceneFile>.rayrai_probes.json, then <dir>/<stem>.rayrai_probes.json. The first existing file wins. Nothing is captured; use the returned entries with captureFilteredReflectionProbe().

Parameters

Parameter	Description
`sceneFile`	Scene/mesh file path, or the sidecar path itself.
`settings` (out)	Optional `quality` block; reset to defaults first.
`loadedSidecarPath` (out)	Optional path of the file that was read (empty if none).

Returns Parsed probes; empty when no sidecar exists or it has no probes array.

loadReflectionProbeSidecarResult static

cpp

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

Struct-returning overload; prefer this in new code.

Parameters

Parameter	Description
`sceneFile`	Scene/mesh file path, or the sidecar path itself.

Returns Probes, quality settings and the sidecar path.

loadEnvironmentSidecar static

cpp

static EnvironmentSidecarSettings loadEnvironmentSidecar(
    const std::string &sceneFile,
    std::string *loadedSidecarPath=nullptr)

Parse a scene's .rayrai_environment.json sidecar (CPU only).

Uses the same lookup as loadReflectionProbeSidecar().

Parameters

Parameter	Description
`sceneFile`	Scene/mesh file path, or the sidecar path itself.
`loadedSidecarPath` (out)	Optional path of the file that was read (empty if none).

Returns Parsed values with presence flags; all flags false when no sidecar exists.

loadWeatherSidecar static

cpp

static WeatherSidecarSettings loadWeatherSidecar(
    const std::string &sceneFile,
    std::string *loadedSidecarPath=nullptr)

Parse a scene's .rayrai_weather.json sidecar (CPU only).

Uses the same lookup as loadReflectionProbeSidecar(). Weather keys are read from a weather object when present, otherwise from the top level.

Parameters

Parameter	Description
`sceneFile`	Scene/mesh file path, or the sidecar path itself.
`loadedSidecarPath` (out)	Optional path of the file, set only when it contained weather or fog data.

Returns Parsed settings; both presence flags false when nothing was found.

writeWeatherSidecar static

cpp

static bool writeWeatherSidecar(
    const std::string &sidecarFile,
    const WeatherSettings &settings,
    const std::vector<LocalFogVolume> &localFogVolumes={})

Write weather settings (and optional fog volumes) as a weather sidecar JSON file.

Parameters

Parameter	Description
`sidecarFile`	Output path; overwritten.
`settings`	Weather settings to write.
`localFogVolumes`	Fog volumes to write; at most kMaxLocalFogVolumes are written.

Returns False when the file cannot be opened for writing.

defaultRenderQualitySettings static

cpp

static RenderQualitySettings defaultRenderQualitySettings(RenderQualityPreset preset)

Return the default settings for a named preset.

Parameters

Parameter	Description
`preset`	Preset to query.

Returns Settings that setRenderQualityPreset() would apply.

recommendDynamicQuality static

cpp

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 never change settings. Otherwise, when the summed GPU time exceeds the preset budget, shadow-bound frames stop per-frame shadow updates, fill-bound frames lower viewerRenderScale by 15 % (not below 0.6 for Fast, 0.75 otherwise), and post-process-bound frames reduce bloom/AO/indirect-lighting cost.

Parameters

Parameter	Description
`settings`	Current settings.
`preset`	Preset that selects the budget (see DynamicQualityRecommendation::targetFrameMs).
`timings`	Pass timings, e.g. from captureRenderPassTimings().

Returns Recommendation.

analyzeRgbaLuminance static

cpp

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.

Parameters

Parameter	Description
`rgba`	RGBA8 pixels (alpha ignored); at most width * height pixels are read.
`width`	Image width in pixels.
`height`	Image height in pixels.

Returns Metrics; zero-filled for empty or invalid input.

recommendExposure static

cpp

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.

Highlights take priority: clipping (> 1 % channels) or p95 above target scales the exposure down to the p95 target; otherwise midtones below 70 % / above 135 % of the median target are corrected toward it without pushing p95 past its target.

Parameters

Parameter	Description
`metrics`	Metrics of an image rendered at `currentExposure`.
`currentExposure`	Exposure used for that image; must be positive.
`targetMedianLuminance`	Desired median display luminance.
`targetP95Luminance`	Desired 95th percentile display luminance.
`minExposure`	Lower clamp for the result; must be positive.
`maxExposure`	Upper clamp for the result.

Returns Recommendation; valid is false for invalid input.

smoothExposure static

cpp

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. Computes current + (target - current) * (1 - exp(-rate * dt)) with both exposures clamped to [minExposure, maxExposure].

Parameters

Parameter	Description
`currentExposure`	Current exposure.
`targetExposure`	Desired exposure.
`deltaSeconds`	Elapsed time in seconds.
`brightenRate`	Rate (1/s) used when the target is brighter.
`darkenRate`	Rate (1/s) used when the target is darker.
`minExposure`	Lower exposure bound.
`maxExposure`	Upper exposure bound.

Returns New exposure; the clamped current exposure when any input is invalid.

analyzeRgbaLuminanceHistogram static

cpp

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.

Parameters

Parameter	Description
`rgba`	RGBA8 pixels.
`width`	Image width in pixels.
`height`	Image height in pixels.
`binCount`	Number of equal-width bins over luminance [0, 1].

Returns Histogram; empty for invalid input.

renderLuminanceHistogramRgba static

cpp

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.

Parameters

Parameter	Description
`histogram`	Histogram to draw.
`width`	Output width in pixels.
`height`	Output height in pixels.

Returns RGBA8 image of width * height pixels, or empty for a non-positive size.

renderCloudDebugRgba static

cpp

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.

Parameters

Parameter	Description
`settings`	Settings providing the cloud parameters.
`width`	Total output width in pixels (panels side by side).
`height`	Output height in pixels.

Returns RGBA8 image, or empty for a non-positive size.

renderRainDebugRgba static

cpp

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.

Parameters

Parameter	Description
`settings`	Settings providing the wet-material parameters.
`diagnostics`	Resolved weather, e.g. weatherDiagnostics().
`width`	Total output width in pixels (panels side by side).
`height`	Output height in pixels.

Returns RGBA8 image, or empty for a non-positive size.

renderSnowDebugRgba static

cpp

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.

Parameters

Parameter	Description
`settings`	Settings providing the snow-material parameters.
`diagnostics`	Resolved weather, e.g. weatherDiagnostics().
`width`	Total output width in pixels (panels side by side).
`height`	Output height in pixels.

Returns RGBA8 image, or empty for a non-positive size.

transformRgbaForOutput static

cpp

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.

Parameters

Parameter	Description
`rgba`	RGBA8 pixels.
`width`	Image width in pixels.
`height`	Image height in pixels.
`transform`	Transform to apply (see RgbaOutputTransform for the order).

Returns Transformed RGBA8 pixels, or empty for invalid input.

analyzeRgbaCalibrationPatches static

cpp

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.

Parameters

Parameter	Description
`rgba`	RGBA8 pixels; must contain at least width * height pixels.
`width`	Image width in pixels.
`height`	Image height in pixels.
`patches`	Reference patches.

Returns Per-patch and aggregate errors.

renderCalibrationPatchReportRgba static

cpp

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

Render a compact calibration error report image from patch metrics.

One row per patch: measured swatch, target swatch, and an error bar that saturates at an RGB error of 0.5.

Parameters

Parameter	Description
`metrics`	Metrics from analyzeRgbaCalibrationPatches().
`width`	Output width in pixels.
`height`	Output height in pixels.

Returns RGBA8 image, or empty for a non-positive size.

recommendCalibrationOutputTransform static

cpp

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.

Parameters

Parameter	Description
`metrics`	Metrics from analyzeRgbaCalibrationPatches().

Returns Recommendation; apply it with transformRgbaForOutput().

Public attributes

Type and limit aliases

Re-exports of namespace-level rayrai types (RenderQuality.hpp, Weather.hpp, SceneEffects.hpp) so they can be spelled RayraiWindow::X. See the aliased type for its documentation.

kMaxAdditionalLights

cpp

static constexpr size_t kMaxAdditionalLights

Maximum number of additional lights kept by addAdditionalLight(); extra lights are dropped.

kMaxAdditionalShadowLights

cpp

static constexpr size_t kMaxAdditionalShadowLights

Maximum number of additional lights that can render shadow maps in one frame.

kMaxLocalFogVolumes

cpp

static constexpr size_t kMaxLocalFogVolumes

Maximum number of local fog volumes kept by addLocalFogVolume().

kMaxProjectedDecals

cpp

static constexpr size_t kMaxProjectedDecals

Maximum number of projected decals kept by addProjectedDecal().

kMaxIrradianceVolumes

cpp

static constexpr size_t kMaxIrradianceVolumes

Maximum number of irradiance volumes kept by addIrradianceVolume().

Internal: static/dynamic layer dirty rect

NDC bounds of the previous frame's dynamic AABB union, used to compute a conservative scissor rect for the current frame's dynamic redraw. Not part of the supported API.

lastDynamicLayerNdcMinX_

cpp

mutable float lastDynamicLayerNdcMinX_

Internal: previous dynamic-layer NDC minimum x.

lastDynamicLayerNdcMinY_

cpp

mutable float lastDynamicLayerNdcMinY_

Internal: previous dynamic-layer NDC minimum y.

lastDynamicLayerNdcMaxX_

cpp

mutable float lastDynamicLayerNdcMaxX_

Internal: previous dynamic-layer NDC maximum x.

lastDynamicLayerNdcMaxY_

cpp

mutable float lastDynamicLayerNdcMaxY_

Internal: previous dynamic-layer NDC maximum y.

lastDynamicLayerDirtyRectValid_

cpp

mutable bool lastDynamicLayerDirtyRectValid_

Internal: the four bounds above are valid.

Ground and heightmap terrain textures

groundTextureId_

cpp

unsigned int groundTextureId_

Ground (halfspace) albedo texture; a procedural checker texture by default.

heightmapTextureId_

cpp

unsigned int heightmapTextureId_

Heightmap albedo texture (sRGB), 0 for none; painted vertex colors tint it.

heightmapNormalTextureId_

cpp

unsigned int heightmapNormalTextureId_

Heightmap tangent-space normal map, 0 for none.

heightmapHeightTextureId_

cpp

unsigned int heightmapHeightTextureId_

Heightmap height (parallax) map, 0 for none.

Camera

CoordinateFrame

FoliageMeshLodBaker

InstancedVisuals

Material

PbrEnvironment

RaisimObject

RayraiGlobalAsset

RayraiWindow

RenderQualitySettings

StreamedFoliage

StreamedTerrain

Visuals

assimp

lidar_grid

tcp_viewer

SceneFileBlock

SceneSync

raisin::RayraiWindow ​

Quick start ​

Lifetime ​

GL context ​

Error model ​

Nested classes ​

Public types ​

AdditionalLight ​

RenderQualityPreset ​

ViewerColorMode ​

ColorGradePreset ​

GlowBlendMode ​

ViewerUpscaleFilter ​

PostProcessDebugMode ​

PointShadowPolicy ​

RenderQualitySettings ​

WeatherPreset ​

WeatherQuality ​

LocalFogVolume ​

WeatherSettings ​

WeatherDiagnostics ​

WeatherSkyEnvironment ​

ProjectedDecal ​

IrradianceVolume ​

WeatherThunderCallback ​

ThreadingMode ​

Constructors & destructor ​

RayraiWindow ​

~RayraiWindow ​

Public member functions ​

setWeatherSettings ​

getWeatherSettings ​

setWeatherThunderCallback ​

setWeatherPreset ​

transitionWeather ​

updateWeather ​

weatherDiagnostics ​

printWeatherDiagnostics ​

generateWeatherSkyEnvironment ​

clearWeatherSkyEnvironment ​

weatherSkyEnvironment ​

setHeightmapPatternResourcePath ​

getHeightmapPatternResourcePath ​

setHeightmapNormalResourcePath ​

getHeightmapNormalResourcePath ​

setHeightmapHeightResourcePath ​

getHeightmapHeightResourcePath ​

setHeightmapTerrainMaterialParameters ​

getHeightmapTerrainNormalStrength ​

getHeightmapTerrainRoughness ​

getHeightmapTerrainDeepParallax ​

getHeightmapTerrainParallaxScale ​

setHeightmapSplatLayer ​

clearHeightmapSplatLayer ​

getHeightmapSplatAlbedoId ​

getHeightmapSplatControlId ​

getHeightmapSplatPrimaryUvScale ​

getHeightmapSplatSecondaryUvScale ​

getHeightmapSplatControlBounds ​

hasHeightmapTerrainTextures ​

applyHeightmapTerrainTextures ​

addLocalFogVolume ​

raisin::RayraiWindow

Quick start

Lifetime

GL context

Error model

Nested classes

Public types

AdditionalLight

RenderQualityPreset

ViewerColorMode

ColorGradePreset

GlowBlendMode

ViewerUpscaleFilter

PostProcessDebugMode

PointShadowPolicy

RenderQualitySettings

WeatherPreset

WeatherQuality

LocalFogVolume

WeatherSettings

WeatherDiagnostics

WeatherSkyEnvironment

ProjectedDecal

IrradianceVolume

WeatherThunderCallback

ThreadingMode

Constructors & destructor

RayraiWindow

~RayraiWindow

Public member functions

setWeatherSettings

getWeatherSettings

setWeatherThunderCallback

setWeatherPreset

transitionWeather

updateWeather

weatherDiagnostics

printWeatherDiagnostics

generateWeatherSkyEnvironment

clearWeatherSkyEnvironment

weatherSkyEnvironment

setHeightmapPatternResourcePath

getHeightmapPatternResourcePath

setHeightmapNormalResourcePath

getHeightmapNormalResourcePath

setHeightmapHeightResourcePath

getHeightmapHeightResourcePath

setHeightmapTerrainMaterialParameters

getHeightmapTerrainNormalStrength

getHeightmapTerrainRoughness

getHeightmapTerrainDeepParallax

getHeightmapTerrainParallaxScale

setHeightmapSplatLayer

clearHeightmapSplatLayer

getHeightmapSplatAlbedoId

getHeightmapSplatControlId

getHeightmapSplatPrimaryUvScale

getHeightmapSplatSecondaryUvScale

getHeightmapSplatControlBounds

hasHeightmapTerrainTextures

applyHeightmapTerrainTextures

addLocalFogVolume

clearLocalFogVolumes

localFogVolumeCount

localFogVolumes

addProjectedDecal

clearProjectedDecals

projectedDecalCount

projectedDecals

addIrradianceVolume

clearIrradianceVolumes

irradianceVolumeCount

irradianceVolumes

addVisualSphere

addVisualBox

addVisualCylinder

addVisualCapsule

addVisualMesh

importVisualScene

threadingMode