passes

Imported from X-GIS/X-GIS (map/src/render/passes/AGENTS.md). Install upstream with npx skills add X-GIS/X-GIS --skill passes. Copyright stays with the author.

passes

Purpose

Contains the fixed linear render-pass chain that structures every GPU frame in X-GIS. Each file implements the RenderPass interface (defined in pass.ts) and represents one bucket of the pipeline: background → opaque → OIT → translucent → points → labels → heatmap → overdraw-compose. All passes are stateless singletons — no per-frame allocation — that receive a FrameContext + SceneView + PassHost (the owning map's renderer view) and emit GPURenderPassEncoder commands. These objects were extracted verbatim from inline passScope blocks in RenderLoop.render during the engine redesign; behaviour is byte-identical to the original inline code.

Key Files

For AI Agents

Working In This Directory

• Passes are stateless. No instance fields. Per-frame state lives in FrameContext or SceneView; cross-frame state belongs on the PassHost (map).
• shouldRun is the only guard. The RenderLoop calls shouldRun before execute; passes must not re-check scene conditions redundantly inside execute except for truly exceptional paths.
• Colour clear ownership is strict. background-pass.ts owns the colour target clear (bucket 0); opaque-pass.ts always uses loadOp: 'load'. Do not add a clearValue + loadOp: 'clear' to any colour attachment in opaque or later passes.
• Depth persistence contract. Depth is stored (depthStoreOp: 'store') by the last opaque sub-pass when scene.hasPoints || scene.hasOit; the points and OIT passes load it (depthLoadOp: 'load'). Breaking this chain causes billboards or translucent buildings to ignore opaque foreground occlusion.
• resolveOwner chain. MSAA resolve (resolveTarget: ctx.screenView) belongs to exactly one pass per frame, determined by scene.resolveOwner in SceneView. Assigning resolveTarget in the wrong pass produces a WebGPU validation error.
• ?debug=overdraw disables most passes. translucent, oit, points, and labels all gate off; only background, opaque (with overdraw pipeline override), and overdraw-compose run. The accumulator clear (a:0) must come from background-pass; do not re-introduce it in opaque-pass.
• Label projector fork must stay in lockstep with the geometry MVP. label-pass.ts selects flat vs ECEF projector using !globeMode && !isGlobeProj(projType) — the same test getViewForProjection uses. If you change the geometry MVP selection, update the label projector fork to match.
• Do not split hot loops in label-pass.ts without profiling; the per-feature dispatch loop is already perf-marked (encoder.label-dispatch.*).

Testing Requirements

• background-pass-clear-value.test.ts — unit tests for backgroundClearValue() covering all 8 projection types, overdraw mode, and the structural invariant that opaque-pass.ts uses loadOp: 'load'. Run with vitest.
• synthetic-earth-surface-overdraw.test.ts — structural + unit tests verifying that SyntheticEarthSurfaceBackend produces a valid BackendTileResult, routes through the non-extruded opaque path, and that the overdraw pipeline override in opaque-pass.ts applies unconditionally. Run with vitest.
• GPU/render behaviour (correct pass ordering, MSAA resolve, depth persistence) is not covered by unit tests here — it requires the playground e2e suite or a local headed GPU run against the render-verification harness (feat/render-verification-harness).

Common Patterns

• Singleton export: every pass file ends with export const xPass: RenderPass = new XPass().
• ctx.passScope(label, fn) wraps every encoder.beginRenderPass call for GPU timeline labelling.
• scene.overdraw / ctx.overdraw — NEVER DEBUG_OVERDRAW in this directory. The URL flag is a build-time constant; the FRAME truth is device-aware (the mode cannot run where the compose is raw WebGPU), and a pass reading the flag while the targets were routed from the frame truth is a half-gated frame (#1046 Inc-F2d). Evaluate at shouldRun time via scene.overdraw; execute has ctx.overdraw.
• Verbatim relocation comments at the top of each file document what inline block was extracted and what mechanical substitutions were made (this.host.X → host.X); preserve these for future readers.

Dependencies

Internal

• ../frame-context — FrameContext: per-frame GPU resources (encoder, textures, MSAA views) + the opaque projection token (engine-blind; content unwraps it via ../projection-token)
• ../scene-view — SceneView: pre-computed per-frame scene summary (opaque groups, OIT/translucent/points flags, resolveOwner)
• ../../render-loop — RenderLoopHost: typed Pick of the map exposing renderers, camera, and GPU context
• ../../debug-flags — debug URL flags (DEBUG_RHI_CHECKER); overdraw is read from scene.overdraw/ctx.overdraw, never the raw DEBUG_OVERDRAW const
• ../../projection/projections-table — worldBandForProjType, isGlobeProj (projection classification)
• runtime/src/engine/shaders/dsl/cpu-projections — projMercatorCpu (clamped CPU Mercator mirror for label anchors)
• ../../render-loop-helpers — makeLabelProjectors, resolveLabelEffectiveDef
• ../../text/text-stage, ../../sprite/icon-stage — glyph/SDF and icon atlas flush
• @xgis/compiler — evaluate, makeEvalProps, resolveColor (per-feature expression evaluation)

External

• No npm runtime dependencies beyond the monorepo. Test files use vitest and Node's node:fs/node:path for structural source-text assertions.