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
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 };
}
}