raisin::Visuals

class · #include <rayrai/Visuals.hpp>

Renderable visual object not owned by raisim::World.

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

The world transform is position, then orientation, then a per-axis scale applied in the mesh's local frame (Z-up world, quaternions passed as wxyz). Built-in primitives and file meshes come from RayraiGlobalAsset and are shared with other visuals; per-visual appearance belongs in the color, material override/remap/overlay and flags below rather than in the shared meshes. Setters only change state (and renderRevision()); GL work happens when the renderer draws, so drawing requires a current GL context.

Nested classes

• struct FrameCacheMaterialState — Summarize static frame-cache material state in one mesh traversal.
• class FrameCacheMaterialStateMemo — Internal: memo keyed by mesh list, letting visuals that share meshes reuse frameCacheMaterialState() results.
• struct MaterialSortKeys — Internal: materialSortKey() for the three common render modes.

Public types

VisibilityRangeFadeMode

enum class VisibilityRangeFadeMode

How setVisibilityRange() thresholds are applied.

Enumerator	Description
Disabled	Hard cut at the thresholds.
Self	Alpha-fade this visual across the margins.
Dependencies	Stored only; the renderer treats it like Disabled (hard cut).

ShadowCastingMode

enum class ShadowCastingMode

Shadow-map participation.

Enumerator	Description
Off	Not drawn into shadow maps.
On	Cast shadows (default).
DoubleSided	Cast shadows from both faces.
ShadowsOnly	Cast shadows but skip the color pass.

Constructors & destructor

Visuals

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

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

Sphere, box, cylinder and capsule use the shared unit primitives (see RayraiGlobalAsset); size them with the set*Size() methods. Mesh loads meshFile through assets (possibly asynchronously, see RayraiGlobalAsset::getMeshes()). Other shape types, a null assets or a missing file leave the visual invalid (isValid() false).

Parameters

Parameter	Description
type	Raisim shape type to render.
name	Visual name.
assets	Global asset cache for primitive meshes.
meshFile	Mesh file path when type is Mesh.

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

Construct a visual from custom OpenGL meshes.

The shape type is Mesh and the list is shared, not copied. Automatic mesh LOD is enabled.

Parameters

Parameter	Description
name	Visual name.
meshes	Mesh list to render; null makes the visual invalid.

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

Construct a visual from custom OpenGL meshes.

Parameters

Parameter	Description
name	Visual name.
meshes	Mesh list to render; null makes the visual invalid.
automaticMeshLodEnabled	Generate and use automatic mesh LODs.

~Visuals

~Visuals() = default

Public member functions

Material queries

Internal: renderer pass-selection queries over the visual's draw materials (override, remaps and overlay included). Each mirrors the RaisimObject query of the same name.

hasPbrMeshes

bool hasPbrMeshes() const

Returns True when any draw material uses the PBR shader.

hasHighFidelityPbrMeshes

bool hasHighFidelityPbrMeshes() const

Returns True when any PBR draw material requires the high-fidelity PBR path.

hasTransmissivePbrMeshes

bool hasTransmissivePbrMeshes() const

Returns True when any PBR draw material needs the transmission pass.

hasProximityFadePbrMeshes

bool hasProximityFadePbrMeshes() const

Returns True when any PBR draw material uses proximity fade.

usesDefaultDepthAndStencilState

bool usesDefaultDepthAndStencilState() const

Returns True when every draw material uses default depth/stencil state.

hasFullPbrMeshes

bool hasFullPbrMeshes() const

Returns True when any PBR draw material cannot use a compact PBR shader.

hasFoliageFastPbrMeshes

bool hasFoliageFastPbrMeshes() const

Returns True when any draw material can use the foliage fast-PBR path.

hasWeatherEligiblePbrMeshes

bool hasWeatherEligiblePbrMeshes() const

Returns True when any draw material reacts to active weather.

hasSimpleMeshes

bool hasSimpleMeshes() const

Returns True when any draw material uses the simple shader.

hasPlanarReflectionMeshes

bool hasPlanarReflectionMeshes() const

Returns True when any PBR draw material uses planar reflection.

hasProceduralGroundCheckerMeshes

bool hasProceduralGroundCheckerMeshes() const

Returns True when any draw material enables Material::proceduralGroundChecker.

setSphereSize

void setSphereSize(double radius)

Set sphere radius (uniform scale of the unit-radius sphere).

Parameters

Parameter	Description
radius	Sphere radius in metres.

setBoxSize

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

Set box dimensions (scale of the unit cube).

Parameters

Parameter	Description
x	Full box length along local X, in metres.
y	Full box length along local Y, in metres.
z	Full box length along local Z, in metres.

setCylinderSize

void setCylinderSize(double radius, double height)

Set cylinder dimensions (scale of the unit cylinder, axis along local Z).

Parameters

Parameter	Description
radius	Cylinder radius in metres.
height	Cylinder height in metres.

setCapsuleSize

void setCapsuleSize(double radius, double height)

Set capsule dimensions.

For a Capsule visual this regenerates a private capsule mesh (only when the size changes) and resets the scale to 1; for other types it sets the scale to (radius, radius, height).

Parameters

Parameter	Description
radius	Capsule radius in metres.
height	Height of the cylindrical section (excluding the caps), in metres.

setMeshScale

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

Set mesh scale factors (applied in the mesh's local frame).

Parameters

Parameter	Description
x	Scale in X.
y	Scale in Y.
z	Scale in Z.

setDefaultPrimitivePbrEnabled

void setDefaultPrimitivePbrEnabled(bool enabled)

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

Edits the material of the shared primitive mesh, so every visual using the same primitive is affected. No-op for mesh visuals.

Parameters

Parameter	Description
enabled	True to allow the PBR pass.

shapeType

raisim::Shape::Type shapeType() const

Returns Shape type this visual was created with (or set via setShapeType()).

setShapeType

void setShapeType(raisim::Shape::Type type)

Change the recorded shape type without touching the meshes; it affects shading type, bounds estimation and LOD eligibility.

Parameters

Parameter	Description
type	New shape type.

configureGroundMaterial

void configureGroundMaterial(
    bool reflective,
    float roughness,
    float metallic,
    bool proceduralChecker=false,
    const RayraiWindow *terrainTextures=nullptr)

Configure this visual's mesh material as a reflective/non-reflective ground, like RaisimObject::configureGroundMaterial(). Used for ground visuals created over the TCP path which don't go through RaisimObject. Differences: a reflective ground here gets IBL and environment strength 0 (planar reflection only), and a Ground-type visual stops casting shadows. HeightMap visuals only get the terrain material reapplied, with the heightmap terrain textures of terrainTextures when it has any. Edits the mesh materials in place.

Parameters

Parameter	Description
reflective	Use a reflective PBR ground with planar reflection.
roughness	Roughness, clamped to [0.04, 1] (reflective only).
metallic	Metallic factor, clamped to [0, 1] (reflective only).
proceduralChecker	Draw a procedural checker instead of the texture.
terrainTextures	Renderer whose heightmap terrain textures a HeightMap visual takes (see RayraiWindow::applyHeightmapTerrainTextures()), or nullptr.

setPosition

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

Set position from components.

Parameters

Parameter	Description
x	X position in world coordinates (m).
y	Y position in world coordinates (m).
z	Z position in world coordinates (m).

void setPosition(const glm::vec3 &pos)

Set position from a vector.

Parameters

Parameter	Description
pos	Position in world coordinates (m).

setOrientation

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

Set orientation from wxyz quaternion.

The quaternion is used as given (not normalized); pass a unit quaternion.

Parameters

Parameter	Description
w	Quaternion w.
x	Quaternion x.
y	Quaternion y.
z	Quaternion z.

void setOrientation(const glm::vec4 &ori)

Set orientation from wxyz quaternion vector.

Parameters

Parameter	Description
ori	Quaternion (w, x, y, z): ori.x is w and ori.w is z, the same layout getOrientation() returns. The identity is glm::vec4(1, 0, 0, 0).

setColor

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

Set object color from components.

Parameters

Parameter	Description
r	Linear red channel in [0, 1].
g	Linear green channel in [0, 1].
b	Linear blue channel in [0, 1].
a	Alpha channel in [0, 1]; values below 1 route the visual to the transparent pass.

void setColor(const glm::vec4 &color)

Set object color from vector.

Parameters

Parameter	Description
color	Linear RGBA color in [0, 1].

setUseMeshColor

void setUseMeshColor(bool use)

Use mesh-provided colors instead of object color.

Untextured meshes then use their own base color (or material base color); the visual's alpha still multiplies the result.

Parameters

Parameter	Description
use	True to use mesh colors.

usesMeshColor

bool usesMeshColor() const

Check if mesh colors are used.

Returns True if mesh colors are used.

setFlatShading

void setFlatShading(bool enabled)

Force flat shading for this visual (overrides the shape's shading type).

Parameters

Parameter	Description
enabled	True to use flat shading.

isFlatShading

bool isFlatShading() const

Check if flat shading is forced.

Returns True if flat shading is used.

setTwoSided

void setTwoSided(bool enabled)

Disable face culling while drawing this visual.

Parameters

Parameter	Description
enabled	True to draw both sides of mesh triangles.

isTwoSided

bool isTwoSided() const

Check if face culling is disabled for this visual.

Returns True if both sides are drawn.

setPbrEnvironment

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

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

Same as the split overload with no irradiance or prefiltered map.

Parameters

Parameter	Description
environmentMap	GL cubemap id (0 clears).
brdfLut	Split-sum BRDF LUT texture id, or 0.
strength	Environment strength (Material::environmentMapStrength).

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

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

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

The ids are written into the materials of this visual's meshes (and LOD meshes), material override, remaps and overlay, skipping materials that look like plain simple-shaded ones; a non-zero cubemap also switches those materials to Type::PBR. Mesh materials are edited in place, so other visuals sharing the same cached meshes see the change. Texture ids are not owned.

Parameters

Parameter	Description
environmentMap	Radiance/display cubemap id.
irradianceMap	Diffuse irradiance cubemap id, or 0.
prefilteredEnvironmentMap	Prefiltered specular cubemap id, or 0.
brdfLut	Split-sum BRDF LUT texture id, or 0.
strength	Environment strength (capped further for heightmap terrain).
boxProjection	Enable box-projected (parallax-corrected) reflections.
probePosition	Probe capture position in world coordinates.
boxMin	World-space minimum corner of the projection box.
boxMax	World-space maximum corner of the projection box.

void setPbrEnvironment(const PbrEnvironment &env)

Apply a PbrEnvironment bundle to all PBR submeshes.

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

Parameters

Parameter	Description
env	Environment bundle (also carries the box-projection settings).

retainSceneHdrCubemaps

void retainSceneHdrCubemaps(std::array<std::shared_ptr<const unsigned int>, 3> textures)

Keep scene HDR cubemaps alive while this visual uses their texture ids.

setCategory

void setCategory(VisualCategory category)

Set the render category used by capture/detection filters.

The category controls whether this user-created visual is included when a rayrai pass excludes non-detectable visualization objects, such as external camera scene-color renders, capture paths that reuse external-camera rendering, or picking/shadow candidate policies that request detectable custom visuals. The normal interactive viewer includes both categories by default.

This is render metadata only; it does not create collision, physics behavior, or a semantic label. New Visuals default to VisualCategory::NotDetectable.

Parameters

Parameter	Description
category	New render category.

See also VisualCategory

setDetectable

void setDetectable(bool detectable)

Convenience helper for toggling the visual render category.

Parameters

Parameter	Description
detectable	True to include this visual in detectable-only capture/detection render passes; false to keep it viewer-only for those passes.

getPosition

glm::vec3 getPosition() const

Get current position.

Returns Position in world coordinates.

getOrientation

glm::vec4 getOrientation() const

Get current orientation as a wxyz quaternion.

Returns Quaternion with x holding w and w holding z.

getScale

glm::vec3 getScale() const

Get current shape or mesh scale.

Returns Per-axis scale (for primitives this encodes the size set by set*Size()).

getColor

glm::vec4 getColor() const

Get current color.

Returns Linear RGBA color in [0, 1].

getCategory

VisualCategory getCategory() const

Get the render category used by capture/detection filters.

Returns Current visual category.

isDetectable

bool isDetectable() const

Check whether detectable-only render passes include this visual.

Returns True when the category is VisualCategory::Detectable.

setCastsShadows

void setCastsShadows(bool castsShadows)

Enable or disable rendering this visual into shadow maps.

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

Parameters

Parameter	Description
castsShadows	True for ShadowCastingMode::On, false for Off.

castsShadows

bool castsShadows() const

Returns True unless the shadow casting mode is Off.

setShadowCastingMode

void setShadowCastingMode(ShadowCastingMode mode)

Parameters

Parameter	Description
mode	New shadow casting mode.

shadowCastingMode

ShadowCastingMode shadowCastingMode() const

Returns Current shadow casting mode.

castsDoubleSidedShadows

bool castsDoubleSidedShadows() const

Returns True for ShadowCastingMode::DoubleSided.

setColorPassVisible

void setColorPassVisible(bool visible)

Show or hide the visual in color passes without affecting shadow casting.

Parameters

Parameter	Description
visible	False hides it from color passes.

colorPassVisible

bool colorPassVisible() const

Returns The flag set by setColorPassVisible().

visibleInColorPass

bool visibleInColorPass() const

Returns True when color-pass visible and not ShadowCastingMode::ShadowsOnly.

setVisibilityRange

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

Set renderer-side camera visibility range.

A zero begin/end disables that side of the range. Self fade uses the margins to alpha-fade this visual near the begin/end thresholds. Distances are measured from the camera to the visual's bounds center, in metres; negative inputs are clamped to 0. Visuals with self fade are drawn in the transparent pass.

Parameters

Parameter	Description
begin	Hidden when closer than this.
end	Hidden when farther than this.
beginMargin	Half-width of the fade band around begin (Self mode).
endMargin	Half-width of the fade band around end (Self mode).
fadeMode	How the thresholds are applied.

visibilityRangeBegin

float visibilityRangeBegin() const

Returns Near visibility threshold in metres (0 = none).

visibilityRangeEnd

float visibilityRangeEnd() const

Returns Far visibility threshold in metres (0 = none).

visibilityRangeBeginMargin

float visibilityRangeBeginMargin() const

Returns Fade half-width around the near threshold.

visibilityRangeEndMargin

float visibilityRangeEndMargin() const

Returns Fade half-width around the far threshold.

visibilityRangeFadeMode

VisibilityRangeFadeMode visibilityRangeFadeMode() const

Returns Current fade mode.

hasVisibilityRange

bool hasVisibilityRange() const

Returns True when either threshold is non-zero.

visibilityRangeUsesSelfFade

bool visibilityRangeUsesSelfFade() const

Returns True when Self fade is active with a non-zero margin on an enabled side.

visibilityRangeAlpha

float visibilityRangeAlpha(const glm::vec3 &viewPos) const

Parameters

Parameter	Description
viewPos	Camera position in world coordinates.

Returns Visibility-range alpha in [0, 1] at viewPos (1 without a range).

isVisibleAt

bool isVisibleAt(const glm::vec3 &viewPos) const

Parameters

Parameter	Description
viewPos	Camera position in world coordinates.

Returns True when visibilityRangeAlpha() exceeds 0.001.

setMaterialOverride

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

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

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

The override replaces the material of every submesh (and takes precedence over material remaps); the meshes' own OpenGLMesh::textures are then ignored.

Parameters

Parameter	Description
material	Material to draw with; null clears the override.

void setMaterialOverride(const Material &material)

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

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

Parameters

Parameter	Description
material	Material to copy.

clearMaterialOverride

void clearMaterialOverride()

Remove the material override; submeshes use their own (or remapped) materials again.

hasMaterialOverride

bool hasMaterialOverride() const

Returns True when a material override is set.

materialOverride

const Material *materialOverride() const

Returns The override material, or nullptr. Owned by this visual (possibly shared).

mutableMaterialOverride

Material *mutableMaterialOverride()

Mutable accessor for the override material.

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

Returns The override material, or nullptr.

setMaterialRemap

void setMaterialRemap(
    const std::string &sourceName,
    std::shared_ptr<Material> material)

Replace the material of matching submeshes.

A submesh matches when its Material::name or OpenGLMesh::debugSourceMeshName equals sourceName; the key "*" matches every submesh not matched by name. Ignored while a material override is set. The material is shared, not copied.

Parameters

Parameter	Description
sourceName	Material or source-mesh name; empty is ignored.
material	Replacement material; null is ignored.

void setMaterialRemap(
    const std::string &sourceName,
    const Material &material)

Copying overload of setMaterialRemap().

Parameters

Parameter	Description
sourceName	Material or source-mesh name; empty is ignored.
material	Material to copy.

clearMaterialRemaps

void clearMaterialRemaps()

Remove all material remaps.

materialRemapCount

size_t materialRemapCount() const

Returns Number of registered remap keys.

setMaterialOverlay

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

Draw every submesh a second time with this material on top of its normal material.

Parameters

Parameter	Description
material	Overlay material (shared, not copied); null clears it.

void setMaterialOverlay(const Material &material)

Copying overload of setMaterialOverlay().

Parameters

Parameter	Description
material	Material to copy.

clearMaterialOverlay

void clearMaterialOverlay()

Remove the overlay material.

hasMaterialOverlay

bool hasMaterialOverlay() const

Returns True when an overlay material is set.

materialOverlay

const Material *materialOverlay() const

Returns The overlay material, or nullptr.

setTransparency

void setTransparency(float transparency)

Fade the whole visual: drawn alpha is multiplied by (1 - transparency). Values above 0 route the visual to the transparent pass; 1 skips drawing.

Parameters

Parameter	Description
transparency	Value clamped to [0, 1].

transparency

float transparency() const

Returns Transparency in [0, 1].

setCustomBounds

void setCustomBounds(const glm::vec3 &localCenter, float localRadius)

Replace the culling bounds with a sphere given in the visual's local (pre-scale) frame; it is scaled by the largest scale component.

Parameters

Parameter	Description
localCenter	Sphere center in local coordinates.
localRadius	Sphere radius; <= 0 disables custom bounds.

clearCustomBounds

void clearCustomBounds()

Return to automatic bounds.

hasCustomBounds

bool hasCustomBounds() const

Returns True when custom bounds are active.

customBoundsLocalCenter

glm::vec3 customBoundsLocalCenter() const

Returns Custom-bounds center in local coordinates.

customBoundsLocalRadius

float customBoundsLocalRadius() const

Returns Custom-bounds radius in local units.

setTransparentSortOffset

void setTransparentSortOffset(float offset)

Bias the transparent sort: the sort distance is reduced by offset (clamped at 0), so a positive offset draws the visual later (as if closer).

Parameters

Parameter	Description
offset	Distance offset in metres.

transparentSortOffset

float transparentSortOffset() const

Returns Transparent sort offset in metres.

setTransparentSortUsesBoundsCenter

void setTransparentSortUsesBoundsCenter(bool enabled)

Parameters

Parameter	Description
enabled	True (default) to sort by the bounds center, false to sort by getPosition().

transparentSortUsesBoundsCenter

bool transparentSortUsesBoundsCenter() const

Returns Whether the transparent sort uses the bounds center.

transparentSortCenter

glm::vec3 transparentSortCenter() const

Returns World point used for transparent sorting.

transparentSortDistanceSquared

float transparentSortDistanceSquared(const glm::vec3 &viewPos) const

Parameters

Parameter	Description
viewPos	Camera position in world coordinates.

Returns Squared sort distance after applying the sort offset.

hasOpaqueDraws

bool hasOpaqueDraws() const

Returns True when some submesh is drawn in the opaque pass (false whenever the visual alpha, transparency or self fade makes it transparent).

hasTransparentDraws

bool hasTransparentDraws() const

Returns True when some submesh is drawn in the transparent pass.

isTransparent

bool isTransparent() const

Check if visual is translucent based on alpha.

Returns True if the color alpha is below 1, transparency is non-zero, self fade is active, or any draw material needs the transparent pass.

hasSpecialBlendMode

bool hasSpecialBlendMode() const

Returns True when at least one draw material uses a blend mode other than Material::BlendMode::Mix.

renderPriority

int renderPriority() const

Returns Highest material render priority across the visual's draw materials (0 if none).

isValid

bool isValid() const

Check if the visual has valid mesh data.

Returns True if a mesh list is assigned (it may still be empty while loading).

renderRevision

uint64_t renderRevision() const

Internal:

Returns Counter bumped on every render-affecting change; used to invalidate frame caches.

getName

const std::string &getName() const

Returns The visual name used by the renderer.

approximateRadius

float approximateRadius() const

Returns Radius from approximateBounds(), or 0 for an invalid visual.

approximateBounds

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

Conservative world-space bounds for coarse culling.

Uses custom bounds when set, mesh vertex bounds for Mesh/Ground/HeightMap visuals, and otherwise a scale-based estimate around getPosition().

Parameters

Parameter	Description
center (out)	Output sphere center.
radius (out)	Output sphere radius.

Returns False for an invalid visual (outputs hold the scale-based estimate).

shadowGeometryWithinBounds

bool shadowGeometryWithinBounds() const

Returns True when shadow depth draws keep every vertex inside approximateBounds(): no mesh, override, remap or overlay material uses billboards, fixed-size scaling or height displacement.

shadowDepthMayDiscard

bool shadowDepthMayDiscard(bool transparentShadowDithering) const

Returns False only when no mesh (at any LOD), override, remap or overlay material can make a shadow depth draw discard: none uses alpha mask, nor alpha blend while transparentShadowDithering is set.

shadowMaterialSignature

uint64_t shadowMaterialSignature() const

Internal: hash of every material input of a shadow depth draw (mesh materials, textures and base colors, override, overlay and remap targets). OpenGLMesh::material and mutableMaterialOverride() are public and change no render revision, so cached shadow layers compare this too.

hasTextures

bool hasTextures() const

Check if any mesh has textures bound.

Returns True if a mesh (or the override/overlay/remapped material) references a texture.

setAutomaticMeshLodEnabled

void setAutomaticMeshLodEnabled(bool enabled)

Enable automatic mesh LOD generation/selection for mesh visuals.

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

Parameters

Parameter	Description
enabled	True to generate (or fetch cached) LODs; false drops them.

automaticMeshLodEnabled

bool automaticMeshLodEnabled() const

Returns True when automatic mesh LOD is enabled for this visual.

setAutomaticMeshLodBias

void setAutomaticMeshLodBias(float bias)

Scale the projected size used for LOD selection; larger values keep finer LODs longer.

Parameters

Parameter	Description
bias	Multiplier, clamped to [0.01, 16] (default 1).

automaticMeshLodBias

float automaticMeshLodBias() const

Returns Current LOD bias.

automaticMeshLodLevelCount

size_t automaticMeshLodLevelCount() const

Returns Number of available mesh LOD levels including the source mesh at level 0 (0 without meshes).

automaticMeshLodTriangleCount

size_t automaticMeshLodTriangleCount(size_t level) const

Parameters

Parameter	Description
level	LOD level; 0 is the source mesh.

Returns Triangle count for one mesh LOD level, or 0 for an invalid level.

automaticMeshLodMaxUvClusterSpan

float automaticMeshLodMaxUvClusterSpan(size_t level) const

Parameters

Parameter	Description
level	Generated LOD level (>= 1).

Returns Largest UV span collapsed into one generated LOD vertex (diagnostics); 0 for level 0.

selectAutomaticMeshLodLevel

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

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

Parameters

Parameter	Description
viewPos	Camera position in world coordinates.
verticalFovDeg	Camera vertical field of view in degrees.
viewportHeight	Viewport height in pixels; <= 0 selects level 0.

Returns Selected level (0 = source mesh).

draw

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

Draw the visual using a shader.

Always uses the source mesh (no LOD) and ignores the visibility range. Sets the shadingType, model and objectColor uniforms and draws each submesh (plus the overlay material, if any) with OpenGLMesh::draw(). The shader must already be in use; requires a current GL context.

Parameters

Parameter	Description
shader	Shader to use for drawing.
mode	Material filter (see OpenGLMesh::RenderMode).

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

Draw the visual using camera-aware automatic mesh LOD.

Like draw(Shader&, OpenGLMesh::RenderMode) but selects a LOD level and applies the visibility-range alpha for viewPos.

Parameters

Parameter	Description
shader	Shader that is already in use.
viewPos	Camera position in world coordinates.
verticalFovDeg	Camera vertical field of view in degrees.
viewportHeight	Viewport height in pixels.
mode	Material filter.

drawWithBoundShader

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

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

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

Parameters

Parameter	Description
shader	Shader that is already in use.
mode	Material filter.

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

Equivalent to the camera-aware draw(); kept for API parity.

Parameters

Parameter	Description
shader	Shader that is already in use.
viewPos	Camera position in world coordinates.
verticalFovDeg	Camera vertical field of view in degrees.
viewportHeight	Viewport height in pixels.
mode	Material filter.

drawSorted

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

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

This is intended for transparent mesh visuals. It is more expensive than draw(), so rayrai only uses it on the transparent visual path. Submeshes are ordered by material render priority, then by distance (farthest first). Uses the source mesh (no LOD) and applies the visibility-range alpha.

Parameters

Parameter	Description
shader	Shader that is already in use.
viewPos	Camera position in world coordinates.
mode	Material filter.

drawsInMode

bool drawsInMode(OpenGLMesh::RenderMode mode) const

Whether drawSorted() in this mode would rasterize anything. Transparent items are submitted once per shader, and a glass-only visual has nothing for the simple and non-transmissive passes; asking first avoids their program binds and per-object submission entirely.

Parameters

Parameter	Description
mode	Material filter.

Returns True if some submesh (or overlay pass) would be drawn in mode.

materialSortKey

uint64_t materialSortKey(OpenGLMesh::RenderMode mode) const

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

Parameters

Parameter	Description
mode	Render mode the draws will use.

Returns Hash-like key combining the submeshes' OpenGLMesh::materialSortKey(); sort only, not unique.

frameCacheMaterialState

FrameCacheMaterialState frameCacheMaterialState(FrameCacheMaterialStateMemo *memo=nullptr) const

Internal: compute FrameCacheMaterialState in one traversal of the submeshes.

Parameters

Parameter	Description
memo	Optional memo to read/write (ignored for non-default PBR environments).

Returns The summarized state.

setMeshes

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

Replace mesh data for this visual.

The list is shared, not copied. Automatic LODs are rebuilt, asset-level LOD caching is disabled for this visual, and the stored PBR environment is reapplied to the new meshes.

Parameters

Parameter	Description
meshes	New mesh list to render; null makes the visual invalid.

updateSingleMeshVertices

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

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

Parameters

Parameter	Description
vertices	New vertex data for the existing mesh.

Returns True when a single mesh was present and updated.

Tangents are recomputed and generated LODs are dropped. The mesh is edited in place (shared users see it) and a GL context must be current.

notifyMeshMaterialsChanged

void notifyMeshMaterialsChanged()

Notify renderer caches after in-place material changes to existing meshes. Also reapplies the stored PBR environment.

applyTextureFilteringQuality

size_t applyTextureFilteringQuality(
    float anisotropy,
    float mipLodBias) const

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

Includes generated LOD meshes; modifies the shared GL texture objects.

Parameters

Parameter	Description
anisotropy	Requested anisotropic filtering level.
mipLodBias	Mip LOD bias.

Returns Number of texture ids updated (summed per mesh).

collectMaterialTextureIds

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

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

Parameters

Parameter	Description
textureIds (in, out)	Ids are appended (duplicates are kept).

accumulateGeometryDiagnostics

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

Accumulate CPU-side mesh geometry diagnostics for this visual.

Parameters

Parameter	Description
diagnostics (in, out)	Totals to add to.
tinyTriangleAreaThreshold	Triangles with smaller (non-zero) area count as tiny.

collectMeshDiagnostics

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

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

Parameters

Parameter	Description
diagnostics (in, out)	One entry is appended per submesh.
tinyTriangleAreaThreshold	Triangles with smaller (non-zero) area count as tiny.