GPU Canvas

GPU Canvas 让 Rive 文件能在 React 运行时中渲染 3D 与着色器内容。它按 Rive 实例选择启用，并在 @rive-app/react-webgl2 4.34.0+ 中可用。

⚠️

GPU Canvas 目前为实验性功能。API 可能在次版本中变更，而无需主版本升级。

要求

• 仅限 @rive-app/react-webgl2。 Canvas2D 包（@rive-app/react-canvas、@rive-app/react-canvas-lite）目前尚不支持 GPU Canvas。
• useOffscreenRenderer 必须保持为 false。 GPU Canvas 渲染需要每个 <canvas> 拥有独立的 WebGL 上下文，而离屏渲染器模式会在页面上的所有 canvas 之间共享一个上下文。
  • React 默认将该选项设为 true，但启用 GPU Canvas 会自动将默认值翻转为 false，因此除非你显式将其设为 true，否则无需改动。

启用 GPU Canvas

在传给 useRive 的参数中设置 enableGPUCanvas: true：

import { useRive } from '@rive-app/react-webgl2';

export default function Scene() {
  const { RiveComponent } = useRive({
    src: 'my_file.riv',
    stateMachine: 'State Machine 1',
    autoplay: true,
    autoBind: true,
    enableGPUCanvas: true,
  });

  return <RiveComponent />;
}

默认导出的 <Rive /> 组件接受相同的 prop：

import Rive from '@rive-app/react-webgl2';

<Rive
  src="my_file.riv"
  stateMachine="State Machine 1"
  enableGPUCanvas
/>

GPU Canvas 默认关闭，但未来的主版本中可能会改变这一默认行为。

在缓存文件上启用 GPU Canvas

useRiveFile 接受相同的标志。RiveFile 的渲染模式在创建时固定，因此更改 enableGPUCanvas 会重新构造该文件：

import { useRive, useRiveFile } from '@rive-app/react-webgl2';

export default function Scene() {
  const { riveFile, status } = useRiveFile({
    src: 'my_file.riv',
    enableGPUCanvas: true,
  });

  const { RiveComponent } = useRive(
    status === 'success'
      ? {
          riveFile,
          stateMachine: 'State Machine 1',
          autoplay: true,
          autoBind: true,
          enableGPUCanvas: true,
        }
      : null
  );

  return <RiveComponent />;
}

RiveFile 上的标志优先于 useRive 上的同名属性。以 enableGPUCanvas: true 创建的 RiveFile 会通过所需的延迟渲染技术进行渲染，即使 useRive 传入 enableGPUCanvas: false（或未设置），运行时也会记录一条警告。useRive 同样会读取文件的模式，因此 GPU Canvas 文件会关闭离屏渲染器优化，即使组件从未设置 enableGPUCanvas: true。

⚠️

GPU Canvas 文件不能在多个 Rive 实例之间共享。 渲染器会将文件绑定到单个 <canvas>，因此你传入的第一个组件会占用它。对每个需要同一 .riv 的组件分别调用 useRiveFile。

额外的组件仍会加载，但不会使用你传入的文件。相反，运行时会记录一条警告，并从该文件已有的 buffer 创建一份新的 .riv 副本。因此，你通过原始文件读取或配置的任何内容都不会应用到这些额外组件上。

限制

每个 GPU Canvas 实例使用自己的 WebGL 上下文，而浏览器会限制一个页面可以持有的上下文数量。请仅对需要它的图形启用 GPU Canvas。参见 WebGL 上下文限制。

相关文档

• 参数和返回值 — 完整 Hook 参考
• Web (JS)：GPU Canvas