Projected-density guard — the shader keep-fraction ladder.
Consumes the per-node density the tracker in projected-density.ts
measures each frame and, for nodes whose blend mode sums energy
(additive / luminous / volumetric — isBlendableMode), thins the DRAW to
a keep fraction of the elements: the material's uDensityDrop uniform
makes the vertex stage discard every element whose hashed storage index
falls below 1 − keep, and applyLodFade multiplies the node's opacity
by 1/keep so the composited brightness stays at the unthinned aggregate.
Sorted alpha-over (normal) nodes are thinned too, compensated in ALPHA
rather than opacity: uDensityAlphaExp = 1/keep raises each survivor's
alpha to 1 − (1 − α)^(1/keep), so keep·N survivors transmit what N
elements did (exact for a stack of equal-alpha layers; the colour of what
shows through is the surviving elements'). max and opaque are never
thinned — a max-projection or an opaque surface has no such knob.
The guard stays OFF for the whole of an offline capture
(setCaptureActive): an export is a quality render, and its frames must
not depend on what the interactive framing happened to thin.
Shaded triangle meshes are excluded: they tile a surface rather than stack
emissive energy, and their materials do not carry uDensityDrop.
Why: on element-dense views the frame cost is elements per pixel, not
pixels (2026-09 audit: 1.5 M points framed into ~1 600 px → 42 ms at DPR 1,
83 ms at DPR 0.5). Beyond a few elements per pixel every further element
is overdraw the eye cannot resolve. The ladder is quantised
(1, 1/2, 1/4, … minKeepFraction) with hysteresis so a slow zoom does
not flicker between steps, and every step change is a CONTENT change for
the adaptive-DPR controller (notifyContentChanged), never per-frame
churn.
Hot-path invariants: no per-frame allocation (the guard mutates the
tracker's records and the mesh's own material in place) and idempotent
per-frame re-assertion of the uniform, so a material rebuilt or replaced
behind the guard's back cannot leave the brightness term without its
thinning (or vice versa).
Projected-density guard — the shader keep-fraction ladder.
Consumes the per-node density the tracker in
projected-density.tsmeasures each frame and, for nodes whose blend mode sums energy (additive / luminous / volumetric —isBlendableMode), thins the DRAW to akeepfraction of the elements: the material'suDensityDropuniform makes the vertex stage discard every element whose hashed storage index falls below1 − keep, andapplyLodFademultiplies the node's opacity by1/keepso the composited brightness stays at the unthinned aggregate. Sorted alpha-over (normal) nodes are thinned too, compensated in ALPHA rather than opacity:uDensityAlphaExp = 1/keepraises each survivor's alpha to1 − (1 − α)^(1/keep), sokeep·Nsurvivors transmit whatNelements did (exact for a stack of equal-alpha layers; the colour of what shows through is the surviving elements').maxandopaqueare never thinned — a max-projection or an opaque surface has no such knob. The guard stays OFF for the whole of an offline capture (setCaptureActive): an export is a quality render, and its frames must not depend on what the interactive framing happened to thin. Shaded triangle meshes are excluded: they tile a surface rather than stack emissive energy, and their materials do not carryuDensityDrop.Why: on element-dense views the frame cost is elements per pixel, not pixels (2026-09 audit: 1.5 M points framed into ~1 600 px → 42 ms at DPR 1, 83 ms at DPR 0.5). Beyond a few elements per pixel every further element is overdraw the eye cannot resolve. The ladder is quantised (1, 1/2, 1/4, …
minKeepFraction) with hysteresis so a slow zoom does not flicker between steps, and every step change is a CONTENT change for the adaptive-DPR controller (notifyContentChanged), never per-frame churn.Hot-path invariants: no per-frame allocation (the guard mutates the tracker's records and the mesh's own material in place) and idempotent per-frame re-assertion of the uniform, so a material rebuilt or replaced behind the guard's back cannot leave the brightness term without its thinning (or vice versa).