pixijs-core-concepts

PixiJS v8 如何将像素绘制到屏幕上的基础模型：渲染器决定使用哪个 GPU 后端，渲染循环负责每帧的工作，环境层则让库适配浏览器、Web Worker 或 SSR 环境。关于场景图本身（容器、变换、销毁），请参阅 pixijs-scene-core-concepts。

快速开始

console.log(app.renderer.name); // 'webgl' | 'webgpu' | 'canvas'

app.ticker.add((ticker) => {
  sprite.rotation += 0.01 * ticker.deltaTime;
});

const tex = app.renderer.extract.texture({ target: app.stage });

app.renderer.render({ container: app.stage });

app.renderer 是由 autoDetectRenderer 选择的 WebGLRenderer、WebGPURenderer 或 CanvasRenderer。TickerPlugin 会自动驱动 renderer.render()；只有在设置 autoStart: false 时才需要手动调用。在 Application.init({ preference }) 中选择后端；设置方法请参阅 pixijs-application。

相关技能： pixijs-application（Application 的构建与生命周期）、pixijs-ticker（每帧逻辑、优先级、FPS 上限）、pixijs-environments（Web Worker、SSR、严格 CSP）、pixijs-custom-rendering（编写 RenderPipe）、pixijs-scene-core-concepts（场景图基础）。

主题

主题	参考资料	适用场景
选择后端	references/renderers.md	偏好设置形式、各渲染器选项、系统和管线
每帧执行	references/render-loop.md	优先级顺序、时间单位、手动渲染

如需深入了解任何单个主题，请打开相应的参考文件。非浏览器目标（DOMAdapter、WebWorkerAdapter、自定义适配器、严格 CSP）请参阅 pixijs-environments 技能。

决策指南

• 正在设置 Application？ 从 pixijs-application 开始。本技能将解释渲染器在底层的工作方式。
• 在 WebGL 和 WebGPU 之间选择？ 使用 ['webgpu', 'webgl'] 作为偏好数组。WebGPU 在可用时速度最快；WebGL 是可靠的后备选项。请参阅 references/renderers.md。
• 在 Web Worker 中运行？ 在 app.init 之前设置 DOMAdapter.set(WebWorkerAdapter)。完整设置方法请参阅 pixijs-environments 技能。
• 需要手动控制渲染时机？ 设置 autoStart: false，并在自己的循环中调用 app.renderer.render(app.stage)。请参阅 references/render-loop.md。
• 要与物理库集成？ 在 UPDATE_PRIORITY.HIGH 添加更新逻辑，以便物理运算先于 LOW 优先级的渲染执行。请参阅 references/render-loop.md。
• 要编写自定义可渲染对象？ 实现 RenderPipe。请参阅 pixijs-custom-rendering 技能。
• 要渲染到纹理或自定义渲染目标？ 将 target 传递给 renderer.render()，或使用显式的颜色和深度附件构建 RenderTarget。请参阅 references/renderers.md。
• 在严格 CSP 下运行？ 导入 'pixi.js/unsafe-eval'。请参阅 pixijs-environments 技能。

快速了解

渲染器 = 系统 + 管线

每个渲染器都由 Systems（生命周期服务：纹理、缓冲区、状态、滤镜、遮罩）和 RenderPipes（逐个可渲染对象的指令构建器：精灵、图形、网格、粒子、文本、平铺）组成。编写自定义可渲染对象意味着要实现 RenderPipe 并通过扩展注册它。后端专用的系统和管线可以通过渲染器加载器扩展（WebGLLoader、WebGPULoader、CanvasLoader）动态导入；请参阅 references/renderers.md。

渲染循环

app.ticker.add(fn) 会注册一个每帧运行的回调。TickerPlugin 会在 UPDATE_PRIORITY.LOW 注册 app.render()，因此，优先级为 NORMAL 或 HIGH 的 ticker 回调会先于绘制运行。若要手动控制，请通过 autoStart: false 禁用此插件。

环境

DOMAdapter 抽象了 PixiJS 调用的所有 DOM 操作（创建画布、加载图像、fetch、解析 XML）。在 Worker 中使用 DOMAdapter.set(WebWorkerAdapter) 进行替换，或为 Node/SSR 实现自定义 Adapter。必须在 Application.init 之前完成。

常见错误

[HIGH] 在 init() 完成前访问 app.renderer

错误：

const app = new Application();
app.init({ width: 800, height: 600 });
console.log(app.renderer.name); // undefined — init() is async

正确：

const app = new Application();
await app.init({ width: 800, height: 600 });
console.log(app.renderer.name); // 'webgl' | 'webgpu' | 'canvas'

Application.init() 是异步的。在 Promise 完成之前，app.renderer、app.canvas 和 app.screen 都不存在。

[HIGH] 在 Application.init 之后设置 DOMAdapter

错误：

const app = new Application();
await app.init({ width: 800, height: 600 });
DOMAdapter.set(WebWorkerAdapter); // too late — init already allocated resources

正确：

DOMAdapter.set(WebWorkerAdapter);
const app = new Application();
await app.init({ width: 800, height: 600 });

此适配器抽象了渲染器在构造期间执行的 DOM 操作（创建画布、加载图像、fetch）。请在 init() 之前替换适配器，否则渲染器中会固化错误的适配器。

[MEDIUM] 将 preference 当作保证

错误：

await app.init({ preference: "webgpu" });
// assume WebGPU is active
useWebGPUOnlyFeature(app.renderer);

正确：

await app.init({ preference: "webgpu" });
if (app.renderer.name === "webgpu") {
  useWebGPUOnlyFeature(app.renderer);
}

preference 只是提示，而非强制要求。如果浏览器不支持 WebGPU，PixiJS 会回退到 WebGL（或 Canvas）。对于特定后端的代码，始终根据 renderer.name 进行分支处理。

API 参考

• autoDetectRenderer
• AbstractRenderer
• WebGLRenderer
• WebGPURenderer
• CanvasRenderer
• Application
• DOMAdapter