@rive-app/webgl2-threads 2.47.1 → 2.49.0

package/rive_advanced.mjs.d.ts

@@ -46,6 +46,9 @@ export interface RiveCanvas {
   RenderPaintStyle: typeof RenderPaintStyle;
   StrokeCap: typeof StrokeCap;
   StrokeJoin: typeof StrokeJoin;
+  StrokePosition: typeof StrokePosition;
+  ImageFilter: typeof ImageFilter;
+  ImageWrap: typeof ImageWrap;
   decodeAudio: DecodeAudio;
   decodeImage: DecodeImage;
   decodeFont: DecodeFont;
@@ -73,6 +76,15 @@ export interface RiveCanvas {
    */
   makeDeferredSession?(): DeferredSession | undefined;
 
+  /**
+   * @experimental Lets deferred renderers replay on one worker shared by the
+   * page. Only in the threaded webgl2 build; call it before loading files, so
+   * their images reach the worker too.
+   *
+   * @returns false where the browser cannot draw WebGL2 on a transferred canvas
+   */
+  enableReplayWorker?(): boolean;
+
   /**
    * Loads a Rive file for the runtime and returns a Rive-specific File class
    *
@@ -203,6 +215,18 @@ export interface RendererOptions {
    * converted to clockwise on a best-effort basis
    */
   inkbleed?: boolean;
+  /**
+   * @experimental (webgl2-threads only) Hands the canvas to the replay worker,
+   * once `enableReplayWorker()` has succeeded. The renderer then replays only
+   * deferred sessions. A canvas handed over before keeps going to the worker.
+   */
+  replayWorker?: boolean;
+  /**
+   * @experimental (webgl2-threads only) Called when the replay worker
+   * restores the renderer's lost context, so an idle instance still draws
+   * and notices it.
+   */
+  onContextRestored?: () => void;
 }
 
 /**
@@ -277,6 +301,22 @@ export declare class RendererWrapper {
    * @returns false if inkbleed was requested but the canvas context does not support it
    */
   setInkbleed?(enabled: boolean): boolean;
+  /**
+   * @experimental Present on renderers whose canvas is on the replay worker,
+   * which can only draw deferred sessions.
+   */
+  replaysOnWorker?(): boolean;
+  /**
+   * @experimental False while the replay worker has yet to take the canvas, or
+   * is as many frames behind as it queues. Skip the frame rather than record it.
+   */
+  acceptsFrame?(): boolean;
+  /**
+   * @experimental True once the replay worker's context was lost and restored.
+   * What it held is gone, so the renderer and the file's session must be
+   * recreated.
+   */
+  contextRestored?(): boolean;
 }
 
 export declare class RenderPathWrapper {
@@ -304,11 +344,15 @@ export declare class RenderPathWrapper {
   close(): void;
 }
 
+export declare class RenderImageWrapper {
+}
+
 export declare class RenderPaintWrapper {
   color(value: number): void;
   thickness(value: number): void;
   join(value: StrokeJoin): void;
   cap(value: StrokeCap): void;
+  strokePosition(value: StrokePosition): void;
   blendMode(value: BlendMode): void;
   style(value: RenderPaintStyle): void;
   linearGradient(sx: number, sy: number, ex: number, ey: number): void;
@@ -323,6 +367,19 @@ export declare class RenderPaintWrapper {
     tx: number,
     ty: number,
   ): void;
+
+  modulatedImage(
+    image: RenderImage,
+    filter: ImageFilter,
+    wrapX: ImageWrap,
+    wrapY: ImageWrap,
+    xx: number,
+    xy: number,
+    yx: number,
+    yy: number,
+    tx: number,
+    ty: number,
+  ): void;
 }
 
 /**
@@ -352,6 +409,8 @@ export declare class RenderPath extends RenderPathWrapper { }
 
 export declare class RenderPaint extends RenderPaintWrapper { }
 
+export declare class RenderImage extends RenderImageWrapper { }
+
 /////////////////////
 // CANVAS RENDERER //
 /////////////////////
@@ -1200,9 +1259,19 @@ export declare class StateMachineInstance {
    */
   textInput(text: string): boolean;
 
+  /**
+   * Submit one frame of gamepad input encoded in the v2 wire format
+   * (see rive-runtime/include/rive/input/gamepad_batch.hpp). Events route to the primary focus
+   * node and bubble up its ancestors; with nothing focused, only scripted drawables receive them.
+   * @param batch - little-endian v2 batch of connected/update/disconnected records
+   * @returns false if the batch was rejected (bad version, malformed record, unknown device,
+   *   or no focus manager)
+   */
+  submitGamepadsFromBuffer(batch: Uint8Array): boolean;
+
   /**
    * The selected text of the focused element, or an empty string when nothing with a
-   * selection is focused. Used to fill the clipboard on copy/cut. An obscured field 
+   * selection is focused. Used to fill the clipboard on copy/cut. An obscured field
    * (i.e. a password) reports empty string.
    */
   selectedText(): string;
@@ -1531,6 +1600,23 @@ export enum BlendMode {
   luminosity = 28,
 }
 
+export enum ImageFilter {
+  bilinear,
+  nearest,
+}
+
+export enum ImageWrap {
+  clamp,
+  repeat,
+  mirror,
+}
+
+export enum StrokePosition {
+  inside,
+  center,
+  outside,
+}
+
 ///////////
 // UTILS //
 ///////////

package/runtimeLoader.d.ts

@@ -10,6 +10,8 @@ export declare class RuntimeLoader {
     private static wasmBinary;
     private static wasmThreadsURL;
     private static triedThreads;
+    private static parallelParts;
+    private static replayWorker;
     private static errorCallbackQueue;
     private constructor();
     /**
@@ -43,6 +45,29 @@ export declare class RuntimeLoader {
      */
     static setWasmThreadsUrl(url: string | null): void;
     static getWasmThreadsUrl(): string | null;
+    /**
+     * Sets how many parts a script's parallel call gets on a page that runs
+     * the threaded build, the page's thread and one worker thread for each
+     * other part. 1 turns parallel calls off, and null leaves the runtime's
+     * default of one part per core, up to 8. Set it before the first file
+     * loads.
+     */
+    static setParallelParts(parts: number | null): void;
+    static getParallelParts(): number | null;
+    private static applyParallelParts;
+    /**
+     * @experimental When the threaded build loads, instances with
+     * `enableGPUCanvas` hand their canvas to one worker that replays every
+     * instance's frames while the page records the next ones. Pass `false`
+     * before the runtime loads to keep replay on the page's thread; a single
+     * instance can opt out with `useReplayWorker: false`. Pages where the
+     * browser cannot draw WebGL2 on a transferred canvas stay on the page's
+     * thread regardless.
+     *
+     * True by default.
+     */
+    static setReplayWorker(enabled: boolean): void;
+    static getReplayWorker(): boolean;
     static setWasmBinary(value: ArrayBuffer | null): void;
     static getWasmBinary(): ArrayBuffer | null;
 }

package/utils/gamepadBatchEncoder.d.ts

@@ -0,0 +1,51 @@
+/** Must match `rive::kGamepadBatchWireVersion` (runtime/include/rive/input/gamepad_batch.hpp). */
+export declare const GAMEPAD_BATCH_VERSION = 2;
+export declare const GAMEPAD_MAX_BUTTONS = 32;
+export declare const GAMEPAD_MAX_AXES = 16;
+/** C++ `rive::GamepadRecordType`. */
+export declare enum GamepadRecordType {
+    Connected = 0,
+    Update = 1,
+    Disconnected = 2
+}
+/** C++ `rive::GamepadInputChangeKind`. */
+export declare enum GamepadChangeKind {
+    Button = 0,
+    Axis = 1
+}
+/** C++ `rive::GamepadMappingKind`. */
+export declare enum GamepadMappingKind {
+    Standard = 0,
+    Unknown = 1
+}
+/**
+ * Builds buffer to send to the state machine for gamepad input connection/updates/disconnect.
+ *
+ * Each `update` record carries a single change: the core
+ * applies and dispatches records in order, so N single-change records in one batch behave like
+ * N separate submits.
+ *
+ * `end()` returns a view into a reused scratch buffer, valid until the next `begin()`.
+ */
+export declare class GamepadBatchEncoder {
+    private buffer;
+    private view;
+    private bytes;
+    private offset;
+    constructor(initialCapacity?: number);
+    begin(): void;
+    /** True when no records were written since `begin()`. */
+    get isEmpty(): boolean;
+    /** Set up buffer size/initialized values for a connected device */
+    connected(deviceId: number, mapping: GamepadMappingKind, buttonValues: ArrayLike<number>, axes: ArrayLike<number>): void;
+    /**  */
+    update(deviceId: number, kind: GamepadChangeKind, index: number, value: number): void;
+    disconnected(deviceId: number): void;
+    end(): Uint8Array;
+    /** ---------------- Helper/private methods ---------------- */
+    private writeU8;
+    private writeU32;
+    private writeI32;
+    private writeF32;
+    private ensure;
+}

package/utils/gamepadInteractions.d.ts

@@ -0,0 +1,25 @@
+import * as rc from "../rive_advanced.mjs";
+export interface GamepadInteractionsParams {
+    /** Hold button/axis input at rest unless DOM focus is within the canvas/overlay. Pads still connect. */
+    requireFocus: boolean;
+    isFocusWithin: () => boolean;
+}
+/**
+ * Per-Rive-instance gamepad bridge driving a single state machine. Tracks what that state
+ * machine has been sent and submits only the difference, so after a pause it catches up
+ * without duplicate connected events.
+ */
+export declare class GamepadInteractions {
+    private params;
+    private encoder;
+    private stateMachine;
+    private lastSentPads;
+    private submitFailures;
+    constructor(params: GamepadInteractionsParams);
+    /** Poll, diff and submit one batch. Call once per frame before advancing. */
+    handleGamepadInputs(time: number, stateMachine: rc.StateMachineInstance | undefined): void;
+    dispose(): void;
+    /** Writes records that bring `lastSentPads` up to `pads`, updating it as it goes. */
+    private encodeDiff;
+    private encodeChanges;
+}

package/utils/index.d.ts

@@ -1,6 +1,7 @@
 export { registerTouchInteractions } from "./registerTouchInteractions";
 export { KeyboardInteractions, FocusSessionState } from "./registerKeyboardInteractions";
 export type { KeyboardInteractionsParams } from "./registerKeyboardInteractions";
+export { GamepadInteractions } from "./gamepadInteractions";
 export { BLANK_URL, sanitizeUrl } from "./sanitizeUrl";
 export { Finalizable, ImageWrapper, AudioWrapper, FontWrapper, FileAssetWrapper, ImageAssetWrapper, AudioAssetWrapper, FontAssetWrapper, finalizationRegistry, CustomFileAssetLoaderWrapper, AssetLoadCallbackWrapper, FileFinalizer, createFinalization, } from "./finalizationRegistry";
 export { RiveFont } from "./riveFont";