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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// 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);
}
}
}
}