DirectionalLight class Lighting and environment

An infinitely-distant light source (e.g. the sun) that illuminates the whole scene from a single direction.

Attach one to a Scene via Scene.directionalLight; leaving it null gives image-based lighting only (the historical behavior). The analytic contribution is layered on top of the IBL ambient term. The shader normalizes direction, so it need not be unit length.

When castsShadow is true the renderer adds a depth-only shadow pass. Shadows are cascaded: the camera view is split into shadowCascadeCount depth ranges out to shadowMaxDistance, each fit with its own shadow map so near geometry stays crisp over a long view distance. The penumbra is a soft Poisson-disk PCF kernel of radius shadowSoftness, and shadowing fades back to lit at the far edge over shadowFadeRange. Cascaded shadows require the scene to render with a perspective projection.

Constructors

DirectionalLight({Vector3? direction, Vector3? color, double intensity = 3.0, int priority = 0, bool castsShadow = false, bool cacheStaticShadows = true, double shadowFadeRange = 2.0, double shadowSoftness = 0.08, int shadowCascadeCount = 4, double shadowMaxDistance = 150.0, double shadowCascadeSplitLambda = 0.6, int shadowMapResolution = 1024, double shadowDepthBias = 0.02, double shadowNormalBias = 0.02, double shadowAmbientStrength = 0.0, DirectionalShadowFilter shadowFilter = DirectionalShadowFilter.rotatedPoisson, ShadowCasterFaces shadowCasterFaces = ShadowCasterFaces.front, bool contactShadows = false, double contactShadowDistance = 0.3, double angularRadius = 0.005})

Creates a DirectionalLight.

Properties

angularRadius ↔ double

The light's angular radius in radians, driving how quickly DirectionalShadowFilter.pcss penumbras widen with caster distance. The default is close to the physical sun; larger values read as an overcast or stylized key light.

getter/setter pair

cacheStaticShadows ↔ bool

Whether nodes marked shadowStatic are cached across frames.

getter/setter pair

castsShadow ↔ bool

Whether this light casts shadows (adds a shadow-map pass).

getter/setter pair

color ↔ Vector3

Linear RGB color of the light.

getter/setter pair

contactShadowDistance ↔ double

How far the contact-shadow march reaches, in world units. Short distances keep the effect to tight contacts; long ones read as a cheap shadow substitute but show screen-space artifacts sooner.

getter/setter pair

contactShadows ↔ bool

Marches the camera depth buffer toward the light for small-scale contact shadowing that shadow-map resolution and bias miss. Runs on the screen-space occlusion chain (enabling this adds those passes even with ambient occlusion off) and needs a perspective camera. Applies whether or not castsShadow is set.

getter/setter pair

direction ↔ Vector3

The direction the light travels, in world space (from the light toward the scene). Need not be unit length.

getter/setter pair

hashCode → int

The hash code for this object.

no setter, inherited

intensity ↔ double

Scalar multiplier applied to color.

getter/setter pair

priority ↔ int

Selects the primary directional light when a render feature supports only one, such as cascaded shadows. Higher values win. Equal priorities fall back to the strongest light.

getter/setter pair

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

shadowAmbientStrength ↔ double

How much the cast shadow also darkens the image-based-lighting ambient, from 0.0 to 1.0.

getter/setter pair

shadowCascadeCount ↔ int

Number of shadow cascades, clamped to 1 through 4. More cascades keep shadows crisp over a longer view distance, each at the cost of one more depth pass. Used by computeCascades.

getter/setter pair

shadowCascadeSplitLambda ↔ double

Blends the cascade split spacing between logarithmic (1.0) and uniform (0.0). Higher values give the near cascades proportionally more resolution. Used by computeCascades.

getter/setter pair

shadowCasterFaces ↔ ShadowCasterFaces

Which faces are rendered into the shadow map. Defaults to ShadowCasterFaces.front; use ShadowCasterFaces.back for solid, watertight geometry (e.g. voxel terrain) to remove grazing-angle self-shadow acne.

getter/setter pair

shadowDepthBias ↔ double

World-space depth bias subtracted from the receiver before the shadow test. Converted into each cascade's clip-space depth range, so a caster's shadow appears at the same world-height threshold in every cascade rather than fading out in the coarser far ones.

getter/setter pair

shadowFadeRange ↔ double

World-space width of the band at the far shadow cascade's edge over which shadowing fades back to lit, so the shadow distance limit is soft rather than a hard cutoff. 0 disables the fade.

getter/setter pair

shadowFilter ↔ DirectionalShadowFilter

The percentage-closer filtering pattern used to sample the shadow map.

getter/setter pair

shadowMapResolution ↔ int

Pixel resolution of the (square) shadow map. With cascades this is the resolution of each cascade's tile.

getter/setter pair

shadowMaxDistance ↔ double

View distance, in world units, out to which computeCascades spreads the shadow cascades. Beyond it surfaces are unshadowed.

getter/setter pair

shadowNormalBias ↔ double

World-space offset along the surface normal applied to the receiver before the shadow lookup ("normal-offset shadows"). Flutter GPU has no slope-scaled depth-bias rasterizer state, so this carries the load of acne removal on grazing surfaces.

getter/setter pair

shadowSoftness ↔ double

World-space radius of the shadow penumbra. Larger values give a softer shadow edge; 0 gives a hard edge. Sampled by a rotated Poisson-disk PCF kernel.

getter/setter pair

Methods

computeCascades(Camera camera, double aspectRatio, [Vector3? worldDirection]) → List<ShadowCascade>

Builds the shadowCascadeCount shadow cascades that cover camera's view out to shadowMaxDistance, for a render target of the given aspectRatio. Returned near-to-far.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Properties

defaultDirection → Vector3

Default world-space travel direction for scene-level lights.

no setter