Interface RenderOptions

Contribution culling (issue #1682): skip colour batches whose world AABB projects below pixelRadius device pixels (raised to interactingPixelRadius while the camera moves). Applies to the batched draw path only — instanced templates, textured meshes and the no-batches fallback are never contribution-culled. Absent or pixelRadius <= 0 disables it (the default), so snapshot/export renders that omit the option stay exhaustive.

Render the active colour overrides almost full-bright so they POP like a highlight rather than reading as normal lit materials. Used while a clash is focused so the amber/cyan pair stands out. (#1277/#1339)

Declared but never read. This is the only occurrence of the name in the package: nothing sets it and nothing consults it, so it is dead on both ends. Depth testing is decided per pipeline at construction time and is not configurable through RenderOptions; there is no substitute field. Slated for removal; see issue #2731.

Global lighting environment (sun direction/colour, hemisphere ambient, exposure, procedural sky). Omitted/empty uses the default rig. See import('./environment.js').LightingEnvironment.

More cutting planes beyond sectionPlane (#7545), each resolved like it; enabled ones clip, and a fragment must survive all (max 7).

Alpha (0..1) for ghosted meshes under ghostExceptIds. Default 0.12.

X-Ray context mode: every non-selected mesh whose expressId is NOT in this set renders at ghostAlpha, so a focused subset (e.g. a clash pair) stays solid while the rest of the model fades to translucent context.

null/absent disables ghosting. Selected meshes (selectedId/selectedIds) are always exempt, and explicit transparencyOverrides entries win over the ghost alpha. Same id space as isolatedIds (federated global id).

Resolution is per entity, with the same batch partition and the same whole-batch fallback documented on transparencyOverrides: an excepted id sharing a colour batch with ghosted ids stays solid on its own, without having to be in selectedIds as well.

Entities to hide. Change detection is by CONTENT, not reference: the renderer snapshots the set and compares element-wise each frame, so mutating the same Set in place and passing a fresh Set per frame are both correct — and a fresh Set with unchanged content does not invalidate the per-batch visibility caches. An empty set is equivalent to omitting the option. The per-frame compare costs O(set size) membership checks.

Only show these entities (null/absent = no isolation). Unlike hiddenIds, an EMPTY set is meaningful: it isolates nothing, hiding everything. Same content-based change-detection contract as hiddenIds.

LOD selection (issue #1682 phase 5): batches whose world AABB projects below screenPx device pixels draw their simplified LOD1 index range (when one was built — see Scene.setLodBuildsEnabled) instead of full detail. Absent or screenPx <= 0 = always full detail.

Frame-local resolution cap; cannot exceed the persistent renderer cap.

One-shot capture renders (IDS/clash/BCF snapshots): synchronously rebuild every GPU-evicted batch before drawing, so isolation options that reveal batches aged out under the residency budget still capture a complete image. Has a frame-time cost proportional to the evicted set — do NOT pass it on the interactive render loop (evicted batches restore asynchronously there).

Sun cast shadows (issue #2670, Phase 2). When enabled, the renderer runs a depth pre-pass from the sun before the colour pass, rasterising every geometry path (flat / quantized / instanced / textured) into a shadow map, then samples it in the shading pass with a rotated 12-tap Poisson-disk PCF kernel to occlude the direct sun term. Absent or enabled: false (the default) skips the pass entirely, so the hot path pays only a boolean check.

• resolution: square shadow-map side in texels. 0 or unset means Auto — the renderer picks from the device's texture limit (2048 on a 4096-capped iGPU, 4096 on an 8192+ GPU). A manual value is honoured but clamped to the device limit so it can't fail texture allocation. A device/Quality dial.
• sunAngleDeg: the sun's apparent angular diameter in degrees (default ~0.53, the real sun on a clear sky). It sets shadow-edge SOFTNESS, not the sun position: larger widens the penumbra. The renderer maps it to the PCF kernel radius (pcfRadius ≈ clamp(sunAngleDeg × 3, 0.75, 8) texels), so a later PCSS swap can consume the same angle without a UI change.

Per-frame alpha overrides — primary use case is X-Ray mode.

Map<expressId, alpha 0..1>. Non-selected meshes/batches whose expressId appears in this map render at the override alpha through the transparent pipeline. Selected meshes (selectedId / selectedIds) are exempt at every site, so highlights always paint with their own alpha.

The alpha applies to THOSE ENTITIES, not to their colour batch (#4129): a batch whose entities no longer share one alpha is drawn as one sub-batch per distinct alpha. A batch that cannot be partitioned — its CPU geometry was released or evicted, it is colour-merged, or it carries more than 8 distinct alphas — falls back to the minimum override alpha across its non-selected ids, so degrading fades too much, never too little.

The renderer snapshots this map at frame start, so callers may freely mutate or recycle their copy after render() returns.

Note: alphas >= 0.99 are treated as opaque (the cutoff for switching to the transparent pipeline). Entries at or above that threshold are no-ops — keep them out of the map to avoid unnecessary work.