pixijs-blend-modes

Réglez container.blendMode pour composer des objets d'affichage avec des équations de blend GPU (modes standard) ou des modes avancés basés sur des filtres. Les transitions de blend mode cassent les render batch, regroupez donc les frères et sœurs de modes similaires ensemble.

Quick Start

const light = new Sprite(await Assets.load("light.png"));
light.blendMode = "add";
app.stage.addChild(light);

const shadow = new Sprite(await Assets.load("shadow.png"));
shadow.blendMode = "multiply";
app.stage.addChild(shadow);

import "pixi.js/advanced-blend-modes";
const overlay = new Sprite(await Assets.load("overlay.png"));
overlay.blendMode = "color-burn";
app.stage.addChild(overlay);

Skills connexes : pixijs-filters (les modes avancés utilisent le pipeline de filtres), pixijs-performance (batching avec blend modes), pixijs-color (manipulation des couleurs).

Core Patterns

Standard blend modes

Les modes standard sont intégrés et utilisent directement les équations de blend GPU :

import { Sprite } from "pixi.js";

sprite.blendMode = "normal"; // standard alpha compositing (effective default at root)
sprite.blendMode = "add"; // additive (lighten, glow effects)
sprite.blendMode = "multiply"; // multiply (darken, shadow effects)
sprite.blendMode = "screen"; // screen (lighten, dodge effects)
sprite.blendMode = "erase"; // erase pixels from render target
sprite.blendMode = "none"; // no blending, overwrites destination
sprite.blendMode = "inherit"; // inherit from parent (this is the actual default value)
sprite.blendMode = "min"; // keeps minimum of source and destination (WebGL2+ only)
sprite.blendMode = "max"; // keeps maximum of source and destination (WebGL2+ only)

Ils sont accélérés matériellement et peu coûteux. Ils ne requièrent pas de filtres.

Advanced blend modes

Les modes avancés nécessitent un import explicite pour enregistrer les extensions. Sur le renderer WebGL, ils nécessitent également useBackBuffer: true au moment de l'initialisation, sinon PixiJS enregistre un avertissement et le blend revient silencieusement à la normale :

import "pixi.js/advanced-blend-modes";
import { Application, Sprite, Assets } from "pixi.js";

const app = new Application();
await app.init({ useBackBuffer: true }); // required for advanced modes on WebGL

const texture = await Assets.load("overlay.png");
const overlay = new Sprite(texture);
overlay.blendMode = "color-burn";

Modes avancés disponibles :

Vous réglez les modes de blend avancés de la même façon que les modes standard, via la propriété blendMode. Ils utilisent des filtres en interne, donc ils coûtent plus cher que les modes standard.

Batch-friendly ordering

Des modes de blend différents cassent le rendering batch. Ordonnez les objets pour minimiser les transitions :

import { Container, Sprite } from "pixi.js";

const scene = new Container();
scene.addChild(screenSprite1); // 'screen'
scene.addChild(screenSprite2); // 'screen'
scene.addChild(normalSprite1); // 'normal'
scene.addChild(normalSprite2); // 'normal'

2 appels de dessin. Un ordre alternant (screen, normal, screen, normal) produirait 4.

Common Mistakes

[HIGH] Not importing advanced-blend-modes extension

Mauvais :

import { Sprite } from "pixi.js";

sprite.blendMode = "color-burn"; // silently falls back to normal

Correct :

import "pixi.js/advanced-blend-modes";
import { Sprite } from "pixi.js";

sprite.blendMode = "color-burn";

Les modes de blend avancés (color-burn, overlay, etc.) nécessitent l'import de l'extension. Sans lui, seuls les modes standard (normal, add, multiply, screen) sont disponibles. Le mode invalide revient silencieusement à la normale.

[MEDIUM] Mixing blend modes across adjacent objects

Les modes de blend différents cassent le render batch. screen / normal / screen / normal produit 4 appels de dessin, tandis que screen / screen / normal / normal produit 2. Triez les enfants pour que les objets ayant le même mode de blend soient adjacents.

[HIGH] Using the v7 BLEND_MODES enum

Mauvais :

import { BLEND_MODES } from "pixi.js";

sprite.blendMode = BLEND_MODES.ADD; // runtime error: BLEND_MODES is undefined

Correct :

sprite.blendMode = "add";

En v8, BLEND_MODES est un type TypeScript uniquement (une union de littéraux de chaîne). Il n'y a pas d'export d'enum à l'exécution, donc BLEND_MODES.ADD évalue l'accès à une propriété sur undefined. Utilisez la forme chaîne.

[HIGH] Advanced blend modes without useBackBuffer

Mauvais :

import "pixi.js/advanced-blend-modes";
await app.init({
  /* no useBackBuffer */
});
sprite.blendMode = "color-burn"; // logs a warning, falls back

Correct :

import "pixi.js/advanced-blend-modes";
await app.init({ useBackBuffer: true });
sprite.blendMode = "color-burn";

Les modes avancés lisent depuis le back buffer. Sur WebGL, le blend revient silencieusement à la normale si le back buffer n'est pas activé. WebGPU active le back buffer inconditionnellement.

API Reference

• Container.blendMode
• OverlayBlend
• ColorBurnBlend
• ColorDodgeBlend
• HardLightBlend
• SoftLightBlend
• DifferenceBlend