Light¶

Inherits: Object
C++ type: Light

Description¶

Represents a light source in a 3D scene. Doriax supports three light types — directional, point, and spot — all sharing the same Light class. The light type determines which properties have effect: a directional light uses direction and an unlimited range, a point light radiates in all directions with a finite range, and a spot light uses both direction and cone angles.

Shadows are opt-in per-light and render via a shadow map. Cascaded shadow maps (CSM) are available for directional lights to spread shadow quality across a large view distance.

Properties¶

Methods¶

Enumerations¶

LightType¶

• DIRECTIONAL - A light that shines uniformly in one direction from infinitely far away, like the sun. Position is irrelevant; only direction matters.
• POINT - A light that radiates equally in all directions from its world-space position, like a light bulb. Use range and intensity to control reach.
• SPOT - A cone-shaped light emanating from its world-space position in the given direction. Use innerConeAngle and outerConeAngle to shape the cone.

Property details¶

type¶

• Setter: void setType(LightType type)
• Getter: LightType getType() const

The light model to use. See LightType for the available values. Changing the type at run-time is supported.

Light sun(&scene);
sun.setType(LightType::DIRECTIONAL);
sun.setDirection(Vector3(-0.5f, -1.0f, -0.5f));

local sun = Light(scene)
sun:setType(LightType.DIRECTIONAL)
sun:setDirection(Vector3(-0.5, -1.0, -0.5))

direction¶

• Setter: void setDirection(Vector3 direction)
• Setter: void setDirection(float x, float y, float z)
• Getter: Vector3 getDirection() const

The normalised direction vector the light shines towards. Used by DIRECTIONAL and SPOT lights.

color¶

• Setter: void setColor(Vector3 color)
• Setter: void setColor(float r, float g, float b)
• Getter: Vector3 getColor() const

The linear-space RGB color of the emitted light. Each channel ranges from 0.0 to 1.0 for standard colours, though values above 1.0 are valid for HDR scenes.

range¶

• Setter: void setRange(float range)
• Getter: float getRange() const

The maximum distance (in world units) at which the light has any effect. Relevant for POINT and SPOT lights. DIRECTIONAL lights have an infinite range and ignore this value.

intensity¶

• Setter: void setIntensity(float intensity)
• Getter: float getIntensity() const

A multiplier applied to the light's color. 1.0 is the default. Higher values create a brighter light without altering the hue.

innerConeAngle / outerConeAngle¶

• Setter: void setConeAngle(float inner, float outer)
• Setter: void setInnerConeAngle(float inner)
• Getter: float getInnerConeAngle() const
• Setter: void setOuterConeAngle(float outer)
• Getter: float getOuterConeAngle() const

Define the shape of a SPOT light. The angle is specified in degrees (or radians if Engine::useDegrees is false).

• innerConeAngle — the full-brightness cone. Everything inside this angle receives 100 % of the light.
• outerConeAngle — the penumbra edge. Light fades to zero between the inner and outer angle.

setConeAngle() sets both values at once.

Light torch(&scene);
torch.setType(LightType::SPOT);
torch.setConeAngle(15.0f, 40.0f);

local torch = Light(scene)
torch:setType(LightType.SPOT)
torch:setConeAngle(15.0, 40.0)

shadows¶

• Setter: void setShadows(bool shadows)
• Getter: bool isShadows() const

Enables shadow map generation for this light. Shadow casting also requires the caster mesh to have castShadows enabled and the receiver mesh to have receiveShadows enabled. See the Mesh documentation.

bias¶

• Setter: void setBias(float bias)
• Getter: float getBias() const

The shadow-map depth bias added to prevent self-shadowing artefacts (shadow acne). Increase this value if you see acne on surfaces; decrease it if you see shadows detaching from geometry (Peter-panning). A good starting value is 0.005.

shadowMapSize¶

• Setter: void setShadowMapSize(unsigned int size)
• Getter: unsigned int getShadowMapSize() const

The resolution of the shadow map texture in pixels (e.g. 512, 1024, 2048). Higher values produce sharper shadows at the cost of GPU memory and fillrate. Must be a power of two.

cameraNear / cameraFar¶

• Setter: void setShadowCameraNearFar(float nearValue, float farValue)
• Setter: void setCameraNear(float nearValue)
• Getter: float getCameraNear() const
• Setter: void setCameraFar(float farValue)
• Getter: float getCameraFar() const

The near and far clip planes of the shadow-map camera. Tighten these around the scene geometry to maximise shadow-map precision. setShadowCameraNearFar() sets both at once.

Has no effect when automaticShadowCamera is true.

automaticShadowCamera¶

• Setter: void setAutomaticShadowCamera(bool automatic)
• Getter: bool isAutomaticShadowCamera() const

When true, the engine automatically fits the shadow-map camera frustum around the visible scene each frame, optimising shadow quality. Disable this if you need manual control over cameraNear / cameraFar.

numCascades¶

• Setter: void setNumCascades(unsigned int numCascades)
• Getter: float getNumCascades() const

Number of cascades for Cascaded Shadow Maps (CSM). Only relevant for DIRECTIONAL lights. More cascades distribute shadow-map resolution more evenly across the view frustum, reducing the "blurry distant shadows" artefact at the cost of additional render passes. Typical values are 1 (off) to 4.