필터

Filters let you apply visual effects (blur, glow, color grading, distortions, and more) to any canvas component, using PixiJS's own .filters property. This functionality is available starting from v1.9.4.

import { showImage } from "@drincs/pixi-vn";
import { BlurFilter } from "pixi.js";

const alien = await showImage("alien", "egg_head");
alien.filters = [new BlurFilter({ strength: 12 })];

Save and restore앵커 링크 복사

A live Filter instance can't be serialized directly - it doesn't expose its own constructor options after creation, and its state lives in GPU-facing resources/uniform groups. Pixi’VN solves this with RegisteredFilters: an extensible registry (the same alias-to-class pattern used by tickers) that knows how to read a filter's current parameters into a serializable object, and reconstruct an equivalent instance from it later.

Every filter listed below is registered out of the box - attach one to any canvas component and it will automatically be saved and restored as part of that component's own save data, no extra setup needed.

Registering your own filters앵커 링크 복사

Use filterDecorator to make a custom filter (yours, or a third-party one Pixi’VN doesn't register itself) save-compatible too:

import { filterDecorator } from "@drincs/pixi-vn/filters";
import { Filter } from "pixi.js";

@filterDecorator({
    toMemory: (filter: MyFilter) => ({ amount: filter.amount }),
})
class MyFilter extends Filter {
    amount: number;
    constructor(args: { amount?: number } = {}) {
        super({ /* ... */ });
        this.amount = args.amount ?? 0;
    }
}

toMemory reads a live instance's current parameters into a plain, JSON-serializable object; that object is passed straight back into the class's constructor to reconstruct it on restore.

Filters that can't be saved앵커 링크 복사

A handful of filters genuinely can't round-trip through this mechanism, and are not registered:

• ColorMapFilter, SimpleLightmapFilter (pixi-filters) - their constructors require a Texture, which isn't itself serializable by this registry.
• DisplacementFilter (pixi.js core) - requires a live Sprite as its displacement map.
• ColorMatrixFilter (pixi.js core) - its state (matrix, alpha) is entirely set through instance methods/setters after construction; the constructor itself accepts no way to seed them.
• TiltShiftAxisFilter (pixi-filters) - exposes no getters at all for its own constructor options. Its subclass TiltShiftFilter, which is fully readable, is registered instead.

You can still use any of these directly (sprite.filters = [new ColorMatrixFilter()]) - they just won't survive a save/restore round-trip unless you register your own toMemory for them, the same way you would for a custom filter.

Combining and removing filters앵커 링크 복사

There is no dedicated addFilter/removeFilter API - .filters is a plain array, so you manage it directly. Assigning a new array replaces whatever was there; to add or remove one filter while keeping the others, read the current array back off the component first:

import { filters } from "@drincs/pixi-vn/filters";

// add a filter, keeping any already attached
alien.filters = [...(alien.filters ?? []), new filters.OutlineFilter({ thickness: 6, color: 0xffee00 })];

// remove only the filters of a given class
alien.filters = (alien.filters ?? []).filter((f) => !(f instanceof filters.OldFilmFilter));

// remove everything
alien.filters = null;

Since every registered filter is saved as part of the component's own save data, whatever list you assign is what gets restored when navigating back and forward through the narration history:

The filters namespace앵커 링크 복사

Every registered filter class is also grouped under the filters namespace, so you don't need to import from pixi.js/pixi-filters directly:

import { filters } from "@drincs/pixi-vn/filters";

alien.filters = [new filters.GlowFilter({ distance: 15, outerStrength: 3 })];

All registered filters앵커 링크 복사

The live example below cycles through every filter registered out of the box, applied one at a time to the same image so they're easy to compare:

Both pixi.js and pixi-filters are peer dependencies of Pixi’VN, so every filter above is already available once you've followed the setup guide - no additional install step needed.