scene: sun shadow maps

[dvoyni]

Parent

Scene follow-ups. Revisited 2026-09-22 against cog 4e178c7. Blocked by scene: move sceneFrame to a uniform block. Absorbs gfx: depth bias for shadow maps.

What it is

Sun shadow maps for both renderers: a shadow camera renders a depth-only pass, and model's shader multiplies a shadow term into the sun's contribution.

The work spans three bundles:

• model owns the shader and the frame packer: SceneFrame (bundles/model/internal/builtin/scene/frame.wgsl:26) and PackFrameLighting (bundles/model/utils.go:137).
• model also owns the bundled PBR material, which gains the shadow entry.
• scene and ecsscene each own a camera vocabulary and a PassTag (bundles/scene/types.go:38-43, bundles/ecsscene/types.go:144-172). Each needs the link from a lit camera to its shadow source.

The storage budget is 8 of 8 (model.md). A depth texture plus a comparison sampler spend no storage slot, but any per-cascade or per-light shadow data in a buffer needs the slot #100 frees. This ticket is blocked on #100 so that the shadow design is never squeezed by the budget.

Settled, still valid

• The shape is in scene.md §Shadows (Extension points: shadows, post-processing, IBL). A shadow camera is a camera:
  • m.LookAt along SunDirection, with an Orthographic projection;
  • one pass with NoTarget() and DepthTarget(tex);
  • a lower Order than the cameras that sample it.
• What casts is decided by the shadow camera's CullMask and by whether the material has a shadow tag entry. There is no per-draw flag; if one is ever added, its zero value means "casts".
• The sun's contribution only. Punctual-light shadows belong with clustered lighting.
• The frame block grows the light-space matrix and bias. Group 0 grows a texture_depth_2d and a sampler_comparison, with a 1x1 default depth texture bound when there is no shadow. The default is still needed, but for a different reason: since #133, an unbound binding costs that draw with gfx.ErrStorageBufferUnsupplied rather than the whole frame.
• Ordering is gfx's job: write-then-read barriers cover depth attachments (#112, 684e995).
• Depth-only passes run on Vulkan since gogpu/wgpu#353 (pinned v0.34.5) and in the browser. depthOnlyPassesWork (extensions/gogpu/internal/gfxdepthonly.go:56-69) refuses GLES, the software HAL and untried HALs with ErrDepthOnlyPassUnsupported. A pass that depends on the output is only valid where it is encoded.

Depth bias (from #32), acceptance-to-be

• DepthBias, DepthBiasSlopeScale and DepthBiasClamp are added to gfx.MaterialState (slots/gfx/internal/types/state.go:119), all three together. A constant bias misses slanted receivers, and the clamp bounds the peter-panning the slope term causes.
• They are plumbed in depthStencilState (extensions/gogpu/internal/gfxbackend.go:708-717). wgpu.DepthStencilState carries them, with DepthBias as an int32.
• The zero value is WebGPU's "no bias", so the change is additive and needs no migration.
• pipelineKey embeds MaterialState whole (slots/gfx/internal/translator.go:35-45). The two float fields keep it comparable but make it NaN-sensitive as a map key, so NaN must be rejected or canonicalised.
• Defaults ship tuned, not zeroed, on model's shadow entry, against a real shadow-casting demo.
• Bias stays per material, through the shadow tag entry (Pipeline state growth for 3D).

What is still open

• Behaviour on GLES and the software HAL, where the shadow pass is refused: draw unshadowed with a report, or refuse the camera?
• The link field's name and shape, in both scene.CameraDescr and ecsscene.Camera.
• Cascades: N textures and N cameras, an atlas through PassDescr.Viewport, or a DepthTarget that takes a layer. All three are additive, and none is chosen.

Trigger

A demo needs sun shadows, and #100 has landed.

[dvoyni]

Unblocked by gfx/wgpu: no barrier between a pass that renders a texture and a later pass that samples it, closed in 684e995, which named this ticket as blocked.

A shadow map is a depth attachment first and a texture second, and that case is covered specifically: translatePasses looks for write-then-read pairs on the depth attachment as well as the colour one, with TestADepthAttachmentSampledLaterGetsABarrier holding it. So the render-then-sample ordering a shadow pass needs is placed by gfx with no shadow-specific code.

[dvoyni]

Two assumptions in the body above are not true on the desktop today, both for the same reason: #115.

• "The pass side needs no gfx change" — and "Depth-only passes … all ship in v1 as capability". They ship in the API, but the Vulkan HAL never actually began a depth-only render pass, and then faulted when it was ended. cog/wgpu currently refuses such a pass on the native path (depthOnlyPassSupported), so a NoTarget() pass is written but does not execute.
• Item 3's default shadow map is the sharpest case: a NoTarget() pass clearing depth to 1.0 with no draws is precisely the shape that does not run. That 1x1 texture would be left undefined rather than cleared — and per item 3's own reasoning, a wrong-but-bound default is worse than an obvious failure, because nothing reports it.

The upstream fix is written and open as gogpu/wgpu#353; the local tree already builds against it. Nothing here needs to change now — but this effort should not start until #353 has merged, a release carries it, and depthOnlyPassSupported is true on the native path. Otherwise every shadow map here is a browser-only feature.

The other half of #115 still stands regardless of the fix and is worth carrying into the cascade design: scene/spec.md § Passes records that a depth-only pass's output may not be depended on in the same frame. That is the constraint a shadow pass feeding a lit camera in one frame has to negotiate.