@rive-app/canvas-single 2.41.0 → 2.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rive-app/canvas-single",
-  "version": "2.41.0",
+  "version": "2.42.0",
   "description": "Rive's high-level canvas based web api all in one js file.",
   "main": "rive.js",
   "homepage": "https://rive.app",

package/rive.d.ts

@@ -379,6 +379,17 @@ export interface RiveParameters {
      * Enum with drawing options for optimizations
      */
     drawingOptions?: DrawOptimizationOptions;
+    /**
+     * @experimental This API is early and may encounter breaking behavior change without a major version bump
+     *
+     * Render GPU Canvas content, which draws through the deferred renderer.
+     *
+     * Only applies when this instance loads its own file (`src`/`buffer`), where it
+     * is forwarded to that file as {@link RiveFileParameters.enableGPUCanvas}. With a
+     * supplied `riveFile` the file's own flag wins, since a file's mode is fixed at
+     * import. False by default.
+     */
+    enableGPUCanvas?: boolean;
     /**
      * Emit performance.mark / performance.measure entries for load lifecycle
      * events and the first 3 render frames. Useful for profiling Rive's
@@ -467,6 +478,14 @@ export interface RiveLoadParameters {
     tabIndex?: number;
     semanticsMode?: SemanticMode;
     semanticsOptions?: RiveSemanticsOptions;
+    /**
+     * @experimental This API is early and may encounter breaking behavior change without a major version bump
+     *
+     * Render GPU Canvas content, which draws through the deferred renderer. Forwarded
+     * to the file this instance loads; with a supplied `riveFile` the file's flag wins.
+     * False by default.
+     */
+    enableGPUCanvas?: boolean;
 }
 export interface RiveResetParameters {
     artboard?: string;
@@ -501,6 +520,19 @@ export interface RiveFileParameters {
      * events. False by default.
      */
     enablePerfMarks?: boolean;
+    /**
+     * @experimental This API is early and may encounter breaking behavior change without a major version bump
+     *
+     * Render GPU Canvas content in this file, importing it through a deferred
+     * rendering session.
+     *
+     * Fixed at import and has no setter: a file's resources are typed by the factory
+     * that made them and can never switch. The session records for the one canvas that
+     * displays the file, so a second Rive instance sharing this file re-imports it into
+     * a session of its own.
+     * False by default.
+     */
+    enableGPUCanvas?: boolean;
 }
 export declare class RiveFile implements rc.FinalizableTarget {
     private static readonly missingErrorMessage;
@@ -517,8 +549,15 @@ export declare class RiveFile implements rc.FinalizableTarget {
     private destroyed;
     selfUnref: boolean;
     private bindableArtboards;
+    private deferred;
+    private session;
+    private _sessionClaimed;
+    private fileFinalizer;
+    private boundElsewhereWarned;
+    private static deferredUnsupportedWarned;
     constructor(params: RiveFileParameters);
     private releaseFile;
+    private releaseSession;
     private releaseBindableArtboards;
     private initData;
     private loadRiveFileBytes;
@@ -538,6 +577,38 @@ export declare class RiveFile implements rc.FinalizableTarget {
      */
     off(type: EventType, callback: EventCallback): void;
     cleanup(): void;
+    private static makeDeferredSession;
+    /**
+     * @internal The deferred session this file imported through, or null if it
+     * was imported in immediate mode.
+     */
+    get deferredSession(): rc.DeferredSession | null;
+    /**
+     * @internal Whether deferred was asked for, even when this build could not
+     * honor it and imported immediate.
+     */
+    get deferredRequested(): boolean;
+    /**
+     * @internal Whether this file's session has ever been attached to a renderer.
+     * Attaching is once per session, so a claimed file re-imports for the next
+     * instance even after the renderer it was bound to is gone.
+     */
+    get sessionClaimed(): boolean;
+    /**
+     * @internal Marks this file's session as spent. There is no matching release:
+     * a session that has been attached can never replay for another renderer.
+     */
+    claimSession(): void;
+    /**
+     * @internal One warning per file however many instances collide on it.
+     */
+    warnBoundElsewhereOnce(): void;
+    /**
+     * @internal Re-imports this file from its retained buffer into a mode of its
+     * own. The copy is owned by whoever asked for it and never joins this file's
+     * reference count.
+     */
+    reimport(deferred: boolean): Promise<RiveFile>;
     /**
      * Unsubscribes all Rive listeners from an event type, or everything if no type is
      * given
@@ -582,6 +653,8 @@ export declare class Rive {
      */
     private readyForPlaying;
     private runtime;
+    private deferredRenderer;
+    private ownsRiveFile;
     private artboard;
     private eventCleanup;
     private _keyboardInteractions;
@@ -681,9 +754,18 @@ export declare class Rive {
     private initializeAudio;
     private initArtboardSize;
     private initData;
+    /**
+     * Settles which rendering mode this Rive instance runs in. The file dictates: its rendering mode
+     * is fixed at import, and an immediate renderer silently drops a deferred
+     * file's resources. Every mismatch warns and degrades to something that
+     * renders, so users shouldn't have a blank canvas. A fallback self-reimport replaces `this.riveFile`;
+     * only a file this instance imported is released when that happens.
+     */
+    private resolveDeferredRendering;
     private initArtboard;
     drawFrame(): void;
     private _canvasSizeChanged;
+    private _deferredWorkPending;
     /**
      * Poll focus state each frame to see if we should focus/blur the canvas in case
      * Rive internally updated focus outside of user interaction (e.g., via listener action)
@@ -723,11 +805,31 @@ export declare class Rive {
      * Rive class
      */
     cleanup(): void;
+    /**
+     * Drops this instance's hold on `this.riveFile`. A reference taken through
+     * getInstance() is given back; a file we imported but never referenced is
+     * released outright so its session goes with it. A caller-supplied file we
+     * never referenced is left alone.
+     *
+     * `isTeardown` distinguishes cleanup() from a reload. Teardown always hands
+     * the reference back, as it always has. A reload must not do that for a
+     * caller-supplied file: a RiveFile carries no reference for its creator, so
+     * releasing here would take the last one and destroy a file the caller still
+     * holds.
+     */
+    private releaseCurrentRiveFile;
     /**
      * Cleans up the Renderer object. Only call this API if you no longer
      * need to render Rive content in your session.
      */
     deleteRiveRenderer(): void;
+    /**
+     * @experimental This API is early and may encounter breaking behavior change without a major version bump
+     *
+     * Whether this instance is rendering through a deferred session. False whenever
+     * a fallback ran, whatever was requested.
+     */
+    get deferredRendererActive(): boolean;
     /**
      * Cleans up any Wasm-generated objects that need to be manually destroyed:
      * artboard instances, animation instances, state machine instances.