LightNode class final
A light placed in the scene graph.
Direction comes from the node's local -Z, the same forward axis cameras use, so SceneNode.lookAt aims a spot light exactly as it aims a camera.
Constructors
- LightNode({LightType type = LightType.directional, LinearColor color = LinearColor.white, double? intensity, double range = 0.0, bool? castsShadow, double innerConeAngle = 0.0, double outerConeAngle = math.pi / 4.0, String? name})
-
A white light of
type; it casts shadows by default only when it is directional. - LightNode.lumens(double lumens, {LightType type = LightType.point, LinearColor color = LinearColor.white, double range = 0.0, bool? castsShadow, double innerConeAngle = 0.0, double outerConeAngle = math.pi / 4.0, String? name})
-
A light of
typerated atlumensof luminous flux, converted once to the candela intensity holds — Photometric.fromLumens over the light's own cone.
Properties
- castsShadow ↔ bool
-
Whether this light wants a shadow map.
getter/setter pair
- channels ↔ int
-
Which channels this light shines on —
gfx-12n's own row.getter/setter pair -
children
→ List<
SceneNode> -
The direct children, in the order they were added, as an unmodifiable
copy made on each call; see childrenView for a hot loop.
no setterinherited
-
childrenView
→ List<
SceneNode> -
The direct children as a read-only view of the node's own list, made
once: no copy per call, for a hot loop, and nothing added to it skips
add's parent, scene and cycle checks. It changes as the children do.
no setterinherited
- color ↔ LinearColor
-
The light's colour, in linear light —
LinearColorsince 1.0 (it was a mutableVector3). Its alpha is ignored. Replaced whole:light.color = const LinearColor(1.0, 0.8, 0.6).getter/setter pair - debugView ↔ DebugView?
-
The debug view this node and its subtree are drawn with, in place of
the frame's —
A5.21. Null, the default, takes the nearest ancestor's, and the frame'sRenderSettings.debugViewwhere no ancestor sets one.getter/setter pairinherited - debugViewInHierarchy → DebugView?
-
The view this node is drawn with: its own debugView, or the nearest
ancestor's, or null when the frame's applies.
no setterinherited
- hasCullableOwnBounds → bool
-
Whether ownBounds may be culled.
no setterinherited
- hashCode → int
-
The hash code for this object.
no setterinherited
- height ↔ double
-
How tall it is, along the node's local +Y.
getter/setter pair
- innerConeAngle ↔ double
-
Half-angle from the spot axis to where the falloff starts, in radians.
getter/setter pair
- intensity ↔ double
-
How bright this light is: lux for a directional light, candela
for a point, spot or area light — see Photometric (since 1.0; the
engine's own unit before it, one of which is legacyUnit).
getter/setter pair
- inverseSceneMatrix → Matrix4
-
The scene-to-node transform, cached on matrixVersion.
no setterinherited
- isSubtreeAlwaysDrawn → bool
-
Whether anything in this subtree has opted out of frustum culling.
no setterinherited
- isVisible ↔ bool
-
Whether this node and its subtree are drawn.
getter/setter pairinherited
- isVisibleInHierarchy → bool
-
True when this node and every ancestor is visible.
no setterinherited
- layerMask ↔ int
-
Bitmask filtered against a render view's mask: a node is drawn in a view
when the two share a bit. Bit 0 is the default layer.
getter/setter pairinherited
- lightChannels ↔ int
-
Which light channels this node accepts —
gfx-12n.getter/setter pairinherited - localMatrix → Matrix4
-
The node-to-parent transform, from its position, rotation and
scale.
no setterinherited
- matrixVersion → int
-
Changes whenever sceneMatrix changes. Use it as an invalidation key.
no setterinherited
- name ↔ String?
-
A label for lookups, logs and tools, or null; need not be unique.
getter/setter pairinherited
- outerConeAngle ↔ double
-
Half-angle from the spot axis to where the light ends, in radians.
getter/setter pair
- ownBounds → Aabb3?
-
This node's own contribution to subtreeBounds, or null when it draws
nothing.
no setterinherited
- parent → SceneNode?
-
The node this one hangs under, or null for a root or a detached node.
no setterinherited
- range ↔ double
-
Distance at which a point or spot light stops contributing. Zero means
unbounded, matching glTF's default.
In metres.
getter/setter pair
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
- scene → Scene?
-
The scene this node currently belongs to, if any.
no setterinherited
- sceneMatrix → Matrix4
-
The node-to-scene transform, always current: scene space is float32
and relative to Scene.origin (docs/CONTRACTS.md, "Three spaces").
no setterinherited
- subtreeBounds → Aabb3?
-
What this node and everything under it occupies, or null when the subtree
draws nothing.
no setterinherited
- type ↔ LightType
-
What kind of light this is: directional, point, spot, area or a custom
kind built on one of them.
getter/setter pair
- width ↔ double
-
How wide the rectangle is, in metres, along the node's local +X —
gfx-77n. Ignored by every other kind.getter/setter pair - worldPosition → WorldPosition
-
Where this node is in the world, in double precision: its scene's
Scene.origin plus the translation of sceneMatrix.
no setterinherited
Methods
-
add(
SceneNode child) → void -
Adds
child, keeping its local transform (so it moves with this node).inherited -
attach(
SceneNode child) → void -
Adds
childwhile preserving its current scene transform.inherited -
findByName(
String target) → SceneNode? -
First descendant with a matching name, or null.
inherited
-
lookAt(
Vector3 target, {Vector3? up}) → void -
Points the node's local -Z at
target, given in scene space.inherited -
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
onAttachedToScene(
Scene scene) → void -
Hook for subclasses to register themselves in the scene's flat registries.
override
-
onDetachedFromScene(
Scene scene) → void -
Hook for subclasses to leave the scene's flat registries, called when
the node leaves
scene; the counterpart of onAttachedToScene.override -
reaches(
int lightChannels) → bool -
Whether this light reaches a mesh on
lightChannels(a mesh'slightChannelsmask): the test every pass applies before lighting it. -
readDirection(
[Vector3? out]) → Vector3 - World-space direction the light points, i.e. the node's local -Z.
-
readDirectionToLight(
[Vector3? out]) → Vector3 - Direction towards the light, which is what shading maths wants.
-
readHalfHeight(
[Vector3? out]) → Vector3 - The half-height vector, local +Y scaled by half of height.
-
readHalfWidth(
[Vector3? out]) → Vector3 -
The rectangle's half-width vector in scene space, i.e. local +X scaled by
half of width. Mutates and returns
out. -
readPosition(
[Vector3? out]) → Vector3 -
Reads the local position into
outto avoid allocating.inherited -
readRotation(
[Quaternion? out]) → Quaternion -
Reads the local rotation into
out, or a new quaternion when it is null, and returns it.inherited -
readScale(
[Vector3? out]) → Vector3 -
Reads the local scale into
out, or a new vector when it is null, and returns it.inherited -
readScenePosition(
[Vector3? out]) → Vector3 -
The translation of sceneMatrix: this node's position in its scene's
own space, float32 and relative to Scene.origin. worldPosition is
the same point in the world.
inherited
-
remove(
SceneNode child) → void -
Detaches
childfrom this node and from the scene with it. Does nothing whenchildis not a child of this node.inherited -
removeFromParent(
) → void -
Detaches this node from its parent.
inherited
-
setLocalForward(
Vector3 direction, {Vector3? up}) → void -
Aims the node's local -Z along
direction, expressed in the parent's space.inherited -
setLocalMatrix(
Matrix4 value) → void -
Replaces the local transform by decomposing a matrix.
inherited
-
setPosition(
double x, double y, double z) → void -
Sets the local position to
x,yandz, in the parent's space.inherited -
setPositionFrom(
Vector3 value) → void -
Sets the local position from
value, in the parent's space.inherited -
setRotation(
Quaternion value) → void -
Sets the local rotation to
value.inherited -
setRotationYawPitchRoll(
double yaw, double pitch, double roll) → void -
Yaw about Y, then pitch about X, then roll about Z — the order that reads
naturally for cameras and turntables.
inherited
-
setScale(
double x, double y, double z) → void -
Sets the local scale factors along
x,yandz.inherited -
setUniformScale(
double value) → void -
Sets the same local scale factor,
value, on all three axes.inherited -
setWorldPosition(
WorldPosition position) → void -
Moves this node so that worldPosition is
position— what a game placing something by a simulation's double-precision position calls: the difference from the scene's origin is narrowed to float32 once, and taken through the parent's inverse when the node has one.inherited -
toString(
) → String -
A string representation of this object.
inherited
-
translate(
double dx, double dy, double dz) → void -
Moves the local position by
dx,dyanddz, in the parent's space.inherited -
traverse(
void visit(SceneNode child)) → void -
Walks this node and its descendants.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited
Static Properties
- maxExtraLights → int
-
How many lights past maxLights a frame can still carry, in the slots
the clustered path reads: 24. A getter for the reason maxLights is.
no setter
- maxLights → int
-
How many lights one draw is lit by in the forward pass: 8. A light past
this is carried by the extra slots, then dropped — see
Scene.overflowingLights.no setter
Static Methods
-
defaultIntensityFor(
LightType type, {double outerConeAngle = math.pi / 4.0}) → double -
The intensity a light of
typeis made with when none is given: sunIlluminance lux for a directional light, and lampLumens for any other, in candela over the solid angle it covers (Photometric.fromLumens with the spot'souterConeAngle): about 63.7 cd for a point lamp. A plugin's own type takes its base's.
Constants
- lampLumens → const double
- The flux a point, spot or area light puts out when it is given no intensity, in lumens: an ordinary household bulb's 800.
- legacyUnit → const double
-
What one unit of the engine's pre-1.0 intensity is worth in lux, or in
candela for a lamp: 5 790.583578 (
π × 1.6 × 1.2 × 960). A light, an ambient or a sun written before 1.0 withxisx * LightNode.legacyUnitnow. - sunIlluminance → const double
- What a directional light shines with when it is given no intensity, in lux: 15 000, the sun through a thin haze, which the default camera (f/4, 1/60 s, ISO 100) exposes as daylight.