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.

5.9 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { CppResourceManager, ESEngineModule } from '../wasm';
import { WasmBridge } from './WasmBridge';

export interface TextureDimensions {
    width: number;
    height: number;
}

/**
 * The C++ ResourceManager is an embind object reached via
 * `module.getResourceManager()`, not a module itself — it owns no heap or
 * onAbort. Guard its method calls with the main module as the abort authority
 * (proxying the embind instance is safe: methods are invoked with the real
 * instance as `this`, and HEAP/$$ pass straight through).
 */
class ResourceManagerBridge extends WasmBridge<CppResourceManager> {
    protected readonly label = 'resourceManager';
}

const bridge = new ResourceManagerBridge();
let rm_: CppResourceManager | null = null;
const dimsCache_ = new Map<number, TextureDimensions>();
const refills_ = new Map<number, TextureRefill>();

/** @internal Wired by the engine plugins — not part of the public API. */
export function initResourceManager(rm: CppResourceManager, module?: ESEngineModule): void {
    // Production (corePlugin) passes the main module → guarded calls. Tests pass
    // only a mock rm → kept raw (unguarded), since they don't exercise abort.
    if (module) {
        bridge.connect(rm, module);
        rm_ = bridge.module;
    } else {
        bridge.disconnect();
        rm_ = rm;
    }
    dimsCache_.clear();
    refills_.clear();
}

export function shutdownResourceManager(): void {
    bridge.disconnect();
    rm_ = null;
    dimsCache_.clear();
    refills_.clear();
}

export function getResourceManager(): CppResourceManager | null {
    return rm_;
}

export function requireResourceManager(): CppResourceManager {
    if (!rm_) {
        throw new Error('ResourceManager not initialized. Call initResourceManager() first.');
    }
    return rm_;
}

/**
 * Set the resident GPU-texture byte budget. When resident bytes exceed this,
 * the C++ ResourcePool evicts least-recently-used unreferenced textures. `0`
 * disables caching — a texture frees the moment its refcount hits zero.
 * Negative / fractional inputs are clamped to a non-negative integer.
 *
 * The engine applies `RuntimeConfig.textureCacheBudget` at startup, so scene
 * switches keep recently-used textures warm by default; call this (or set
 * `textureCacheBudget` in the build config) to size it for your game.
 *
 * This is the single game-facing surface over the C++ budget; there is no
 * parallel TS-side budget to drift from it.
 */
export function setTextureBudget(bytes: number): void {
    requireResourceManager().setTextureBudget(Math.max(0, Math.floor(bytes)));
}

/**
 * Warn once when the CPU copies the graphics device keeps to survive a GPU loss
 * ({@link ResourceStats.retainedBytes}) grow past `bytes`; 0 never warns. The
 * engine applies `RuntimeConfig.retainedBudget` at startup.
 */
export function setRetainedBudget(bytes: number): void {
    requireResourceManager().setRetainedBudget?.(Math.max(0, Math.floor(bytes)));
}

/** GPU resource counts + texture residency figures. See {@link getResourceStats}. */
export interface ResourceStats {
    shaderCount: number;
    textureCount: number;
    vertexBufferCount: number;
    indexBufferCount: number;
    cacheHits: number;
    cacheMisses: number;
    /** Resident texture bytes (RGBA8 estimate) — held + evictable entries. */
    textureBytes: number;
    /** The texture pool's resident-byte budget (0 = eviction off). */
    textureBudget: number;
    /** Cached refCount==0 textures awaiting revive or eviction. */
    textureEvictableCount: number;
    /** CPU copies the graphics device keeps so content survives a device loss. */
    retainedBytes: number;
}

/**
 * Snapshot of GPU resource usage from the C++ ResourceManager — the
 * observability side of the texture budget: watch `textureBytes` against
 * `textureBudget` and `textureEvictableCount` to size the warm cache.
 * Returns null when the resource manager isn't initialized (or a test mock
 * doesn't model stats).
 */
export function getResourceStats(): ResourceStats | null {
    if (!rm_ || typeof rm_.getResourceStats !== 'function') return null;
    return rm_.getResourceStats();
}

/**
 * Free every evictable cached texture now (memory pressure). Held textures
 * and the budget are untouched; the warm cache refills as textures are
 * released afterwards. The engine calls this on OS memory warnings — call it
 * yourself before a known memory spike (e.g. a huge one-off allocation).
 * Returns the number of textures freed (0 when uninitialized / mocked).
 */
export function trimTextureCache(): number {
    if (!rm_ || typeof rm_.trimTextureCache !== 'function') return 0;
    return rm_.trimTextureCache();
}

/** Puts a texture's content back after a device loss; true once its handle holds it again. */
export type TextureRefill = () => boolean | Promise<boolean>;

/**
 * @internal Names who refills `handle` when the device owes its content — for a
 * texture no asset path can load again. Handles belong to one resource manager,
 * so the refills go with it.
 */
export function provideTextureContent(handle: number, refill: TextureRefill): void {
    refills_.set(handle, refill);
}

/** @internal The texture is being released; nothing will be owed for it. */
export function withdrawTextureContent(handle: number): void {
    refills_.delete(handle);
}

/** @internal Who refills `handle`, if anyone said. */
export function textureRefill(handle: number): TextureRefill | undefined {
    return refills_.get(handle);
}

export function evictTextureDimensions(handle: number): void {
    dimsCache_.delete(handle);
}

export function getTextureDimensions(handle: number): TextureDimensions | null {
    if (!handle) return null;
    const cached = dimsCache_.get(handle);
    if (cached) return cached;
    if (!rm_) return null;
    const dims = rm_.getTextureDimensions(handle);
    if (dims) dimsCache_.set(handle, dims);
    return dims;
}