pixijs-blend-modes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Set

container.blendMode

to composite display objects with GPU blend equations (standard modes) or filter-based advanced modes. Blend-mode transitions break render batches, so group like-mode siblings together.

设置

container.blendMode

，即可通过GPU混合公式（标准模式）或基于滤镜的高级模式合成显示对象。混合模式的切换会打断渲染批处理，因此请将相同模式的同级对象归为一组。

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);

Related skills:

pixijs-filters

(advanced modes use the filter pipeline),

pixijs-performance

(batching with blend modes),

pixijs-color

(color manipulation).

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);

相关技能：

pixijs-filters

（高级模式使用滤镜管线）、

pixijs-performance

（混合模式下的批处理）、

pixijs-color

（颜色操作）。

Core Patterns

核心模式

Standard blend modes

标准混合模式

Standard modes are built in and use GPU blend equations directly:

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)

These are hardware-accelerated and cheap. They do not require filters.

标准模式是内置的，直接使用GPU混合公式：

import { Sprite } from "pixi.js";

sprite.blendMode = "normal"; // 标准alpha合成（根节点的默认有效模式）
sprite.blendMode = "add"; // 加法模式（提亮、发光效果）
sprite.blendMode = "multiply"; // 正片叠底（加深、阴影效果）
sprite.blendMode = "screen"; // 滤色（提亮、减淡效果）
sprite.blendMode = "erase"; // 擦除渲染目标中的像素
sprite.blendMode = "none"; // 无混合，直接覆盖目标
sprite.blendMode = "inherit"; // 继承父级模式（这是实际的默认值）
sprite.blendMode = "min"; // 保留源和目标中的最小值（仅WebGL2+支持）
sprite.blendMode = "max"; // 保留源和目标中的最大值（仅WebGL2+支持）

这些模式由硬件加速，性能开销低，无需使用滤镜。

Advanced blend modes

高级混合模式

Advanced modes require an explicit import to register the extensions. On the WebGL renderer they also require

useBackBuffer: true

at init time, or PixiJS logs a warning and the blend silently falls back:

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";

Available advanced modes:

Mode	Effect
`color-burn`	Darkens by increasing contrast
`color-dodge`	Brightens by decreasing contrast
`darken`	Keeps darker of two layers
`difference`	Absolute difference
`divide`	Divides bottom by top
`exclusion`	Similar to difference, lower contrast
`hard-light`	Multiply or screen based on top layer
`hard-mix`	High contrast threshold blend
`lighten`	Keeps lighter of two layers
`linear-burn`	Adds and subtracts to darken
`linear-dodge`	Adds layers together
`linear-light`	Linear burn or dodge based on top layer
`luminosity`	Luminosity of top, hue/saturation of bottom
`negation`	Inverted difference
`overlay`	Multiply or screen based on bottom layer
`pin-light`	Replaces based on lightness comparison
`saturation`	Saturation of top, hue/luminosity of bottom
`soft-light`	Gentle overlay effect
`subtract`	Subtracts top from bottom
`vivid-light`	Color burn or dodge based on top layer
`color`	Hue and saturation of top, luminosity of bottom

You set advanced blend modes the same way as standard ones, via the

blendMode

property. They use filters internally, so they cost more than standard modes.

高级模式需要显式导入以注册扩展。在WebGL渲染器中，还需要在初始化时设置

useBackBuffer: true

，否则PixiJS会记录警告并自动回退到标准模式：

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

const app = new Application();
await app.init({ useBackBuffer: true }); // WebGL下使用高级模式的必要配置

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

可用的高级模式：

模式	效果
`color-burn`	通过提高对比度来加深颜色
`color-dodge`	通过降低对比度来提亮颜色
`darken`	保留两个图层中较暗的部分
`difference`	计算颜色的绝对差
`divide`	用底层颜色除以上层颜色
`exclusion`	与difference类似，但对比度更低
`hard-light`	根据上层颜色选择正片叠底或滤色
`hard-mix`	高对比度阈值混合
`lighten`	保留两个图层中较亮的部分
`linear-burn`	通过加减操作加深颜色
`linear-dodge`	将两个图层颜色相加
`linear-light`	根据上层颜色选择linear burn或linear dodge
`luminosity`	保留上层的亮度，底层的色相/饱和度
`negation`	反转颜色差值
`overlay`	根据底层颜色选择正片叠底或滤色
`pin-light`	根据亮度比较结果替换颜色
`saturation`	保留上层的饱和度，底层的色相/亮度
`soft-light`	柔和的叠加效果
`subtract`	用底层颜色减去上层颜色
`vivid-light`	根据上层颜色选择color burn或color dodge
`color`	保留上层的色相和饱和度，底层的亮度

设置高级混合模式的方式与标准模式相同，都是通过

blendMode

属性。它们内部使用滤镜，因此性能开销比标准模式更高。

Batch-friendly ordering

批处理友好的排序方式

Different blend modes break the rendering batch. Order objects to minimize 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 draw calls. Alternating order (

screen, normal, screen, normal

) would produce 4.

不同的混合模式会打断渲染批处理。对对象进行排序以减少模式切换：

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次绘制调用。如果交替排序（

screen、normal、screen、normal

）则会产生4次绘制调用。

Common Mistakes

常见错误

[HIGH] Not importing advanced-blend-modes extension

[高风险] 未导入advanced-blend-modes扩展

Wrong:

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";

Advanced blend modes (color-burn, overlay, etc.) require the extension import. Without it, only standard modes (normal, add, multiply, screen) are available. The invalid mode silently falls back.

错误示例：

import { Sprite } from "pixi.js";

sprite.blendMode = "color-burn"; // 自动回退到normal模式

正确示例：

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

sprite.blendMode = "color-burn";

高级混合模式（color-burn、overlay等）需要导入扩展。如果不导入，仅能使用标准模式（normal、add、multiply、screen），无效模式会自动回退。

[MEDIUM] Mixing blend modes across adjacent objects

[中风险] 在相邻对象间混合不同的混合模式

Different blend modes break the render batch.

screen / normal / screen / normal

produces 4 draw calls, while

screen / screen / normal / normal

produces 2. Sort children so objects with the same blend mode are adjacent.

不同的混合模式会打断渲染批处理。

screen / normal / screen / normal

会产生4次绘制调用，而

screen / screen / normal / normal

仅产生2次。请对子级进行排序，让相同混合模式的对象相邻。

[HIGH] Using the v7 BLEND_MODES enum

[高风险] 使用v7版本的BLEND_MODES枚举

Wrong:

import { BLEND_MODES } from "pixi.js";

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

Correct:

sprite.blendMode = "add";

In v8,

BLEND_MODES

is a TypeScript type only (a union of string literals). There is no runtime enum export, so

BLEND_MODES.ADD

evaluates to accessing a property on

undefined

. Use the string form.

错误示例：

import { BLEND_MODES } from "pixi.js";

sprite.blendMode = BLEND_MODES.ADD; // 运行时错误：BLEND_MODES未定义

正确示例：

sprite.blendMode = "add";

在v8版本中，

BLEND_MODES

仅作为TypeScript类型存在（字符串字面量的联合类型）。没有运行时枚举导出，因此

BLEND_MODES.ADD

会尝试访问

undefined

的属性。请使用字符串形式。

[HIGH] Advanced blend modes without useBackBuffer

[高风险] 使用高级混合模式但未启用useBackBuffer

Wrong:

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";

Advanced modes read from the back buffer. On WebGL, the blend silently falls back if the back buffer is not enabled. WebGPU enables the back buffer unconditionally.

错误示例：

import "pixi.js/advanced-blend-modes";
await app.init({
  /* 未设置useBackBuffer */
});
sprite.blendMode = "color-burn"; // 记录警告并回退

正确示例：

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

高级模式需要读取后台缓冲区。在WebGL中，如果未启用后台缓冲区，混合会自动回退。WebGPU会无条件启用后台缓冲区。

pixijs-blend-modes

Original

Translation

Quick Start

快速开始

Core Patterns

核心模式

Standard blend modes

标准混合模式

Advanced blend modes

高级混合模式

Batch-friendly ordering

批处理友好的排序方式

Common Mistakes

常见错误

[HIGH] Not importing advanced-blend-modes extension

[高风险] 未导入advanced-blend-modes扩展

[MEDIUM] Mixing blend modes across adjacent objects

[中风险] 在相邻对象间混合不同的混合模式

[HIGH] Using the v7 BLEND_MODES enum

[高风险] 使用v7版本的BLEND_MODES枚举

[HIGH] Advanced blend modes without useBackBuffer

[高风险] 使用高级混合模式但未启用useBackBuffer

API Reference

API参考