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.

21.8 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { Entity } from '../types';
import type { ShaderHandle } from '../render/material';
import type { EngineApi } from '../ecs/bridge/engineApi';
import { defineResource } from '../ecs/resource';
import { handleWasmError } from '../wasm/wasmError';
import { WasmBridge } from '../wasm/WasmBridge';
import { PostProcessStack, PostProcessState } from './PostProcessStack';
import type { QualityProfile } from '../render/quality';
import { qualityPassAllowed } from './qualityFilter';
import { effectPassNames } from './effects';

/**
 * The post-process entry points as a core that HAS them answers them. Named, not
 * re-declared: the signatures come from the generated engine surface, so this
 * cannot drift from the C++ (PostProcessBindings.hpp) that produced it.
 */
type PostProcessCore = Required<Pick<NonNullable<EngineApi>,
    'postprocess_init' | 'postprocess_shutdown' | 'postprocess_resize'
    | 'postprocess_isInitialized' | 'postprocess_begin' | 'postprocess_end'
    | 'postprocess_clearPasses' | 'postprocess_addPass' | 'postprocess_setPassScale'
    | 'postprocess_setPassContinuesEffect'
    | 'postprocess_setPassTexture'
    | 'postprocess_setUniformFloat' | 'postprocess_setUniformVec4'
    | 'postprocess_setBypass' | 'postprocess_setOutputTransform' | 'postprocess_setMsaaSamples'
    | 'postprocess_setPresentRequired'
    | 'postprocess_setOutputViewport'
    | 'postprocess_beginScreenCapture' | 'postprocess_endScreenCapture'
    | 'postprocess_executeScreenPasses' | 'postprocess_addScreenPass'
    | 'postprocess_clearScreenPasses' | 'postprocess_setScreenUniformFloat'
    | 'postprocess_setScreenUniformVec4'>>
    // A core without a compute stage (or built before there was one) does not answer this one.
    & Pick<NonNullable<EngineApi>, 'postprocess_addComputePass' | 'postprocess_supportsCompute' | 'postprocess_addNativePass' | 'postprocess_setDisplayLut'>;

/** Guarded view of the core: after a wasm abort a call throws instead of reaching
 *  a dead module; a native host's bindings never abort. */
class PostProcessBridge extends WasmBridge<NonNullable<EngineApi>> {
    protected readonly label = 'postprocess';
}

const bridge = new PostProcessBridge();
let module: PostProcessCore | null = null;
/** Four floats the committed format decision is read back through. */
let hdrPtr = 0;

/**
 * The format one frame committed its intermediates to. @experimental
 *
 * `fellBack` is `requested !== effective`, stated so a reader does not have to
 * compare two strings to learn whether anything gave way — and `linear` is what
 * separates a granted ask from no ask at all, which the pair alone cannot say.
 */
export interface HdrFormat {
    requested: string;
    effective: string;
    /** Why they differ; `none` when they do not. */
    reason: string;
    /** Whether the project asked for a linear pipeline this frame. */
    linear: boolean;
    fellBack: boolean;
}

/**
 * @internal Wired by the engine plugins — not part of the public API.
 * Takes whichever core is present (see ecs/engineApi.ts). A core built without
 * ES_ENABLE_POSTPROCESS answers none of these entry points; the plugin checks that
 * before calling, which is what makes the narrowing here sound.
 */
/** Whether the last App shut the pipeline down under a renderer that may have outlived it. */
let restartOwed = false;

export function initPostProcessAPI(engine: NonNullable<EngineApi>): void {
    bridge.connect(engine);
    module = bridge.module as PostProcessCore;
    const heap = engine as unknown as { _malloc?(n: number): number };
    if (!hdrPtr && typeof heap._malloc === 'function') hdrPtr = heap._malloc(4 * 4);
    // The renderer outlives an App on a warm restart, and the last App shut this down. A linear frame is encoded here,
    // so waiting for a camera with effects to bring it back left every scene without one showing raw linear values.
    // Only then: on a first boot the renderer starts its own, and starting one before it exists would make a second.
    const core = module as PostProcessCore;
    if (restartOwed && hasPostProcessCore(core) && !core.postprocess_isInitialized()) core.postprocess_init(1, 1);
    restartOwed = false;
}

/** A core built without ES_ENABLE_POSTPROCESS (the lite mini-game engine) has none of these entry points: no chain, nothing to ask. */
function hasPostProcessCore(core: PostProcessCore): boolean {
    return typeof core.postprocess_isInitialized === 'function';
}

/** @internal Wired by the engine plugins — not part of the public API. */
export function shutdownPostProcessAPI(): void {
    // Per-App state dies with its App; here we only tear down the shared module.
    if (module) {
        try {
            if (hasPostProcessCore(module) && module.postprocess_isInitialized()) {
                module.postprocess_shutdown();
                restartOwed = true;
            }
        } catch (e) {
            handleWasmError(e, 'PostProcess.shutdown');
        }
    }
    if (hdrPtr && module) {
        (module as unknown as { _free?(p: number): void })._free?.(hdrPtr);
        hdrPtr = 0;
    }
    bridge.disconnect();
    module = null;
}

/**
 * Whether the device the chain runs on has a compute stage (WebGPU). False before the chain is up, and on WebGL2.
 * An effect that has a compute version and a fragment one asks which to build.
 */
export function deviceHasCompute(): boolean {
    try {
        return getModule().postprocess_supportsCompute?.() === true;
    } catch {
        return false;
    }
}

function getModule(): PostProcessCore {
    if (!module) {
        throw new Error('PostProcess API not initialized. Call initPostProcessAPI() first.');
    }
    return module;
}

/**
 * Push a stack's enabled passes to the engine. `force` re-pushes a stack that has
 * not been edited — needed because the engine's pass list is torn down after every
 * camera (see {@link PostProcessAPI._resetAfterCamera}), so "not dirty" says the
 * stack is unchanged, NOT that the engine still holds it.
 */
export function syncStackToWasm(stack: PostProcessStack, force = false,
    allow: (name: string) => boolean = () => true): void {
    if (!force && !stack.isDirty) return;

    const m = getModule();

    try {
        m.postprocess_clearPasses();
    } catch (e) {
        handleWasmError(e, 'PostProcess._applyForCamera:clearPasses');
        return;
    }

    for (const pass of stack.passes) {
        if (!pass.enabled || !allow(pass.name)) continue;
        try {
            if (pass.native) {
                if (!m.postprocess_addNativePass) continue;
                m.postprocess_addNativePass(pass.name, pass.native);
            } else if (pass.compute) {
                // No compute on this core (WebGL2): the pass is left out and the picture goes through as it was.
                if (!m.postprocess_addComputePass) continue;
                m.postprocess_addComputePass(pass.name, pass.compute.source, pass.compute.params.join(','),
                    pass.compute.workgroupSize[0], pass.compute.workgroupSize[1]);
            } else {
                m.postprocess_addPass(pass.name, pass.shader);
            }
            // Only when it is not 1: every pass that predates fractional sizing
            // means full size, and saying so is the same answer.
            if (pass.scale !== 1) m.postprocess_setPassScale(pass.name, pass.scale);
            if (pass.continuesEffect) m.postprocess_setPassContinuesEffect(pass.name);
        } catch (e) {
            handleWasmError(e, `PostProcess._applyForCamera:addPass("${pass.name}")`);
            continue;
        }

        for (const [name, value] of pass.floatUniforms) {
            try {
                m.postprocess_setUniformFloat(pass.name, name, value);
            } catch (e) {
                handleWasmError(e, `PostProcess._applyForCamera:setUniform("${pass.name}", "${name}")`);
            }
        }

        for (const [name, value] of pass.vec4Uniforms) {
            try {
                m.postprocess_setUniformVec4(pass.name, name, value.x, value.y, value.z, value.w);
            } catch (e) {
                handleWasmError(e, `PostProcess._applyForCamera:setUniformVec4("${pass.name}", "${name}")`);
            }
        }

        for (const [name, handle] of pass.textureUniforms) {
            try {
                m.postprocess_setPassTexture(pass.name, name, handle);
            } catch (e) {
                handleWasmError(e, `PostProcess._applyForCamera:setPassTexture("${pass.name}", "${name}")`);
            }
        }
    }

    // The display look rides the stack as the passes do, and goes with them (clearPasses above): said again for every camera that has one.
    if (stack.displayLut.amount > 0) {
        try {
            m.postprocess_setDisplayLut?.(stack.displayLut.texture, stack.displayLut.amount);
        } catch (e) {
            handleWasmError(e, 'PostProcess._applyForCamera:setDisplayLut');
        }
    }

    stack.clearDirty();
}

/**
 * Per-App post-process API. Owns this App's `state` (stacks, camera bindings,
 * screen stack) and drives the shared C++ post-process pipeline via the module.
 * The wasm-call methods are shared on the prototype; only `state` is per-App.
 *
 * B2b-3a: a single default instance is exported to keep call sites unchanged;
 * B2b-3b flips this to a per-App `defineResource` injected into the pipeline.
 */
/**
 * The curve a frame applies on its way to the display — the pipeline's, not an
 * effect a stack happens to hold, so it runs once and last. `none` leaves values
 * alone, which is the exact round trip flat content wants; `aces` maps radiance
 * above 1 down a filmic shoulder, which is what a lit 3D scene needs; `neutral`
 * (Khronos PBR Neutral) rolls highlights off while keeping hue and saturation, so a
 * sunlit red stays red where `aces` walks it toward cream.
 *
 * @experimental
 */
export type OutputTransform = 'none' | 'aces' | 'neutral';

/**
 * The curve's number at the wasm boundary. Here and not at each call: the
 * translation was written twice, and a third curve would have reached one of
 * them and been silently read as `none` by the other.
 */
export function outputTransformCode(transform: OutputTransform | undefined): number {
    return transform === 'aces' ? 1 : transform === 'neutral' ? 2 : 0;
}

export class PostProcessAPI {
    readonly state = new PostProcessState();

    /** Volume-system bookkeeping (per-App): camera → the stack it created, and shared effect shaders. */
    readonly volumeStacks = new Map<Entity, PostProcessStack>();
    readonly volumeShaders = new Map<string, ShaderHandle>();

    /**
     * Which stack the engine's pass list currently holds, or null when it holds
     * none. Distinct from the stack's own dirty flag, which only tracks edits:
     * every camera ends by clearing the engine's passes, so a stack that was
     * pushed last frame and never edited must still be pushed again this frame.
     */
    private engineStack_: PostProcessStack | null = null;
    private qualityFilter_: Readonly<QualityProfile> | null = null;

    setQualityFilter(profile: Readonly<QualityProfile> | null): void {
        if (this.qualityFilter_ === profile) return;
        this.qualityFilter_ = profile;
        this.engineStack_ = null;
    }

    /** How the quality level in force smooths edges: the volume system adds the temporal pass where it says `temporal`. */
    get antialiasing(): 'msaa' | 'temporal' {
        return this.qualityFilter_?.antialiasing ?? 'msaa';
    }

    /** Whether the quality level in force has the dynamic GI run its cheaper way: the volume system sets the effect's switches from it. */
    get dynamicGIReduced(): boolean {
        return this.qualityFilter_?.dynamicGIReduced ?? false;
    }

    /**
     * Whether the quality level in force runs an effect, by its type. For a system that prepares something for an effect off the GPU (the dynamic GI
     * builds a distance field, a second of a phone's CPU): it asks before it does.
     */
    effectAllowed(type: string): boolean {
        const passes = effectPassNames(type);
        return (passes.length > 0 ? passes : [type]).every((name) => qualityPassAllowed(this.qualityFilter_, name));
    }

    private allowQualityPass_ = (name: string): boolean => {
        return qualityPassAllowed(this.qualityFilter_, name);
    };

    // -- per-App state (stacks / bindings / screen stack) --------------------

    get screenStack(): PostProcessStack | null {
        return this.state.screenStack;
    }

    setScreenStack(stack: PostProcessStack | null): void {
        this.state.screenStack = stack;
    }

    createStack(): PostProcessStack {
        return this.state.createStack();
    }

    bind(camera: Entity, stack: PostProcessStack): void {
        if (stack.isDestroyed) {
            throw new Error('Cannot bind a destroyed PostProcessStack');
        }
        this.state.cameraBindings.set(camera, stack);
    }

    unbind(camera: Entity): void {
        this.state.cameraBindings.delete(camera);
    }

    getStack(camera: Entity): PostProcessStack | null {
        return this.state.cameraBindings.get(camera) ?? null;
    }

    // -- shared C++ pipeline commands ----------------------------------------

    init(width: number, height: number): boolean {
        try {
            return getModule().postprocess_init(width, height);
        } catch (e) {
            handleWasmError(e, `PostProcess.init(${width}x${height})`);
            return false;
        }
    }

    shutdown(): void {
        try {
            getModule().postprocess_shutdown();
        } catch (e) {
            handleWasmError(e, 'PostProcess.shutdown');
        }
    }

    resize(width: number, height: number): void {
        try {
            getModule().postprocess_resize(width, height);
        } catch (e) {
            handleWasmError(e, `PostProcess.resize(${width}x${height})`);
        }
    }

    isInitialized(): boolean {
        if (!module || !hasPostProcessCore(module)) return false;
        try {
            return module.postprocess_isInitialized();
        } catch (e) {
            handleWasmError(e, 'PostProcess.isInitialized');
            return false;
        }
    }

    setBypass(bypass: boolean): void {
        try {
            getModule().postprocess_setBypass(bypass);
        } catch (e) {
            handleWasmError(e, 'PostProcess.setBypass');
        }
    }

    /**
     * The curve the frame applies on its way to the display.
     *
     * Applied to whatever the chain produced, so it also engages the capture: a
     * project that asks for a curve gets one with an empty stack. See
     * {@link OutputTransform} for which to want.
     */
    setOutputTransform(transform: OutputTransform): void {
        try {
            getModule().postprocess_setOutputTransform(outputTransformCode(transform));
        } catch (e) {
            handleWasmError(e, 'PostProcess.setOutputTransform');
        }
    }

    /**
     * Multisampling the scene target should rasterise with; 1 turns it off. The
     * device clamps it, so this is the project's ASK, not what it gets — a
     * backend with no MSAA answers 1 whatever is set here.
     */
    setMsaaSamples(samples: number): void {
        try {
            getModule().postprocess_setMsaaSamples(samples >>> 0);
        } catch (e) {
            handleWasmError(e, 'PostProcess.setMsaaSamples');
        }
    }

    /**
     * What the scene target is ACTUALLY multisampled at, and the most this
     * device can do. @experimental
     *
     * Two numbers because a request and a capability are different facts: asking
     * for 8 where the backend allows 1 is not a typo, and only saying both tells
     * those apart. `0` means nothing here can answer.
     */
    msaaCapability(): { effective: number; max: number } {
        try {
            // Off the module rather than through PostProcessCore, a Required<> of
            // what a chain cannot run WITHOUT: these two only report on it, and a
            // host binding neither still has a working chain.
            const m = getModule() as unknown as {
                postprocess_effectiveMsaaSamples?(): number;
                postprocess_maxMsaaSamples?(): number;
            };
            return {
                effective: m.postprocess_effectiveMsaaSamples?.() ?? 0,
                max: m.postprocess_maxMsaaSamples?.() ?? 0,
            };
        } catch (e) {
            handleWasmError(e, 'PostProcess.msaaCapability');
            return { effective: 0, max: 0 };
        }
    }

    /**
     * The format decision the last frame COMMITTED to. @experimental
     *
     * The frame's own answer, not the device asked again. `linear` false is a
     * project that never asked for HDR, which is not a fallback. The names come
     * from the engine — a second spelling of the enum's order is drift.
     */
    hdrFormat(): HdrFormat | null {
        try {
            const m = getModule() as unknown as {
                postprocess_hdrFormat?(p: number): number;
                postprocess_hdrFormatNames?(): string;
            };
            if (!m.postprocess_hdrFormat || !m.postprocess_hdrFormatNames || !hdrPtr) return null;
            if (!m.postprocess_hdrFormat(hdrPtr)) return null;
            const heap = (bridge.module as unknown as { HEAPF32?: Float32Array }).HEAPF32;
            if (!heap) return null;
            const f = heap.subarray(hdrPtr >> 2, (hdrPtr >> 2) + 4);
            const [requested, effective, reason] = m.postprocess_hdrFormatNames().split('|');
            return {
                requested: requested ?? '', effective: effective ?? '',
                reason: reason ?? 'none', linear: f[3] === 1,
                fellBack: (requested ?? '') !== (effective ?? ''),
            };
        } catch (e) {
            handleWasmError(e, 'PostProcess.hdrFormat');
            return null;
        }
    }

    begin(): void {
        try {
            getModule().postprocess_begin();
        } catch (e) {
            handleWasmError(e, 'PostProcess.begin');
        }
    }

    end(): void {
        try {
            getModule().postprocess_end();
        } catch (e) {
            handleWasmError(e, 'PostProcess.end');
        }
    }

    /** Say the frame needs a present when the rects alone cannot: a 1x letterbox
     *  and a split-screen viewport are the same geometry and differ only in intent. */
    setPresentRequired(required: boolean): void {
        try {
            getModule().postprocess_setPresentRequired?.(required);
        } catch (e) {
            handleWasmError(e, 'PostProcess.setPresentRequired');
        }
    }

    setOutputViewport(x: number, y: number, w: number, h: number): void {
        try {
            getModule().postprocess_setOutputViewport(x, y, w, h);
        } catch (e) {
            handleWasmError(e, 'PostProcess.setOutputViewport');
        }
    }

    // -- per-camera / screen orchestration (state + commands) ----------------

    _applyForCamera(camera: Entity): void {
        const stack = this.state.cameraBindings.get(camera);
        if (!stack || stack.isDestroyed || stack.enabledPassCount === 0) {
            this.setBypass(true);
            return;
        }

        if (!this.isInitialized()) {
            this.init(1, 1);
        }

        this.setBypass(false);
        syncStackToWasm(stack, this.engineStack_ !== stack, this.allowQualityPass_);
        this.engineStack_ = stack;
    }

    _resetAfterCamera(): void {
        try {
            getModule().postprocess_clearPasses();
            getModule().postprocess_setBypass(true);
            this.engineStack_ = null;
        } catch (e) {
            handleWasmError(e, 'PostProcess._resetAfterCamera');
        }
    }

    _beginScreenCapture(): void {
        try {
            getModule().postprocess_beginScreenCapture();
        } catch (e) {
            handleWasmError(e, 'PostProcess._beginScreenCapture');
        }
    }

    _endScreenCapture(): void {
        try {
            getModule().postprocess_endScreenCapture();
        } catch (e) {
            handleWasmError(e, 'PostProcess._endScreenCapture');
        }
    }

    _applyScreenStack(): void {
        const stack = this.state.screenStack;
        if (!stack || stack.isDestroyed || stack.enabledPassCount === 0) return;

        const m = getModule();
        try {
            m.postprocess_clearScreenPasses();
        } catch (e) {
            handleWasmError(e, 'PostProcess._applyScreenStack:clearScreenPasses');
            return;
        }

        for (const pass of stack.passes) {
            if (!pass.enabled || !this.allowQualityPass_(pass.name)) continue;
            try {
                m.postprocess_addScreenPass(pass.name, pass.shader);
            } catch (e) {
                handleWasmError(e, `PostProcess._applyScreenStack:addScreenPass("${pass.name}")`);
                continue;
            }

            for (const [name, value] of pass.floatUniforms) {
                try {
                    m.postprocess_setScreenUniformFloat(pass.name, name, value);
                } catch (e) {
                    handleWasmError(e, `PostProcess._applyScreenStack:setScreenUniform("${pass.name}", "${name}")`);
                }
            }

            for (const [name, value] of pass.vec4Uniforms) {
                try {
                    m.postprocess_setScreenUniformVec4(pass.name, name, value.x, value.y, value.z, value.w);
                } catch (e) {
                    handleWasmError(e, `PostProcess._applyScreenStack:setScreenUniformVec4("${pass.name}", "${name}")`);
                }
            }
        }
    }

    _executeScreenPasses(): void {
        try {
            getModule().postprocess_executeScreenPasses();
        } catch (e) {
            handleWasmError(e, 'PostProcess._executeScreenPasses');
        }
    }
}

/**
 * Per-App post-process resource. Published + injected into the render pipeline
 * by `PostProcessPlugin`; read as `app.getResource(PostProcess)`.
 */
export const PostProcess = defineResource<PostProcessAPI>(null!, 'PostProcess');