# `StageSettings`

> Contract 2.0.0 · package sha256 `a857eca95b35921109faf997094bb4192f12527d9d0fcd4be7e97f06425bad6e` · generated from `configurator-runtime.d.ts` by `services/onsite-scripter/scripts/build-contract-docs.mjs`; edit the source, not this file.

Interface · `import type { StageSettings } from '@holostep-configurators/runtime-client/contract';` · stable · since 2.0.0 · section 9. Stage

Colour pipeline: shading is linear Rec.709 in a frame of at least half-float. AO and bloom act on
that frame; then [`exposureEv`](StageSettings.exposureEv.md), the tone curve and [`grade`](StageSettings.grade.md) apply once, in every render path (live,
low tier, capture). Colour and gradient backgrounds, 'unlit' and `exactColor` surfaces skip
exposure and the curve, not [`grade`](StageSettings.grade.md), which acts on the encoded output ([`grade`](StageSettings.grade.md)); environment and
panorama backdrops take both ([`BackgroundSpec`](BackgroundSpec.md)).
Every field merges over the document's value, and each stage layer over the layers below it
([`Stage.set`](Stage.set.md)).
One runtime-owned exception, render recovery: on a device whose render self-check fails or whose
GPU can't render a half-float target, the runtime drops effects step by step (AO, bloom and
accumulation among them; spec section 5.5). Exposure, the curve and [`grade`](StageSettings.grade.md) still apply once on
every level, so the colours hold; the effects differ.

## Members

| Member | Kind | Summary |
| --- | --- | --- |
| <a id="lights"></a>[`lights?`](StageSettings.lights.md) | property | The runtime's own rig: 'default', 'none' (the rig is off; a collection's light items still shine), or scaled. |
| <a id="environment"></a>[`environment?`](StageSettings.environment.md) | property | Image-based lighting: a built-in ('room', 'studio'), an HDR, or 'none' (no image-based lighting; the lights alone). |
| <a id="background"></a>[`background?`](StageSettings.background.md) | property | What is drawn behind the scene: a colour, a gradient, 'transparent' (the page shows through), 'environment' or an image backdrop ([`BackgroundSpec`](BackgroundSpec.md)). |
| <a id="ground"></a>[`ground?`](StageSettings.ground.md) | property | `on`: draw the ground's shadow on these parts (a floor). |
| <a id="exposureev"></a>[`exposureEv?`](StageSettings.exposureEv.md) | property | Relative stops, 0 = unchanged. |
| <a id="tonemapping"></a>[`toneMapping?`](StageSettings.toneMapping.md) | property | Named curves are formulas published with golden images. |
| <a id="ambientocclusion"></a>[`ambientOcclusion?`](StageSettings.ambientOcclusion.md) | property | `radius`: metres, or 'auto' from role 'product' bounds. |
| <a id="bloom"></a>[`bloom?`](StageSettings.bloom.md) | property | `threshold` is scene-linear. |
| <a id="grade"></a>[`grade?`](StageSettings.grade.md) | property | Applied after the tone curve and the output's sRGB encoding, in every render path, capture included, to every pixel the canvas draws: colour and gradient backgrounds, 'unlit' and `exactColor` surfaces skip exposure and… |

## Declaration

```ts
export interface StageSettings {
  lights?: 'default' | 'none' | {
    intensity: number;
  };
  environment?: 'room' | 'studio' | 'none' | {
    url?: string;
    intensity?: number;
    rotationDeg?: number;
    blur?: number;
  };
  background?: BackgroundSpec;
  ground?: 'shadow' | 'none' | {
    shadow: {
      opacity?: number;
      sizeM?: number;
      y?: number;
      on?: Query;
    };
  };
  exposureEv?: number;
  toneMapping?: 'product' | 'mood' | 'aces' | 'none' | {
    curve: readonly Point2[];
  };
  ambientOcclusion?: boolean | {
    radius?: number | 'auto';
    strength?: number;
  };
  bloom?: boolean | {
    strength?: number;
    threshold?: number;
  };
  grade?: {
    saturation?: number;
  };
}
```

## Generic-API test (spec 3.1)

| Rule | Result |
| --- | --- |
| 1. Neutral name | pass: `StageSettings` names no product |
| 2. A precedent | not recorded: no ledger row (coverage.json) names this member or its owner |
| 3. Two apps, or labs | pass: 28 apps (fleet cross-check: app-04c2774145, app-0c773a4ee3, app-37356bf09f, app-378d190f1b, app-4762caacdc, app-4f16d2f6da, app-4fd23bc869, app-510d750508 and 20 more) |
| 4. The cheaper fix first | not recorded per member (Appendix B decides it per need) |