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.

10.9 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
//
// The native RendererBackend — the embedded-Dawn sibling of the wasm renderer
// bindings the SDK's frame runs on.
//
// Before this, the native host wrote its own frame in C++: one hard-coded
// orthographic projection, collect, flush, present. Everything the SDK decides
// about a frame — which cameras exist, their viewport rects, clear flags and
// ortho size, y-sort layers, which scenes are active, what draws just before the
// flush — lived only on the web side, so each of those had to be re-implemented
// natively or go missing.
//
// The frame is now ONE implementation (CameraPlugin -> RenderPipeline ->
// Renderer) over two backends: the wasm module marshals through its heap, this
// one calls the host's es_renderer_* bindings with the typed arrays as they are.
// The C++ host keeps what only it can do: the swapchain and the present.

import type { CppRegistry } from '../../wasm';
import type { RendererBackend, RenderStats } from '../../render/renderer';
import { RENDERER_BINDINGS, RENDERER_OPTIONAL_BINDINGS, RENDERER_STATS_BINDINGS } from './nativeBindings';
import { createNativeHeap, type NativeHeap } from './nativeHeap';
import { ATLAS_REFUSAL, LIGHT_REFUSAL } from '../../render/refusals';

/** Invoke a host-provided global by name; throws if the host did not bind it
 *  (these are the frame contract — a missing one is a broken host, not a
 *  degraded frame). */
/**
 * The floats a LOD decision or a light's standing is read back through, allocated
 * once — the wider of the two, since neither outlives a call.
 *
 * Held for the process rather than per call: it is sixteen bytes against a heap
 * whose views must not be rebuilt (see nativeHeap.ts), and an inspect runs while
 * a panel is open, which is every frame.
 */
let lodScratch: { heap: NativeHeap; ptr: number } | null = null;

function hostCall(scope: Record<string, unknown>, name: string, args: unknown[]): unknown {
    const fn = scope[name];
    if (typeof fn !== 'function') {
        throw new Error(`native host binding "${name}" is missing`);
    }
    return (fn as (...a: unknown[]) => unknown)(...args);
}

/**
 * Build the RendererBackend over the host's frame bindings. `scope` holds the
 * globals (the QuickJS global object on a device; a plain object in tests).
 *
 * The registry argument every wasm call carries is implicit here: a native host
 * has exactly one C++ registry, the one it created the World over, so the
 * bindings take none.
 */
/** A host entry point that may not exist, as a callable or null. */
function optional(
    scope: Record<string, unknown>,
    name: string,
): ((...args: unknown[]) => unknown) | null {
    const fn = scope[name];
    return typeof fn === 'function' ? (fn as (...args: unknown[]) => unknown) : null;
}

export function createNativeRendererBackend(
    scope: Record<string, unknown> = globalThis as unknown as Record<string, unknown>,
): RendererBackend {
    const lodHeap = (): { heap: NativeHeap; ptr: number } | null => {
        if (lodScratch) return lodScratch;
        const heap = createNativeHeap(scope);
        if (!heap) return null;
        lodScratch = { heap, ptr: heap._malloc(9 * 4) };
        return lodScratch;
    };
    return {
        // The renderer is already up: the host created the device and sized the
        // surface before the SDK booted. Resizing still matters (rotation).
        init: (): void => {},
        resize: (width, height): void => {
            hostCall(scope, RENDERER_BINDINGS.resize, [width, height]);
        },
        beginFrame: (elapsedSec): void => {
            hostCall(scope, RENDERER_BINDINGS.beginFrame, [elapsedSec]);
        },
        setOrigin: (x, y, z): void => {
            optional(scope, RENDERER_OPTIONAL_BINDINGS.setOrigin)?.(x, y, z);
        },
        updateTransforms: (_registry: CppRegistry): void => {
            hostCall(scope, RENDERER_BINDINGS.updateTransforms, []);
        },
        begin: (viewProjection, target, clearFlags, r, g, b, a, clearX, clearY, clearW, clearH): void => {
            hostCall(scope, RENDERER_BINDINGS.begin,
                [viewProjection, target, clearFlags, r, g, b, a, clearX, clearY, clearW, clearH]);
        },
        submitAll: (_registry: CppRegistry, vpX, vpY, vpW, vpH): void => {
            hostCall(scope, RENDERER_BINDINGS.submitAll, [vpX, vpY, vpW, vpH]);
        },
        flush: (): void => {
            hostCall(scope, RENDERER_BINDINGS.flush, []);
        },
        end: (): void => {
            hostCall(scope, RENDERER_BINDINGS.end, []);
        },
        endFrame: (): void => {
            optional(scope, RENDERER_OPTIONAL_BINDINGS.endFrame)?.();
        },
        hasScreenOverlay: (): boolean =>
            optional(scope, RENDERER_OPTIONAL_BINDINGS.beginScreenOverlay) !== null,
        beginScreenOverlay: (projection, vpX, vpY, vpW, vpH): void => {
            optional(scope, RENDERER_OPTIONAL_BINDINGS.beginScreenOverlay)?.(
                projection, vpX, vpY, vpW, vpH);
        },
        submitScreenOverlay: (_registry: CppRegistry): void => {
            optional(scope, RENDERER_OPTIONAL_BINDINGS.submitScreenOverlay)?.();
        },
        endScreenOverlay: (target): void => {
            optional(scope, RENDERER_OPTIONAL_BINDINGS.endScreenOverlay)?.(target);
        },
        setStage: (stage): void => {
            hostCall(scope, RENDERER_BINDINGS.setStage, [stage]);
        },
        setViewport: (x, y, w, h): void => {
            hostCall(scope, RENDERER_BINDINGS.setViewport, [x, y, w, h]);
        },
        setYSortLayers: (mask): void => {
            hostCall(scope, RENDERER_BINDINGS.setYSortLayers, [mask >>> 0]);
        },
        // Optional (RENDERER_OPTIONAL_BINDINGS): a host built before 2.5D simply
        // stays painter-ordered rather than failing the whole frame contract.
        setDepthLayers: (mask): void => {
            const fn = scope[RENDERER_OPTIONAL_BINDINGS.setDepthLayers];
            if (typeof fn === 'function') (fn as (m: number) => void)(mask >>> 0);
        },
        setTreeSortLayers: (mask): void => {
            const fn = scope[RENDERER_OPTIONAL_BINDINGS.setTreeSortLayers];
            if (typeof fn === 'function') (fn as (m: number) => void)(mask >>> 0);
        },
        setCullingMask: (mask): void => {
            const fn = scope[RENDERER_OPTIONAL_BINDINGS.setCullingMask];
            if (typeof fn === 'function') (fn as (m: number) => void)(mask >>> 0);
        },
        setViewId: (view): void => {
            const fn = scope[RENDERER_OPTIONAL_BINDINGS.setViewId];
            if (typeof fn === 'function') (fn as (v: number) => void)(view >>> 0);
        },
        lodInspect: (view, entity) => {
            const fn = scope[RENDERER_OPTIONAL_BINDINGS.lodInspect];
            const heap = lodHeap();
            if (typeof fn !== 'function' || !heap) return null;
            if (!(fn as (v: number, e: number, p: number) => number)(view >>> 0, entity >>> 0, heap.ptr)) {
                return null;
            }
            const f = heap.heap.HEAPF32;
            const i = heap.ptr >> 2;
            return {
                level: f[i]! < 0 ? null : f[i]!,
                unbiased: f[i + 1]! < 0 ? null : f[i + 1]!,
                levels: f[i + 2]!,
                screenSize: f[i + 3]!,
            };
        },
        shadowStatus: (entity) => {
            const fn = scope[RENDERER_OPTIONAL_BINDINGS.shadowStatus];
            const heap = lodHeap();
            if (typeof fn !== 'function' || !heap) return null;
            if (!(fn as (e: number, p: number) => number)(entity >>> 0, heap.ptr)) return null;
            const f = heap.heap.HEAPF32;
            const i = heap.ptr >> 2;
            const refusal = ATLAS_REFUSAL[f[i + 2]!];
            return {
                requested: f[i]!, granted: f[i + 1]!, refusal: refusal ?? 'none',
                deniedCasters: f[i + 3]!, reducedCasters: f[i + 4]!,
            };
        },
        lightStatus: (entity) => {
            const fn = scope[RENDERER_OPTIONAL_BINDINGS.lightStatus];
            const heap = lodHeap();
            if (typeof fn !== 'function' || !heap) return null;
            if (!(fn as (e: number, p: number) => number)(entity >>> 0, heap.ptr)) return null;
            const f = heap.heap.HEAPF32;
            const i = heap.ptr >> 2;
            return {
                accepted: f[i] === 1,
                refusal: LIGHT_REFUSAL[f[i + 1]!] ?? 'none',
                limit: f[i + 2]!, requested: f[i + 3]!, refusedCount: f[i + 4]!,
                environmentSunAim: f[i + 5] === 1 ? [f[i + 6]!, f[i + 7]!, f[i + 8]!] : null,
            };
        },
        setLodPreview: (view, entity, level): void => {
            const fn = scope[RENDERER_OPTIONAL_BINDINGS.setLodPreview];
            if (typeof fn === 'function') {
                (fn as (v: number, e: number, l: number) => void)(view >>> 0, entity >>> 0, level ?? -1);
            }
        },
        setViewShading: (view, mode): void => {
            const fn = scope[RENDERER_OPTIONAL_BINDINGS.setViewShading];
            if (typeof fn === 'function') (fn as (v: number, m: number) => void)(view >>> 0, mode);
        },
        setMeshEdgeBuffers: (enabled): void => {
            const fn = scope[RENDERER_OPTIONAL_BINDINGS.setMeshEdgeBuffers];
            if (typeof fn === 'function') (fn as (e: boolean) => void)(enabled);
        },
        setViewSkinWeights: (view, entity, joint): void => {
            const fn = scope[RENDERER_OPTIONAL_BINDINGS.setViewSkinWeights];
            if (typeof fn === 'function') (fn as (v: number, e: number, j: number) => void)(view >>> 0, entity >>> 0, joint);
        },
        getStats: (): RenderStats => {
            const read = (name: string): number => {
                const fn = scope[name];
                return typeof fn === 'function' ? ((fn as () => number)() ?? 0) : 0;
            };
            return {
                drawCalls: read(RENDERER_STATS_BINDINGS.drawCalls),
                gpuDraws: read(RENDERER_STATS_BINDINGS.gpuDraws),
                triangles: read(RENDERER_STATS_BINDINGS.triangles),
                sprites: read(RENDERER_STATS_BINDINGS.sprites),
                text: read(RENDERER_STATS_BINDINGS.text),
                skeletal: 0,   // the skeletal runtimes have no native counterpart yet
                meshes: read(RENDERER_STATS_BINDINGS.meshes),
                culled: read(RENDERER_STATS_BINDINGS.culled),
            };
        },
    };
}

/**
 * The drawable surface in pixels, as the host currently sees it. The camera
 * plugin reads it every frame, so a rotation or a resized window reaches the
 * projection without anyone pushing an event.
 */
export function nativeSurfaceSize(
    scope: Record<string, unknown> = globalThis as unknown as Record<string, unknown>,
): { width: number; height: number } {
    const size = hostCall(scope, RENDERER_BINDINGS.surfaceSize, []) as
        { width: number; height: number } | undefined;
    return size ?? { width: 0, height: 0 };
}