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.

15.5 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    renderPipeline.ts
 * @brief   Unified render pipeline for runtime and editor
 */

import type { CppRegistry } from '../wasm';
import type { Entity } from '../types';
import { Renderer } from './renderer';
import type { PostProcessAPI } from '../postprocess';
import type { ScreenOverlayData } from '../ui/core/screen-overlay';
import { Draw, beginPresentedDraw, endPresentedDraw, isDrawAPIReady } from './draw';
import {
    getDrawCallbacks,
    unregisterDrawCallback,
    getPreSceneDrawCallbacks,
    unregisterPreSceneDrawCallback,
} from './customDraw';
import { log } from '../util/logger';
import { planPresent, RenderResolution } from '../camera/presentPlan';
import type { QualityController } from './quality';
import { RenderDemand } from './renderDemand';

export interface Viewport {
    x: number;
    y: number;
    w: number;
    h: number;
}

export interface RenderParams {
    registry: { _cpp: CppRegistry };
    viewProjection: Float32Array;
    width: number;
    height: number;
    elapsed: number;
    /** Background for the pass's load-op clear (default opaque black). */
    clearColor?: { x: number; y: number; z: number; w: number };
    /**
     * The caller already opened the frame (`beginFrame`) — as the render system
     * does, so the transform pass can run before the cameras are read. Opening a
     * frame twice ages the render-target pool twice, so it must happen once.
     */
    frameAlreadyBegun?: boolean;
}

export interface CameraRenderParams {
    registry: { _cpp: CppRegistry };
    viewProjection: Float32Array;
    /** The view-projection for the render origin, which the renderer is begun with; absent, `viewProjection` (the origin is zero). */
    renderViewProjection?: Float32Array;
    viewportPixels: Viewport;
    clearFlags: number;
    elapsed: number;
    cameraEntity?: Entity;
    /** Background for the camera's load-op clear (default opaque black). */
    clearColor?: { x: number; y: number; z: number; w: number };
    /** Sorting layers this camera draws (`Camera.cullingMask`); omitted = all. */
    cullingMask?: number;
    /** Offscreen target to draw into; 0 (default) is the screen. */
    renderTarget?: number;
    /** World units the camera shows vertically (`2 * halfH`); drives the render size. */
    worldHeight?: number;
    /** How the render resolution is chosen; omitted = render straight to the surface. */
    renderPolicy?: RenderResolution;
}

export class RenderPipeline {
    private frameElapsed_ = 0;
    get frameElapsed(): number { return this.frameElapsed_; }
    private renderingEnabled_ = true;
    /** Which frames are drawn, when the game has asked for only those that can look different. */
    readonly demand = new RenderDemand();
    private lastWidth_ = 0;
    private lastHeight_ = 0;
    private activeScenes_: Set<string> | null = null;
    private preFlushCallbacks_: ((registry: { _cpp: CppRegistry }, viewProjection?: Float32Array) => void)[] = [];
    private screenOverlayCallbacks_: ((registry: { _cpp: CppRegistry }, viewProjection?: Float32Array) => void)[] = [];
    private postProcess_: PostProcessAPI | null = null;
    private quality_: QualityController | null = null;
    private applyQuality_: (() => void) | null = null;
    private warnedMissingPresent_ = false;

    /** @experimental */
    get renderingEnabled(): boolean { return this.renderingEnabled_; }

    /** @experimental */
    setRenderingEnabled(enabled: boolean): void { this.renderingEnabled_ = enabled; }

    setQuality(quality: QualityController, apply?: () => void): void {
        this.quality_ = quality;
        this.applyQuality_ = apply ?? null;
    }

    setActiveScenes(scenes: Set<string> | null): void {
        this.activeScenes_ = scenes;
    }

    /**
     * Inject this App's post-process API (by PostProcessPlugin). When null, the
     * pipeline does no post-processing — it has no hard dependency on the
     * post-process subsystem.
     */
    setPostProcess(pp: PostProcessAPI | null): void {
        this.postProcess_ = pp;
    }

    /** The optional projection is the current pass; legacy manual hosts may omit it. */
    addPreFlushCallback(cb: (registry: { _cpp: CppRegistry }, viewProjection?: Float32Array) => void): void {
        this.preFlushCallbacks_.push(cb);
    }

    /**
     * Register geometry a plugin draws into the SCREEN overlay rather than into a
     * camera — the sibling of {@link addPreFlushCallback}, separate for the same
     * reason the two collects are: a callback that ran in both would put the same
     * glyph in each list. Runs between the overlay's collect and its pass.
     */
    addScreenOverlayCallback(cb: (registry: { _cpp: CppRegistry }, viewProjection?: Float32Array) => void): void {
        this.screenOverlayCallbacks_.push(cb);
    }

    /**
     * Run what plugins registered to draw just before the frame flushes (glyph
     * quads, today). {@link submitScene} calls this in the middle of its own
     * sequence; a host that owns its render loop in C++ — the native one — calls
     * it directly at the same point, between collecting the scene and flushing,
     * so text lands in the same frame either way.
     */
    runPreFlushCallbacks(registry: { _cpp: CppRegistry }, viewProjection?: Float32Array): void {
        for (const cb of this.preFlushCallbacks_) cb(registry, viewProjection);
    }

    beginFrame(elapsedSec = 0): void {
        this.frameElapsed_ = elapsedSec;
        this.applyQuality_?.();
        this.quality_?.setLimitation('fixed-render-resolution', false);
        this.quality_?.setLimitation('resolution-present-unavailable', false);
        this.postProcess_?.setQualityFilter(this.quality_?.enabled ? this.quality_.profile : null);
        Renderer.beginFrame(elapsedSec);
    }

    /**
     * Closes the frame. The pair of {@link beginFrame}, and the last thing a
     * frame does: a backend that borrows the swapchain image for a frame gives it
     * back here, so everything drawn after the first camera — a second camera,
     * the screen post stack, the overlay — still has somewhere to land.
     */
    endFrame(): void {
        Renderer.endFrame();
    }

    /**
     * The frame's screen-space overlay: one pass, after every camera and after
     * post. It takes a projection and a rect and no camera, which is what makes a
     * HUD hold still while the view moves. Silent when the core has no overlay
     * pass, which has not partitioned the domains either.
     */
    renderScreenOverlay(
        registry: { _cpp: CppRegistry },
        overlay: ScreenOverlayData,
        target = 0,
    ): void {
        if (!overlay.active || overlay.vpW === 0 || overlay.vpH === 0) return;
        if (!Renderer.hasScreenOverlay()) return;

        Renderer.beginScreenOverlay(overlay.projection,
                                    overlay.vpX, overlay.vpY, overlay.vpW, overlay.vpH);
        // Set after begin (which clears the list) and before the collect it gates,
        // exactly as a camera's own mask is.
        Renderer.setCullingMask(overlay.layerMask);
        Renderer.submitScreenOverlay(registry);
        for (const cb of this.screenOverlayCallbacks_) cb(registry, overlay.projection);
        Renderer.endScreenOverlay(target);
    }

    beginScreenCapture(): void {
        const pp = this.postProcess_;
        if (pp && pp.screenStack && pp.screenStack.enabledPassCount > 0) {
            if (!pp.isInitialized()) {
                pp.init(1, 1);
            }
            pp._applyScreenStack();
            pp._beginScreenCapture();
        }
    }

    endScreenCapture(): void {
        const pp = this.postProcess_;
        if (pp && pp.screenStack && pp.screenStack.enabledPassCount > 0) {
            pp._endScreenCapture();
            pp._executeScreenPasses();
        }
    }

    submitScene(
        registry: { _cpp: CppRegistry },
        viewProjection: Float32Array,
        viewport: Viewport,
        _elapsed: number,
    ): void {
        // Underlays (editor grid / world-space guides) draw first so the scene's
        // sprites, flushed below, occlude them.
        this.executePreSceneDrawCallbacks(viewProjection, viewport, _elapsed);

        Renderer.updateTransforms(registry);
        Renderer.submitAll(registry, viewport.x, viewport.y, viewport.w, viewport.h);
        this.runPreFlushCallbacks(registry, viewProjection);
        Renderer.flush();

        this.executeDrawCallbacks(viewProjection, viewport, _elapsed, registry._cpp);
    }

    render(params: RenderParams): void {
        const { registry, viewProjection, width, height, elapsed } = params;

        if (width !== this.lastWidth_ || height !== this.lastHeight_) {
            Renderer.resize(width, height);
            this.lastWidth_ = width;
            this.lastHeight_ = height;
        }

        if (!params.frameAlreadyBegun) Renderer.beginFrame(elapsed);
        Renderer.setViewport(0, 0, width, height);
        Renderer.begin(viewProjection, 0, /*clear color+depth*/ 3, params.clearColor);
        // The mask is sticky in the draw list; this path has no camera to own one.
        Renderer.setCullingMask(0xFFFFFFFF);
        Renderer.setViewId(0);
        this.submitScene(registry, viewProjection, { x: 0, y: 0, w: width, h: height }, elapsed);
        Renderer.end();
    }

    renderCamera(params: CameraRenderParams): void {
        const { registry, viewProjection, viewportPixels: vp, clearFlags, elapsed, cameraEntity } = params;

        // Where the scene is drawn and where it lands are two rects. A sprite that
        // scales itself can only clamp at its own texture's edge, so every boundary
        // breaks; scaling one whole image has no interior boundary to break.
        let plan = planPresent(
            params.renderPolicy ?? RenderResolution.Surface,
            params.worldHeight ?? 0, vp.w, vp.h);
        const quality = this.quality_;
        const scale = quality?.renderScale ?? 1;
        const fixedResolution = (params.renderPolicy ?? RenderResolution.Surface)
            !== RenderResolution.Surface;
        const scaling = scale < 1 && !fixedResolution && !params.renderTarget;
        if (scale < 1 && fixedResolution) quality?.setLimitation('fixed-render-resolution', true);
        if (scaling && !this.postProcess_) {
            quality?.setLimitation('resolution-present-unavailable', true);
        }
        if (scaling && this.postProcess_) {
            plan = { ...plan, renderWidth: Math.max(1, Math.round(vp.w * scale)),
                renderHeight: Math.max(1, Math.round(vp.h * scale)), oneToOne: false };
        }
        if (!plan.oneToOne && !this.postProcess_) {
            if (!this.warnedMissingPresent_) {
                log.warn('render', 'Resolution policy needs post-processing; using surface resolution');
                this.warnedMissingPresent_ = true;
            }
            plan = planPresent(RenderResolution.Surface, 0, vp.w, vp.h);
        }
        const scene: Viewport = plan.oneToOne
            ? vp
            : { x: 0, y: 0, w: plan.renderWidth, h: plan.renderHeight };
        const present: Viewport = plan.oneToOne
            ? vp
            : { x: vp.x + plan.x, y: vp.y + plan.y, w: plan.width, h: plan.height };

        const pp = this.postProcess_;
        pp?.setQualityFilter(quality?.enabled ? quality.profile : null);
        const hasStack = pp !== null && cameraEntity !== undefined && pp.getStack(cameraEntity) !== null;
        // A scaling present needs the chain even with no effects on it: the blit
        // that ends the chain IS the present, and nothing else can draw one.
        const hasPostProcess = pp !== null && (hasStack || !plan.oneToOne);

        if (hasPostProcess) {
            // A present is not an effect: with no stack nothing else would ever
            // bring the pipeline up, and an uninitialised one reports itself
            // disengaged — so the policy would go quietly missing.
            if (!pp!.isInitialized()) pp!.init(1, 1);
            if (hasStack) pp!._applyForCamera(cameraEntity!);
        }
        if (pp?.isInitialized()) {
            pp.resize(scene.w, scene.h);
            pp.setOutputViewport(present.x, present.y, present.w, present.h);
            // A letterbox at 1x is the same size as its chain and merely offset, so
            // the engine cannot read the need for it off the rects.
            pp.setPresentRequired(!plan.oneToOne);
        }
        if (hasPostProcess) {
            pp!.begin();
        }

        Renderer.setViewport(scene.x, scene.y, scene.w, scene.h);
        // The camera's clear rides begin as a region-scoped load-op — no scissor
        // dance, no sticky clear state at the boundary.
        Renderer.begin(params.renderViewProjection ?? viewProjection, params.renderTarget ?? 0, clearFlags, params.clearColor, scene);
        // Set after begin (which clears the draw list) and before the collect it gates.
        Renderer.setCullingMask(params.cullingMask ?? 0xFFFFFFFF);
        // The camera IS the view: a level picked from how big something looks is
        // this camera's answer, and the next camera must be free to disagree.
        Renderer.setViewId(cameraEntity ?? 0);
        this.submitScene(registry, viewProjection, scene, elapsed);
        Renderer.end();

        if (hasPostProcess) {
            pp!.end();
            if (hasStack) pp!._resetAfterCamera();
        }
    }

    private executePreSceneDrawCallbacks(
        viewProjection: Float32Array,
        viewport: Viewport,
        elapsed: number,
    ): void {
        const cbs = getPreSceneDrawCallbacks();
        // Same bargain as the post-scene pass: a core with no Draw API has no
        // batch to open, and the callbacks would have nowhere to draw.
        if (cbs.size === 0 || !isDrawAPIReady()) return;
        Draw.begin(viewProjection, viewport.w, viewport.h);
        const failed: string[] = [];
        for (const [id, fn] of cbs.entries()) {
            try {
                fn({ width: viewport.w, height: viewport.h, elapsed });
            } catch (e) {
                log.error('render', `pre-scene callback '${id}' error`, e);
                failed.push(id);
            }
        }
        Draw.end();
        for (const id of failed) {
            unregisterPreSceneDrawCallback(id);
        }
    }

    private executeDrawCallbacks(viewProjection: Float32Array, viewport: Viewport, elapsed: number, registry: CppRegistry): void {
        const cbs = getDrawCallbacks();
        // Plugins register overlays at build time whether one is ever turned on,
        // and a core with no Draw API has no batch to open — opening one throws
        // the frame away for a callback that would have drawn nothing.
        if (cbs.size > 0 && isDrawAPIReady()) {
            beginPresentedDraw(viewProjection, viewport.w, viewport.h);
            const failed: string[] = [];
            for (const [id, entry] of cbs.entries()) {
                if (entry.registry !== undefined && entry.registry !== registry) continue;
                if (entry.scene && this.activeScenes_ && !this.activeScenes_.has(entry.scene)) continue;
                try {
                    entry.fn(elapsed, {
                        viewProjection,
                        width: viewport.w,
                        height: viewport.h,
                    });
                } catch (e) {
                    log.error('render', `callback '${id}' error`, e);
                    failed.push(id);
                }
            }
            endPresentedDraw();
            for (const id of failed) {
                unregisterDrawCallback(id);
            }
        }
    }
}