pixijs-blend-modes

将 container.blendMode 设为使用 GPU 混合方程（标准模式）或基于滤镜的高级模式来合成显示对象。混合模式切换会中断渲染批次，因此应将模式相同的同级对象分组放置。

快速入门

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（颜色处理）。

核心模式

标准混合模式

标准模式内置其中，可直接使用 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)

这些模式由硬件加速，开销很低，也不需要滤镜。

高级混合模式

高级模式需要显式导入扩展才能注册。在 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 }); // required for advanced modes on 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	类似差值，但对比度较低
hard-light	根据上层执行正片叠底或滤色
hard-mix	高对比度阈值混合
lighten	保留两个图层中较亮的颜色
linear-burn	通过加减来加深颜色
linear-dodge	将图层相加
linear-light	根据上层执行线性加深或线性减淡
luminosity	使用上层的亮度，以及底层的色相和饱和度
negation	反转差值
overlay	根据底层执行正片叠底或滤色
pin-light	根据亮度比较替换颜色
saturation	使用上层的饱和度，以及底层的色相和亮度
soft-light	柔和的叠加效果
subtract	从底层中减去上层
vivid-light	根据上层执行颜色加深或颜色减淡
color	使用上层的色相和饱和度，以及底层的亮度

高级混合模式与标准模式的设置方式相同，即通过 blendMode 属性设置。它们在内部使用滤镜，因此开销高于标准模式。

便于批处理的排序

不同的混合模式会中断渲染批次。调整对象顺序，以尽量减少模式切换：

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 次。

常见错误

[HIGH] 未导入 advanced-blend-modes 扩展

错误：

import { Sprite } from "pixi.js";

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

正确：

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

sprite.blendMode = "color-burn";

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

[MEDIUM] 相邻对象使用不同的混合模式

不同的混合模式会中断渲染批次。screen / normal / screen / normal 会产生 4 次绘制调用，而 screen / screen / normal / normal 会产生 2 次。对同级对象排序，让混合模式相同的对象相邻。

[HIGH] 使用 v7 的 BLEND_MODES 枚举

错误：

import { BLEND_MODES } from "pixi.js";

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

正确：

sprite.blendMode = "add";

在 v8 中，BLEND_MODES 仅是 TypeScript 类型（由字符串字面量组成的联合类型）。它不会作为运行时枚举导出，因此 BLEND_MODES.ADD 等同于访问 undefined 的属性。请使用字符串形式。

[HIGH] 使用高级混合模式时未启用 useBackBuffer

错误：

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

正确：

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

高级模式会读取后备缓冲区。在 WebGL 上，如果未启用后备缓冲区，混合模式会静默回退。WebGPU 则会始终启用后备缓冲区。

[MEDIUM] 高 DPI 渲染器上的高级混合模式出现裁切或缩放

高级混合模式基于滤镜实现，并使用 Filter.defaultOptions，其默认分辨率为 1。在高 DPI 渲染目标上，混合对象可能会出现裁切、缩放或仅部分应用的情况。

错误：

import "pixi.js/advanced-blend-modes";

sprite.blendMode = "overlay"; // renders at resolution 1, can clip on retina

正确：

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

Filter.defaultOptions.resolution = "inherit"; // set before creating affected objects

sprite.blendMode = "overlay";

将 Filter.defaultOptions.resolution = "inherit" 设置为 "inherit"，可使高级混合模式以渲染目标的分辨率进行渲染。这会增加内存和运行时开销，因此请仅在需要高保真度的场景中应用。

API 参考

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