Filters

A Filter is a post-render effect applied to a single drawable’s output. Every RenderNode — sprites, containers, graphics, meshes, text — carries a filters array. Each filter in that array transforms the node’s rendered pixels before the result composites into the parent.

Filters are the right tool for per-node visual effects: soften an avatar with blur, tint a background container, apply a CRT shader to a whole scene layer. They are not screen-wide post-processing — that belongs to Post-processing, which combines RenderTexture targets with filter chains. The relationship: a filter is the building block; post-processing is the composition technique.

Attaching filters

Filters go on the drawable. The array is processed in order — filter 0 receives the node’s raw render, filter 1 receives filter 0’s output, and so on:

import { BlurFilter, Color, ColorFilter } from '@codexo/exojs';

const blur = new BlurFilter({ radius: 3, quality: 2 });
const tint = new ColorFilter(new Color(140, 210, 255));

sprite.filters = [blur, tint];

Set filters to an empty array to clear the chain. Assigning a new array replaces the old one — you don’t need to manually remove individual filters. An empty array means no extra render passes.

Each filter in the chain costs one additional render pass per frame for that drawable. Three filters on a container means three extra passes. The Render pipeline debugging chapter covers pass-count inspection and reduction strategies.

BlurFilter

A box blur, not a shader — it works by rendering the input texture multiple times at symmetric pixel offsets with additive blending. Higher quality produces more offset samples per axis and a smoother result at the cost of more draw calls:

const blur = new BlurFilter({ radius: 4, quality: 2 });
sprite.filters = [blur];

// Live — animate the radius without reconstructing anything
blur.radius = tween.progress * 12;
blur.quality = 3;

radius clamps to >= 0 (0 = no blur). quality floors to >= 1 and controls sample count: quality * 2 + 1 samples per axis. For most cases quality 1 or 2 is sufficient — higher values are useful for large-radius fast-moving blurs where undersampling creates visible gaps.

ColorFilter

Multiplies the rendered output by a tint color. The simplest filter — one multiplicative blend:

const color = new ColorFilter(new Color(255, 160, 120));
sprite.filters = [color];

// Live — mutate the color without rebuilding anything
color.color.setRGB(180, 220, 255);

Use for tinting, flash effects, fade-to-black, or any per-drawable color manipulation that should happen after the node’s own tint and blend mode are applied.

LutFilter

Maps every pixel through a Look-Up Table texture. Two modes:

• 1D LUT (palette): N×1 texture, indexed by a single channel. Palette cycling, posterisation, indexed-color effects.
• 3D LUT (color grading): N²×N unwrapped cube texture with trilinear interpolation. Cinematic color grading, film stock emulation, tone mapping.

import { LutFilter } from '@codexo/exojs';

// From a DaVinci/OBS/Photoshop-exported PNG strip
const lutTexture = LutFilter.fromImage(myPngImage);
const filter = new LutFilter({ mode: '3d', size: 17 }).setLut(lutTexture);
sprite.filters = [filter];

// Switch LUTs live without rebuilding the filter
filter.setLut(differentLutTexture);

LutFilter.fromImage(image) wraps an HTMLImageElement or HTMLCanvasElement as a texture with LUT-appropriate defaults (linear filtering, clamp-to-edge, no mipmaps). identityLut1D() and identityLut3D() create no-op identity textures for testing. The setLut() method swaps textures at runtime — instant, no shader recompilation.

Custom shader filters

WebGl2ShaderFilter and WebGpuShaderFilter accept a fragment shader source and an optional uniforms map. They render a fullscreen quad and execute the shader against the filter input texture:

import { WebGl2ShaderFilter } from '@codexo/exojs';

const waveFilter = new WebGl2ShaderFilter({
    fragmentSource: `
        #version 300 es
        precision mediump float;
        uniform sampler2D uTexture;
        uniform float uTime;
        in vec2 vUv;
        out vec4 fragColor;

        void main() {
            vec2 uv = vUv;
            uv.y += sin(uv.x * 12.0 + uTime * 3.0) * 0.03;
            fragColor = texture(uTexture, uv);
        }
    `,
    uniforms: { uTime: 0 },
});

sprite.filters = [waveFilter];

// Update uniforms per frame
update(delta) {
    this._time += delta.seconds;
    waveFilter.uniforms.uTime = this._time;
}

Use WebGpuShaderFilter identically for WebGPU — same fragmentSource and uniforms shape, only the shader language differs (WGSL instead of GLSL). For backend-portable filters, construct the appropriate variant based on app.backend.backendType.

Both auto-bind uTexture (the filter input) and uResolution (output dimensions) — you don’t declare these in your fragment source unless you want to read them. Custom uniforms are set from the uniforms map before each pass. Accepted value types: number, [n, n]/[n, n, n]/[n, n, n, n] tuples, Float32Array, Int32Array, Texture, and RenderTexture.

Composition and layering

Filters on a Container apply to the container’s entire rendered subtree — every child is drawn into an off-screen target first, then the filter chain processes that target. A blur on a container blurs all children together, not individually:

const world = new Container();
world.filters = [new BlurFilter({ radius: 2 })];
world.addChild(hero);   // hero is drawn into container's RT, then blurred
world.addChild(enemy);  // enemy is drawn into same RT, then blurred

Filters on individual children inside an unfiltered container each get their own pass. The cost model: one filtered container with N children costs 1 + filter_count passes (children batch into one RT). N individually filtered children cost N * (1 + filter_count) passes.

For static subtrees that don’t change every frame, set container.cacheAsBitmap = true. The filter chain bakes once and subsequent frames skip the per-frame re-rendering — one texture draw instead of the full subtree + filters.

Filters vs. mesh materials

A filter transforms a drawable’s rendered pixels — it operates on the 2D output, in screen texture space. A MeshMaterial replaces the drawable’s vertex and fragment stages entirely — it operates in geometry space. The distinction matters:

• Use a filter for post-render effects: blur, tint, color grade, CRT scanlines, vignette.
• Use a MeshMaterial for per-vertex effects: displacement, custom lighting, procedural geometry.
• Use both together: a MeshMaterial on the mesh, plus a filter on the mesh’s parent container.

The next chapter, Custom mesh shaders, covers attaching a MeshMaterial in detail.

Examples

import { Application, BlurFilter, Color, Scene, Sprite, Texture } from '@codexo/exojs';
import { mountControlPanel, mountControls } from '@examples/runtime';

const app = new Application({
    canvas: {
        width: 1280,
        height: 720,
        mount: document.body,
        sizingMode: 'fit',
    },
    clearColor: Color.black,
});

// High-detail, high-contrast content so the blur visibly softens hard edges.
const PIXEL_GRID = assets.technical.filtering.pixelGrid128;

const MAX_RADIUS = 14;

class BlurFilterScene extends Scene {
    private blur!: BlurFilter;
    private sprite!: Sprite;
    private enabled = true;
    private hud!: ReturnType<typeof mountControls>;
    private panel!: ReturnType<typeof mountControlPanel>;
    private slider!: ReturnType<ReturnType<typeof mountControlPanel>['addSlider']>;

    override async load(loader): Promise<void> {
        await loader.load(Texture, { grid: PIXEL_GRID });
    }

    override init(loader): void {
        const { width, height } = this.app.canvas;

        this.blur = new BlurFilter({ radius: 4, quality: 2 });
        this.sprite = new Sprite(loader.get(Texture, 'grid')).setAnchor(0.5).setScale(4.5).setPosition(width / 2, height / 2);
        this.sprite.filters = [this.blur];

        this.hud = mountControls({
            title: 'Blur Filter',
            controls: [
                { keys: 'Radius', action: 'soften the sprite (box-blur passes)' },
                { keys: 'Filter', action: 'toggle to compare before / after' },
            ],
            status: this.statusText(),
            hint: 'Drag the Radius slider — the live value is shown to its right.',
        });

        this.panel = mountControlPanel({ title: 'Blur' });
        this.slider = this.panel.addSlider({
            label: 'Radius',
            min: 0,
            max: MAX_RADIUS,
            step: 0.1,
            value: this.blur.radius,
            onChange: value => {
                this.blur.radius = value;
                this.refresh();
            },
        });
        this.panel.addToggle({
            label: 'Filter',
            value: true,
            onChange: on => {
                this.enabled = on;
                this.sprite.filters = on ? [this.blur] : [];
                this.refresh();
            },
        });
    }

    private statusText(): string {
        if (!this.enabled) {
            return 'Filter: OFF (original sprite)';
        }

        return `Radius: ${this.blur.radius.toFixed(1)} px`;
    }

    private refresh(): void {
        this.hud.setStatus(this.statusText());
    }

    override draw(context): void {
        context.backend.clear();
        context.render(this.sprite);
    }
}

app.start(new BlurFilterScene());

A single BlurFilter with an interactive radius slider — the basic filter pattern.

import { Application, BlurFilter, Color, ColorFilter, RenderBackendType, Scene, Sprite, Texture, WebGl2ShaderFilter, WebGpuShaderFilter } from '@codexo/exojs';
import { mountControlPanel, mountControls } from '@examples/runtime';

const app = new Application({
    canvas: {
        width: 1280,
        height: 720,
        mount: document.body,
        sizingMode: 'fit',
    },
    clearColor: Color.black,
});

const PRIMARY_RAMP = assets.technical.color.primaryRamp;

const glsl = `#version 300 es
precision mediump float; uniform sampler2D uTexture; in vec2 vUv; out vec4 fragColor;
void main(){ vec4 c=texture(uTexture,vUv); fragColor=vec4(c.rgb*vec3(1.0,0.9,1.2),c.a);} `;
const wgsl = `@group(0) @binding(1) var uTexture:texture_2d<f32>; @group(0) @binding(2) var uSampler:sampler; @fragment fn main(@location(0) vUv:vec2<f32>)->@location(0) vec4<f32>{ let c=textureSample(uTexture,uSampler,vUv); return vec4<f32>(c.rgb*vec3<f32>(1.0,0.9,1.2),c.a);} `;

class FilterStackScene extends Scene {
    private sprite!: Sprite;
    private blur!: BlurFilter;
    private tint!: ColorFilter;
    private custom!: WebGl2ShaderFilter | WebGpuShaderFilter;
    // The filter chain is applied in this fixed order; each entry can be toggled.
    private active = { blur: true, tint: true, custom: true };
    private hud!: ReturnType<typeof mountControls>;
    private panel!: ReturnType<typeof mountControlPanel>;

    override async load(loader): Promise<void> {
        await loader.load(Texture, { ramp: PRIMARY_RAMP });
    }

    override init(loader): void {
        const { width, height } = this.app.canvas;

        this.sprite = new Sprite(loader.get(Texture, 'ramp')).setAnchor(0.5).setScale(4).setPosition(width / 2, height / 2);
        this.blur = new BlurFilter({ radius: 4, quality: 2 });
        this.tint = new ColorFilter(new Color(140, 210, 255));
        this.custom =
            app.backend.backendType === RenderBackendType.WebGpu
                ? new WebGpuShaderFilter({ fragmentSource: wgsl })
                : new WebGl2ShaderFilter({ fragmentSource: glsl });
        this.rebuild();

        this.hud = mountControls({
            title: 'Filter Stack',
            controls: [{ keys: 'Blur / Tint / Custom', action: 'toggle each layer independently' }],
            status: this.statusText(),
            hint: 'Filters compose in order: Blur → Tint → Custom. Toggle any subset.',
        });

        this.panel = mountControlPanel({ title: 'Layers' });
        this.panel.addToggle({
            label: 'Blur',
            value: this.active.blur,
            onChange: on => {
                this.active.blur = on;
                this.rebuild();
            },
        });
        this.panel.addToggle({
            label: 'Tint',
            value: this.active.tint,
            onChange: on => {
                this.active.tint = on;
                this.rebuild();
            },
        });
        this.panel.addToggle({
            label: 'Custom',
            value: this.active.custom,
            onChange: on => {
                this.active.custom = on;
                this.rebuild();
            },
        });
    }

    private rebuild(): void {
        const filters = [];

        if (this.active.blur) filters.push(this.blur);
        if (this.active.tint) filters.push(this.tint);
        if (this.active.custom) filters.push(this.custom);

        this.sprite.filters = filters;
        this.hud?.setStatus(this.statusText());
    }

    private statusText(): string {
        const labels = [this.active.blur && 'Blur', this.active.tint && 'Tint', this.active.custom && 'Custom'].filter(Boolean);

        return labels.length > 0 ? `Active: ${labels.join(' → ')}` : 'Active: none (original sprite)';
    }

    override draw(context): void {
        context.backend.clear();
        context.render(this.sprite);
    }
}

app.start(new FilterStackScene());

Three filters chained on one sprite — blur, tint, and a custom shader — demonstrating filter ordering and composition.

Where to go next

The next chapter, Particles, covers the data-oriented particle system — spawn modules, update modules, distributions, and CPU/GPU auto-routing.