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.

31.5 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { AssetLoader, LoadContext, TextureResult } from '../AssetLoader';
import { linearColorSpace, samplesAsSrgb } from '../../ecs/env';
import { platformCreateImage } from '../../platform/base';
import type { PlatformImage } from '../../platform/types';
import { decodeImageBitmap, readImagePixels, shrinkBitmap } from '../imageDecode';
import { requireResourceManager } from '../../wasm/resourceManager';
import { TextureContent, type ESEngineModule } from '../../wasm';
import { withMalloc } from '../../wasm/wasmScratch';
import {
    isKtx2, isKtx2Path, loadCompressedTexture, levelsFrom, chooseEngineTargetFormat, engineFormatCode,
    compressedUploadDecision, detectCompressedTextureSupport, glInternalFormat,
    supportedTargetFormats, hostUploadDecision, RAW_PAYLOAD_UPLOAD,
    CompressedTextureFormat,
    type BasisTranscoder, type TextureUploadDecision,
} from '../compressed';
import { TextureFormatLog, type TextureFormatReport } from '../textureFormatReport';
import {
    uploadBoundTextureImage, applyBoundTextureSampling, handOverNewTexture, findWebGL2Context,
} from '../glTextureUpload';
import { createTextureFromPixels, type TextureParams } from '../../runtime/runtimeAssets';
import { isTextureRecipePath, renderTextureRecipe } from '../textureRecipe';

/**
 * Decode a texture ref to raw RGBA pixels on the current platform. Set by a
 * caller that fetches through a channel `TextureLoader`'s URL-based `<img>`
 * decode can't reach — e.g. the runtime scene loader, whose asset providers
 * pre-decode from `estella://` / WeChat package files / inlined data-URLs. When
 * set, non-KTX2 textures upload through this instead of `loadImage(url)`.
 */
export type TexturePixelDecoder = (
    path: string,
    flip: boolean,
    maxEdge?: number,
) => Promise<{ width: number; height: number; pixels: Uint8Array; sourceWidth?: number; sourceHeight?: number }>;

/**
 * Where a host keeps its textures GPU-compressed: the KTX2 for `path`, `'pending'`
 * while it is being made, or null for one that is not. A pending texture is drawn
 * from a preview no larger than {@link TEXTURE_PREVIEW_EDGE}, so art still being
 * compressed is not held in video memory in full.
 */
export type TextureCompressedSource = (path: string) => Promise<Uint8Array | 'pending' | null>;

/** The longest edge a texture waiting for its compressed form is drawn at. */
export const TEXTURE_PREVIEW_EDGE = 1024;
let nextImageRevision = Date.now();

/**
 * Texture import-time settings. Applied when the GL texture is first uploaded,
 * because WebGL sampler state lives on the texture object — the only way to
 * change filter/wrap after the fact is to hold the GL texture id and call
 * `texParameteri`. See {@link TextureLoader#importSettingsResolver}.
 */
export interface TextureImportSettings {
    readonly filter?: 'linear' | 'nearest';
    readonly wrap?: 'repeat' | 'clamp' | 'mirror';
    readonly mipmaps?: boolean;
    /** Whether the image stores sRGB-encoded color (default). Authored-linear
     *  data (normal maps, masks) sets false so the linear pipeline skips the
     *  hardware EOTF. Ignored in gamma mode. */
    readonly srgb?: boolean;
    /**
     * 9-slice border in texture pixels. A property of the IMAGE (where its
     * corners end), not of any one entity — so it is authored once at import
     * and every `UIVisual` set to NineSlice inherits it. Applied to the texture
     * handle's metadata at load; a UIVisual may still override per entity.
     */
    readonly sliceBorder?: { readonly left: number; readonly right: number; readonly top: number; readonly bottom: number };
}

export type TextureImportSettingsResolver = (ref: string) => TextureImportSettings | undefined;

/** An asset's settings for the engine's pixel upload: mipmapped unless it says not, as the WebGL upload is. */
function pixelParams(settings: TextureImportSettings | undefined): TextureParams {
    return { filterMode: settings?.filter, wrapMode: settings?.wrap, srgb: settings?.srgb, mipmaps: settings?.mipmaps ?? true };
}

/**
 * Canonical residency key for a texture: the resolved load path plus the
 * flip-orientation flag (flipped and raw uploads are genuinely different GPU
 * objects). One string serves as both the SDK's AsyncCache key and the C++
 * ResourcePool path identity, so a texture whose last reference was released
 * can be revived by `acquireTextureByPath` under the exact same key the next
 * `loadTexture` looks up.
 */
export function textureResidencyKey(path: string, flip: boolean): string {
    return `${path}:${flip ? 'f' : 'n'}`;
}

const isPng = (b: Uint8Array): boolean => b.byteLength > 8 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47;

export class TextureLoader implements AssetLoader<TextureResult> {
    private readonly imageRevisions_ = new Map<string, number>();

    /** End the browser image-cache identity when an asset's bytes change. */
    invalidate(path: string): boolean {
        this.imageRevisions_.set(path, ++nextImageRevision);
        return false;
    }
    readonly type = 'texture';
    readonly extensions = ['.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp', '.ktx2'];

    private module_: ESEngineModule | null;
    /**
     * Basis transcoder for KTX2 assets. Either injected directly via
     * {@link setTranscoder} (tests / embedded realms) or acquired lazily on the
     * first KTX2 load via {@link setTranscoderProvider} — AssetPlugin wires the
     * provider to `app.sideModules.acquire('basis')`, so the basis wasm is only
     * fetched when a project actually uses compressed textures (self-gating, like
     * physics / spine).
     */
    private transcoder_: BasisTranscoder | null = null;
    private transcoderProvider_: (() => Promise<BasisTranscoder | null>) | null = null;
    private transcoderPending_: Promise<BasisTranscoder | null> | null = null;
    setTranscoder(t: BasisTranscoder | null): void { this.transcoder_ = t; }
    setTranscoderProvider(p: (() => Promise<BasisTranscoder | null>) | null): void {
        this.transcoderProvider_ = p;
    }

    /** The transcoder, acquiring it once on demand. Concurrent KTX2 loads share
     *  the in-flight acquisition so the basis module loads exactly once. */
    private async ensureTranscoder_(): Promise<BasisTranscoder | null> {
        if (this.transcoder_) return this.transcoder_;
        if (!this.transcoderProvider_) return null;
        if (!this.transcoderPending_) this.transcoderPending_ = this.transcoderProvider_();
        this.transcoder_ = await this.transcoderPending_;
        return this.transcoder_;
    }
    /**
     * What every texture this loader uploaded became, and the device capability
     * that constrained it. Owned by the loader, so it is scoped to the realm that
     * took the decisions and cannot outlive the textures it describes.
     */
    private readonly formats_ = new TextureFormatLog();
    /** Where each texture this loader decoded from a file came from: what a resize decodes again. */
    private readonly sources_ = new Map<number, { path: string; flip: boolean; settings?: TextureImportSettings; fullWidth: number; fullHeight: number }>();
    private pendingStartEdge_ = 0;
    /** How many loads began smaller than their file (texture streaming), and how many were asked to: a report, and what a check reads. */
    startedSmall = 0;
    askedSmall = 0;
    /** The same sources by residency key, kept past a release: a texture revived from the warm cache is the same file at the size it was left at. */
    private readonly sourcesByKey_ = new Map<string, { path: string; flip: boolean; settings?: TextureImportSettings; fullWidth: number; fullHeight: number }>();
    /** The decision the in-flight upload came to. Set by the one entry point that
     *  chooses a path (decodeAndUpload_) and read by the one that records. */
    private lastDecision_: TextureUploadDecision = RAW_PAYLOAD_UPLOAD;
    private deviceFormats_: CompressedTextureFormat[] | null = null;

    /**
     * Optional hook that returns per-asset import settings. Invoked at
     * load-time with the ORIGINAL ref (pre-resolution), so callers can key
     * off `@uuid:...` directly. Undefined-result falls back to defaults.
     */
    importSettingsResolver: TextureImportSettingsResolver | null = null;

    constructor(module: ESEngineModule | null) {
        this.module_ = module;
    }

    /** Currently-effective settings for the in-flight load. Set by Assets.ts
     *  before delegating to load(); cleared when done. Avoids threading a new
     *  param through the AssetLoader interface, which is also implemented by
     *  non-texture loaders that don't need it. */
    private pendingSettings_: TextureImportSettings | undefined;
    setPendingSettings(s: TextureImportSettings | undefined): void { this.pendingSettings_ = s; }

    /** Platform pixel decoder (see {@link TexturePixelDecoder}). Null ⇒ the
     *  default URL `<img>` decode path (editor / app Assets, unchanged). */
    private pixelDecoder_: TexturePixelDecoder | null = null;
    setPixelDecoder(decoder: TexturePixelDecoder | null): void { this.pixelDecoder_ = decoder; }
    get pixelDecoder(): TexturePixelDecoder | null { return this.pixelDecoder_; }

    /** Compressed-texture source (see {@link TextureCompressedSource}). */
    private compressedSource_: TextureCompressedSource | null = null;
    setCompressedSource(source: TextureCompressedSource | null): void { this.compressedSource_ = source; }

    async load(path: string, ctx: LoadContext): Promise<TextureResult> {
        const settings = this.pendingSettings_;
        this.pendingSettings_ = undefined;
        return this.loadWithFlip(path, ctx, true, settings);
    }

    async loadRaw(path: string, ctx: LoadContext): Promise<TextureResult> {
        const settings = this.pendingSettings_;
        this.pendingSettings_ = undefined;
        return this.loadWithFlip(path, ctx, false, settings);
    }

    async loadFromPixels(
        width: number, height: number, pixels: Uint8Array, flipY: boolean, content: TextureContent,
    ): Promise<TextureResult> {
        const rm = requireResourceManager();
        // A collage of colour images, so colour: the engine takes the code as said.
        const format = samplesAsSrgb(true) ? 2 : 1;
        // Native (no wasm heap): upload the bytes directly. Web embind lacks this
        // method, so it takes the heap path below unchanged.
        if (rm.createTextureFromBytes) {
            const handle = rm.createTextureFromBytes(width, height, pixels, format, flipY, content);
            return { handle, width, height };
        }
        if (!this.module_) {
            throw new Error('TextureLoader.loadFromPixels: no wasm module and no native byte-upload path');
        }
        const module = this.module_;
        const handle = withMalloc(module, pixels.length, ptr => {
            module.HEAPU8.set(pixels, ptr);
            return rm.createTexture(width, height, ptr, pixels.length, format, flipY, content);
        });
        return { handle, width, height };
    }

    unload(asset: TextureResult): void {
        this.sources_.delete(asset.handle);
        const rm = requireResourceManager();
        rm.releaseTexture(asset.handle);
    }

    /**
     * Loads the bytes onto the GPU WITHOUT claiming the path — what a re-upload
     * after a device loss wants, since the identity belongs to the handle being
     * recovered. Claiming it leaves the pool holding two records, and the loser
     * is swept up by the next loss with nobody able to re-upload it.
     */
    async loadDetached(
        path: string, ctx: LoadContext, flip: boolean, settings?: TextureImportSettings,
    ): Promise<TextureResult> {
        return this.decodeAndUpload_(path, ctx, flip, settings);
    }

    /**
     * Decode the texture behind @p handle again, no larger than @p maxEdge texels on a side (0 is its full size), and move the new
     * pixels behind the handle: everything that holds the handle — a material, a renderer, a batch key — sees the new size at once.
     * The texture streamer's one move. False for a handle this loader did not decode from a file, or one the host cannot re-point.
     */
    async resize(handle: number, maxEdge: number, ctx: LoadContext): Promise<{ width: number; height: number } | null> {
        const source = this.sources_.get(handle);
        const rm = requireResourceManager();
        if (!source || !rm.adoptTextureContent) return null;
        const fresh = await this.decodeAndUpload_(source.path, ctx, source.flip, source.settings, maxEdge);
        const moved = rm.adoptTextureContent(handle, fresh.handle);
        rm.releaseTexture(fresh.handle);
        return moved ? { width: fresh.width, height: fresh.height } : null;
    }

    /** Whether @p handle was decoded from a file by this loader, so it can be decoded again at another size. */
    resizable(handle: number): boolean { return this.sources_.has(handle); }

    /** The size of the file behind @p handle, whatever size it is held at; null for one this loader did not decode from a file. */
    fullSize(handle: number): { width: number; height: number } | null {
        const s = this.sources_.get(handle);
        return s ? { width: s.fullWidth, height: s.fullHeight } : null;
    }

    /** Decode the next load no larger than @p edge on a side (texture streaming's start), where the file's own size can still be known. */
    setPendingStartEdge(edge: number): void { this.pendingStartEdge_ = Math.max(0, edge); }

    /** A texture the warm cache gave back under @p key is the one this loader decoded under it: resizable again. */
    adoptRevived(handle: number, key: string): void {
        const source = this.sourcesByKey_.get(key);
        if (source) this.sources_.set(handle, source);
    }

    private async loadWithFlip(
        path: string, ctx: LoadContext, flip: boolean, settings?: TextureImportSettings,
    ): Promise<TextureResult> {
        const start = this.pendingStartEdge_;
        this.pendingStartEdge_ = 0;
        if (start > 0) this.askedSmall++;
        const result = await this.decodeAndUpload_(path, ctx, flip, settings, start);
        const source = { path, flip, settings, fullWidth: result.fullWidth ?? result.width, fullHeight: result.fullHeight ?? result.height };
        this.sources_.set(result.handle, source);
        if (result.fullWidth !== undefined) this.startedSmall++;
        this.sourcesByKey_.set(textureResidencyKey(path, flip), source);
        // Recorded HERE, once, for every path into the loader — the compressed
        // paths, the pixel decoder and the <img> upload alike. A record kept only
        // where a fallback happens cannot say that everything else was fine.
        this.formats_.record(textureResidencyKey(path, flip), this.lastDecision_);
        // Path identity in the C++ pool: after the last release the texture can
        // survive as an evictable cache entry (budget permitting) and the next
        // load revives it by this key instead of re-fetching + re-decoding.
        // Optional-chained: minimal test mocks may not model the pool surface.
        requireResourceManager().registerTextureWithPath?.(
            result.handle, textureResidencyKey(path, flip));
        return result;
    }

    private async decodeAndUpload_(
        path: string, ctx: LoadContext, flip: boolean, settings?: TextureImportSettings, maxEdge = 0,
    ): Promise<TextureResult> {
        // A build that shipped a small copy beside the file (texture streaming) is read from the copy whenever the size asked for
        // fits in it: the file itself is downloaded only once a view needs more than the copy holds.
        const tail = maxEdge > 0 ? ctx.catalog.getStreamTail?.(path) ?? null : null;
        if (tail && maxEdge <= Math.max(tail.width, tail.height)) {
            const made = await this.decodeFile_(path, tail.path, ctx, flip, settings, maxEdge, true);
            return { ...made, fullWidth: tail.fullWidth, fullHeight: tail.fullHeight };
        }
        return this.decodeFile_(path, ctx.catalog?.getBuildPath(path) ?? path, ctx, flip, settings, maxEdge, false);
    }

    /** Decode @p path (whose bytes are at @p buildPath; @p copy when that is its small copy) no larger than @p maxEdge, and upload it. */
    private async decodeFile_(
        path: string, buildPath: string, ctx: LoadContext, flip: boolean, settings: TextureImportSettings | undefined, maxEdge: number,
        copy: boolean,
    ): Promise<TextureResult> {
        this.lastDecision_ = RAW_PAYLOAD_UPLOAD;
        // A recipe is drawn here, from its source, and is then a texture like any decoded one.
        if (isTextureRecipePath(buildPath)) {
            const drawn = await renderTextureRecipe(path, (p) => ctx.backend.fetchBinary(p === path ? buildPath : ctx.catalog?.getBuildPath(p) ?? p));
            const handle = createTextureFromPixels(this.module_, drawn, TextureContent.Asset, flip, pixelParams(settings));
            return { handle, width: drawn.width, height: drawn.height };
        }
        if (isKtx2Path(buildPath)) {
            const buf = await ctx.backend.fetchBinary(buildPath);
            return this.uploadKtx2_(path, new Uint8Array(buf), settings, maxEdge);
        }
        let preview = false;
        if (!copy && this.compressedSource_) {
            const compressed = await this.compressedSource_(path);
            // The source may answer with the image a build ships rather than a KTX2 —
            // a PNG resized or with its clear texels' colour filled in — and it is drawn
            // the way any image is, so the editor shows the pixels the package holds.
            if (compressed instanceof Uint8Array && isPng(compressed)) return this.uploadImageBytes_(compressed, flip, settings, maxEdge);
            if (compressed instanceof Uint8Array) return this.uploadKtx2_(path, compressed, settings, maxEdge);
            preview = compressed === 'pending';
        }
        // The smaller of a preview's edge and the one asked for: a texture held small is decoded small.
        const edge = preview ? (maxEdge > 0 ? Math.min(maxEdge, TEXTURE_PREVIEW_EDGE) : TEXTURE_PREVIEW_EDGE) : maxEdge;
        // A platform pixel decoder (runtime scene loader) pre-decodes to RGBA and
        // uploads through the shared createTexture path — the same code the old
        // runtimeLoader.loadTextures used — instead of a URL-based <img>.
        if (this.pixelDecoder_) {
            // A decoder resolves a logical path itself; a copy is named by where it is.
            const result = await this.pixelDecoder_(copy ? buildPath : path, flip, edge);
            const handle = createTextureFromPixels(this.module_, result, TextureContent.Asset, flip, pixelParams(settings));
            // A decoder that made it smaller says what it was made from; one that could not (a host decoding whole) answers with the
            // file's own size, and the texture is simply whole.
            return result.sourceWidth !== undefined && result.sourceHeight !== undefined
                ? { handle, width: result.width, height: result.height, fullWidth: result.sourceWidth, fullHeight: result.sourceHeight }
                : { handle, width: result.width, height: result.height };
        }
        const url = ctx.backend.resolveUrl(buildPath);
        const full = { width: 0, height: 0 };
        const img = await this.loadImage(url, flip, edge, copy ? undefined : this.imageRevisions_.get(path), full);
        const made = this.createTextureFromImage(img, flip, settings);
        return full.width > made.width || full.height > made.height ? { ...made, fullWidth: full.width, fullHeight: full.height } : made;
    }

    /** An encoded image in memory, through the same image path a URL takes. */
    private async uploadImageBytes_(
        bytes: Uint8Array, flip: boolean, settings?: TextureImportSettings, maxEdge = 0,
    ): Promise<TextureResult> {
        const url = URL.createObjectURL(new Blob([bytes as Uint8Array<ArrayBuffer>], { type: 'image/png' }));
        try {
            const full = { width: 0, height: 0 };
            const img = await this.loadImage(url, flip, maxEdge, undefined, full);
            const made = this.createTextureFromImage(img, flip, settings);
            return full.width > made.width || full.height > made.height ? { ...made, fullWidth: full.width, fullHeight: full.height } : made;
        } finally {
            URL.revokeObjectURL(url);
        }
    }

    /**
     * Upload a KTX2 (Basis) compressed texture: transcode to a device-supported GPU
     * format (or RGBA8 fallback), and upload. KTX2 carries its own orientation, so
     * the `flip` flag does not apply.
     */
    private async uploadKtx2_(
        path: string, bytes: Uint8Array, settings?: TextureImportSettings, maxEdge = 0,
    ): Promise<TextureResult> {
        const made = await this.uploadKtx2Levels_(path, bytes, settings, maxEdge);
        // The header's pixelWidth and pixelHeight (bytes 20 and 24): the file's size, whatever level the upload started at.
        if (bytes.byteLength >= 28) {
            const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
            const fullWidth = view.getUint32(20, true), fullHeight = view.getUint32(24, true);
            if (fullWidth > made.width || fullHeight > made.height) return { ...made, fullWidth, fullHeight };
        }
        return made;
    }

    private async uploadKtx2Levels_(
        path: string, bytes: Uint8Array, settings?: TextureImportSettings, maxEdge = 0,
    ): Promise<TextureResult> {
        if (!isKtx2(bytes)) throw new Error(`TextureLoader: ${path} is not a KTX2 file`);
        // Native (embedded Dawn): the ResourceManager transcodes the KTX2 with the
        // host's basis library and uploads the compressed blocks — no WebGL2, no
        // wasm transcoder. sRGB follows the texture's settings, as on every path.
        const rm = requireResourceManager();
        if (rm.createTextureFromKTX2) {
            const r = rm.createTextureFromKTX2(bytes, samplesAsSrgb(settings?.srgb));
            if (!r) throw new Error(`TextureLoader: KTX2 transcode failed for ${path}`);
            // A host that reports no format says nothing rather than claiming
            // success: -1 with no block refusal reads as "this device offered
            // none", the honest reading of an absent answer.
            this.lastDecision_ = hostUploadDecision(r.format ?? -1, r.blockRefused ?? false);
            return { handle: r.handle, width: r.width, height: r.height };
        }
        const transcoder = await this.ensureTranscoder_();
        if (!transcoder) {
            throw new Error('TextureLoader: no Basis transcoder available (basis side module missing — KTX2 assets need it)');
        }
        const gl = this.getWebGL2Context();
        if (!gl) {
            // No GL context (the WebGPU backend): ask the ENGINE which format it
            // samples and upload through it. Sampler state is what the GL path
            // below still has and this one does not — here it takes the defaults.
            return this.loadCompressedViaEngine(path, transcoder, bytes, samplesAsSrgb(settings?.srgb), maxEdge);
        }
        // A WebGL2 context implies a wasm module (native has neither, and threw
        // above on the missing gl); the KTX2 path is web-only.
        const r = await loadCompressedTexture(gl, this.module_!, transcoder, bytes,
            { ...settings, srgb: samplesAsSrgb(settings?.srgb), maxEdge });
        this.lastDecision_ = r.decision;
        return { handle: r.handle, width: r.width, height: r.height };
    }

    /**
     * KTX2 through the engine's own upload, for a backend with no GL context.
     * Falls back to an RGBA decode when no compressed format is available or the
     * transcode to it fails — the same bargain the GL path makes.
     */
    private async loadCompressedViaEngine(
        path: string, transcoder: BasisTranscoder, bytes: Uint8Array, srgb: boolean, maxEdge = 0,
    ): Promise<TextureResult> {
        const rm = requireResourceManager();
        const module = this.module_;
        if (module && rm.supportsCompressedFormat && rm.createCompressedTexture) {
            const supports = rm.supportsCompressedFormat.bind(rm);
            const target = chooseEngineTargetFormat((code) => supports(code), srgb);
            const whole = target ? await transcoder.transcode(bytes, target) : null;
            const t = whole ? levelsFrom(whole, maxEdge) : null;
            this.lastDecision_ = compressedUploadDecision(target, t !== null);
            if (target && t) {
                const code = engineFormatCode(target, srgb);
                // Level 0 first, packed, as the device unpacks them, every level of the chain: the device copies each as whole blocks
                // (its physical size), so a level whose side is not a multiple of four is uploaded too. Stopping at the first such level
                // left a 1240x1268 hair atlas with level 0 alone, sampled unfiltered at any distance.
                const levels = t.levels ?? [t];
                const size = levels.reduce((n, l) => n + l.data.length, 0);
                const handle = withMalloc(module, size, (ptr) => {
                    let at = ptr;
                    for (const l of levels) { module.HEAPU8.set(l.data, at); at += l.data.length; }
                    return rm.createCompressedTexture!(t.width, t.height, code, ptr, size, levels.length,
                        TextureContent.Asset);
                });
                if (handle) return { handle, width: t.width, height: t.height };
                // The upload itself failed after a good transcode — the payload
                // still becomes RGBA, and saying "compressed" here would be a
                // record of what was intended rather than what happened.
                this.lastDecision_ = compressedUploadDecision(target, false);
            }
        } else {
            this.lastDecision_ = compressedUploadDecision(null, false);
        }
        const decoded = await transcoder.transcodeToRgba(bytes);
        if (!decoded) throw new Error(`TextureLoader: KTX2 decode failed for ${path}`);
        const rgba = levelsFrom(decoded, maxEdge);
        return this.loadFromPixels(rgba.width, rgba.height, rgba.data, false, TextureContent.Asset);
    }

    /**
     * Decode `src` into a GPU-uploadable source. When `createImageBitmap` is
     * available we bake the vertical orientation into the bitmap here via
     * `imageOrientation`, NOT later via `UNPACK_FLIP_Y_WEBGL`: Chromium/ANGLE
     * silently ignore that pixel-store flag for `ImageBitmap` sources, so relying
     * on it uploads every texture upside-down. The raw `<img>` fallback keeps the
     * flag (it works for element/pixel sources) — see {@link createTextureFromImage}.
     */
    private loadImage(src: string, flip: boolean, maxEdge = 0, revision?: number, full?: { width: number; height: number }): Promise<PlatformImage | ImageBitmap> {
        return new Promise((resolve, reject) => {
            const img = platformCreateImage();
            img.crossOrigin = 'anonymous';
            img.onload = async () => {
                if (full) { full.width = img.width; full.height = img.height; }
                if (typeof createImageBitmap !== 'undefined') {
                    try {
                        resolve(await shrinkBitmap(await decodeImageBitmap(img, flip), maxEdge));
                        return;
                    } catch {
                        // fallback
                    }
                }
                resolve(img);
            };
            img.onerror = () => reject(new Error(`Failed to load image: ${src}`));
            if (revision && typeof HTMLImageElement !== 'undefined' && img instanceof HTMLImageElement
                && !src.startsWith('data:') && !src.startsWith('blob:')) {
                const url = new URL(src, document.baseURI);
                url.searchParams.set('_esTextureRevision', String(revision));
                img.src = url.href;
            } else {
                img.src = src;
            }
        });
    }

    private createTextureFromImage(
        img: PlatformImage | ImageBitmap, flip: boolean, settings?: TextureImportSettings,
    ): TextureResult {
        const { width, height } = img;
        const gl = this.getWebGL2Context();

        // A bitmap is already oriented by loadImage (imageOrientation); flipping it
        // again at upload would double-flip it. Only raw <img>/pixel sources need
        // the UNPACK_FLIP_Y_WEBGL flip.
        const uploadFlip = (typeof ImageBitmap !== 'undefined' && img instanceof ImageBitmap)
            ? false : flip;

        if (gl) {
            return this.createTextureWebGL2(gl, img, width, height, uploadFlip, settings);
        }
        return this.createTextureFallback(img, width, height, uploadFlip, settings);
    }

    private getWebGL2Context(): WebGL2RenderingContext | null {
        return findWebGL2Context(this.module_?.GL);
    }

    /**
     * Which compressed formats this device samples, best first.
     *
     * The INPUT to every upload decision, and the half a realm answers without
     * loading one. Null when nothing could be asked — an empty list would read as
     * a capability. Cached, since `getExtension` also ENABLES.
     */
    deviceFormats(): CompressedTextureFormat[] | null {
        if (this.deviceFormats_) return this.deviceFormats_;
        const srgb = linearColorSpace();
        const gl = this.getWebGL2Context();
        if (gl) {
            const support = detectCompressedTextureSupport(gl);
            return (this.deviceFormats_ =
                supportedTargetFormats((f) => glInternalFormat(support, f, srgb) !== null));
        }
        const rm = requireResourceManager();
        if (rm.supportsCompressedFormat) {
            const supports = rm.supportsCompressedFormat.bind(rm);
            return (this.deviceFormats_ =
                supportedTargetFormats((f) => supports(engineFormatCode(f, srgb))));
        }
        return null;
    }

    /** What the textures this loader uploaded became, and on what device. */
    formatReport(): TextureFormatReport {
        const formats = this.deviceFormats();
        return this.formats_.report(formats ?? [], formats !== null);
    }

    private createTextureWebGL2(
        gl: WebGL2RenderingContext,
        img: PlatformImage | ImageBitmap,
        width: number, height: number, flip: boolean,
        settings?: TextureImportSettings,
    ): TextureResult {
        // This path runs only with a live WebGL2 context, which implies a module.
        const handle = handOverNewTexture(this.module_!, gl, (g) => {
            uploadBoundTextureImage(g, img, flip, settings?.srgb);
            applyBoundTextureSampling(g, settings);
        }, { width, height, content: TextureContent.Asset });
        return { handle, width, height };
    }

    private createTextureFallback(
        img: PlatformImage | ImageBitmap,
        width: number, height: number, flip: boolean,
        settings?: TextureImportSettings,
    ): TextureResult {
        // The 2D-canvas fallback is web-only: it decodes through an offscreen
        // canvas + wasm heap upload. Native never reaches it — it sets a
        // pixelDecoder, so decodeAndUpload_ takes the createTextureFromPixels
        // (byte) path before this — so require the module rather than pretend.
        if (!this.module_) {
            throw new Error('TextureLoader: 2D-canvas fallback needs a wasm module (native uses the pixel-decode path)');
        }
        const { pixels } = readImagePixels(img);
        const handle = createTextureFromPixels(this.module_, { width, height, pixels }, TextureContent.Asset, flip,
            pixelParams(settings));
        return { handle, width, height };
    }
}