Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

27.1 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
vi.mock('../src/render/material', () => ({
    Material: {
        createShader: vi.fn().mockReturnValue(42),
        compileShader: vi.fn().mockReturnValue(42),
        releaseShader: vi.fn(),
    },
}));

import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { PostProcessAPI, PostProcessStack, postProcessEffects, initPostProcessAPI, shutdownPostProcessAPI, getEffectDef } from '../src/postprocess';
import { Material } from '../src/render/material';
import { setLinearColorSpace } from '../src/ecs/env';
import type { ESEngineModule } from '../src/wasm';
import { registerBasicEffectSources } from '../src/postprocess/sources/basic';
import { registerAtmosphereEffectSources } from '../src/postprocess/sources/atmosphere';
import { registerLightingEffectSources } from '../src/postprocess/sources/lighting';

// The effects' shaders are installed by group: a package that uses them imports the group; these tests use them all.
registerBasicEffectSources();
registerAtmosphereEffectSources();
registerLightingEffectSources();

// =============================================================================
// Mock WASM module for PostProcess API
// =============================================================================

function createPostProcessMockModule() {
    const mock = {
        postprocess_init: vi.fn().mockReturnValue(true),
        postprocess_shutdown: vi.fn(),
        postprocess_resize: vi.fn(),
        postprocess_addPass: vi.fn().mockReturnValue(0),
        postprocess_clearPasses: vi.fn(),
        postprocess_setUniformFloat: vi.fn(),
        postprocess_setUniformVec4: vi.fn(),
        postprocess_isInitialized: vi.fn().mockReturnValue(true),
        postprocess_setBypass: vi.fn(),
        postprocess_setOutputViewport: vi.fn(),
    };

    return mock;
}

type MockModule = ReturnType<typeof createPostProcessMockModule>;

// =============================================================================
// Tests
// =============================================================================

describe('PostProcess API', () => {
    let mock: MockModule;
    let pp: PostProcessAPI;

    beforeEach(() => {
        mock = createPostProcessMockModule();
        initPostProcessAPI(mock as unknown as ESEngineModule);
        vi.clearAllMocks();
        pp = new PostProcessAPI();
    });

    afterEach(() => {
        shutdownPostProcessAPI();
    });

    // =========================================================================
    // initPostProcessAPI / shutdownPostProcessAPI
    // =========================================================================

    describe('initPostProcessAPI', () => {
        it('should set the module without throwing', () => {
            expect(() => initPostProcessAPI(mock as unknown as ESEngineModule)).not.toThrow();
        });
    });

    describe('shutdownPostProcessAPI', () => {
        it('should call postprocess_shutdown when initialized', () => {
            mock.postprocess_isInitialized.mockReturnValue(true);
            shutdownPostProcessAPI();
            expect(mock.postprocess_shutdown).toHaveBeenCalledOnce();
        });

        it('should not call postprocess_shutdown when not initialized', () => {
            mock.postprocess_isInitialized.mockReturnValue(false);
            shutdownPostProcessAPI();
            expect(mock.postprocess_shutdown).not.toHaveBeenCalled();
        });

        it('should handle double shutdown gracefully', () => {
            mock.postprocess_isInitialized.mockReturnValue(true);
            shutdownPostProcessAPI();
            shutdownPostProcessAPI();
            expect(mock.postprocess_shutdown).toHaveBeenCalledOnce();
        });
    });

    // =========================================================================
    // Uninitialized guard
    // =========================================================================

    describe('uninitialized guard', () => {
        it('should return false for isInitialized after shutdown', () => {
            shutdownPostProcessAPI();
            expect(pp.isInitialized()).toBe(false);
        });

        it('should return false from init after shutdown', () => {
            shutdownPostProcessAPI();
            expect(pp.init(800, 600)).toBe(false);
        });

        it('should not throw from shutdown after shutdown', () => {
            shutdownPostProcessAPI();
            expect(() => pp.shutdown()).not.toThrow();
        });

        it('should not throw from setBypass after shutdown', () => {
            shutdownPostProcessAPI();
            expect(() => pp.setBypass(true)).not.toThrow();
        });
    });

    // =========================================================================
    // Pipeline lifecycle
    // =========================================================================

    describe('pipeline lifecycle', () => {
        it('should call postprocess_init with width and height', () => {
            pp.init(1920, 1080);
            expect(mock.postprocess_init).toHaveBeenCalledWith(1920, 1080);
        });

        it('should return the WASM result from init', () => {
            mock.postprocess_init.mockReturnValue(true);
            expect(pp.init(800, 600)).toBe(true);

            mock.postprocess_init.mockReturnValue(false);
            expect(pp.init(800, 600)).toBe(false);
        });

        it('should call postprocess_shutdown', () => {
            pp.shutdown();
            expect(mock.postprocess_shutdown).toHaveBeenCalledOnce();
        });

        it('should call postprocess_resize with width and height', () => {
            pp.resize(1280, 720);
            expect(mock.postprocess_resize).toHaveBeenCalledWith(1280, 720);
        });
    });

    // =========================================================================
    // PostProcessStack
    // =========================================================================

    describe('PostProcessStack', () => {
        it('should create a stack with unique id', () => {
            const stack1 = pp.createStack();
            const stack2 = pp.createStack();
            expect(stack1.id).not.toBe(stack2.id);
        });

        it('should add passes and track count', () => {
            const stack = pp.createStack();
            stack.addPass('bloom', 1);
            stack.addPass('blur', 2);
            expect(stack.passCount).toBe(2);
        });

        it('should remove passes by name', () => {
            const stack = pp.createStack();
            stack.addPass('bloom', 1);
            stack.addPass('blur', 2);
            stack.removePass('bloom');
            expect(stack.passCount).toBe(1);
            expect(stack.passes[0].name).toBe('blur');
        });

        it('should set pass enabled state', () => {
            const stack = pp.createStack();
            stack.addPass('bloom', 1);
            stack.setEnabled('bloom', false);
            expect(stack.enabledPassCount).toBe(0);
            stack.setEnabled('bloom', true);
            expect(stack.enabledPassCount).toBe(1);
        });

        it('should set float uniforms on passes', () => {
            const stack = pp.createStack();
            stack.addPass('bloom', 1);
            stack.setUniform('bloom', 'u_intensity', 0.5);
            const pass = stack.passes[0];
            expect(pass.floatUniforms.get('u_intensity')).toBe(0.5);
        });

        it('should set vec4 uniforms on passes', () => {
            const stack = pp.createStack();
            stack.addPass('bloom', 1);
            stack.setUniformVec4('bloom', 'u_color', { x: 1, y: 0.5, z: 0.25, w: 1 });
            const pass = stack.passes[0];
            expect(pass.vec4Uniforms.get('u_color')).toEqual({ x: 1, y: 0.5, z: 0.25, w: 1 });
        });

        it('should enable/disable all passes', () => {
            const stack = pp.createStack();
            stack.addPass('bloom', 1);
            stack.addPass('blur', 2);
            stack.setAllPassesEnabled(false);
            expect(stack.enabledPassCount).toBe(0);
            stack.setAllPassesEnabled(true);
            expect(stack.enabledPassCount).toBe(2);
        });

        it('should mark as destroyed after destroy()', () => {
            const stack = pp.createStack();
            expect(stack.isDestroyed).toBe(false);
            stack.destroy();
            expect(stack.isDestroyed).toBe(true);
        });

        it('should support chaining on addPass/removePass/setEnabled/setUniform', () => {
            const stack = pp.createStack();
            const result = stack
                .addPass('bloom', 1)
                .setEnabled('bloom', true)
                .setUniform('bloom', 'u_intensity', 0.5)
                .removePass('bloom');
            expect(result).toBe(stack);
        });
    });

    // =========================================================================
    // Camera binding
    // =========================================================================

    describe('camera binding', () => {
        it('should bind a stack to a camera entity', () => {
            const stack = pp.createStack();
            pp.bind(1 as any, stack);
            expect(pp.getStack(1 as any)).toBe(stack);
        });

        it('should unbind a camera', () => {
            const stack = pp.createStack();
            pp.bind(1 as any, stack);
            pp.unbind(1 as any);
            expect(pp.getStack(1 as any)).toBeNull();
        });

        it('should return null for unbound camera', () => {
            expect(pp.getStack(99 as any)).toBeNull();
        });

        it('should throw when binding a destroyed stack', () => {
            const stack = pp.createStack();
            stack.destroy();
            expect(() => pp.bind(1 as any, stack)).toThrow('destroyed');
        });
    });

    // =========================================================================
    // Bypass mode
    // =========================================================================

    describe('bypass mode', () => {
        it('should call postprocess_setBypass with true', () => {
            pp.setBypass(true);
            expect(mock.postprocess_setBypass).toHaveBeenCalledWith(true);
        });

        it('should call postprocess_setBypass with false', () => {
            pp.setBypass(false);
            expect(mock.postprocess_setBypass).toHaveBeenCalledWith(false);
        });
    });

    // =========================================================================
    // _applyForCamera
    // =========================================================================

    describe('_applyForCamera', () => {
        it('should set bypass=true when camera has no bound stack', () => {
            pp._applyForCamera(1 as any);
            expect(mock.postprocess_setBypass).toHaveBeenCalledWith(true);
        });

        it('should sync enabled passes to WASM when stack is bound', () => {
            const stack = pp.createStack();
            stack.addPass('bloom', 42);
            stack.setUniform('bloom', 'u_intensity', 0.5);
            pp.bind(1 as any, stack);

            pp._applyForCamera(1 as any);

            expect(mock.postprocess_setBypass).toHaveBeenCalledWith(false);
            expect(mock.postprocess_clearPasses).toHaveBeenCalled();
            expect(mock.postprocess_addPass).toHaveBeenCalledWith('bloom', 42);
            expect(mock.postprocess_setUniformFloat).toHaveBeenCalledWith('bloom', 'u_intensity', 0.5);
        });

        it('should set bypass=true when all passes are disabled', () => {
            const stack = pp.createStack();
            stack.addPass('bloom', 42);
            stack.setEnabled('bloom', false);
            pp.bind(1 as any, stack);

            pp._applyForCamera(1 as any);
            expect(mock.postprocess_setBypass).toHaveBeenCalledWith(true);
        });

        it('should sync vec4 uniforms to WASM', () => {
            const stack = pp.createStack();
            stack.addPass('bloom', 42);
            stack.setUniformVec4('bloom', 'u_color', { x: 1, y: 0.5, z: 0.25, w: 1 });
            pp.bind(1 as any, stack);

            pp._applyForCamera(1 as any);
            expect(mock.postprocess_setUniformVec4).toHaveBeenCalledWith('bloom', 'u_color', 1, 0.5, 0.25, 1);
        });

        // Every camera ends by clearing the engine's pass list, so an unedited
        // stack still has to be re-pushed the next frame. Trusting the stack's
        // dirty flag alone left the engine with zero passes from frame 2 on.
        it('re-pushes an unedited stack after the engine\'s passes were reset', () => {
            const stack = pp.createStack();
            stack.addPass('bloom', 42);
            pp.bind(1 as any, stack);

            pp._applyForCamera(1 as any);
            pp._resetAfterCamera();
            mock.postprocess_addPass.mockClear();

            pp._applyForCamera(1 as any);
            expect(mock.postprocess_addPass).toHaveBeenCalledWith('bloom', 42);
        });

        it('does not re-push an unedited stack the engine still holds', () => {
            const stack = pp.createStack();
            stack.addPass('bloom', 42);
            pp.bind(1 as any, stack);

            pp._applyForCamera(1 as any);
            mock.postprocess_addPass.mockClear();

            pp._applyForCamera(1 as any);
            expect(mock.postprocess_addPass).not.toHaveBeenCalled();
        });
    });

    // =========================================================================
    // _resetAfterCamera
    // =========================================================================

    describe('_resetAfterCamera', () => {
        it('should clear passes and set bypass=true', () => {
            pp._resetAfterCamera();
            expect(mock.postprocess_clearPasses).toHaveBeenCalled();
            expect(mock.postprocess_setBypass).toHaveBeenCalledWith(true);
        });
    });

    // =========================================================================
    // Built-in effects
    // =========================================================================

    describe('built-in effects', () => {
        // Effects are fragment-only PostProcess-domain .esshaders on the
        // reflected #pragma param seam, compiled via Material.compileShader.
        const lastSource = (): string => {
            const calls = (Material.compileShader as ReturnType<typeof vi.fn>).mock.calls;
            return calls[calls.length - 1][0] as string;
        };

        it('should create blur as a param-reflected PostProcess esshader', () => {
            const handle = postProcessEffects.createBlur();
            const src = lastSource();
            expect(src).toContain('#pragma domain PostProcess');
            expect(src).toContain('#pragma param u_intensity float');
            expect(src).not.toContain('#pragma vertex'); // canonical stage is engine-injected
            expect(handle).toBe(42);
        });

        it('should create vignette with its params reflected', () => {
            postProcessEffects.createVignette();
            expect(lastSource()).toContain('#pragma param u_softness float');
            // Full at the radius, soft inside it, over the frame's own ellipse or a circle to the corner; the defaults are the shape it was.
            expect(lastSource()).toContain('#pragma param u_radius float default(1)');
            expect(lastSource()).toContain('#pragma param u_roundness float default(0)');
            expect(lastSource()).toContain('smoothstep(u_radius - u_softness, u_radius, dist)');
            expect(lastSource()).toContain('smoothstep(mc.u_radius - mc.u_softness, mc.u_radius, dist)');
            expect(lastSource()).toContain('mix(length(uv), length(uv * round) / length(round), u_roundness)');
            expect(lastSource()).toContain('mix(length(uv), length(uv * round) / length(round), mc.u_roundness)');
        });

        it('should create grayscale with Rec.601 luma weights', () => {
            postProcessEffects.createGrayscale();
            expect(lastSource()).toContain('0.299');
        });

        it('should size chromatic aberration from the injected viewport', () => {
            postProcessEffects.createChromaticAberration();
            const src = lastSource();
            expect(src).toContain('u_intensity * u_viewport.zw');
            expect(src).not.toContain('u_resolution');
        });

        it('should create color grade with every grading param reflected', () => {
            postProcessEffects.createColorGrade();
            const src = lastSource();
            for (const p of ['u_exposure', 'u_contrast', 'u_saturation', 'u_temperature', 'u_tint']) {
                expect(src).toContain(`#pragma param ${p} float`);
            }
        });

        it('registers colorGrade with identity defaults (no-op at defaults)', () => {
            const def = getEffectDef('colorGrade');
            expect(def?.label).toBe('Color Grade');
            const defaults = Object.fromEntries((def?.uniforms ?? []).map(u => [u.name, u.defaultValue]));
            // Identity: 2^0=1, contrast 1, saturation 1, no white-balance shift, no S-curve; the tints are white and the lift black.
            expect(defaults).toEqual({
                u_exposure: 0, u_contrast: 1, u_saturation: 1, u_temperature: 0, u_tint: 0,
                u_toneLow: 0.03, u_toneHigh: 0.55, u_curve: 0, u_gain: 1, u_offset: 0,
            });
            const colours = Object.fromEntries((def?.colors ?? []).map(c => [c.name, c.defaultValue]));
            expect(colours.u_shadowTint).toEqual({ r: 1, g: 1, b: 1, a: 1 });
            expect(colours.u_highlightTint).toEqual({ r: 1, g: 1, b: 1, a: 1 });
            expect(colours.u_lift).toEqual({ r: 0, g: 0, b: 0, a: 1 });
        });

        it('colorGrade has a gain and an offset, applied before the lift in both languages', () => {
            postProcessEffects.createColorGrade();
            const src = lastSource();
            expect(src).toContain('#pragma param u_gain float default(1)');
            expect(src).toContain('#pragma param u_offset float default(0) range(-0.5,0.5)');
            expect(src.indexOf('c = c * u_gain + u_offset;')).toBeGreaterThan(0);
            expect(src.indexOf('c = c * u_gain + u_offset;')).toBeLessThan(src.indexOf('c += u_lift.rgb * 0.1;'));
            expect(src.indexOf('c = c * mc.u_gain + vec3f(mc.u_offset);')).toBeLessThan(src.indexOf('c += mc.u_lift.rgb * 0.1;'));
            expect(src.indexOf('c = c * mc.u_gain + vec3f(mc.u_offset);')).toBeGreaterThan(0);
        });

        it('colorGrade takes contrast about the mid-grey of the colour space it runs in', () => {
            const sourceFor = (linear: boolean): string => {
                setLinearColorSpace(linear);
                try {
                    postProcessEffects.createColorGrade();
                    return lastSource();
                } finally {
                    setLinearColorSpace(false);
                }
            };
            const gamma = sourceFor(false);
            expect(gamma).toContain('c = (c - 0.5) * u_contrast + 0.5;');
            expect(gamma).toContain('c = (c - 0.5) * mc.u_contrast + 0.5;');
            const linear = sourceFor(true);
            expect(linear).toContain('c = 0.18 * pow(max(c, vec3(1e-6)) / 0.18, vec3(u_contrast));');
            expect(linear).toContain('c = 0.18 * pow(max(c, vec3f(1e-6)) / 0.18, vec3f(mc.u_contrast));');
            expect(linear).not.toContain('- 0.5');
        });

        it('every effect ships a WGSL twin and stays fragment-only', () => {
            postProcessEffects.createLutGrade();
            postProcessEffects.createBlur();
            postProcessEffects.createVignette();
            postProcessEffects.createGrayscale();
            postProcessEffects.createBloomExtract();
            postProcessEffects.createBloomKawase(0);
            postProcessEffects.createBloomComposite();
            postProcessEffects.createColorGrade();
            postProcessEffects.createChromaticAberration();
            postProcessEffects.createTonemap();
            postProcessEffects.createFxaa();
            postProcessEffects.createLensDistortion();
            postProcessEffects.createPixelate();
            postProcessEffects.createOutline();

            const calls = (Material.compileShader as ReturnType<typeof vi.fn>).mock.calls;
            expect(calls.length).toBe(14);
            for (const c of calls) {
                const src = c[0] as string;
                expect(src).toContain('#pragma domain PostProcess');
                expect(src).toContain('#pragma fragment wgsl');
                expect(src).toContain('fn fs_main(');
                expect(src).not.toContain('#pragma vertex');
                expect(src).not.toContain('u_resolution'); // u_viewport replaced it
            }
        });

        it('lutGrade declares the LUT as a texture param', () => {
            postProcessEffects.createLutGrade();
            expect(lastSource()).toContain('#pragma param u_lut texture default(white)');
        });

        it('bloom composite reads the untouched scene through the engine unit', () => {
            postProcessEffects.createBloomComposite();
            const src = lastSource();
            expect(src).toContain('u_sceneTexture'); // GLSL: loose engine sampler (unit 1)
            expect(src).toContain('t1, s1');         // WGSL twin: the unit-1 pair
        });
    });

    // =========================================================================
    // Extended effect library (tonemap / FXAA / lens distortion / pixelate)
    // =========================================================================

    describe('extended effects', () => {
        const lastSource = (): string => {
            const calls = (Material.compileShader as ReturnType<typeof vi.fn>).mock.calls;
            return calls[calls.length - 1][0] as string;
        };

        it('should create an ACES tonemap shader with exposure', () => {
            const handle = postProcessEffects.createTonemap();
            const src = lastSource();
            expect(src).toContain('#pragma param u_exposure float');
            // The curve is pinned where it is defined (test_shader_variant.cpp);
            // what this layer owns is that the effect REACHES it, in both dialects.
            expect(src).toContain('acesFilmic(c), src.a)');
            expect(src).toContain('vec4f(acesFilmic(c), src.a)');
            // The other fit is the effect's own, behind u_curve, in both dialects; off, the engine's curve is what runs.
            expect(src).toContain('#pragma param u_curve float default(0)');
            expect(src).toContain('u_curve > 0.5 ? acesFitted(c) : acesFilmic(c)');
            expect(src).toContain('if (mc.u_curve > 0.5) { return vec4f(acesFitted(c), src.a); }');
            expect(handle).toBe(42);
        });

        it('should create an FXAA shader sampling by the injected viewport', () => {
            const handle = postProcessEffects.createFxaa();
            const src = lastSource();
            expect(src).toContain('u_viewport.zw');
            expect(src).toContain('#pragma param u_intensity float');
            expect(handle).toBe(42);
        });

        it('should create a lens distortion shader with strength and zoom', () => {
            const handle = postProcessEffects.createLensDistortion();
            const src = lastSource();
            expect(src).toContain('#pragma param u_strength float');
            expect(src).toContain('#pragma param u_zoom float');
            expect(handle).toBe(42);
        });

        it('should create a pixelate shader with pixel size', () => {
            const handle = postProcessEffects.createPixelate();
            expect(lastSource()).toContain('#pragma param u_pixelSize float');
            expect(handle).toBe(42);
        });

        it('should create a Sobel outline shader with intensity/threshold/thickness', () => {
            const handle = postProcessEffects.createOutline();
            const src = lastSource();
            expect(src).toContain('#pragma param u_intensity float');
            expect(src).toContain('#pragma param u_threshold float');
            expect(src).toContain('#pragma param u_thickness float');
            // Rec.601 luma weights — guards the edge-detection identity.
            expect(src).toContain('0.587');
            expect(handle).toBe(42);
        });

        it('registers the extended effects with matching factories and labels', () => {
            expect(getEffectDef('tonemap')?.label).toBe('Tonemap (ACES)');
            expect(getEffectDef('fxaa')?.label).toBe('FXAA');
            expect(getEffectDef('lensDistortion')?.label).toBe('Lens Distortion');
            expect(getEffectDef('pixelate')?.label).toBe('Pixelate');
            expect(getEffectDef('outline')?.label).toBe('Outline');
        });

        it('uses identity defaults where the effect is meant to be tuned up from off', () => {
            const def = (t: string) =>
                Object.fromEntries((getEffectDef(t)?.uniforms ?? []).map(u => [u.name, u.defaultValue]));
            // Tonemap: 2^0 = 1 exposure (the ACES curve itself always applies).
            expect(def('tonemap')).toEqual({ u_exposure: 0, u_curve: 0 });
            // Lens distortion: strength 0 + zoom 1 == sample uv unchanged (no-op).
            expect(def('lensDistortion')).toEqual({ u_strength: 0, u_zoom: 1 });
            // FXAA full strength by default; pixelate visibly chunky so it reads as on.
            expect(def('fxaa')).toEqual({ u_intensity: 1 });
            expect(def('pixelate')).toEqual({ u_pixelSize: 4 });
            // Outline visible when added (intensity 1); 0 is an exact no-op.
            expect(def('outline')).toEqual({ u_intensity: 1, u_threshold: 0.2, u_thickness: 1 });
        });
    });

    // =========================================================================
    // WASM exception safety
    // =========================================================================

    describe('WASM exception safety', () => {
        it('should return false when postprocess_init throws', () => {
            mock.postprocess_init.mockImplementation(() => { throw new Error('WASM crash'); });
            expect(pp.init(800, 600)).toBe(false);
        });

        it('should not throw when postprocess_shutdown throws', () => {
            mock.postprocess_shutdown.mockImplementation(() => { throw new Error('WASM crash'); });
            expect(() => pp.shutdown()).not.toThrow();
        });

        it('should not throw when postprocess_resize throws', () => {
            mock.postprocess_resize.mockImplementation(() => { throw new Error('WASM crash'); });
            expect(() => pp.resize(800, 600)).not.toThrow();
        });

        it('should return false when postprocess_isInitialized throws', () => {
            mock.postprocess_isInitialized.mockImplementation(() => { throw new Error('WASM crash'); });
            expect(pp.isInitialized()).toBe(false);
        });
    });
});

describe('outputTransformCode', () => {
    it('spells each curve as the number the wasm boundary reads', async () => {
        const { outputTransformCode } = await import('../src/postprocess');
        expect(outputTransformCode(undefined)).toBe(0);
        expect(outputTransformCode('none')).toBe(0);
        expect(outputTransformCode('aces')).toBe(1);
        expect(outputTransformCode('neutral')).toBe(2);
    });
});