lecodes-sdk 2.0.12 → 2.1.0

package/dist/types/gl/Scene.d.ts

@@ -8,17 +8,8 @@ import { Camera } from "./Camera";
 import { SceneAudio } from "./audio/SceneAudio";
 import { type ControlsHandle, type ControlsOptions } from "./controls";
 import { Material } from "./Material";
+import { PostProcessing, type PostProcessingOptions } from "./postProcessing";
 import { Node } from "./Node";
-export type AmbientOcclusionOptions = {
-    /** Strength of the darkening (default 1). */
-    intensity?: number;
-    /** How far the occlusion reaches, in metres (default 0.3). */
-    radius?: number;
-    /** Falloff contrast; >1 tightens it into the crease (default 1). */
-    power?: number;
-    /** Sample count + filtering (default 'medium'). Not the buffer resolution — that stays half. */
-    quality?: "low" | "medium" | "high" | "ultra";
-};
 /** `SceneOptions.taa` / `scene.setAntialias("taa", 4, taa)`: the temporal anti-aliasing knobs. */
 export type TaaOptions = {
     /** Render the 3D at this fraction (0.5–1) and TAA-upscale it to the viewport; 1 = none. */
@@ -74,14 +65,10 @@ export type SceneOptions = {
      *  rather than inflating the lights: scaling lamps past what they physically emit gives bright
      *  fixtures in a black room, because it changes the RATIO, not the level. */
     exposureCompensation?: number;
-    /** Bloom post-processing. */
-    bloom?: boolean;
-    bloomIntensity?: number;
-    /** Tone mapping operator. `'aces'` (default, filament's ACES legacy) desaturates bright colours
-     *  towards white — HDR fire reads pale; `'neutral'` (Khronos PBR Neutral) keeps hue and
-     *  saturation until very bright; `'linear'` clips each channel (what an engine without a
-     *  tonemapper shows — saturated, Unity-without-post-processing look); `'filmic'` (Uncharted). */
-    toneMapping?: "aces" | "neutral" | "linear" | "filmic";
+    /** The look: tone mapping, colour grading, a `.cube` LUT, bloom, vignette, ambient occlusion,
+     *  screen-space reflections, depth of field — as one object (`scene.postProcessing` after the
+     *  fact; every field is live, postProcessing.ts says which are free to animate). */
+    postProcessing?: PostProcessingOptions;
     /** The sky. Three forms:
      *  - a colour — a flat clear colour;
      *  - `{ texture }` — a KTX1 **cubemap**, the sharp `<name>_skybox.ktx` that filament's `cmgen`
@@ -96,12 +83,6 @@ export type SceneOptions = {
     skybox?: ColorInput | "environment" | {
         texture: string;
     };
-    /** Screen-space ambient occlusion — the contact darkening in creases and where props meet the
-     *  ground. Without it an IBL lights a crease exactly as brightly as an open face, so everything
-     *  reads as pasted onto the floor rather than standing on it. `true` takes defaults tuned for
-     *  human-scale props; `radius` is world-space metres and is the one knob that must follow the
-     *  scene's scale (~0.3 for objects on a table, ~0.6-1 for a yard of crates and containers). */
-    ambientOcclusion?: boolean | AmbientOcclusionOptions;
     /** Distance fog / aerial perspective: distant geometry loses contrast so the eye reads depth, and
      *  the hard edge where a finite level ends against the skybox goes away. By default the fog applies
      *  at every distance — the skybox included — so the sky itself takes the fog colour and the horizon
@@ -167,6 +148,14 @@ export declare class Scene implements Presentable {
     readonly audio: SceneAudio;
     readonly _touchStartListeners: Array<(ev: TouchStartEvent<Node | null>) => void>;
     private _material?;
+    private readonly _postProcessing;
+    /** The scene's post-processing (postProcessing.ts): a live object — write a field
+     *  (`scene.postProcessing.contrast = 1.1`), or `apply({ ... })` several at once (named fields
+     *  only), `reset()` for the defaults. Read-only: there is nothing to assign. An overlay's grading
+     *  is its parent's; its bloom, vignette and the rest are its own. */
+    get postProcessing(): PostProcessing;
+    /** An explicit throw, not a bare getter: a bundle evaluated in sloppy mode would swallow the assignment silently. */
+    set postProcessing(_: never);
     private static _active;
     static get active(): Scene | null;
     constructor(options?: SceneOptions);
@@ -181,8 +170,6 @@ export declare class Scene implements Presentable {
     set skybox(sky: ColorInput | "environment" | {
         texture: string;
     });
-    /** Runtime form of `ambientOcclusion` (a graphics-settings menu). `false` turns it off. */
-    setAmbientOcclusion(options: boolean | AmbientOcclusionOptions): void;
     /** Runtime form of `fog` (weather, entering a building). `false` turns it off. */
     setFog(options: FogOptions | false): void;
     setMaterialGlobalParameter(i: number, x: number, y: number, z: number, w: number): void;
@@ -196,8 +183,6 @@ export declare class Scene implements Presentable {
      *  0.5 = full detail twice as far, 1 = the defaults. Engine-wide, live. Only GLBs that carry
      *  `_LOD<n>` meshes (`lecodes assets doctor --lod`) have levels to switch. */
     setLodBias(bias: number): void;
-    /** Runtime form of `bloom` / `bloomIntensity` (a graphics-settings menu). */
-    setBloom(enabled: boolean, intensity?: number): void;
     /**
      * How bright the environment (IBL) lights the scene, in lux — `SceneOptions.environmentIntensity`
      * after the fact. Live: it changes the probe's intensity, not the probe, so it costs nothing and

package/dist/types/gl/postProcessing.d.ts

@@ -0,0 +1,228 @@
+import { type ColorInput } from "../core/color";
+import type { Texture } from "./Texture";
+export type ToneMappingOperator = "aces" | "neutral" | "linear" | "filmic";
+/** A linear RGB triple. */
+export type Rgb = readonly [number, number, number];
+export type Quality = "low" | "medium" | "high" | "ultra";
+export type BloomOptions = {
+    /** How much of the blurred highlights is added back, 0..1 (default 0.2). */
+    intensity?: number;
+    /** Only what is brighter than 1.0 after exposure blooms (default true); false makes everything
+     *  glow a little — the soft "dreamy" look. */
+    threshold?: boolean;
+    /** Clamp of one pixel's contribution (default 1000); lower it when a few emissive pixels flicker. */
+    highlight?: number;
+    /** Depth of the blur chain, 1..12 (default 6): how far the glow spreads. */
+    levels?: number;
+    /** The blur's sample count (default 'medium'). */
+    quality?: Quality;
+    /** Ghosts + halo around the brightest spots (default false). */
+    lensFlare?: boolean;
+    /** A "dirty lens": this texture multiplied into the bloom (default none). */
+    dirt?: Texture | null;
+    /** How much of the dirt shows, 0..1 (default 0.2). */
+    dirtStrength?: number;
+};
+export type VignetteOptions = {
+    /** How far from the centre the darkening starts, 0..1 (default 0.5). */
+    midPoint?: number;
+    /** 0 follows the aspect ratio, 1 is a circle (default 0.5). */
+    roundness?: number;
+    /** Softness of the edge, 0..1 (default 0.5). */
+    feather?: number;
+    /** The colour at the edge (default black). */
+    color?: ColorInput;
+};
+/** Screen-space ambient occlusion — the contact darkening in creases and where props meet the
+ *  ground. Without it an IBL lights a crease exactly as brightly as an open face, so everything
+ *  reads as pasted onto the floor rather than standing on it. `true` takes defaults tuned for
+ *  human-scale props; `radius` is world-space metres and is the one knob that must follow the
+ *  scene's scale (~0.3 for objects on a table, ~0.6-1 for a yard of crates and containers). */
+export type AmbientOcclusionOptions = {
+    /** Strength of the darkening (default 1). */
+    intensity?: number;
+    /** How far the occlusion reaches, in metres (default 0.3). */
+    radius?: number;
+    /** Falloff contrast; >1 tightens it into the crease (default 1). */
+    power?: number;
+    /** Sample count + filtering (default 'medium'). Not the buffer resolution — that stays half. */
+    quality?: Quality;
+};
+/** Screen-space reflections: glossy surfaces reflect what is ON SCREEN, by a ray march through the
+ *  depth buffer (a wet floor reflecting the lamps above it). Nothing off screen reflects and a
+ *  reflection ends at the frame's edge — the classic limit. A per-pixel ray: a real cost on a
+ *  phone, not measured yet. */
+export type ScreenSpaceReflectionsOptions = {
+    /** Metres a ray travels before giving up (default 3). */
+    maxDistance?: number;
+    /** Metres a surface is assumed to extend behind its depth — a hit inside it counts (default 0.1). */
+    thickness?: number;
+    /** Pixels per ray step: 1 = exact and slow, 2..4 the usual (default 2). */
+    stride?: number;
+};
+/** Depth of field: the camera focuses at `focusDistance` and everything else blurs as the lens
+ *  would — as if it were at f/`aperture`, WITHOUT touching the exposure (the camera's own aperture,
+ *  f/16 by default, would show next to no blur; the engine scales the blur instead of opening the
+ *  lens). The physics are honest and therefore mild: a game camera is a WIDE lens (fov 60° is a
+ *  21 mm lens), and a wide lens at f/1.4 still blurs a prop 9 m behind a 2.5 m focus by only ~2 px
+ *  of 600 — `strength` multiplies the blur for the look a 50 mm lens would give (3-4 reads as
+ *  "cinematic" at fov 60°). All live: a focus pull is a `focusDistance` written every frame. */
+export type DepthOfFieldOptions = {
+    /** Metres from the camera to the plane in focus (default 10). */
+    focusDistance?: number;
+    /** The f-number the blur should look like (default 2.8; smaller = shallower). */
+    aperture?: number;
+    /** Multiplier on the blur (default 1 = the physics of the camera's lens). */
+    strength?: number;
+};
+export type WhiteBalance = {
+    /** Blue / yellow axis, -1 (cool, 50 000 K) .. 1 (warm, 2 000 K); 0 = none. */
+    temperature?: number;
+    /** Green / magenta axis, -1 .. 1; 0 = none. */
+    tint?: number;
+};
+/** Where the tonal zones of `shadows` / `midtones` / `highlights` fade into each other, in 0..1 of
+ *  the (linear) luminance: `shadows` = (start, end) of the shadows → midtones fade (default 0, 0.333),
+ *  `highlights` = (start, end) of the midtones → highlights fade (default 0.55, 1). */
+export type TonalRanges = {
+    shadows?: readonly [number, number];
+    highlights?: readonly [number, number];
+};
+/** Per-channel curves: a gamma on the shadows, the point where shadows stop and highlights start,
+ *  and a scale on the highlights — each per RGB channel, `[1, 1, 1]` = none. */
+export type ColorCurves = {
+    shadowGamma?: Rgb;
+    midPoint?: Rgb;
+    highlightScale?: Rgb;
+};
+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
+     *  pale; `'neutral'` (Khronos PBR Neutral) keeps hue and saturation until very bright; `'linear'`
+     *  clips each channel (what an engine without a tonemapper shows — saturated, Unity-without-post
+     *  look); `'filmic'` is the Uncharted curve. */
+    toneMapping?: ToneMappingOperator;
+    /** Post-exposure in stops, applied AFTER bloom to the finished picture (default 0). Not the
+     *  camera's `exposureCompensation`, which scales the light itself — what bloom and fog see. */
+    exposure?: number;
+    whiteBalance?: WhiteBalance;
+    /** 0..2, 1 = none. Applied in log space. */
+    contrast?: number;
+    /** 0..2, 1 = none. */
+    saturation?: number;
+    /** Saturation that spares what is already saturated, 0..2, 1 = none. */
+    vibrance?: number;
+    /** Linear RGB multiplier of the shadows zone, `[1, 1, 1]` = none. */
+    shadows?: Rgb;
+    midtones?: Rgb;
+    highlights?: Rgb;
+    ranges?: TonalRanges;
+    /** ASC CDL — the lift / gamma / gain of a grading suite, per channel, applied in log space:
+     *  `slope` multiplies (gain; `[1, 1, 1]` = none), `offset` adds (lift; `[0, 0, 0]` = none),
+     *  `power` is the exponent (gamma; `[1, 1, 1]` = none). */
+    slope?: Rgb;
+    offset?: Rgb;
+    power?: Rgb;
+    curves?: ColorCurves;
+    /** A 3D LUT from a grading tool (Resolve, Photoshop, Unity's Color Lookup) applied last, after
+     *  the operator, in display-referred sRGB — a `.cube` file: `asset('./look.cube')`, or a bare
+     *  staged filename. `null` removes it. */
+    lut?: string | null;
+    /** `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. */
+    vignette?: boolean | VignetteOptions;
+    /** `true` = defaults (radius 0.3 m), an object = its knobs, `false` = off. */
+    ambientOcclusion?: boolean | AmbientOcclusionOptions;
+    /** `true` = defaults, an object = its knobs, `false` = off. */
+    screenSpaceReflections?: boolean | ScreenSpaceReflectionsOptions;
+    /** `true` = focus at 10 m as f/2.8, an object = its knobs, `false` = off. */
+    depthOfField?: boolean | DepthOfFieldOptions;
+};
+/** The float layout of `_creator.setColorGrading` — creator.h's ColorGradingParam. Indices never
+ *  move; a new field goes at the end and COUNT grows. */
+export declare const CG: {
+    readonly TONE_MAPPING: 0;
+    readonly EXPOSURE: 1;
+    readonly TEMPERATURE: 2;
+    readonly TINT: 3;
+    readonly CONTRAST: 4;
+    readonly VIBRANCE: 5;
+    readonly SATURATION: 6;
+    readonly SHADOWS: 7;
+    readonly MIDTONES: 10;
+    readonly HIGHLIGHTS: 13;
+    readonly RANGES: 16;
+    readonly SLOPE: 20;
+    readonly OFFSET: 23;
+    readonly POWER: 26;
+    readonly SHADOW_GAMMA: 29;
+    readonly MID_POINT: 32;
+    readonly HIGHLIGHT_SCALE: 35;
+    readonly LUT: 38;
+    readonly COUNT: 39;
+};
+/** The scene's post-processing (`scene.postProcessing`). Read a field for the current value, write
+ *  one to change it; `apply(options)` writes the named ones; `reset()` is the defaults. */
+export declare class PostProcessing {
+    private _g;
+    private _bloom;
+    private _vignette;
+    private _ao;
+    private _ssr;
+    private _dof;
+    private _dirty;
+    private _lutDirty;
+    private _sentLut;
+    private _sent;
+    private readonly _sceneId;
+    /** Write the fields named in `options`, nothing else — at every level: `{ bloom: { intensity:
+     *  0.4 } }` changes one bloom knob, `{ whiteBalance: { tint: 0.1 } }` keeps the temperature.
+     *  The grading band goes to the engine at once (one bake), not in a microtask. */
+    apply(options: PostProcessingOptions): this;
+    /** Every field back to its default: the engine's own look, every live feature off. */
+    reset(): this;
+    get toneMapping(): ToneMappingOperator;
+    set toneMapping(v: ToneMappingOperator);
+    get exposure(): number;
+    set exposure(v: number);
+    get whiteBalance(): Required<WhiteBalance>;
+    set whiteBalance(v: WhiteBalance);
+    get contrast(): number;
+    set contrast(v: number);
+    get saturation(): number;
+    set saturation(v: number);
+    get vibrance(): number;
+    set vibrance(v: number);
+    get shadows(): Rgb;
+    set shadows(v: Rgb);
+    get midtones(): Rgb;
+    set midtones(v: Rgb);
+    get highlights(): Rgb;
+    set highlights(v: Rgb);
+    get ranges(): Required<TonalRanges>;
+    set ranges(v: TonalRanges);
+    get slope(): Rgb;
+    set slope(v: Rgb);
+    get offset(): Rgb;
+    set offset(v: Rgb);
+    get power(): Rgb;
+    set power(v: Rgb);
+    get curves(): Required<ColorCurves>;
+    set curves(v: ColorCurves);
+    get lut(): string | null;
+    set lut(v: string | null);
+    get bloom(): Required<BloomOptions> | false;
+    set bloom(v: boolean | BloomOptions);
+    get vignette(): Required<VignetteOptions> | false;
+    set vignette(v: boolean | VignetteOptions);
+    get ambientOcclusion(): Required<AmbientOcclusionOptions> | false;
+    set ambientOcclusion(v: boolean | AmbientOcclusionOptions);
+    get screenSpaceReflections(): Required<ScreenSpaceReflectionsOptions> | false;
+    set screenSpaceReflections(v: boolean | ScreenSpaceReflectionsOptions);
+    get depthOfField(): Required<DepthOfFieldOptions> | false;
+    set depthOfField(v: boolean | DepthOfFieldOptions);
+    private _touch;
+    /** Send the grading band now (it is sent on its own at the end of the current handler). */
+    flush(): void;
+}

package/dist/types/runtime/app.d.ts

@@ -16,11 +16,40 @@ type AppEventMap = {
      *  it to `animateTo` to move a composer in sync with the keyboard. */
     keyboard: (height: number, duration: number) => void;
 };
+/** The installed app this bundle runs in — see `app.host`. */
+export interface AppHost {
+    /** The store build's version string (Android versionName, iOS CFBundleShortVersionString; app.json
+     *  `version` in a `lecodes app` shell). `undefined` where the host is not an installed app. */
+    version?: string;
+    /** The store build's build number (versionCode / CFBundleVersion; app.json `buildNumber` /
+     *  `versionCode`). `undefined` where the host is not an installed app, `0` when not numeric. */
+    build?: number;
+    /** The SDK embedded in the host — the lecodes-ios-sdk / lecodes-android-sdk release a shell pins,
+     *  the runtime's version elsewhere. */
+    sdk: string;
+}
+/** The bundle that is running — see `app.bundle`. */
+export interface AppBundle {
+    /** The SDK this bundle was compiled with (`app.sdkVersion`). */
+    sdk: string;
+    /** When it was compiled (ISO 8601) — the `// last-updated:` header line; `undefined` on a bundle
+     *  without it. */
+    updatedAt?: string;
+}
 export declare const app: {
     /** The SDK this app was compiled with (semver, e.g. `"2.0.0"`). Its major is the bundle ↔ runtime
      *  contract: a host runs only bundles of its own major, and the launchers send it as `?sdk=` when
-     *  they fetch a published bundle — the platform keeps one bundle per major. */
+     *  they fetch a published bundle — the platform keeps one bundle per major. Also `app.bundle.sdk`. */
     sdkVersion: string;
+    /** The INSTALLED app: the store build this bundle runs in. After an over-the-air update the code
+     *  is newer than the binary, so a feature that needs native support added in a later store build
+     *  (a plugin, an SDK method) branches on `app.host.sdk` / `app.host.build` — and on `typeof` of
+     *  the method itself, which is the final word. Minor and patch of the SDK never gate anything. */
+    readonly host: AppHost;
+    /** The RUNNING code: what the compiler stamped into this bundle's header. `updatedAt` is the
+     *  compile time — what the updater compares before replacing a bundle (an older one never
+     *  replaces a newer one), useful for an "about" screen or a support log. */
+    readonly bundle: AppBundle;
     /** Current lifecycle state. `"background"` while the app is not the foreground app / the tab is
      *  hidden. `"active"` on hosts that don't track it. */
     readonly state: AppState;

package/dist/types/version.d.ts

@@ -1,4 +1,4 @@
-export declare const SDK_VERSION = "2.0.12";
+export declare const SDK_VERSION = "2.1.0";
 /** The major of a semver string, or null when it is not one. */
 export declare const sdkMajor: (version: string | null | undefined) => number | null;
 /** The `// sdk: <version>` line of a compiled bundle's header (sdk/src/compile/header.ts), read from