Overlap & Light Diagnostics

Three fill-pressure families mirror Unreal optimization view modes. They stay orthogonal to Shader Complexity (shaderCost). Enable them from the native runtime via createDebugRenderPlan() flags, or from the optional R3F demo and DebugViews controls.

Source	Label	Question
overdraw	Measured Overlap	How many translucent / alpha-cutout layers survive depth at this pixel?
overdrawVisual	Overlap Visualization (approx)	Additive teaching view — not a layer counter. Opt-in source only.
lightComplexity	Light Overlap	How many dynamic lights reach this pixel? (v1: analytic estimate)

Measured overlap (overdraw)

v1 counts contributors only:

• Counts: transparent meshes, alpha-tested foliage cards, stacked glass-style layers.
• Does not count: opaque solids (cliff, ground, rocks). They write depth in a prepass and occlude contributors behind them.
• Pipeline: opaque depth prepass → ONE ONE blend counter → heatmap. R channel stores count / 16.

Legend: none → heavy. In the R3F demo, select Overlap and use the overlap legend ramp.

?scene=overdraw&debugView=overdraw

The repo Overlap demo tab opens this preset. Foliage cards should read hotter than the opaque cliff.

Caution

Do not use decodeHeatmapCost() for layer counts — that helper is for shader-cost heatmaps only. Measured overlap reads linear R from the diagnostic pass.

Overlap visualization (overdrawVisual)

Godot/Unity-style additive replacement — useful for teaching, not an integer layer counter. Opt-in source only; not in DEFAULT_DEBUG_VIEWS.

Light overlap (lightComplexity)

Label: Light Overlap (source id lightComplexity unchanged).

Fragment-side counter on the default forward renderer:

• Includes: PointLight, SpotLight, RectAreaLight within analytic range / cone / rect proxy.
• Excludes: DirectionalLight, AmbientLight, HemisphereLight, environment IBL.
• v1 limits: no shadow sampling; no clustered/tiled culling parity; custom app lightsNode will not match; rect lights use a bounding proxy.

Legend: Low → High (UE-style blue → cyan → yellow → red → white).

?scene=lights&debugView=lightComplexity

Treat v1 as overlap discovery, not a ground-truth “lights executed in the real shader” read.

Demo scenes

Tab	URL	Default view
Overlap	?scene=overdraw&debugView=overdraw	Measured Overlap
Overlap+Lights	?scene=overlap-lights&debugView=lightComplexity	Light Overlap
Lights	?scene=lights&debugView=lightComplexity	Light Overlap

Overlap+Lights reuses the foliage cliff scene with six overlapping point lights on the shrubs. Switch the View control to compare layer overlap and light overlap on the same geometry.

Social capture preset for overlap breakdown screenshots:

/?capture=social&scene=overdraw

Open the preset in the running demo (pnpm dev) with a WebGPU-capable browser.

Native runtime

Pass-backed flags from createDebugRenderPlan():

• usesOverdrawPass — measured layer overlap subgraph
• usesOverdrawVisualPass — additive approx (optional)
• usesLightComplexityPass — light overlap (v1 analytic)

Plan overlap passes with usesOverdrawPass, usesOverdrawVisualPass, and usesLightComplexityPass from createDebugRenderPlan().

Related

• Native Runtime

• R3F

• Built-in Views

• Shader Cost Heatmap — separate signal from overlap

• Performance Model