/** * Stable public entry point for the Baked Motion product block. * @module three-blocks/baked-motion */ import type * as THREE from 'three/webgpu'; import { BakedMotion as BakedMotionImplementation } from './BakedMotion/BakedMotion.cjs'; import type { BakedMotionParameters as BakedMotionParametersImplementation, BakedMotionRotationParameters as BakedMotionRotationParametersImplementation, BakedMotionTiltParameters as BakedMotionTiltParametersImplementation, BakedMotionTimelineParameters as BakedMotionTimelineParametersImplementation, BakedMotionViewSource as BakedMotionViewSourceImplementation } from './BakedMotion/BakedMotion.cjs'; export { BakedMotionError } from './BakedMotion/BakedMotionError.cjs'; import type { BakedMotionDiagnostics as BakedMotionDiagnosticsImplementation, BakedMotionErrorCode as BakedMotionErrorCodeImplementation, BakedMotionState as BakedMotionStateImplementation } from './BakedMotion/BakedMotionError.cjs'; import type { BakedMotionFrameSample as BakedMotionFrameSampleImplementation, BakedMotionManifest as BakedMotionManifestImplementation, BakedMotionParameterValues as BakedMotionParameterValuesImplementation } from './BakedMotion/BakedMotionManifest.cjs'; /** Persisted Baked Motion package discriminator. */ export declare const BAKED_MOTION_TYPE = "utsubo-utsbv"; /** Persisted Baked Motion manifest version understood by this runtime. */ export declare const BAKED_MOTION_VERSION = 3; /** Validated, versioned Baked Motion runtime manifest. */ export type BakedMotionManifest = BakedMotionManifestImplementation; /** Parameter values accepted when mapping a manifest sample to stored frames. */ export type BakedMotionParameterValues = BakedMotionParameterValuesImplementation; /** One- or two-dimensional stored-frame sample selected from a manifest. */ export type BakedMotionFrameSample = BakedMotionFrameSampleImplementation; /** Timeline-mode playback parameters currently sampled by the runtime. */ export type BakedMotionTimelineParameters = BakedMotionTimelineParametersImplementation; /** Pointer-tilt parameters currently sampled by the runtime. */ export type BakedMotionTiltParameters = BakedMotionTiltParametersImplementation; /** View-rotation parameters currently sampled by the runtime. */ export type BakedMotionRotationParameters = BakedMotionRotationParametersImplementation; /** Current mode-specific parameters sampled by a Baked Motion instance. */ export type BakedMotionParameters = BakedMotionParametersImplementation; /** Camera, object, or vector-like input accepted by {@link BakedMotion.setView}. */ export type BakedMotionViewSource = BakedMotionViewSourceImplementation; /** Stable host-facing Baked Motion lifecycle state. */ export type BakedMotionState = BakedMotionStateImplementation; /** Stable code carried by a failed Baked Motion operation. */ export type BakedMotionErrorCode = BakedMotionErrorCodeImplementation; /** Immutable local-only runtime diagnostic snapshot. */ export type BakedMotionDiagnostics = BakedMotionDiagnosticsImplementation; /** Media delivery policy: one whole-file request per track (default) or opt-in verified range segments. */ export type BakedMotionDelivery = 'full' | 'segments'; /** Node material driven by decoded Baked Motion colour, alpha, and depth. */ export type BakedMotionMaterial = THREE.NodeMaterial; /** Geometry displayed by a Baked Motion instance. */ export type BakedMotionGeometry = THREE.BufferGeometry; /** Scene object exposed as the renderable Baked Motion output. */ export type BakedMotionMesh = THREE.Mesh; /** Minimal response consumed by Baked Motion's injectable fetch implementation. */ export interface BakedMotionFetchResponse { /** Whether the response completed with a successful HTTP status. */ readonly ok: boolean; /** Numeric HTTP status used in load failures. */ readonly status: number; /** Optional readable response headers used to validate exact byte ranges and pin ETags. */ readonly headers?: { get(name: string): string | null; }; /** Optional streaming body used to enforce full-response byte caps before retention. */ readonly body?: ReadableStream | null; /** Read and decode a JSON response body. */ json(): Promise; /** Optional raw text reader used to enforce the manifest byte cap before parsing. */ text?(): Promise; /** Read an encoded media response body. */ arrayBuffer(): Promise; } /** Injectable network function used to load manifests and `.af` tracks. */ export type BakedMotionFetch = (input: string, init?: RequestInit) => Promise; /** Renderer operations used by the decoded-view GPU cache. */ export interface BakedMotionRenderer { /** Optional renderer backend used to inspect the texture-array layer limit. */ readonly backend?: unknown; /** Initialize a texture before copying decoded frames into it. */ initTexture(texture: THREE.Texture): void; /** Copy a decoded texture into one layer of an owned texture array. */ copyTextureToTexture(source: THREE.Texture, destination: THREE.Texture, sourceRegion?: THREE.Box2 | THREE.Box3 | null, destinationPosition?: THREE.Vector2 | THREE.Vector3 | null, sourceLevel?: number, destinationLevel?: number): void; /** Optional GPU-cache render-target surface. */ initRenderTarget?(target: THREE.RenderTarget): void; /** Return the renderer's current render target. */ getRenderTarget?(): THREE.RenderTarget | null; /** Return the active cube-map face for render-target restoration. */ getActiveCubeFace?(): number; /** Return the active mip level for render-target restoration. */ getActiveMipmapLevel?(): number; /** Select the render target used while uploading a decoded view. */ setRenderTarget?(target: THREE.RenderTarget | null, activeCubeFace?: number, activeMipmapLevel?: number): void; /** Render one upload pass. */ render?(scene: THREE.Object3D, camera: THREE.Camera): void | Promise; } /** Runtime construction and playback options for {@link BakedMotion}. */ export interface BakedMotionOptions { /** Custom manifest/media fetch implementation, primarily for controlled runtimes. */ fetchImpl?: BakedMotionFetch; /** Borrowed renderer used only for texture-array uploads; never disposed. */ renderer?: BakedMotionRenderer; /** Borrowed node material to drive; never disposed by Baked Motion. */ material?: BakedMotionMaterial; /** Borrowed geometry; omitted geometry is created and owned by Baked Motion. */ geometry?: BakedMotionGeometry; /** Face the camera via world-up billboarding. Defaults to true only for the owned plane. */ billboard?: boolean; /** Borrowed mesh whose original geometry and material remain caller-owned. */ mesh?: BakedMotionMesh; /** World-space height of the generated billboard geometry. */ height?: number; /** Optional Three.js object name assigned to the renderable mesh. */ name?: string; /** Whether timeline playback starts in the playing state. */ playing?: boolean; /** Whether timeline playback wraps at the manifest duration. */ loop?: boolean; /** Timeline playback multiplier. */ playbackRate?: number; /** Use bounded CPU-backed data-texture slots instead of VideoFrameTexture uploads. */ cpuUpload?: boolean; /** * Media delivery policy. Defaults to `'full'`: one verified whole-file request per selected * track. `'segments'` opts in to demand-driven verified HTTP range requests — only for * servers known to honor `Range` and interactions that tolerate on-demand fetch latency. */ delivery?: BakedMotionDelivery; /** Whether decoded depth is written into the material depth node. */ writeDepth?: boolean; /** WebCodecs hardware-acceleration preference. */ hardwareAcceleration?: HardwareAcceleration; /** Maximum wall-clock milliseconds allowed for first decoder output after submission. */ admissionTimeoutMs?: number; /** Automatic ordered fallback, or one exact normalized rendition ID. */ rendition?: 'auto' | string; /** Highest coded rendition width eligible in automatic mode. */ maxRenditionWidth?: number; /** Maximum complete `.af` resource accepted. */ maxFullFileBytes?: number; /** * Opt into the fixed grid re-seek pacer. Omit for decode-time adaptive pacing; any supplied * value preserves fixed cadence behavior, and `0` keeps every seek immediate. */ seekInterval?: number; } /** * Validate and normalize an unknown Baked Motion manifest. * Throws when the discriminator, version, axes, tracks, camera, or bounds are invalid. */ export declare const parseBakedMotionManifest: (input: unknown) => BakedMotionManifest; /** Map authored mode parameters to the stored frame indices and interpolation weights. */ export declare const paramToFrame: (manifest: BakedMotionManifest, values: BakedMotionParameterValues) => BakedMotionFrameSample; /** * Runtime-only Baked Motion playback facade. * * The facade owns decoded media and any material or geometry it creates. Objects supplied in * {@link BakedMotionOptions} are borrowed. It performs no packing or authoring work. */ export interface BakedMotion { /** Current observable lifecycle state. */ readonly state: BakedMotionState; /** Validated manifest, available after {@link BakedMotion.ready} resolves. */ readonly manifest: BakedMotionManifest | null; /** Current timeline time in seconds. */ readonly time: number; /** Whether timeline playback advances during {@link BakedMotion.update}. */ readonly playing: boolean; /** Whether timeline playback wraps at the end of the clip. */ loop: boolean; /** Timeline playback multiplier. */ playbackRate: number; /** Whether timeline playback is holding its last complete frame while the next sample loads. */ readonly buffering: boolean; /** Last mode-specific parameters submitted to the sampler. */ readonly parameters: BakedMotionParameters | null; /** Resolves when the most recently requested streamed sample has reached its slots. */ readonly frameReady: Promise; /** Driven material; borrowed when supplied in options, otherwise owned by this instance. */ readonly material: BakedMotionMaterial; /** Renderable Three.js mesh to add directly to a scene. */ readonly mesh: BakedMotionMesh; /** * Resolves after manifest validation, media initialization, and initial sampling. Rejects on * fetch, format, or codec failure. */ readonly ready: Promise; /** Return a deeply immutable point-in-time diagnostic snapshot. */ getDiagnostics(): Readonly; /** * The presented view as a texture-style node — the map-consumable form of Baked Motion * (decoded `VideoFrame`s in `THREE.VideoFrameTexture` slots, blended by the presentation * weights). Assign it like any node: `material.colorNode = motion.node`. Requires * `await motion.ready`. */ readonly node: BakedMotionImplementation['node']; /** `motion.node` at a custom coordinate. */ sample: BakedMotionImplementation['sample']; /** Set timeline time and request its decoded sample; valid only for timeline manifests. */ setTime(seconds: number): this; /** Set a tilt target in normalized device coordinates; call `update()` to ease toward it. */ setPointer(x: number, y: number): this; /** Sample rotation parameters from a camera/object position; valid only for rotation manifests. */ setView(camera: BakedMotionViewSource): this; /** * Advance timeline or pointer easing by elapsed seconds. Call once after input/control updates * and before rendering the frame. */ update(deltaSeconds: number): this; /** Park decoder sessions while retaining the current texture contents. */ suspend(): this; /** Re-admit decoder sessions and present the newest parameters into retained textures. */ resume(): Promise; /** Resume timeline advancement. */ play(): this; /** Pause timeline advancement while retaining the current decoded sample. */ pause(): this; /** * Release owned decoders, textures, geometry, and material. Idempotent; borrowed renderer, * mesh, geometry, and material resources are not disposed. */ dispose(): void; } interface BakedMotionConstructor { readonly prototype: BakedMotion; /** Create a Baked Motion player for a manifest URL and optional runtime controls. */ new (manifestURL: string | URL, options?: BakedMotionOptions): BakedMotion; } /** * Construct runtime Baked Motion playback without wrapping the implementation object. * Initialization failures are reported by the instance's `ready` promise. */ export declare const BakedMotion: BakedMotionConstructor;