LodComponent class Scene graph

A MeshComponent that draws one of several level-of-detail variants of an object, chosen each frame from how large the object appears on screen.

Supply LodLevels highest detail first, with strictly descending LodLevel.screenSize thresholds (a fraction of the viewport height). The engine picks the highest-detail level whose threshold the object's projected size still meets, and draws nothing once the size falls below the smallest threshold (the cull floor; set the last level's threshold to 0 to never cull). Selection is per view, so the same object can pick different levels in a split-screen frame.

lodBias scales the projected size before selection (above 1 keeps detail at a greater distance), and hysteresis is a dead-band around each threshold so an object hovering on a boundary does not flip-flop.

Because selection is screen-size based it is field-of-view aware and resolution independent. The highest-detail level's bounds are used for frustum culling, so culling stays conservative.

Current limitations:

  • The shadow and depth-prepass passes always draw the highest-detail level and ignore the LOD cull, so a tiny object culled in the color pass can still cast a shadow or write depth (a per-pass LOD bias is future work).
  • Selection memory (for the hysteresis dead-band) is shared across views, so a multi-view frame can see one view's last choice bias another's.
  • Hardware-instanced draws are not supported here; a LodComponent draws a single mesh, so it picks one level for the whole node.
  • A non-perspective camera disables the metric and draws the highest-detail level.
node.addComponent(LodComponent([
  LodLevel(geometry: high, material: mat, screenSize: 0.4),
  LodLevel(geometry: mid, material: mat, screenSize: 0.15),
  LodLevel(geometry: low, material: mat, screenSize: 0.04),
]));
Inheritance

Constructors

LodComponent(List<LodLevel> levels, {double lodBias = 1.0, double hysteresis = 0.1, double blendRange = 0.0})
Creates an LOD component over levels (highest detail first).

Properties

blendRange ↔ double
Half-width of the cross-fade band as a fraction of each threshold. 0 hard-switches between levels; a positive value dither-blends adjacent levels. Settable to toggle or tune cross-fade at runtime.
getter/setter pair
enabled ↔ bool
Whether this component's update hook runs each frame.
getter/setter pairinherited
hashCode → int
The hash code for this object.
no setterinherited
isAttached → bool
Whether this component is currently attached to a node.
no setterinherited
isLoaded → bool
Whether onLoad has completed.
no setterinherited
isMounted → bool
Whether the owning node is part of a live scene graph.
no setterinherited
lodBias ↔ double
Multiplies the projected size before selection. Above 1 keeps higher detail farther away; below 1 drops detail sooner. Settable at runtime.
getter/setter pair
mesh ↔ Mesh
The mesh this component draws.
getter/setter pairinherited
node → Node
The node this component is attached to.
no setterinherited
renderItems → List<RenderItem>
The render items registered for this component's mesh primitives, empty while not mounted. Exposed so a subclass (the LOD component) can tag the items it just registered.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

cloneFor(Node cloneOwner) → Component?
Returns a copy of this component for cloneOwner, the Node.clone counterpart of the owning node, or null to not carry the component to clones (the default).
inherited
fixedUpdate(double fixedDt) → void
Called once per fixed physics step while the component is mounted, enabled, and loaded. fixedDt is the fixed timestep of the surrounding PhysicsWorld, not the frame interval.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
onAttach() → void
Called when this component is added to a node.
inherited
onDetach() → void
Called when this component is removed from a node.
inherited
onLoad() → Future<void>
Optional asynchronous setup, such as loading an asset.
inherited
onMount() → void
Called when the owning node enters a live scene graph.
inherited
onRenderItemsRegistered() → void
Called after this component registers its render items, on mount and on every re-registration (mesh assignment, refreshMaterials).
override
onUnmount() → void
Called when the owning node leaves a live scene graph.
inherited
toString() → String
A string representation of this object.
inherited
update(double deltaSeconds) → void
Called once per frame while the component is mounted, enabled, and loaded. deltaSeconds is the elapsed time since the previous tick.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited