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.

12.5 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    runtimeAssets.ts
 * @brief   Shared runtime asset primitives — the pluggable asset-fetch provider
 *          interface and the decoded-pixels → GL texture upload — used by the
 *          builder runtime loader and the spine scene loader (and any editor that
 *          drives the same load path). Kept in its own module so neither the
 *          runtime loader nor the spine loader has to import the other.
 */
import { TextureContent, type ESEngineModule, type CppResourceManager } from '../wasm';
import { samplesAsSrgb } from '../ecs/env';
import type { Backend } from '../asset/Backend';
import type { ParsedTextureImportSettings } from '../asset/textureImportSettings';
import { provideTextureContent, requireResourceManager } from '../wasm/resourceManager';
import { isKtx2Path, type BasisTranscoder } from '../asset/compressed';
import { withMalloc } from '../wasm/wasmScratch';

/**
 * How a target supplies scene assets to the single `Assets` channel, built from
 * canonical parts instead of a bespoke provider:
 *   - `backend`  — canonical fetch (text/binary, incl. KTX2 containers)
 *   - `decodePixels` — platform image → RGBA (URL `<img>` can't reach `estella://`
 *     / WeChat package files / inlined data-URLs); `flip` is applied on upload via
 *     `createTextureFromPixels`, so decoders return top-first and ignore it
 *   - `resolveRef` — ref → resolved (extension-bearing) path; must run before the
 *     `TextureLoader` KTX2 extension check, so uuid/manifest lookup lives HERE, not
 *     in `backend.resolveUrl`. Omit for identity.
 * (Signature declared locally, not imported from TextureLoader — that module
 * imports from this one, so importing back would cycle.)
 */
export interface RuntimeAssetSource {
    backend: Backend;
    decodePixels(path: string, flip: boolean, maxEdge?: number): Promise<{ width: number; height: number; pixels: Uint8Array }>;
    resolveRef?(ref: string): string;
    /**
     * The LOGICAL source path a ref was authored at (e.g. `assets/spine/hero.atlas`),
     * even after a content-addressed build renamed the physical file to a hash. A
     * loader that resolves a SIBLING by name — a Spine atlas naming its page PNG
     * relative to itself — needs the logical directory, which `resolveRef` (a build
     * path) has lost. Optional: a realm that stages under logical paths has nothing
     * to recover, and a caller falls back to the resolved path.
     */
    resolveAddress?(ref: string): string | null;
    /**
     * A texture as its host keeps it GPU-compressed (TextureLoader's
     * `TextureCompressedSource`). The editor's play realm supplies it, so the
     * running game holds the art compressed as the edit viewport does.
     */
    compressedTexture?(path: string): Promise<Uint8Array | 'pending' | null>;
    /**
     * Every asset path this realm ships (logical, extension-bearing). Powers
     * content-driven discovery of assets NO scene references — locale string
     * tables (`.eslocale`), which Text binds by KEY, not path. Optional: a
     * realm without it simply can't auto-load such assets (the runtime loader
     * warns when a scene needs them).
     */
    listAssetPaths?(): string[];
    /**
     * Per-texture import settings (filter/wrap/sRGB and the 9-slice border) for a
     * ref. These belong to the ASSET, not to any scene that uses it, which is why
     * they arrive through the realm's source alongside `resolveRef` rather than
     * being copied into every scene that references the texture — a copy in the
     * scene goes stale the moment the `.meta` changes.
     *
     * Optional: a realm without it renders with loader defaults. Each realm has
     * the data already — the editor from its asset database, a cooked build from
     * the `importer` block the cook copies into the ship manifest.
     */
    textureImportSettings?(ref: string): ParsedTextureImportSettings | undefined;
    /** The rectangle no pose of this spine PAIR leaves, in the skeleton's own
     *  space. Both refs, since an atlas the promise was not recorded against
     *  inherits nothing; a realm without this certifies nothing. */
    spineCulling?(skeleton: string, atlas: string):
        { x: number; y: number; width: number; height: number } | undefined;
}

export interface TextureParams {
    filterMode?: string;
    wrapMode?: string;
    /** sRGB-encoded color image (default true); see TextureImportSettings.srgb. */
    srgb?: boolean;
    /** A mip chain, rebuilt whenever the pixels change. */
    mipmaps?: boolean;
}

const FILTER_MODE_MAP: Record<string, number> = { 'nearest': 0, 'linear': 1 };
/** Set on a filter code to ask `rm_createTextureEx` for a mip chain. */
const FILTER_MIPMAPPED = 2;

/** The `rm_createTextureEx` filter code: nearest or linear, and whether it has mips. */
export function textureFilterCode(params: TextureParams): number {
    return (FILTER_MODE_MAP[params.filterMode ?? 'linear'] ?? 1) | (params.mipmaps ? FILTER_MIPMAPPED : 0);
}
const WRAP_MODE_MAP: Record<string, number> = { 'repeat': 0, 'clamp': 1, 'mirror': 2 };

/** Upload decoded RGBA pixels as a GL texture; returns the engine texture handle.
 *  `module` is the wasm-heap marshalling vehicle; it may be null on the native
 *  (embedded-Dawn) backend, whose ResourceManager takes the bytes directly. */
/**
 * A texture for an ATLAS PAGE, in whichever form the cook left it — KTX2 through the
 * ResourceManager or the realm's transcoder, the choice TextureLoader makes. After a
 * device loss the page is decoded again and moved behind the handle the skeleton holds.
 */
export async function createAtlasPageTexture(
    staged: string,
    fetchBinary: (path: string) => Promise<ArrayBuffer>,
    decodePixels: (path: string) => Promise<{ width: number; height: number; pixels: Uint8Array }>,
    transcoderProvider: (() => Promise<BasisTranscoder | null>) | undefined,
    module: ESEngineModule | null,
): Promise<{ handle: number; width: number; height: number }> {
    const upload = () => uploadAtlasPage(staged, fetchBinary, decodePixels, transcoderProvider, module);
    const page = await upload();
    provideTextureContent(page.handle, async () => {
        const fresh = await upload();
        const rm = requireResourceManager();
        const moved = rm.adoptTextureContent?.(page.handle, fresh.handle) ?? false;
        rm.releaseTexture(fresh.handle);
        return moved;
    });
    return page;
}

async function uploadAtlasPage(
    staged: string,
    fetchBinary: (path: string) => Promise<ArrayBuffer>,
    decodePixels: (path: string) => Promise<{ width: number; height: number; pixels: Uint8Array }>,
    transcoderProvider: (() => Promise<BasisTranscoder | null>) | undefined,
    module: ESEngineModule | null,
): Promise<{ handle: number; width: number; height: number }> {
    if (!isKtx2Path(staged)) {
        const decoded = await decodePixels(staged);
        return { handle: createTextureFromPixels(module, decoded, TextureContent.AtlasPage, false), ...decoded };
    }
    const bytes = new Uint8Array(await fetchBinary(staged));
    const rm = requireResourceManager();
    if (rm.createTextureFromKTX2) {
        const r = rm.createTextureFromKTX2(bytes, samplesAsSrgb());
        if (!r) throw new Error(`KTX2 transcode failed: ${staged}`);
        return r;
    }
    const transcoder = await transcoderProvider?.();
    if (!transcoder) throw new Error('KTX2 atlas page but no Basis transcoder in this realm');
    const rgba = await transcoder.transcodeToRgba(bytes);
    if (!rgba) throw new Error(`KTX2 transcode failed: ${staged}`);
    const decoded = { width: rgba.width, height: rgba.height, pixels: rgba.data };
    return { handle: createTextureFromPixels(module, decoded, TextureContent.AtlasPage, false), ...decoded };
}

export function createTextureFromPixels(
    module: ESEngineModule | null,
    result: { width: number; height: number; pixels: Uint8Array },
    content: TextureContent,
    flipY: boolean = true,
    params?: TextureParams,
    owner?: CppResourceManager,
): number {
    const rm = owner ?? requireResourceManager();
    // Format code 2 = sRGB-encoded color (linear pipeline); 1 = plain RGBA8.
    const format = samplesAsSrgb(params?.srgb) ? 2 : 1;
    // Native path: no wasm heap — the ResourceManager uploads the bytes itself.
    // The wasm embind object has no createTextureFromBytes, so web falls through
    // to the heap path below unchanged.
    if (rm.createTextureFromBytes) {
        const filter = params ? textureFilterCode(params) : undefined;
        const wrap = params?.wrapMode ? WRAP_MODE_MAP[params.wrapMode] ?? 1 : undefined;
        return rm.createTextureFromBytes(result.width, result.height, result.pixels, format, flipY, content, filter, wrap);
    }
    if (!module) {
        throw new Error('createTextureFromPixels: a wasm module is required for the heap upload path');
    }
    return withMalloc(module, result.pixels.length, ptr => {
        module.HEAPU8.set(result.pixels, ptr);

        if (params && (params.filterMode || params.wrapMode || params.mipmaps) && rm.createTextureEx) {
            const filter = textureFilterCode(params);
            const wrap = WRAP_MODE_MAP[params.wrapMode ?? 'clamp'] ?? 1;
            return rm.createTextureEx(result.width, result.height, ptr, result.pixels.length, format, flipY, filter, wrap, content);
        }
        return rm.createTexture(result.width, result.height, ptr, result.pixels.length, format, flipY, content);
    });
}

/**
 * A 2D texture array of same-size RGBA8 layers, for a `textureArray` material param (`Material.tex(handle)`).
 * Layers go up in the rows given, never flipped, and are fixed: there is no sub-rectangle update. Pass
 * `TextureContent.Retained` for an array that must survive a device loss. Returns 0 when the engine refuses it.
 */
export function createTextureArrayFromPixels(
    module: ESEngineModule | null,
    source: { width: number; height: number; layers: readonly Uint8Array[] },
    content: TextureContent,
    params?: TextureParams,
    owner?: CppResourceManager,
): number {
    const { width, height, layers } = source;
    const layerBytes = width * height * 4;
    if (layers.length === 0 || layers.some((layer) => layer.length !== layerBytes)) {
        throw new Error(`createTextureArrayFromPixels: every layer must be ${width}x${height} RGBA8 (${layerBytes} bytes)`);
    }
    const rm = owner ?? requireResourceManager();
    const format = samplesAsSrgb(params?.srgb) ? 2 : 1;
    const filter = params ? textureFilterCode(params) : -1;
    const wrap = WRAP_MODE_MAP[params?.wrapMode ?? 'clamp'] ?? 1;
    const total = layerBytes * layers.length;
    // Native path: no wasm heap, so the layers go over as one run of bytes and the host copies them.
    if (rm.createTextureArrayFromBytes) {
        const bytes = new Uint8Array(total);
        layers.forEach((layer, i) => bytes.set(layer, i * layerBytes));
        return rm.createTextureArrayFromBytes(width, height, layers.length, bytes, format, filter, wrap, content);
    }
    if (!rm.createTextureArray || !module) {
        throw new Error('createTextureArrayFromPixels: needs the wasm ResourceManager and its heap');
    }
    return withMalloc(module, total, ptr => {
        if (!ptr) return 0;
        layers.forEach((layer, i) => module.HEAPU8.set(layer, ptr + i * layerBytes));
        return rm.createTextureArray!(width, height, layers.length, ptr, total, format, filter, wrap, content);
    });
}

/**
 * Upload pixels into a sub-rectangle of an existing texture. Lets the dynamic
 * glyph atlas pack glyphs individually instead of re-uploading
 * the whole atlas. `pixels` must match the texture's format (RGBA8) and the
 * rect must lie inside the texture (the engine bounds-checks and no-ops if not).
 */
export function updateTextureSubregion(
    module: ESEngineModule | null,
    handle: number,
    x: number,
    y: number,
    width: number,
    height: number,
    pixels: Uint8Array,
    owner?: CppResourceManager,
): void {
    if (width <= 0 || height <= 0 || pixels.length === 0) return;
    const rm = owner ?? requireResourceManager();
    // Native byte path (no wasm heap); web embind lacks it and takes the heap path.
    if (rm.updateTextureSubregionFromBytes) {
        rm.updateTextureSubregionFromBytes(handle, x, y, width, height, pixels);
        return;
    }
    if (!rm.updateTextureSubregion || !module) return;
    withMalloc(module, pixels.length, ptr => {
        module.HEAPU8.set(pixels, ptr);
        rm.updateTextureSubregion(handle, x, y, width, height, ptr, pixels.length);
    });
}