pixijs-core-concepts

Modèle fondateur pour la façon dont PixiJS v8 affiche les pixels à l'écran : le renderer choisit le backend GPU à utiliser, la boucle de rendu pilote le travail par frame, et la couche d'environnement adapte la librairie aux contextes navigateur, Web Worker ou SSR. Pour le graphe de scène lui-même (Containers, transforms, destroy), voir pixijs-scene-core-concepts.

Démarrage rapide

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 est le WebGLRenderer, WebGPURenderer, ou CanvasRenderer choisi par autoDetectRenderer. Le TickerPlugin pilote renderer.render() automatiquement ; appelez-le manuellement seulement avec autoStart: false. La sélection du backend se fait dans Application.init({ preference }); voir pixijs-application pour la configuration.

Skills associées : pixijs-application (construction et cycle de vie d'Application), pixijs-ticker (logique par frame, priorités, limitation FPS), pixijs-environments (Web Worker, SSR, CSP strict), pixijs-custom-rendering (écrire un RenderPipe), pixijs-scene-core-concepts (bases du graphe de scène).

Sujets

Pour des approfondissements sur un sujet particulier, ouvrez le fichier de référence correspondant. Les cibles non-navigateur (DOMAdapter, WebWorkerAdapter, adaptateurs personnalisés, CSP strict) sont couverts dans la skill pixijs-environments.

Guide de décision

• Vous mettez en place une Application ? Commencez par pixijs-application. Cette skill explique ce que fait le renderer sous le capot.
• Choisir entre WebGL et WebGPU ? Utilisez ['webgpu', 'webgl'] comme tableau de préférence. WebGPU est le plus rapide où disponible ; WebGL est le fallback fiable. Voir references/renderers.md.
• Exécuter dans un Web Worker ? Configurez DOMAdapter.set(WebWorkerAdapter) avant app.init. Voir la skill pixijs-environments pour la configuration complète.
• Besoin de contrôle manuel sur quand le rendu se produit ? Configurez autoStart: false et appelez app.renderer.render(app.stage) depuis votre propre boucle. Voir references/render-loop.md.
• Intégration avec une librairie de physique ? Ajoutez votre mise à jour à UPDATE_PRIORITY.HIGH afin que la physique s'exécute avant le rendu à LOW. Voir references/render-loop.md.
• Écrire un renderable personnalisé ? Implémentez un RenderPipe. Voir la skill pixijs-custom-rendering.
• Exécuter sous CSP strict ? Importez 'pixi.js/unsafe-eval'. Voir la skill pixijs-environments.

Concepts rapides

Renderer = systèmes + pipes

Chaque renderer est composé de Systems (services de cycle de vie : textures, buffers, état, filtres, masques) et de RenderPipes (constructeurs d'instructions par renderable : sprite, graphics, mesh, particle, text, tiling). Écrire un renderable personnalisé signifie implémenter un RenderPipe et le regristrer via extensions.

La boucle de rendu

app.ticker.add(fn) enregistre un callback qui s'exécute chaque frame. Le TickerPlugin enregistre app.render() à UPDATE_PRIORITY.LOW, donc les callbacks du ticker à NORMAL ou HIGH s'exécutent avant le dessin. Désactivez le plugin avec autoStart: false pour un contrôle manuel.

Environnements

DOMAdapter abstrait chaque appel DOM que PixiJS effectue (création de canvas, chargement d'images, fetch, analyse XML). Échangez avec DOMAdapter.set(WebWorkerAdapter) pour les Workers ou implémentez un Adapter personnalisé pour Node/SSR. Doit être fait avant Application.init.

Erreurs courantes

[HIGH] Accéder à app.renderer avant que init() se résolve

Incorrect :

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

Correct :

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

Application.init() est asynchrone. app.renderer, app.canvas, et app.screen n'existent pas jusqu'après la résolution de la promesse.

[HIGH] Configurer DOMAdapter après Application.init

Incorrect :

const app = new Application();
await app.init({ width: 800, height: 600 });
DOMAdapter.set(WebWorkerAdapter); // trop tard — init a déjà alloué les ressources

Correct :

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

L'adapter abstrait les appels DOM que le renderer effectue pendant la construction (création de canvas, chargement d'images, fetch). Échangez-le avant init() ou le mauvais adapter sera intégré au renderer.

[MEDIUM] Traiter preference comme une garantie

Incorrect :

await app.init({ preference: "webgpu" });
// supposer que WebGPU est actif
useWebGPUOnlyFeature(app.renderer);

Correct :

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

preference est une suggestion, pas une exigence. Si le navigateur manque de support WebGPU, PixiJS bascule vers WebGL (ou Canvas). Branchez toujours sur renderer.name pour le code spécifique au backend.

Référence API

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