lecodes-sdk 2.2.13 → 2.3.0

package/src/gl/postProcessing.ts

@@ -12,12 +12,13 @@
 // Two bands inside, because the engine treats them differently:
 //
 //  - The GRADING band — tone mapping, exposure, white balance, contrast / saturation / vibrance,
-//    shadows / midtones / highlights, slope / offset / power, curves, the .cube LUT — is baked by the
-//    engine into the ONE 3D lookup table the frame always samples. Free per frame; a CHANGE re-bakes
-//    a 32³ table on the CPU. So writes here are COALESCED: a field write marks the band dirty and the
-//    whole band goes to the engine once, in a microtask (the end of the current handler), and the
-//    values are quantised to 1/1000 so a tween that barely moves does not re-bake. Not a thing to
-//    animate every frame; a blend between two looks over a second is fine (a few dozen bakes).
+//    shadows / midtones / highlights, slope / offset / power, curves, the .cube LUT, the HDR look —
+//    is baked by the engine into the ONE 3D lookup table the frame always samples. Free per frame;
+//    a CHANGE re-bakes a 32³ table on the CPU. So writes here are COALESCED: a field write marks the
+//    band dirty and the whole band goes to the engine once, in a microtask (the end of the current
+//    handler), and the values are quantised to 1/1000 (the HDR look to 0.05) so a tween that barely
+//    moves does not re-bake. Not a thing to animate every frame; a blend between two looks over a
+//    second is fine (a few dozen bakes).
 //  - The LIVE band — bloom, vignette, ambient occlusion, screen-space reflections, depth of field —
 //    is a set of view options: written to the engine at once, free to animate (a focus pull every
 //    frame is what depthOfField is for).
@@ -134,6 +135,26 @@ export type ColorCurves = {
   highlightScale?: Rgb
 }
 
+/** The look on an HDR display — a screen with headroom above SDR white (Apple's XDR panels, an
+ *  external display in HDR mode), where the operator is stretched past SDR white toward the peak.
+ *  Ignored on SDR: stored, read back, nothing changes on screen (`device.hdr.available` says which
+ *  display this is). Part of the grading band — a change is a bake — and quantised to 0.05 steps. */
+export type HdrLook = {
+  /** How much of the picture reaches for the display's headroom, 0..1 (default 0.35). 0 touches only
+   *  what SDR clipped — the SDR grade kept exactly, but a mostly-mid-tone frame then looks flat next
+   *  to its one bright spot; 1 lifts nearly everything above black toward the peak. A sunlit
+   *  exterior takes 1, a dim interior wants less. */
+  strength?: number
+  /** Where white lands, as a multiple of SDR white, 1..8 (default 1) — the "HDR brightness" of a
+   *  console game's calibration screen, where 1.5–2 is the norm. It scales the WHOLE picture: at 1
+   *  a white wall is as bright as the UI's white (faithful, and dim next to what "HDR on" is
+   *  expected to look like), at 2 twice that, and highlights still climb above it (the engine keeps
+   *  `headroom / paperWhite` for them, clamped at the peak). `strength` decides how much of the
+   *  picture reaches for the peak; this decides where the picture starts — a game that wants to read
+   *  as "HDR on" rather than "SDR with a brighter sun" wants this over `strength`. */
+  paperWhite?: number
+}
+
 export type PostProcessingOptions = {
   /** The operator that folds the scene's HDR light into the display's range (default 'aces').
    *  `'aces'` (filament's ACES legacy) desaturates bright colours towards white — HDR fire reads
@@ -167,6 +188,11 @@ export type PostProcessingOptions = {
    *  the operator, in display-referred sRGB — a `.cube` file: `asset('./look.cube')`, or a bare
    *  staged filename. `null` removes it. */
   lut?: string | null
+  /** The look on an HDR display: `strength` 0..1 (how much of the picture reaches for the peak:
+   *  0 only what SDR clipped … 1 nearly everything; default 0.35), `paperWhite` 1..8 (where white
+   *  lands × SDR white — the console "HDR brightness", 1.5–2 the norm; default 1). Ignored on SDR.
+   *  An overlay takes its parent's, like the rest of the grading. */
+  hdr?: HdrLook
   /** `true` = defaults (intensity 0.2), an object = its knobs, `false` = off. */
   bloom?: boolean | BloomOptions
   /** `true` = defaults (a soft black edge), an object = its knobs, `false` = off. */
@@ -180,12 +206,13 @@ export type PostProcessingOptions = {
 }
 
 /** The float layout of `_creator.setColorGrading` — creator.h's ColorGradingParam. Indices never
- *  move; a new field goes at the end and COUNT grows. */
+ *  move; a new field goes at the end and COUNT grows (the engine takes an older bundle's shorter
+ *  array, down to the 39 before HDR_*, with the tail at its defaults). */
 export const CG = {
   TONE_MAPPING: 0, EXPOSURE: 1, TEMPERATURE: 2, TINT: 3, CONTRAST: 4, VIBRANCE: 5, SATURATION: 6,
   SHADOWS: 7, MIDTONES: 10, HIGHLIGHTS: 13, RANGES: 16, SLOPE: 20, OFFSET: 23, POWER: 26,
-  SHADOW_GAMMA: 29, MID_POINT: 32, HIGHLIGHT_SCALE: 35, LUT: 38,
-  COUNT: 39,
+  SHADOW_GAMMA: 29, MID_POINT: 32, HIGHLIGHT_SCALE: 35, LUT: 38, HDR_STRENGTH: 39, HDR_PAPER_WHITE: 40,
+  COUNT: 41,
 } as const
 
 const TONE_MAPPING_MODE: Record<ToneMappingOperator, number> = { aces: 0, neutral: 1, linear: 2, filmic: 3 }
@@ -196,6 +223,10 @@ const ONE: Rgb = [ 1, 1, 1 ]
 const ZERO: Rgb = [ 0, 0, 0 ]
 const rgb = (v: Rgb | undefined, d: Rgb): Rgb => v ? [ v[0], v[1], v[2] ] : d
 const pair = (v: readonly [number, number] | undefined, d: readonly [number, number]): readonly [number, number] => v ? [ v[0], v[1] ] : d
+/** The HDR look on the wire: clamped to its range and quantised to 0.05 — a slider must not re-bake a
+ *  32³ LUT per pixel of travel (the quantum is the SDK's; the engine only clamps). */
+const hdrStep = (v: number, min: number, max: number, d: number): number =>
+  Number.isFinite(v) ? Math.round(Math.min(max, Math.max(min, v)) * 20) / 20 : d
 
 /** The grading band, normalised: every field present. */
 type Grading = {
@@ -218,12 +249,15 @@ type Grading = {
   midPoint: Rgb
   highlightScale: Rgb
   lut: string | null
+  hdrStrength: number
+  hdrPaperWhite: number
 }
 
 const defaultGrading = (): Grading => ({
   toneMapping: "aces", exposure: 0, temperature: 0, tint: 0, contrast: 1, saturation: 1, vibrance: 1,
   shadows: ONE, midtones: ONE, highlights: ONE, rangeShadows: [ 0, 0.333 ], rangeHighlights: [ 0.55, 1 ],
   slope: ONE, offset: ZERO, power: ONE, shadowGamma: ONE, midPoint: ONE, highlightScale: ONE, lut: null,
+  hdrStrength: 0.35, hdrPaperWhite: 1,
 })
 
 const BLOOM_DEFAULTS: Required<BloomOptions> = { intensity: 0.2, threshold: true, highlight: 1000, levels: 6, quality: "medium", lensFlare: false, dirt: null, dirtStrength: 0.2 }
@@ -279,6 +313,7 @@ export class PostProcessing {
     if (options.power !== undefined) this.power = options.power
     if (options.curves !== undefined) this.curves = options.curves
     if (options.lut !== undefined) this.lut = options.lut
+    if (options.hdr !== undefined) this.hdr = options.hdr
     this.flush()
     if (options.bloom !== undefined) this.bloom = options.bloom
     if (options.vignette !== undefined) this.vignette = options.vignette
@@ -348,6 +383,12 @@ export class PostProcessing {
   }
   get lut(): string | null { return this._g.lut }
   set lut(v: string | null) { this._g.lut = v; this._lutDirty = v !== this._sentLut; this._touch() }
+  get hdr(): Required<HdrLook> { return { strength: this._g.hdrStrength, paperWhite: this._g.hdrPaperWhite } }
+  set hdr(v: HdrLook) {
+    if (v.strength !== undefined) this._g.hdrStrength = v.strength
+    if (v.paperWhite !== undefined) this._g.hdrPaperWhite = v.paperWhite
+    this._touch()
+  }
 
   // ---- the live band: view options, written at once ----
 
@@ -445,6 +486,8 @@ export class PostProcessing {
     put3(CG.MID_POINT, g.midPoint)
     put3(CG.HIGHLIGHT_SCALE, g.highlightScale)
     p[CG.LUT] = g.lut !== null ? 1 : 0
+    p[CG.HDR_STRENGTH] = hdrStep(g.hdrStrength, 0, 1, 0.35)
+    p[CG.HDR_PAPER_WHITE] = hdrStep(g.hdrPaperWhite, 1, 8, 1)
     return p
   }
 }