raisin::Material

class · #include <rayrai/Material.hpp>

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

Plain data: every field is public and read when the material is drawn. usesPbrShading() decides the shader: a material whose type is SIMPLE_COLOR or TEXTURED and whose other fields keep their defaults is drawn by the cheaper simple mesh shader, while Type::PBR (the default) or any PBR-only feature selects the PBR shader; forceSimpleShading overrides both. Texture fields hold OpenGL texture ids that the material does not own (0 = unused). Colors are linear RGB(A) in [0, 1] unless noted.

Nested classes

• struct AlphaSettings — Grouped alpha-handling configuration.
• struct FoliageSettings — Grouped foliage wind/weather authoring fields.
• struct ParallaxSettings — Grouped tangent-space heightmap / parallax controls.
• struct TextureBindingInfo — One row of textureBindingTable(): how applyTo() binds a material texture.
• struct TextureSlotInfo — Static per-slot metadata for the TextureSlot enum.
• struct UvTransform — Per-texture UV transform (glTF KHR_texture_transform style).
• struct VertexDisplacementSettings — Grouped height-map vertex-displacement controls.

Public types

TextureSlot

enum class TextureSlot

Material texture slots, indexing textureUvTransforms and textureSlotInfo().

Enumerator	Description
Albedo
Normal
BentNormal
Metallic
Roughness
MetallicRoughness
Ao
Emissive
Clearcoat
ClearcoatRoughness
ClearcoatNormal
SheenColor
SheenRoughness
Transmission
Refraction
Thickness
Subsurface
SubsurfaceTransmittance
Backlight
Anisotropy
WeatherMask
Rim
Height
DetailMask
DetailAlbedo
DetailNormal
Lightmap
TextureBlend
Count	Number of slots (not a valid slot).

Type

enum class Type

Defines the user-facing type of material for easier configuration.

Only Type::PBR forces the PBR shader by itself; SIMPLE_COLOR and TEXTURED use the simple mesh shader unless a PBR-only feature is set (see usesPbrShading()).

Enumerator	Description
SIMPLE_COLOR	Basic diffuse material with a solid color.
TEXTURED	A simple textured material (uses albedoMap).
PBR	Full PBR material with metallic/roughness properties.

NormalMapConvention

enum class NormalMapConvention

Tangent-space normal-map convention.

Enumerator	Description
OpenGL	+Y/green-up normal maps.
DirectX	-Y/green-down normal maps, common in Unreal assets.

AlphaMode

enum class AlphaMode

glTF-style alpha handling for imported materials.

Enumerator	Description
Opaque	Alpha ignored.
Mask	Discard texels with alpha below alphaCutoff.
Hash	Stochastic (dithered) alpha test, scaled by alphaHashScale.
Blend	Alpha-blended in the transparent pass.

BlendMode

enum class BlendMode

Godot-style transparent compositing mode.

Enumerator
Mix
Add
Subtract
Multiply
PremultipliedAlpha

AlphaAntiAliasing

enum class AlphaAntiAliasing

Godot-style alpha-edge smoothing for masked materials.

Enumerator
Off
AlphaToCoverage
AlphaToCoverageAndToOne

DistanceFadeMode

enum class DistanceFadeMode

Godot-style distance fade behavior.

Enumerator
Disabled
PixelAlpha
PixelDither
ObjectDither

DiffuseMode

enum class DiffuseMode

Godot-style direct diffuse BRDF mode.

Enumerator
Burley
Lambert
LambertWrap
Toon

SpecularMode

enum class SpecularMode

Godot-style direct specular BRDF mode.

Enumerator
SchlickGgx
Toon
Disabled

ShadingModel

enum class ShadingModel

Higher-level shading-model selection.

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

Enumerator	Description
Standard	Burley diffuse + GGX specular (default PBR look).
Lambert	Lambert diffuse + GGX specular (cheaper PBR).
Toon	Toon diffuse + Toon specular (stylized).
Unlit	Skip lighting entirely; emissive-style flat color.

DetailBlendMode

enum class DetailBlendMode

Detail albedo compositing mode.

Enumerator
SoftMultiply
Mix
Add
Subtract
Multiply

TextureChannel

enum class TextureChannel

Godot-style channel selector for scalar texture maps.

Enumerator
Red
Green
Blue
Alpha
Gray

DepthState

enum class DepthState

Optional per-material OpenGL depth-state override.

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

Enumerator	Description
Inherit	Keep the render pass's state.
Enabled	Force on.
Disabled	Force off.
Inverted	Depth test on with an inverted comparison (depthTest only).

StencilCompare

enum class StencilCompare

Godot-style stencil comparison operator.

Enumerator
Always
Less
Equal
LessOrEqual
Greater
NotEqual
GreaterOrEqual

StencilEffectMode

enum class StencilEffectMode

Automatic stencil-based highlight effects (PBR path).

Enumerator	Description
Disabled	No automatic effect.
Outline	Draw the mesh, then a grown overlay shell where the stencil differs.
Xray	Draw the mesh, then an overlay without depth test where the stencil differs.
Custom	Use the raw stencil fields as authored.

CullMode

enum class CullMode

Per-material face-culling mode.

Enumerator
Back
Front
Disabled

TextureRepeatMode

enum class TextureRepeatMode

Shader-side material texture repeat override.

Enumerator
Inherit
Repeat
Disabled
Mirror

TextureFilter

enum class TextureFilter

Godot-style per-material texture filtering mode.

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

Enumerator
Inherit
Nearest
Linear
NearestWithMipmaps
LinearWithMipmaps
NearestWithMipmapsAnisotropic
LinearWithMipmapsAnisotropic

EmissionOperator

enum class EmissionOperator

Godot-style emission texture compositing operator.

Enumerator
Add
Multiply

BillboardMode

enum class BillboardMode

Camera-facing material billboard mode.

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

Enumerator
Disabled
Enabled
FixedZ
Particles

UvLayer

enum class UvLayer

Detail/material secondary UV selector.

Enumerator
Uv1
Uv2

FoliageType

enum class FoliageType

Viewer-side foliage classification for wind deformation and diagnostics.

Enumerator
None
Grass
LeafCard
Bush
Branch
TreeTrunk
Crop
Vine

Constructors & destructor

Material

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

Construct a new Material object.

Parameters

Parameter	Description
name	A unique name for the material.

Public member functions

isTransmissive

bool isTransmissive() const

Optical transmission of this pass (does not traverse nextPass).

Returns True if transmission or refraction factor is positive or its map is set.

hasTransmissivePass

bool hasTransmissivePass() const

Returns True when this pass or any nextPass isTransmissive().

hasProximityFadePass

bool hasProximityFadePass() const

Returns True when this pass or any nextPass enables proximity fade.

usesDefaultDepthAndStencilState

bool usesDefaultDepthAndStencilState() const

Returns True when this pass and every nextPass render with the pass's own depth test/write and no stencil or decal depth handling.

applyTo

void applyTo(Shader &shader) const

Applies the material's properties to a shader.

This method binds the necessary textures and sets all material-related uniforms on the provided shader before a draw call. It also makes shader the active program. Requires a current GL context.

Parameters

Parameter	Description
shader	The shader to which the properties will be applied.

setShadingModel

void setShadingModel(ShadingModel model)

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

Helper for the common case where callers want "PBR/Lambert/Toon/Unlit" rather than picking a DiffuseMode + SpecularMode pair and remembering to clear the unlit flag. Unlit only sets unlit and leaves the BRDF modes unchanged.

Parameters

Parameter	Description
model	Desired shading model.

shadingModel

ShadingModel shadingModel() const

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

Returns Unlit when the unlit flag is set, otherwise picks the closest Standard/Lambert/Toon based on the current diffuseMode / specularMode. A Toon diffuse or specular mode yields Toon; Burley diffuse yields Standard; anything else yields Lambert.

Returns The classification.

alphaSettings

AlphaSettings alphaSettings() const

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

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

Returns Copy of the alpha fields.

setAlphaSettings

void setAlphaSettings(const AlphaSettings &s)

Write alphaMode, blendMode, alphaAntialiasing from one struct.

Parameters

Parameter	Description
s	Values to write.

foliageSettings

FoliageSettings foliageSettings() const

Returns Copy of the foliage fields.

setFoliageSettings

void setFoliageSettings(const FoliageSettings &f)

Write all foliage fields at once.

Parameters

Parameter	Description
f	Values to write.

parallaxSettings

ParallaxSettings parallaxSettings() const

Returns Copy of the parallax fields.

setParallaxSettings

void setParallaxSettings(const ParallaxSettings &p)

Write all parallax fields at once.

Parameters

Parameter	Description
p	Values to write.

vertexDisplacementSettings

VertexDisplacementSettings vertexDisplacementSettings() const

Returns Copy of the vertex-displacement fields.

setVertexDisplacementSettings

void setVertexDisplacementSettings(const VertexDisplacementSettings &p)

Write both vertex-displacement fields.

Parameters

Parameter	Description
p	Values to write.

usesPbrShading

bool usesPbrShading() const

Decide between the simple and the PBR shader.

Returns False when forceSimpleShading is set; otherwise true for Type::PBR, a next pass, or any field that only the PBR shader implements.

canUseCorePbr

bool canUseCorePbr() const

Returns True when this material (and every next pass) can be drawn by the compact core PBR shader without losing authored features.

canUseFoliageFastPbr

bool canUseFoliageFastPbr() const

Returns True when this material (and every next pass) can use the compact alpha-masked foliage PBR shader.

receivesActiveWeather

bool receivesActiveWeather() const

True when this material actually picks up weather (wetness/snow).

Mirrors the per-material weather gate in the full PBR fragment shader: a non-PBR or non-porous material, or one that opts out of both wetness and snow, receives no weather effect — so it does not require the weather-capable full shader even when weather is globally enabled. Used by the scene-level shader selection so a per-material weather opt-out actually preserves the core/foliage-fast path (it previously did not).

Returns True when any pass in the chain receives weather.

canUseCompactPbr

bool canUseCompactPbr() const

Returns True when either compact PBR shader can reproduce this material.

requiresHighFidelityPbr

bool requiresHighFidelityPbr() const

Returns True when this PBR material (or a next pass) uses transmission, volume, subsurface, backlight, anisotropy, iridescence or sheen, which benefit from the high-fidelity PBR shader.

needsTransparentPass

bool needsTransparentPass() const

Returns True when this material or a next pass must be sorted and rendered by the transparent pass.

hasDepthTestOverride

bool hasDepthTestOverride() const

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

hasDepthWriteOverride

bool hasDepthWriteOverride() const

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

usesInvertedDepthTest

bool usesInvertedDepthTest() const

Returns True when this material wants an inverted depth comparison.

hasStencilOverride

bool hasStencilOverride() const

Returns True when stencilReference is non-negative.

resolveDepthTest

bool resolveDepthTest(bool passDefault) const

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

Parameters

Parameter	Description
passDefault	Depth-test state of the current pass.

Returns Whether depth testing is enabled (Inverted counts as enabled).

resolveDepthWrite

bool resolveDepthWrite(bool passDefault) const

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

Parameters

Parameter	Description
passDefault	Depth-write state of the current pass.

Returns Whether depth writes are enabled.

usesTwoSidedLighting

bool usesTwoSidedLighting() const

Returns True when back-facing fragments should use two-sided lighting (doubleSided or CullMode::Disabled).

textureUvTransform

UvTransform &textureUvTransform(TextureSlot slot)

Parameters

Parameter	Description
slot	Texture slot; must not be TextureSlot::Count (not bounds-checked).

Returns Mutable reference into textureUvTransforms.

const UvTransform &textureUvTransform(TextureSlot slot) const

Parameters

Parameter	Description
slot	Texture slot; must not be TextureSlot::Count (not bounds-checked).

Returns Reference into textureUvTransforms.

hasPerTextureUvTransforms

bool hasPerTextureUvTransforms() const

Returns True when any slot has an authored UV transform.

perTextureUvTransformCount

size_t perTextureUvTransformCount() const

Returns Number of slots with an authored UV transform.

Static member functions

pbr static

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

Build a metallic/roughness PBR material with sensible defaults.

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

Parameters

Parameter	Description
name	Material name.
baseColor	Linear RGBA albedo tint.
metallic	Metallic factor in [0, 1].
roughness	Roughness factor in [0, 1].

Returns The configured material.

glass static

static Material glass(
    std::string name="Glass",
    float thickness=0.0f,
    const glm::vec3 &tint=glm::vec3(1.0f),
    float attenuationDistance=1.0f,
    float roughness=0.04f,
    float indexOfRefraction=1.5f)

Dielectric glass. Zero thickness represents a thin window; positive thickness is an authored world-space optical path length for a solid. Tint is the transmitted color after attenuationDistance world units. Keep alpha at one: transmission, not coverage, makes glass transparent. Enable RenderQualitySettings::screenSpaceRefraction for scene transmission. Sets transmissionFactor = 1 and metallic = 0; a thin pane (thickness <= 0) is also made double-sided.

Parameters

Parameter	Description
name	Material name.
thickness	Optical path length in world units (clamped to >= 0).
tint	Transmitted color, clamped to [0, 1].
attenuationDistance	Distance at which tint is reached (min 1e-4).
roughness	Surface roughness.
indexOfRefraction	IOR, clamped to [1, 3].

Returns The configured material.

unlitColor static

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

Build an unlit material that ignores scene lighting.

Useful for HUD elements, debug visuals, holograms, light-emitting decals. Named unlitColor rather than unlit to avoid colliding with the bool unlit data member. Sets unlit, which selects the PBR shader's unlit path.

Parameters

Parameter	Description
name	Material name.
color	Linear RGBA color.

Returns The configured material.

simpleColor static

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

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

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

Parameters

Parameter	Description
name	Material name.
color	Linear RGBA color.

Returns The configured material.

foliage static

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

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

Sets foliageType, a PBR type with roughness 0.85 and metallic 0, and doubleSided (no culling, two-sided lighting). Other foliage fields keep their defaults; in particular foliageWindStrength stays 0, so there is no wind deformation until it is set.

Parameters

Parameter	Description
name	Material name.
foliageKind	Foliage category.
baseColor	Linear RGBA albedo tint.

Returns The configured material.

defaultGround static

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

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

Convenient default for the world's ground plane / heightmap when no authored material is supplied. Base color 0.55 grey, roughness 0.9, metallic 0.

Parameters

Parameter	Description
name	Material name.

Returns The configured material.

textureBindingTable static

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

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

Returns Static table with one entry per bindable map (including IBL cubemaps).

textureSlotName static

static const char *textureSlotName(TextureSlot slot)

Parameters

Parameter	Description
slot	Texture slot.

Returns Slot name (e.g. "albedo"), or "unknown" for out-of-range values.

textureSlotInfo static

static const TextureSlotInfo &textureSlotInfo(TextureSlot slot)

Look up metadata for a texture slot by enum.

Parameters

Parameter	Description
slot	Texture slot.

Returns Metadata describing the slot. Count is invalid and returns an entry named "unknown" with both flags false.

Public attributes

name

std::string name

Material name used for debugging or lookup.

type

Type type

Material type hint; see usesPbrShading() for how it selects the shader.

forceSimpleShading

bool forceSimpleShading

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

baseColorFactor

glm::vec4 baseColorFactor

Base color factor (albedo tint).

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

useVertexColorAsAlbedo

bool useVertexColorAsAlbedo

Multiply base albedo and opacity by mesh vertex colors.

vertexColorIsSrgb

bool vertexColorIsSrgb

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

textureBlendFactor

float textureBlendFactor

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

metallicFactor

float metallicFactor

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

roughnessFactor

float roughnessFactor

Roughness factor (0 smooth, 1 rough); the PBR shader clamps to [0.04, 1].

ao

float ao

Constant ambient-occlusion multiplier (1 = no occlusion), combined with aoMap.

emissiveFactor

glm::vec3 emissiveFactor

Emissive color factor in linear RGB.

iblStrength

float iblStrength

Strength of the simple procedural image-based lighting approximation.

environmentMapStrength

float environmentMapStrength

Blend amount for the optional environment cubemap.

environmentBoxProjection

bool environmentBoxProjection

Enable box-projected parallax correction for local reflection probes.

environmentProbePosition

glm::vec3 environmentProbePosition

Local reflection probe capture position in world space.

environmentBoxMin

glm::vec3 environmentBoxMin

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

environmentBoxMax

glm::vec3 environmentBoxMax

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

normalStrength

float normalStrength

Strength of tangent-space normal-map perturbation.

normalMapYScale

float normalMapYScale

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

bentNormalStrength

float bentNormalStrength

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

normalMapConvention

NormalMapConvention normalMapConvention

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

alphaMode

AlphaMode alphaMode

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

blendMode

BlendMode blendMode

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

renderPriority

int renderPriority

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

nextPass

std::shared_ptr<Material> nextPass

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

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

alphaCutoff

float alphaCutoff

Alpha cutoff used for masked materials.

alphaHashScale

float alphaHashScale

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

alphaAntialiasing

AlphaAntiAliasing alphaAntialiasing

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

alphaAntialiasingEdge

float alphaAntialiasingEdge

Width of the smoothed alpha-test edge.

distanceFadeMode

DistanceFadeMode distanceFadeMode

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

distanceFadeMin

float distanceFadeMin

Camera distance (world units) where fade-out starts.

distanceFadeMax

float distanceFadeMax

Camera distance (world units) where fade-out reaches zero visibility.

proximityFadeEnabled

bool proximityFadeEnabled

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

proximityFadeDistance

float proximityFadeDistance

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

aoStrength

float aoStrength

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

aoLightAffect

float aoLightAffect

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

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

emissiveStrength

float emissiveStrength

Multiplier for emissive texture/factor contribution.

emissionOperator

EmissionOperator emissionOperator

Combine emissiveFactor and emissiveMap by addition or multiplication.

specularFactor

float specularFactor

glTF-style dielectric specular strength multiplier.

specularColorFactor

glm::vec3 specularColorFactor

glTF-style dielectric specular color multiplier.

diffuseMode

DiffuseMode diffuseMode

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

specularMode

SpecularMode specularMode

Direct specular BRDF selector.

ior

float ior

Index of refraction used to derive dielectric F0.

transmissionFactor

float transmissionFactor

Optical transmission strength for thin panes and authored-thickness volumes.

refractionFactor

float refractionFactor

Godot-style screen refraction strength independent of physical transmission.

volumeThicknessFactor

float volumeThicknessFactor

Authored optical path length in world units; zero denotes a thin sheet.

dielectricPriority

int dielectricPriority

Geometry-refraction overlap precedence: larger values win. This is not renderPriority. Use distinct priorities for overlapping different media.

dielectricVolumeId

unsigned int dielectricVolumeId

Nonzero explicitly joins submeshes/visuals into one dielectric volume. Zero gives each visual (or articulated visual body) its own volume.

volumeAttenuationDistance

float volumeAttenuationDistance

Distance over which volume attenuation reaches the authored color.

volumeAttenuationColor

glm::vec3 volumeAttenuationColor

Tinted volume attenuation color for thick glass approximation.

subsurfaceScatteringStrength

float subsurfaceScatteringStrength

Godot-style subsurface scattering strength.

subsurfaceTransmittanceColor

glm::vec3 subsurfaceTransmittanceColor

Tint for subsurface transmittance through thin/soft materials.

subsurfaceTransmittanceDepth

float subsurfaceTransmittanceDepth

Approximate material depth used to damp subsurface transmittance.

subsurfaceTransmittanceBoost

float subsurfaceTransmittanceBoost

Extra gain for subsurface transmittance from back-facing light.

subsurfaceSkinMode

bool subsurfaceSkinMode

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

backlightColor

glm::vec3 backlightColor

Additive backlight tint for thin materials.

metallicTextureChannel

TextureChannel metallicTextureChannel

Channel sampled from metallicMap.

roughnessTextureChannel

TextureChannel roughnessTextureChannel

Channel sampled from roughnessMap.

aoTextureChannel

TextureChannel aoTextureChannel

Channel sampled from aoMap.

refractionTextureChannel

TextureChannel refractionTextureChannel

Channel sampled from transmission/refraction map.

uvScaleOffset

glm::vec4 uvScaleOffset

UV transform as scale.xy and offset.zw.

uvRotation

float uvRotation

UV rotation in radians.

uv2ScaleOffset

glm::vec4 uv2ScaleOffset

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

uv2Rotation

float uv2Rotation

Secondary UV rotation in radians.

textureRepeatMode

TextureRepeatMode textureRepeatMode

Shader-side repeat behavior for material texture coordinates.

textureFilter

TextureFilter textureFilter

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

textureFilterAnisotropy

float textureFilterAnisotropy

Requested anisotropy level for anisotropic textureFilter modes.

albedoTextureForceSrgb

bool albedoTextureForceSrgb

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

albedoTextureMsdf

bool albedoTextureMsdf

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

msdfPixelRange

float msdfPixelRange

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

msdfOutlineSize

float msdfOutlineSize

Optional MSDF outline expansion in source pixels.

billboardMode

BillboardMode billboardMode

Rotate the rendered material geometry toward the active camera.

billboardKeepScale

bool billboardKeepScale

Preserve the model scale when billboardMode is enabled.

particlesAnimHFrames

int particlesAnimHFrames

Horizontal frame count for Godot-style particle atlas animation.

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

particlesAnimVFrames

int particlesAnimVFrames

Vertical frame count for Godot-style particle atlas animation.

particlesAnimLoop

bool particlesAnimLoop

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

particlesAnimFrameProgress

float particlesAnimFrameProgress

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

particleTrailsEnabled

bool particleTrailsEnabled

Stretch particle billboards into renderer-side trail quads.

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

particleTrailLength

float particleTrailLength

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

particleTrailTaper

float particleTrailTaper

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

particleTrailWorldDirection

glm::vec3 particleTrailWorldDirection

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

fixedSize

bool fixedSize

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

fixedSizeScale

float fixedSizeScale

Multiplier for fixed-size material scaling.

usePointSize

bool usePointSize

Render GL point primitives with an authored material point size.

pointSize

float pointSize

Material point size in screen pixels for point primitive meshes.

useZClipScale

bool useZClipScale

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

zClipScale

float zClipScale

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

useFovOverride

bool useFovOverride

Override the apparent camera FOV for this material in degrees.

fovOverrideDegrees

float fovOverrideDegrees

Vertical FOV used when useFovOverride is enabled.

triplanarEnabled

bool triplanarEnabled

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

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

triplanarWorldSpace

bool triplanarWorldSpace

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

triplanarScale

glm::vec3 triplanarScale

Triplanar projection scale along local/world XYZ.

triplanarOffset

glm::vec3 triplanarOffset

Triplanar projection offset along local/world XYZ.

triplanarSharpness

float triplanarSharpness

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

uv2TriplanarEnabled

bool uv2TriplanarEnabled

Triplanar projection for textures that explicitly use secondary UVs.

uv2TriplanarWorldSpace

bool uv2TriplanarWorldSpace

Use world-space coordinates for UV2 triplanar projection.

uv2TriplanarScale

glm::vec3 uv2TriplanarScale

UV2 triplanar projection scale along local/world XYZ.

uv2TriplanarOffset

glm::vec3 uv2TriplanarOffset

UV2 triplanar projection offset along local/world XYZ.

uv2TriplanarSharpness

float uv2TriplanarSharpness

UV2 triplanar blend sharpness.

textureUvTransforms

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

Authored UV transforms per texture slot.

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

clearcoatFactor

float clearcoatFactor

Optional clearcoat layer strength.

clearcoatRoughnessFactor

float clearcoatRoughnessFactor

Optional clearcoat roughness.

iridescenceFactor

float iridescenceFactor

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

iridescenceThickness

float iridescenceThickness

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

sheenFactor

float sheenFactor

Optional cloth/fabric sheen strength.

sheenColorFactor

glm::vec3 sheenColorFactor

Optional cloth/fabric sheen color.

sheenRoughnessFactor

float sheenRoughnessFactor

Optional cloth/fabric sheen roughness.

anisotropyFactor

float anisotropyFactor

Optional anisotropic specular strength for brushed materials.

anisotropyRotation

float anisotropyRotation

Tangent-frame anisotropy rotation in radians.

unlit

bool unlit

Render base color without scene lighting, for glTF KHR_materials_unlit.

proceduralGroundChecker

bool proceduralGroundChecker

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

usePlanarReflection

bool usePlanarReflection

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

planarReflectionStrength

float planarReflectionStrength

Blend strength for planar reflections on this material.

dontReceiveShadows

bool dontReceiveShadows

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

disableAmbientLight

bool disableAmbientLight

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

disableFog

bool disableFog

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

disableSpecularOcclusion

bool disableSpecularOcclusion

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

shadowToOpacity

bool shadowToOpacity

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

doubleSided

bool doubleSided

Disable back-face culling for this material.

cullMode

CullMode cullMode

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

thinTwoSidedLighting

bool thinTwoSidedLighting

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

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

thinBackDiffuseScale

float thinBackDiffuseScale

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

thinTransmissionStrength

float thinTransmissionStrength

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

thinTransmissionColor

glm::vec3 thinTransmissionColor

Tint for generic thin-surface transmitted light.

foliageType

FoliageType foliageType

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

foliageWindStrength

float foliageWindStrength

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

foliageRootHeight

float foliageRootHeight

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

foliageTipHeight

float foliageTipHeight

Local-space height where foliage deformation reaches full strength.

foliageStiffness

float foliageStiffness

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

foliageFlutterWeight

float foliageFlutterWeight

High-frequency leaf/card flutter multiplier.

foliageTwoSidedLighting

bool foliageTwoSidedLighting

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

foliageDepthLodViewCount

int foliageDepthLodViewCount

Fixed depth-capture surfaces: select the nearest captured viewing angle in instanced scene/shadow shaders. Supported layouts: six axis views or eight azimuth views plus two poles (10). Zero uses ordinary geometry.

foliageDepthLodBlendWidth

float foliageDepthLodBlendWidth

Screen-stable coverage blend between neighbouring capture directions. Alignment width in [0, .25]; zero retains the nearest-view selection. This smooths capture rotation, rather than changing the geometry LOD.

foliageTransmissionStrength

float foliageTransmissionStrength

Thin-leaf direct and indirect transmission strength for viewer PBR foliage. High-fidelity indirect lighting also gathers the opposite hemisphere.

foliageTransmissionColor

glm::vec3 foliageTransmissionColor

Linear RGB tint of base color for thin-leaf transmitted light.

foliageWeatherResponse

bool foliageWeatherResponse

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

foliageWetResponse

float foliageWetResponse

Per-material rain/wetness response multiplier for foliage.

foliageSnowResponse

float foliageSnowResponse

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

weatherAffectsWetness

bool weatherAffectsWetness

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

weatherAffectsSnow

bool weatherAffectsSnow

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

weatherPorosity

float weatherPorosity

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

weatherPuddleEligible

bool weatherPuddleEligible

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

weatherSnowEligible

bool weatherSnowEligible

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

rimFactor

float rimFactor

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

rimTint

float rimTint

Blend between neutral rim light and rimColor/texture tint.

rimPower

float rimPower

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

rimColor

glm::vec3 rimColor

Authored rim-light tint color.

growEnabled

bool growEnabled

Extrude vertices along their local normals before rendering this material.

growAmount

float growAmount

Local-space grow extrusion distance.

heightmapScale

float heightmapScale

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

heightmapVertexDisplacementScale

float heightmapVertexDisplacementScale

Local-space vertex displacement distance driven by heightMap.

This moves existing vertices along their normals before rendering. It does not create tessellation; dense meshes show the effect more clearly than coarse meshes.

heightmapVertexDisplacementMidlevel

float heightmapVertexDisplacementMidlevel

Height value treated as the neutral vertex-displacement surface.

heightmapDeepParallax

bool heightmapDeepParallax

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

heightmapMinLayers

int heightmapMinLayers

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

heightmapMaxLayers

int heightmapMaxLayers

Maximum layer count for deep parallax at grazing views.

heightmapFlip

glm::vec2 heightmapFlip

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

heightmapInvert

bool heightmapInvert

Invert sampled height-map values before parallax displacement.

detailAlbedoBlend

float detailAlbedoBlend

Blend amount for detail albedo texture.

detailUvLayer

UvLayer detailUvLayer

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

detailAlbedoBlendMode

DetailBlendMode detailAlbedoBlendMode

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

detailNormalStrength

float detailNormalStrength

Strength for detail tangent-space normal map.

aoUsesUv2

bool aoUsesUv2

Sample the ambient-occlusion texture from secondary UVs.

emissiveUsesUv2

bool emissiveUsesUv2

Sample the emissive texture from secondary UVs.

lightmapUsesUv2

bool lightmapUsesUv2

Sample the baked lightmap texture from secondary UVs.

lightmapStrength

float lightmapStrength

Baked diffuse-indirect lightmap strength.

lightmapTint

glm::vec3 lightmapTint

Optional tint/multiplier for baked lightmap texels.

decalDepthBias

bool decalDepthBias

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

tinySurfaceDetail

bool tinySurfaceDetail

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

depthTest

DepthState depthTest

Optional override for whether this material participates in depth testing.

depthWrite

DepthState depthWrite

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

stencilReference

int stencilReference

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

stencilRead

bool stencilRead

Compare existing stencil values against stencilReference before drawing.

stencilWrite

bool stencilWrite

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

stencilWriteDepthFail

bool stencilWriteDepthFail

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

stencilCompare

StencilCompare stencilCompare

Stencil comparison operator used when stencilRead is enabled.

stencilMask

unsigned int stencilMask

Bit mask used for stencil reads and writes.

stencilEffectMode

StencilEffectMode stencilEffectMode

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

stencilEffectColor

glm::vec4 stencilEffectColor

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

stencilOutlineThickness

float stencilOutlineThickness

Normal-direction expansion used by stencil outline mode.

albedoMap

unsigned int albedoMap

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

foliageTextureAtlasApplied

bool foliageTextureAtlasApplied

True after the foliage atlas path has remapped this material's UVs.

foliageTextureAtlasUvRect

glm::vec4 foliageTextureAtlasUvRect

UV atlas rectangle used by the foliage atlas path: offset.xy, scale.zw.

textureBlendMap

unsigned int textureBlendMap

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

terrainSplatAlbedoMap

unsigned int terrainSplatAlbedoMap

Optional secondary albedo layer used by terrain splat blending.

terrainSplatControlMap

unsigned int terrainSplatControlMap

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

terrainSplatPrimaryUvScale

float terrainSplatPrimaryUvScale

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

terrainSplatSecondaryUvScale

float terrainSplatSecondaryUvScale

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

terrainSplatControlBounds

glm::vec4 terrainSplatControlBounds

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

hasTerrainSplat

bool hasTerrainSplat

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

normalMap

unsigned int normalMap

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

bentNormalMap

unsigned int bentNormalMap

Optional bent normal map for ambient/specular occlusion direction.

metallicMap

unsigned int metallicMap

Metallic map (OpenGL id, 0 if unused).

roughnessMap

unsigned int roughnessMap

Roughness map (OpenGL id, 0 if unused).

metallicRoughnessMap

unsigned int metallicRoughnessMap

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

ormMap

unsigned int ormMap

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

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

aoMap

unsigned int aoMap

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

emissiveMap

unsigned int emissiveMap

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

clearcoatMap

unsigned int clearcoatMap

Optional clearcoat intensity texture, red channel.

clearcoatRoughnessMap

unsigned int clearcoatRoughnessMap

Optional clearcoat roughness texture, red channel.

clearcoatNormalMap

unsigned int clearcoatNormalMap

Optional clearcoat tangent-space normal texture.

sheenColorMap

unsigned int sheenColorMap

Optional sheen color texture, RGB channels.

sheenRoughnessMap

unsigned int sheenRoughnessMap

Optional sheen roughness texture.

transmissionMap

unsigned int transmissionMap

Optional transmission texture, red channel.

refractionMap

unsigned int refractionMap

Optional screen refraction texture.

thicknessMap

unsigned int thicknessMap

Optional volume thickness texture.

subsurfaceMap

unsigned int subsurfaceMap

Optional subsurface scattering strength texture.

subsurfaceTransmittanceMap

unsigned int subsurfaceTransmittanceMap

Optional subsurface transmittance color texture.

backlightMap

unsigned int backlightMap

Optional backlight color texture.

anisotropyMap

unsigned int anisotropyMap

Optional anisotropy texture.

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

anisotropyMapAlphaStrength

bool anisotropyMapAlphaStrength

Read anisotropy strength from anisotropyMap alpha instead of blue.

weatherMaskMap

unsigned int weatherMaskMap

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

rimMap

unsigned int rimMap

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

heightMap

unsigned int heightMap

Optional height map for tangent-space parallax offset.

detailMaskMap

unsigned int detailMaskMap

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

detailAlbedoMap

unsigned int detailAlbedoMap

Optional detail albedo texture.

detailNormalMap

unsigned int detailNormalMap

Optional detail tangent-space normal texture.

lightmapMap

unsigned int lightmapMap

Optional baked diffuse-indirect lightmap.

environmentMap

unsigned int environmentMap

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

irradianceMap

unsigned int irradianceMap

Optional diffuse irradiance cubemap for high-fidelity IBL.

prefilteredEnvironmentMap

unsigned int prefilteredEnvironmentMap

Optional prefiltered specular cubemap for high-fidelity IBL.

brdfLut

unsigned int brdfLut

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

importReport

std::string importReport

Human-readable import notes for debugging material differences.