Back to Details

pixijs-core-concepts

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Foundational model for how PixiJS v8 gets pixels on the screen: the renderer decides which GPU backend to use, the render loop drives per-frame work, and the environment layer adapts the library to browser, Web Worker, or SSR contexts. For the scene graph itself (Containers, transforms, destroy), see 
pixijs-scene-core-concepts
.
PixiJS v8将像素渲染到屏幕的基础模型：渲染器决定使用哪个GPU后端，渲染循环驱动每帧的工作，环境层使库适配浏览器、Web Worker或SSR上下文。关于场景图本身（Containers、transforms、destroy），请查看
pixijs-scene-core-concepts
。

Quick Start

快速入门

ts
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
is the 
WebGLRenderer
, 
WebGPURenderer
, or 
CanvasRenderer
chosen by 
autoDetectRenderer
. The TickerPlugin drives 
renderer.render()
automatically; call it manually only with 
autoStart: false
. Backend selection happens in 
Application.init({ preference })
; see 
pixijs-application
for setup.
Related skills: 
pixijs-application
(Application construction and lifecycle), 
pixijs-ticker
(per-frame logic, priorities, FPS capping), 
pixijs-environments
(Web Worker, SSR, strict CSP), 
pixijs-custom-rendering
(writing a RenderPipe), 
pixijs-scene-core-concepts
(scene graph basics).
ts
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
（应用构建与生命周期）、
pixijs-ticker
（每帧逻辑、优先级、FPS限制）、
pixijs-environments
（Web Worker、SSR、严格CSP）、
pixijs-custom-rendering
（编写RenderPipe）、
pixijs-scene-core-concepts
（场景图基础）。

Topics

主题

TopicReferenceWhen
Choosing a backendreferences/renderers.mdPreference forms, per-renderer options, systems and pipes
Per-frame executionreferences/render-loop.mdPriority order, time units, manual rendering
For deep dives into any single topic, open the corresponding reference file. Non-browser targets (
DOMAdapter
, 
WebWorkerAdapter
, custom adapters, strict CSP) are covered in the 
pixijs-environments
skill.
主题参考文档适用场景
选择后端references/renderers.md偏好设置、各渲染器选项、系统与管道
每帧执行逻辑references/render-loop.md优先级顺序、时间单位、手动渲染
如需深入了解任一主题，请打开对应的参考文档。非浏览器目标（
DOMAdapter
、
WebWorkerAdapter
、自定义适配器、严格CSP）在
pixijs-environments
技能中讲解。

Decision guide

决策指南

  • Setting up an Application? Start with 
    pixijs-application
    . This skill explains what the renderer does under the hood.
  • Choosing between WebGL and WebGPU? Use 
    ['webgpu', 'webgl']
    as your preference array. WebGPU is fastest where available; WebGL is the reliable fallback. See 
    references/renderers.md
    .
  • Running in a Web Worker? Set 
    DOMAdapter.set(WebWorkerAdapter)
    before 
    app.init
    . See the 
    pixijs-environments
    skill for complete setup.
  • Need manual control over when rendering happens? Set 
    autoStart: false
    and call 
    app.renderer.render(app.stage)
    from your own loop. See 
    references/render-loop.md
    .
  • Integrating with a physics library? Add your update at 
    UPDATE_PRIORITY.HIGH
    so physics runs before the render at 
    LOW
    . See 
    references/render-loop.md
    .
  • Writing a custom renderable? Implement a 
    RenderPipe
    . See 
    pixijs-custom-rendering
    skill.
  • Running under strict CSP? Import 
    'pixi.js/unsafe-eval'
    . See the 
    pixijs-environments
    skill.
  • 设置应用程序？ 从
    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
    技能。
  • 在严格CSP下运行？ 导入
    'pixi.js/unsafe-eval'
    。请查看
    pixijs-environments
    技能。

Quick concepts

核心概念

Renderer = systems + pipes

渲染器 = 系统 + 管道

Each renderer is composed of 
Systems
(lifecycle services: textures, buffers, state, filters, masks) and 
RenderPipes
(per-renderable instruction builders: sprite, graphics, mesh, particle, text, tiling). Writing a custom renderable means implementing a 
RenderPipe
and registering it via extensions.
每个渲染器由
Systems
（生命周期服务：纹理、缓冲区、状态、滤镜、遮罩）和
RenderPipes
（每个可渲染对象的指令构建器：精灵、图形、网格、粒子、文本、平铺）组成。编写自定义可渲染对象意味着实现一个
RenderPipe
并通过扩展进行注册。

The render loop

渲染循环

app.ticker.add(fn)
registers a callback that runs every frame. The 
TickerPlugin
registers 
app.render()
at 
UPDATE_PRIORITY.LOW
, so ticker callbacks at 
NORMAL
or 
HIGH
run before the draw. Disable the plugin with 
autoStart: false
for manual control.
app.ticker.add(fn)
注册一个每帧运行的回调函数。TickerPlugin会在
UPDATE_PRIORITY.LOW
优先级注册
app.render()
，因此
NORMAL
或
HIGH
优先级的ticker回调会在绘制前运行。设置
autoStart: false
可禁用该插件，实现手动控制。

Environments

环境适配

DOMAdapter
abstracts every DOM call PixiJS makes (canvas creation, image loading, fetch, XML parsing). Swap with 
DOMAdapter.set(WebWorkerAdapter)
for Workers or implement a custom 
Adapter
for Node/SSR. Must be done before 
Application.init
.
DOMAdapter
抽象了PixiJS进行的所有DOM调用（画布创建、图片加载、fetch、XML解析）。在Worker环境中可替换为
DOMAdapter.set(WebWorkerAdapter)
，或为Node/SSR实现自定义
Adapter
。必须在
Application.init
之前完成替换。

Common Mistakes

常见错误

[HIGH] Accessing app.renderer before init() resolves

[高风险] 在init()完成前访问app.renderer

Wrong:
ts
const app = new Application();
app.init({ width: 800, height: 600 });
console.log(app.renderer.name); // undefined — init() is async
Correct:
ts
const app = new Application();
await app.init({ width: 800, height: 600 });
console.log(app.renderer.name); // 'webgl' | 'webgpu' | 'canvas'
Application.init()
is async. 
app.renderer
, 
app.canvas
, and 
app.screen
do not exist until after the promise resolves.
错误示例：
ts
const app = new Application();
app.init({ width: 800, height: 600 });
console.log(app.renderer.name); // undefined — init()是异步的
正确示例：
ts
const app = new Application();
await app.init({ width: 800, height: 600 });
console.log(app.renderer.name); // 'webgl' | 'webgpu' | 'canvas'
Application.init()
是异步的。
app.renderer
、
app.canvas
和
app.screen
要等到Promise解析后才会存在。

[HIGH] Setting DOMAdapter after Application.init

[高风险] 在Application.init之后设置DOMAdapter

Wrong:
ts
const app = new Application();
await app.init({ width: 800, height: 600 });
DOMAdapter.set(WebWorkerAdapter); // too late — init already allocated resources
Correct:
ts
DOMAdapter.set(WebWorkerAdapter);
const app = new Application();
await app.init({ width: 800, height: 600 });
The adapter abstracts DOM calls the renderer makes during construction (canvas creation, image loading, fetch). Swap it before 
init()
or the wrong adapter is baked into the renderer.
错误示例：
ts
const app = new Application();
await app.init({ width: 800, height: 600 });
DOMAdapter.set(WebWorkerAdapter); // 太晚了 — init已经分配了资源
正确示例：
ts
DOMAdapter.set(WebWorkerAdapter);
const app = new Application();
await app.init({ width: 800, height: 600 });
适配器会抽象渲染器在构建过程中进行的DOM调用（画布创建、图片加载、fetch）。必须在
init()
之前替换，否则错误的适配器会被固化到渲染器中。

[MEDIUM] Treating 
preference
as a guarantee

[中风险] 将
preference
视为绝对保证

Wrong:
ts
await app.init({ preference: "webgpu" });
// assume WebGPU is active
useWebGPUOnlyFeature(app.renderer);
Correct:
ts
await app.init({ preference: "webgpu" });
if (app.renderer.name === "webgpu") {
  useWebGPUOnlyFeature(app.renderer);
}
preference
is a hint, not a demand. If the browser lacks WebGPU support, PixiJS falls back to WebGL (or Canvas). Always branch on 
renderer.name
for backend-specific code.
错误示例：
ts
await app.init({ preference: "webgpu" });
// 假设WebGPU已激活
useWebGPUOnlyFeature(app.renderer);
正确示例：
ts
await app.init({ preference: "webgpu" });
if (app.renderer.name === "webgpu") {
  useWebGPUOnlyFeature(app.renderer);
}
preference
是一个提示，而非强制要求。如果浏览器不支持WebGPU，PixiJS会回退到WebGL（或Canvas）。对于后端特定代码，务必根据
renderer.name
进行分支处理。

API Reference

API参考