pixi-effects 0.48.1 → 0.49.0

package/dist/3d.d.ts

@@ -0,0 +1,303 @@
+import { b as SpaceNow, c as SequenceCommon, d as PropValue, e as Sequence, f as PathRouters, S as SequenceSpec } from './types-kt7DQKfO.js';
+import { Renderer, RenderTexture } from 'pixi.js';
+import { View3D, Container3D, Camera3D, View3DOptions, FlatMaterial, Model3D } from '@pixi/3d';
+import { C as CanvasCheck } from './Canvas-BfZkAFJm.js';
+
+/** Handed to setup / update / dispose. One per scene3d layer. */
+interface Scene3DContext {
+    /** The PixiJS 3D view the layer shows: a PixiJS display object that draws the scene inside PixiJS's own renderer. */
+    view: View3D;
+    /** `view.root`: add the meshes, models and lights here. */
+    root: Container3D;
+    /** `view.camera`: the view owns its camera (fov in degrees, `mode` perspective or orthographic); place it with `position.set` and `lookAt`. */
+    camera: Camera3D;
+    /** PixiJS's renderer (the same one that draws every layer). */
+    renderer: Renderer;
+    /** The layer's size in composition px. */
+    width: number;
+    height: number;
+    /** What setup returned in `objects`, plus `camera` and `view`: the names keyframes reach as `scene3d.<name>.<path>`. */
+    objects: Record<string, object>;
+    /** With `followCamera`: the composition's camera (and lights, fog) at this moment, as plain numbers, set before every `update`; undefined otherwise. */
+    space?: SpaceNow;
+}
+interface Scene3DSetupResult {
+    /** Objects addressable from keyframes as `scene3d.<name>.<path>` (`camera` and `view` are added unless you name your own). */
+    objects?: Record<string, object>;
+}
+interface Scene3DSequenceSpec extends SequenceCommon {
+    type: 'scene3d';
+    /** Layer size in composition px. Expressions allowed (e.g. 'W * 0.5'). Default: the parent composition's size. */
+    width?: PropValue;
+    height?: PropValue;
+    /**
+     * Options for the PixiJS 3D view (`environment`, `toneMapping`, `exposure`, `shadowQuality`, `passes`, `cull`, ...). `width`, `height` and `autoResize` belong to the layer.
+     * The layer draws with `cull: 'cpu'` unless you name one (the GPU cull of large batches is not the same from draw to draw on WebGPU).
+     */
+    view?: Omit<View3DOptions, 'width' | 'height' | 'autoResize'>;
+    /**
+     * Live in the composition's space: before every frame the view's camera is put where the composition's `camera` layer is (position, look-at, vertical fov), so a
+     * `cameraPath()` flies through the flat layers and this scene together. The scene is in composition PIXELS with y flipped: a point the composition calls (x, y, z) is
+     * (x, -y, z) here. Give the layer the composition's size (the default).
+     */
+    followCamera?: boolean;
+    /**
+     * The composition's `light` layers become PixiJS 3D lights in this scene (ambient, point, spot, parallel; same position, colour, intensity, cone, falloff), moved every
+     * frame. A parallel or spot light with `castsShadows` casts in the scene (meshes cast and receive by default in PixiJS 3D); a point light cannot cast in PixiJS 3D (it says so).
+     */
+    followLights?: boolean;
+    /** The composition camera's fog (`fogNear` / `fogFar` / `fogColor`) becomes the view's linear fog, every frame (PixiJS 3D fades by smoothstep; no `fogAmount` below 1). */
+    followFog?: boolean;
+    /**
+     * A rebuild (`setVars`, `resize`, `rebuild`) keeps this layer's scene when the layer did not change (same `name`, same `setup` function, size and options): `setup` runs once,
+     * not at every rebuild, and a model is not loaded again. Default `true`; a layer with no `name` is always built again. `false`: `setup` runs again at every rebuild (when it
+     * reads something a variable changes). `update` is the new composition's own and runs on the kept scene.
+     */
+    reuse?: boolean;
+    /** The view's resolution (1 draws at the layer's size; another value draws the scene at that scale and composites it). */
+    resolution?: number;
+    /** Build the scene: add objects to `ctx.root`, place `ctx.camera`. May be async (a model loads): Movie.init waits for it. */
+    setup: (ctx: Scene3DContext) => Promise<Scene3DSetupResult | void> | Scene3DSetupResult | void;
+    /**
+     * Per frame; `t` is the layer's own time in seconds. MUST set everything from `t` (no clock, no unseeded randomness, no state carried from the last call):
+     * playback, a seek and an export each draw a frame on its own. A model's clip: `model.player.getState(name).gotoAndStop(t)`.
+     */
+    update?: (t: number, ctx: Scene3DContext) => void;
+    /** Cleanup for resources you made (the view and everything under its root are destroyed by the layer). */
+    dispose?: (ctx: Scene3DContext) => void;
+}
+
+/**
+ * A `scene3d` layer: a PixiJS 3D scene (`View3D`) drawn inside PixiJS's own renderer, in the layer's place in the stack. The author builds the scene in `setup` and
+ * sets it from the time in `update`; `awaitFrameAt` (the per-frame hook `Movie` awaits for playback, seek and export alike) runs `update`, and PixiJS draws the view with the stage.
+ */
+declare class Scene3DSequence extends Sequence {
+    private _view;
+    private _ctx;
+    private _objects;
+    private _warned;
+    /** The animation players under the root (found after setup). */
+    private _players;
+    /** The layer's own last filter: what PixiJS 3D ignores on its view (alpha, its parents' alpha, a basic blend mode) applied to the view's picture. Only there while needed. */
+    private _look;
+    /** An advanced blend mode on a layer with no filter of its own: its blend filter, owned by the layer (the view's own blend mode would be shut inside the look filter's pass). */
+    private _blend;
+    /** The layer's time, what PixiJS 3D's shader time `uTime` reads once pinned (see `_pinShaderTime`). */
+    private _time;
+    /** Things to do before every frame of the scene is drawn (the 2D layers shown on meshes: `layerTexture`), and their handles. */
+    private _drawHooks;
+    private _shown;
+    /** Resources the 2D layers on meshes leave to this layer to free when it goes (shared, like `_shown`, with a layer that takes the scene over). */
+    private _owned;
+    /** What a rebuild matches this layer by (core/reuse.ts); null: never kept (`reuse: false`, no `name`, view options that are not plain data). */
+    private _key;
+    /** The layer of the tree being replaced whose scene this one takes over at the swap (`commitReuse`): until then it is not this layer's. */
+    private _borrowed;
+    /** True once another layer took this layer's scene: destroying this one must not let it go. */
+    private _donated;
+    private _pendingRebinds;
+    private _lightMirror;
+    private _fogMirror;
+    private _pinned;
+    /** The scene may have changed since the meshes were last made pickable (a frame ran `update`): the next pick walks it again, the picks after it do not. */
+    private _pickStale;
+    /** The PixiJS 3D view this layer shows (null before build and after destroy). */
+    get view(): View3D | null;
+    private get _spec();
+    private _say;
+    private _who;
+    protected pathRouters(): PathRouters;
+    build(): Promise<void>;
+    /** Reuse (core/reuse.ts): the key this layer is matched by, while it can still lend its scene. */
+    reuseKey(): string | null;
+    private _lendable;
+    /**
+     * Take over a layer of the tree being replaced. The view is a PixiJS display object with one parent, so the old view stays in the old tree (which goes on drawing while this tree is
+     * built); this layer has a view of its own, and at the swap (`commitReuse`) the old view's whole scene, its camera with it, moves into this one. The objects setup made (and every
+     * value an author kept from setup: the camera, the meshes) are the same objects.
+     */
+    private _borrow;
+    /** The new tree is on stage: the scene of the layer this one borrowed from moves into this layer's view, for good. */
+    commitReuse(): void;
+    /** Unknown keys (with the likely one), and the keys only a three layer has. */
+    private _checkKeys;
+    /**
+     * PixiJS 3D (0.1.0) writes `performance.now()` into the shader time `uTime` of every view at every draw: a shader bit that reads it would follow the wall clock.
+     * The view's global uniforms exist once PixiJS has drawn it; from then on `uTime` reads the layer's time and the pipe's write is ignored. Tried before every frame
+     * until it holds (drawing the view on its own at build to make them sooner broke a stencil mask on it later). This reaches into the view's per-renderer data
+     * (`_gpuData[renderer.uid].globalUniformGroup.uniforms`); when that is there but has no `uTime` (another version), say so once.
+     */
+    private _pinShaderTime;
+    /**
+     * `followCamera` (and, later, `followLights` / `followFog`): before each frame, ask the composition for its camera at this moment (the layer's time on the composition's
+     * clock) and put the view's camera there. `ctx.space` keeps the raw numbers for `update`, which runs after and may override.
+     */
+    private _followSpace;
+    /** followCamera shows the whole composition through the layer's picture: a layer of another shape would show it squeezed or cut. Said once at build. */
+    private _checkFollowShape;
+    /** PixiJS 3D draws the view in its materials' colours: a tint does nothing. Said once, at build. */
+    private _checkTint;
+    /**
+     * Every frame, before the draw: PixiJS 3D ignores the view's alpha (and its parents') and a basic blend mode, so when the layer is not at full strength or blends,
+     * its picture goes through one AlphaFilter of the layer's own, last in its filter list, that applies them. A layer at alpha 1 with a normal blend has no such filter.
+     */
+    syncFrame(): void;
+    /**
+     * Models, animation players and particle systems update themselves on PixiJS's shared ticker unless told otherwise: their picture would follow the browser's clock,
+     * not the video's time. Turn that off on everything under the root, and say once what was turned off (the author drives them from `update`).
+     */
+    private _stopSelfUpdating;
+    /**
+     * Per-frame hook, duck-typed by `Movie._awaitVideoFrames` (as the video and three layers are): the single frame path of playback, seek and export.
+     * `update` sets the scene from the time; PixiJS draws the view with the rest of the stage.
+     */
+    awaitFrameAt(local: number): Promise<void>;
+    /**
+     * A clip still playing after `update` (a model made with `autoPlay`, a `player.play(name)` in setup) is posed by nobody: it would move with the ticker, or not at all.
+     * The layer poses it from its own time (its speed and loop kept) and leaves it playing, so it plays in the video as it would in a page. A clip `update` poses itself
+     * (`gotoAndStop(t)` stops it) is left alone. Nothing is remembered from one frame to the next: the frame depends on this frame's `update` only.
+     */
+    private _poseClips;
+    /**
+     * The determinism check (`check`, `movie.review()`): the scene set by `update` and drawn at a few moments in two orders, with one draw thrown away first, and the pictures
+     * compared, as the canvas and three layers are. A scene whose same frame is not the same picture (state kept from call to call, a clock, a player or particle system on its
+     * own clock, a motion blur that reads the last frame) is reported. It draws the view alone into a texture of its own size with PixiJS's renderer; the next real frame sets
+     * the scene again, so nothing is left behind.
+     */
+    checkDeterminism(times: number[]): CanvasCheck;
+    /** What `layerTexture` asks of this layer: the layers listed before it, PixiJS's renderer, and a place to hook in before every frame. */
+    private _makeHost;
+    /** True when this layer shows 2D layers on its meshes (`layerTexture`): the movie runs its frame after the rest of the frame is ready (projections, filters fed), as for a three layer. */
+    get showsLayers(): boolean;
+    /** The 2D layer that a material shows (`layerTexture`), for a click on the mesh to reach it (movie.pick); null for any other material. */
+    screenOf(material: unknown): {
+        source: Sequence;
+        at(u: number, v: number): {
+            x: number;
+            y: number;
+        };
+    } | null;
+    /** The view's global point at (u, v) of its picture (0..1, v down). */
+    private _globalAt;
+    /**
+     * Make the scene's meshes hit by a ray, exactly: PixiJS 3D only hits nodes whose eventMode is not 'passive', and by default against the mesh's bounding box (a sphere's corners
+     * count, and the hit has no uv). A mesh the author left as it was gets eventMode 'static' and hitVolume 'geometry' (per triangle: the silhouette, the normal and the uv a 2D
+     * layer on the mesh needs); the author's own choice is kept.
+     */
+    private _makePickable;
+    /**
+     * `movie.pick`: a ray through (u, v) of the layer's picture (0..1, v down) from the view's camera, and what it meets first: the object's name (its own label, or its nearest
+     * labelled ancestor's), where (scene units), how far from the camera, and the node. Uses the transforms of the last render, which is the frame on screen. null when it meets nothing.
+     */
+    pickAt(u: number, v: number): {
+        object: string;
+        point: [number, number, number];
+        distance: number;
+        object3d: unknown;
+        uv?: {
+            u: number;
+            v: number;
+        };
+        material?: unknown;
+    } | null;
+    /**
+     * `hit.scene3d.grab(plane)`: a function of a point (u, v) of the layer's picture that gives where the pointer's ray meets a plane through the grabbed point, and how far that is
+     * from it (`delta`): move the object by it. `plane`: 'screen' (facing the camera: the default), 'floor' (horizontal: y up), 'wall' (z constant), or a normal [x, y, z].
+     * null where the ray never meets the plane.
+     */
+    dragPlane(point: [number, number, number], plane?: 'screen' | 'floor' | 'wall' | [number, number, number]): (u: number, v: number) => {
+        point: [number, number, number];
+        delta: [number, number, number];
+    } | null;
+    private _resolvePath;
+    private _warnPath;
+    private _destroyView;
+    destroy(): void;
+}
+
+/**
+ * `layerTexture(ctx, 'screen')`: a live 2D layer (a `composition`) as the picture on a mesh of a `scene3d` layer (a phone's screen, a television, a billboard, a label).
+ *
+ * The 2D layer stays a layer of the movie: the timeline drives it, its own `at` / `duration` / keyframes / filters apply. It is not drawn on the stage any more: before each
+ * frame of the scene3d layer (after the timeline has put every layer at that frame), PixiJS draws it into a RenderTexture, and the material shows that texture. PixiJS 3D takes
+ * a PixiJS texture as it is: no copy, no read-back, the same on WebGL and WebGPU.
+ */
+
+interface LayerTextureOptions {
+    /** Pixels of the texture per pixel of the 2D layer: 2 for a screen that is seen large. Default 1. */
+    resolution?: number;
+    /** The 2D layer's empty and half-transparent parts let what is behind the mesh show through (a sticker, a hologram). Default `false`: an opaque screen, empty parts black. */
+    transparent?: boolean;
+}
+interface LayerTexture {
+    /** An unlit material that shows the 2D layer: put it on a mesh. A screen shines by itself, so the scene's lights do not shade it. */
+    material: FlatMaterial;
+    /** The texture behind the material (a PixiJS RenderTexture, redrawn every frame). */
+    texture: RenderTexture;
+    /** The size of the texture in pixels. */
+    width: number;
+    height: number;
+    /** Stop showing the layer on the mesh (it is drawn on the stage again; the mesh keeps the last picture). The material and the texture are freed with the scene3d layer. */
+    dispose(): void;
+}
+declare function layerTexture(ctx: Scene3DContext, name: string, options?: LayerTextureOptions): Promise<LayerTexture>;
+
+interface LoadModelOptions {
+    /** A clip name, a clip index, or `false` (no animation: the model's bind pose). Default: the first clip, if the file has one. */
+    animation?: string | number | false;
+    /** The clip time is `t x speed + offset` (the layer's seconds). Defaults 1 and 0. */
+    speed?: number;
+    offset?: number;
+    /** `true` (default): the clip repeats; `false`: it holds its last pose. */
+    loop?: boolean;
+}
+interface LoadedModel {
+    /** Add this to `ctx.root`. A group whose origin is the centre of the model's bounding box (bind pose): position, turn and `fit` it about its centre. */
+    object: Container3D;
+    /** The PixiJS 3D model inside `object` (its `player`, `materials`, `skeletons`). */
+    model: Model3D;
+    /** The names of the clips the file has. */
+    clips: string[];
+    /** The size of the model's bounding box now (with `fit`), in the scene's units. */
+    size(): {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Scale `object` so the model's longest side is `n` (a model in metres in a scene in composition pixels: `fit(400)` under `followCamera`). */
+    fit(n: number): void;
+    /** Pose the model at the layer's time `t` (seconds): the clip at `t x speed + offset`, looped or held. A seek, an export and a repeat give the same pose. */
+    pose(t: number): void;
+}
+/** Load a glTF / GLB (a URL relative to the page) as a PixiJS 3D model, ready to pose from the time. Call it in a scene3d layer's `setup` (await it). */
+declare function loadModel(url: string, options?: LoadModelOptions): Promise<LoadedModel>;
+interface FitCameraOptions {
+    /** The direction the camera sits in from the centre of the object, any length. Default `[0.45, 0.3, 1]`: a three-quarter view, a little from the side and above. */
+    direction?: [number, number, number];
+    /** Free room around the object: 1.1 (the default) leaves 10 %. */
+    margin?: number;
+}
+/**
+ * Put the layer's camera where the whole of `object` (its bounding box now, with its scale and place) fits the picture, looking at its centre: the smallest distance at which
+ * the 8 corners of the box fit both the vertical and the horizontal field of view. Uses the camera's `fov` and the layer's shape; `near` and `far` follow the distance.
+ * The box is the pose of now: for a clip that travels far, place the camera yourself.
+ */
+declare function fitCamera(ctx: Scene3DContext, object: Container3D, options?: FitCameraOptions): void;
+
+/**
+ * pixi-effects/3d — 3D scenes drawn by PixiJS 3D (`@pixi/3d`), the main 3D engine.
+ *
+ * Import this entry BEFORE `movie.init` and call `register3D()` once: PixiJS loads the 3D drawing code while its renderer starts, so a
+ * renderer that started before `@pixi/3d` was imported cannot draw a `scene3d` layer. The core `pixi-effects` entry never loads `@pixi/3d`.
+ */
+
+/**
+ * Register the `scene3d` layer type. Explicit call so `sideEffects: false` bundlers cannot drop it; calling it again is fine.
+ * It also turns off the self-updating of models and animation players (they would move with the browser's clock, not the video's time):
+ * pose a clip from the time in `update` with `model.player.getState(name).gotoAndStop(t)`.
+ */
+declare function register3D(): void;
+/** Typing helper: accepts a strongly-typed scene3d spec and returns it as a core SequenceSpec, keeping `@pixi/3d` types out of the core union. */
+declare function scene3d(spec: Scene3DSequenceSpec): SequenceSpec;
+
+export { type FitCameraOptions, type LayerTexture, type LayerTextureOptions, type LoadModelOptions, type LoadedModel, type Scene3DContext, Scene3DSequence, type Scene3DSequenceSpec, type Scene3DSetupResult, fitCamera, layerTexture, loadModel, register3D, scene3d };