RaiSim

Appearance

Get started

raisin::Light ​

class · #include <rayrai/Light.hpp>

Simple light with optional shadow map support.

Supports all LightType models and owns the shadow-map framebuffer and depth textures used by the renderer. GL resources are created lazily by the shadow pre-pass methods (which need a current OpenGL context) and released in the destructor when the creating context is current; otherwise the ids are dropped without deletion. Non-copyable and non-movable.

Constructors & destructor ​

Light ​

cpp
Light()

Default constructor creates a directional light.

No GL resources are created here; the shadow framebuffer is allocated on first use, so construction does not need a GL context.

cpp
Light(const Light &) = delete
cpp
Light(Light &&) = delete

~Light ​

cpp
~Light()

Public member functions ​

operator= ​

cpp
Light &operator=(const Light &) = delete
cpp
Light &operator=(Light &&) = delete

setAsDirectional ​

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

Configure as a directional light.

Parameters

ParameterDescription
dirDirection pointing from the light toward the scene (normalized here).
diffColorDiffuse color (linear RGB).

setAsPoint ​

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

Configure as a point light.

Parameters

ParameterDescription
posLight position in world coordinates.
diffColorDiffuse color (linear RGB).

setSpotAngles ​

cpp
void setSpotAngles(float innerDeg, float outerDeg)

Set the spotlight cone half-angles in degrees.

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

Parameters

ParameterDescription
innerDegHalf-angle in degrees where falloff begins.
outerDegHalf-angle in degrees where light reaches zero.

setRange ​

cpp
void setRange(float rangeMeters)

Set the attenuation of a point, spot or area light from its range in metres.

Sets the inverse-quadratic coefficients 1, 4.5/range and 75/range^2: full intensity at the source, about 1% (1/80.5) at the range, and still decreasing beyond it (it never reaches zero, and the range does not limit which objects the light shades). Use this instead of writing constant/linear/quadratic by hand. radius, the source size, is not changed.

Parameters

ParameterDescription
rangeMetersDistance at which the light contribution falls to about 1%.

ensureShadowFramebuffer ​

cpp
bool ensureShadowFramebuffer()

Create or resize the shadow framebuffer and 2D depth texture.

Requires a current OpenGL context. Resources created in a different context are discarded and recreated.

Returns Always true.

Exceptions

ExceptionDescription
std::runtime_error(via the framebuffer completeness check) if the framebuffer is incomplete; resources are discarded in that case.

shadowPrePass ​

cpp
bool shadowPrePass()

Prepare for 2D shadow depth rendering.

Ensures the framebuffer, updates lightSpaceMatrix_, binds the FBO, sets the viewport, clears depth, enables polygon offset and disables face culling (restored by shadowPostPass()). Requires a current GL context.

Returns Always true; failures throw as in ensureShadowFramebuffer().

shadowPrePassInto ​

cpp
bool shadowPrePassInto(unsigned int framebuffer, bool clearDepth)

Prepare 2D shadow depth rendering into another framebuffer.

Same as shadowPrePass() but binds framebuffer, whose depth attachment must match the allocated shadow map size, and clears depth only when clearDepth is set. Call ensureShadowFramebuffer() first.

Parameters

ParameterDescription
framebufferFramebuffer to render into.
clearDepthClear the depth attachment before rendering.

Returns Always true.

updateShadowMatrix ​

cpp
void updateShadowMatrix(int snapResolution)

Recompute lightSpaceMatrix_ (used by standalone shadow maps and atlas tiles).

Directional lights use an orthographic box (see setShadowOrtho()) around the shadow center; spot lights a perspective frustum fitted to the outer cone; area lights a 150 degree frustum; point lights a 90 degree frustum.

Parameters

ParameterDescription
snapResolutionShadow-map resolution in texels used to snap directional shadows to the texel grid (reduces shimmering).

pointShadowPrePassFace ​

cpp
bool pointShadowPrePassFace(int face)

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

Updates lightSpaceMatrix_ and the face's entry in pointLightSpaceMatrices_, then binds that cubemap face for depth rendering. Requires a current GL context.

Parameters

ParameterDescription
faceCubemap face index in OpenGL order [0, 5] (clamped).

Returns Always true; failures throw std::runtime_error.

shadowPostPass ​

cpp
void shadowPostPass()

Restore the caller's face-cull state, disable polygon offset and bind the default framebuffer after shadow rendering.

setShadowResolution ​

cpp
void setShadowResolution(int res)

Set shadow-map resolution.

Releases existing shadow resources when the value changes; they are recreated at the new size on the next pre-pass.

Parameters

ParameterDescription
resShadow map size in pixels (min 64; also capped at the driver's maximum texture size on allocation).

setShadowsEnabled ​

cpp
void setShadowsEnabled(bool e)

Enable or disable shadow sampling.

Parameters

ParameterDescription
eTrue to enable shadows.

setShadowParams ​

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

Set shadow bias and filtering parameters.

Parameters

ParameterDescription
biasDepth bias to reduce acne.
strengthShadow darkening strength.
pcfRadiusPCF filter radius in shadow-map texels.

setShadowOrtho ​

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

Configure the shadow projection volume.

Parameters

ParameterDescription
halfSizeHalf-size of the orthographic box (directional lights only), in metres.
zNearNear plane in metres (all light types).
zFarFar plane in metres (all light types).

setShadowCenter ​

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

Set the center point used for directional shadow projection.

Parameters

ParameterDescription
centerWorld-space center.

setShadowPosition ​

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

Override the light position used for directional shadow projection.

Parameters

ParameterDescription
posWorld-space light position.
enableTrue to use the custom position, false to revert to auto position.

Public attributes ​

Color terms

Linear RGB multipliers (not clamped; values above 1 brighten). The ambient term is added without distance attenuation.

ambient ​

cpp
glm::vec3 ambient

Constant term added regardless of surface orientation.

diffuse ​

cpp
glm::vec3 diffuse

Lambertian term.

specular ​

cpp
glm::vec3 specular

Highlight term.

Attenuation

Inverse-quadratic falloff for point, spot and area lights: intensity / (constant + linear*r + quadratic*r^2) where r is in metres (never less than radius). Ignored for directional lights. Use setRange() for a more ergonomic alternative.

constant ​

cpp
float constant

Constant denominator term.

linear ​

cpp
float linear

Coefficient of r (1/m).

quadratic ​

cpp
float quadratic

Coefficient of r^2 (1/m^2).

Projector (light cookie)

Optional 2D texture that tints the light; not applied to point lights.

projectorMap ​

cpp
unsigned int projectorMap

GL 2D texture id; 0 disables. Not owned by the light.

projectorStrength ​

cpp
float projectorStrength

Blend toward the projector color, [0, 1]; 0 disables.

projectorUvScaleOffset ​

cpp
glm::vec4 projectorUvScaleOffset

Projector UV transform: uv * xy + zw.

Camera-distance fade

When enabled, non-directional lights fade out smoothly over [distanceFadeBegin, distanceFadeBegin + distanceFadeLength] of camera distance.

distanceFadeEnabled ​

cpp
bool distanceFadeEnabled

Enable the camera-distance fade.

distanceFadeBegin ​

cpp
float distanceFadeBegin

Metres from camera.

distanceFadeShadow ​

cpp
float distanceFadeShadow

Metres from camera at which the shadow starts fading.

distanceFadeLength ​

cpp
float distanceFadeLength

Metres of fade band.

Internal shadow state

Public for the renderer; prefer the setters above.

shadowFbo_ ​

cpp
unsigned int shadowFbo_

Shadow framebuffer id (shared by the 2D and cubemap passes).

shadowDepthTex_ ​

cpp
unsigned int shadowDepthTex_

2D shadow depth texture (directional/spot/area).

shadowCubeDepthTex_ ​

cpp
unsigned int shadowCubeDepthTex_

Point-light cubemap depth texture.

shadowRes_ ​

cpp
int shadowRes_

Requested shadow-map resolution (set via setShadowResolution()).

shadowAllocatedRes_ ​

cpp
int shadowAllocatedRes_

Allocated 2D depth texture size; 0 when unallocated.

shadowCubeAllocatedRes_ ​

cpp
int shadowCubeAllocatedRes_

Allocated cubemap face size; 0 when unallocated.

lightSpaceMatrix_ ​

cpp
glm::mat4 lightSpaceMatrix_

World-to-light-clip matrix from the last updateShadowMatrix()/pre-pass.

pointLightSpaceMatrices_ ​

cpp
std::array<glm::mat4, 6> pointLightSpaceMatrices_

Per-face matrices from pointShadowPrePassFace().

shadowsEnabled_ ​

cpp
bool shadowsEnabled_

Set via setShadowsEnabled().

shadowBias_ ​

cpp
float shadowBias_

Set via setShadowParams().

shadowStrength_ ​

cpp
float shadowStrength_

Set via setShadowParams().

shadowPCFRadius_ ​

cpp
float shadowPCFRadius_

Set via setShadowParams() (texels).

shadowOrthoHalfSize_ ​

cpp
float shadowOrthoHalfSize_

Set via setShadowOrtho() (m).

shadowNear_ ​

cpp
float shadowNear_

Set via setShadowOrtho() (m).

shadowFar_ ​

cpp
float shadowFar_

Set via setShadowOrtho() (m).

shadowCenter_ ​

cpp
glm::vec3 shadowCenter_

Set via setShadowCenter().

shadowPosition_ ​

cpp
glm::vec3 shadowPosition_

Set via setShadowPosition().

shadowUseCustomPosition_ ​

cpp
bool shadowUseCustomPosition_

Set via setShadowPosition().

type ​

cpp
LightType type

Active light type.

position ​

cpp
glm::vec3 position

World-space light position (point, spot and area lights).

direction ​

cpp
glm::vec3 direction

Direction the light travels, i.e. pointing from the light toward the scene (directional, spot and area lights). Need not be unit length.

spotInnerCos ​

cpp
float spotInnerCos

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

spotOuterCos ​

cpp
float spotOuterCos

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

radius ​

cpp
float radius

Light source size in metres. It is not a cutoff: the attenuation distance is clamped to at least this value (area lights use a quarter of it, min 0.1 m), and for area lights it also softens specular highlights.

areaSize ​

cpp
glm::vec2 areaSize

Area-light width (along areaRight) and height (along areaUp) in metres.

areaRight ​

cpp
glm::vec3 areaRight

Area-light width axis in world space (normalized by the shader).

areaUp ​

cpp
glm::vec3 areaUp

Area-light height axis in world space (normalized by the shader).

negative ​

cpp
bool negative

Subtract this light's contribution instead of adding it.

temperatureEnabled ​

cpp
bool temperatureEnabled

Tint the color terms by temperatureKelvin (normalized to D65).

temperatureKelvin ​

cpp
float temperatureKelvin

Kelvin.

RaiSim — physics for robotics and AI.

© 2026 RaiSim Tech Inc.