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.

refactor(sdk): one image-decode path for every texture provider

esengine549e4e17aab8
diff --git a/desktop/src/engine/spineLoad.ts b/desktop/src/engine/spineLoad.ts
index 139df25c3..4722ddd4f 100644
--- a/desktop/src/engine/spineLoad.ts
+++ b/desktop/src/engine/spineLoad.ts
@@ -2,12 +2,12 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { SpinePlugin, loadSpineSceneEntities } from 'esengine/spine';
import type { RuntimeAssetProvider } from 'esengine/spine';
-import type { App, SceneData } from 'esengine';
+import { decodeImagePixels, type App, type SceneData } from 'esengine';
/**
* Fetch-backed asset provider for spine in the editor: skeleton/atlas come over
- * fetch as text/bytes; the atlas PNG is decoded to RGBA via createImageBitmap →
- * canvas → getImageData (the same path the play realm uses — robust across the
+ * fetch as text/bytes; the atlas PNG is decoded to RGBA via the shared
+ * `decodeImagePixels` (the same path the play realm uses — robust across the
* editor's http/app:// origins). `toUrl` maps an asset ref to a fetchable URL.
*/
class EditorSpineProvider implements RuntimeAssetProvider {
@@ -32,19 +32,7 @@ class EditorSpineProvider implements RuntimeAssetProvider {
async loadPixels(ref: string): Promise<{ width: number; height: number; pixels: Uint8Array }> {
const r = await fetch(this.toUrl(ref));
if (!r.ok) throw new Error(`spine texture ${r.status}: ${ref}`);
- const bitmap = await createImageBitmap(await r.blob(), {
- premultiplyAlpha: 'none',
- colorSpaceConversion: 'none',
- });
- const canvas = document.createElement('canvas');
- canvas.width = bitmap.width;
- canvas.height = bitmap.height;
- const ctx = canvas.getContext('2d');
- if (!ctx) throw new Error('2d context unavailable for spine texture decode');
- ctx.drawImage(bitmap, 0, 0);
- bitmap.close?.();
- const data = ctx.getImageData(0, 0, canvas.width, canvas.height);
- return { width: canvas.width, height: canvas.height, pixels: new Uint8Array(data.data.buffer) };
+ return decodeImagePixels(await r.blob());
}
}
diff --git a/sdk/src/asset/imageDecode.ts b/sdk/src/asset/imageDecode.ts
new file mode 100644
index 000000000..5a8af609e
--- /dev/null
+++ b/sdk/src/asset/imageDecode.ts
@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file imageDecode.ts
+ * @brief The single image-decode path for every texture provider (editor,
+ * play realm, preview, spine). Routing all of them through one module
+ * keeps premultiply / colorspace / orientation identical, so the
+ * edit/play/ship paths can't drift — that drift is the texture-flip
+ * class of bug. Vertical orientation is baked via `imageOrientation`,
+ * NEVER `UNPACK_FLIP_Y_WEBGL`, which Chromium/ANGLE silently ignore for
+ * `ImageBitmap` sources (uploads every texture upside-down otherwise).
+ */
+import { platformCreateCanvas } from '../platform';
+
+/**
+ * Canonical `createImageBitmap` options. premultiply + colorspace conversion are
+ * OFF so the engine owns blending and color (matching the C++ upload); `flip`
+ * bakes a vertical flip into the bitmap so callers upload it as-is.
+ */
+export function imageBitmapOptions(flip: boolean): ImageBitmapOptions {
+ return {
+ premultiplyAlpha: 'none',
+ colorSpaceConversion: 'none',
+ imageOrientation: flip ? 'flipY' : 'from-image',
+ };
+}
+
+/**
+ * Decode a source into a GL-oriented `ImageBitmap` for direct `texImage2D` upload
+ * (the editor/web TextureLoader). With `flip`, the result samples file-top at v=1;
+ * upload it with `UNPACK_FLIP_Y_WEBGL` off (the orientation is already baked).
+ */
+export function decodeImageBitmap(src: ImageBitmapSource, flip: boolean): Promise<ImageBitmap> {
+ return createImageBitmap(src, imageBitmapOptions(flip));
+}
+
+export interface DecodedPixels {
+ width: number;
+ height: number;
+ pixels: Uint8Array;
+}
+
+/**
+ * Decode a source into a top-first RGBA pixel buffer for the C++ `createTexture`
+ * upload path (play realm, preview, spine). Orientation stays top-first here; the
+ * consumer chooses the final convention via `createTextureFromPixels(flipY)` —
+ * v=1=top for general textures, v=0=top for spine / bitmap fonts.
+ */
+export async function decodeImagePixels(src: ImageBitmapSource): Promise<DecodedPixels> {
+ const bitmap = await decodeImageBitmap(src, false);
+ try {
+ const canvas = platformCreateCanvas(bitmap.width, bitmap.height);
+ canvas.width = bitmap.width;
+ canvas.height = bitmap.height;
+ const ctx = canvas.getContext('2d', { willReadFrequently: true }) as
+ | CanvasRenderingContext2D
+ | OffscreenCanvasRenderingContext2D
+ | null;
+ if (!ctx) throw new Error('imageDecode: 2D context unavailable for pixel decode');
+ ctx.drawImage(bitmap as CanvasImageSource, 0, 0);
+ const data = ctx.getImageData(0, 0, bitmap.width, bitmap.height);
+ return { width: bitmap.width, height: bitmap.height, pixels: new Uint8Array(data.data.buffer) };
+ } finally {
+ bitmap.close?.();
+ }
+}
diff --git a/sdk/src/asset/index.ts b/sdk/src/asset/index.ts
index 86010f305..9e101fbf9 100644
--- a/sdk/src/asset/index.ts
+++ b/sdk/src/asset/index.ts
@@ -8,6 +8,7 @@ export {
} from './AddressableManifest';
export { AsyncCache } from './AsyncCache';
export { Assets, AssetPlugin, assetPlugin, type AssetsData } from './AssetPlugin';
+export { decodeImageBitmap, decodeImagePixels, imageBitmapOptions, type DecodedPixels } from './imageDecode';
export { MaterialLoader, type LoadedMaterial, type ShaderLoader } from './MaterialLoader';
export { AssetRefCounter, type AssetRefInfo } from './AssetRefCounter';
diff --git a/sdk/src/asset/loaders/TextureLoader.ts b/sdk/src/asset/loaders/TextureLoader.ts
index 3c4c0fc07..e01498d95 100644
--- a/sdk/src/asset/loaders/TextureLoader.ts
+++ b/sdk/src/asset/loaders/TextureLoader.ts
@@ -2,6 +2,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { AssetLoader, LoadContext, TextureResult } from '../AssetLoader';
import { platformCreateCanvas, platformCreateImage } from '../../platform';
+import { decodeImageBitmap } from '../imageDecode';
import { requireResourceManager } from '../../resourceManager';
import type { ESEngineModule } from '../../wasm';
import { withMalloc } from '../../wasmScratch';
@@ -136,12 +137,7 @@ export class TextureLoader implements AssetLoader<TextureResult> {
img.onload = async () => {
if (typeof createImageBitmap !== 'undefined') {
try {
- const bitmap = await createImageBitmap(img, {
- premultiplyAlpha: 'none',
- colorSpaceConversion: 'none',
- imageOrientation: flip ? 'flipY' : 'from-image',
- });
- resolve(bitmap);
+ resolve(await decodeImageBitmap(img, flip));
return;
} catch {
// fallback
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index a64b493e2..1bcf2e284 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -50,6 +50,10 @@ export {
assetPlugin,
MaterialLoader,
AssetRefCounter,
+ decodeImageBitmap,
+ decodeImagePixels,
+ imageBitmapOptions,
+ type DecodedPixels,
type AddressableManifest,
type AddressableManifestGroup,
type AddressableManifestAsset,
diff --git a/sdk/src/playRealmRuntime.ts b/sdk/src/playRealmRuntime.ts
index 7cfc4d040..86dea43fa 100644
--- a/sdk/src/playRealmRuntime.ts
+++ b/sdk/src/playRealmRuntime.ts
@@ -21,6 +21,7 @@ import type { AddressableManifest } from './asset/AddressableManifest';
import type { SceneData } from './scene';
import { fetchPhysicsModule } from './physics';
import type { Vec2 } from './types';
+import { decodeImagePixels } from './asset/imageDecode';
const UUID_PREFIX = '@uuid:';
@@ -47,12 +48,11 @@ export interface PlayRealmRuntimeConfig {
/**
* Fetches scene assets over the realm origin, resolving `@uuid:` refs through the
- * editor-supplied manifest. Images are decoded via fetch → blob →
- * `createImageBitmap` → canvas → getImageData (NOT `<img crossorigin>`: Chromium
- * refuses CORS-mode images for custom schemes like `estella://`, and a non-CORS
- * `<img>` would taint the canvas so getImageData throws — fetch+blob sidesteps
- * both). `estella://` is fetchable because it's a privileged supportFetchAPI
- * scheme; the editor's handler returns `access-control-allow-origin: *`.
+ * editor-supplied manifest. Images go fetch → blob → the shared `decodeImagePixels`
+ * (NOT `<img crossorigin>`: Chromium refuses CORS-mode images for custom schemes
+ * like `estella://`, and a non-CORS `<img>` would taint the canvas so getImageData
+ * throws — fetch+blob sidesteps both). `estella://` is fetchable because it's a
+ * privileged supportFetchAPI scheme; the editor returns `access-control-allow-origin: *`.
*/
class FetchAssetProvider implements RuntimeAssetProvider {
constructor(private readonly manifest: Record<string, string>) {}
@@ -68,19 +68,7 @@ class FetchAssetProvider implements RuntimeAssetProvider {
const url = this.resolvePath(ref);
const res = await fetch(url);
if (!res.ok) throw new Error(`image fetch failed (${res.status}): ${url}`);
- const bitmap = await createImageBitmap(await res.blob(), { premultiplyAlpha: 'none', colorSpaceConversion: 'none' });
- try {
- const cv = document.createElement('canvas');
- cv.width = bitmap.width;
- cv.height = bitmap.height;
- const ctx = cv.getContext('2d');
- if (!ctx) throw new Error('2d context unavailable');
- ctx.drawImage(bitmap, 0, 0);
- const id = ctx.getImageData(0, 0, bitmap.width, bitmap.height);
- return { width: bitmap.width, height: bitmap.height, pixels: new Uint8Array(id.data.buffer) };
- } finally {
- bitmap.close();
- }
+ return decodeImagePixels(await res.blob());
}
async readText(ref: string): Promise<string> {
diff --git a/sdk/src/preview/WebAssetProvider.ts b/sdk/src/preview/WebAssetProvider.ts
index 51402bde5..d53370863 100644
--- a/sdk/src/preview/WebAssetProvider.ts
+++ b/sdk/src/preview/WebAssetProvider.ts
@@ -9,6 +9,7 @@ import type { RuntimeAssetProvider } from '../runtimeLoader';
import type { SceneData } from '../scene';
import { getComponentAssetFieldDescriptors, getComponentSpineFieldDescriptor } from '../scene';
import { getAssetTypeEntry } from '../assetTypes';
+import { decodeImagePixels } from '../asset/imageDecode';
import { log } from '../logger';
export class WebAssetProvider implements RuntimeAssetProvider {
@@ -124,20 +125,8 @@ export class WebAssetProvider implements RuntimeAssetProvider {
}
async loadPixels(ref: string): Promise<{ width: number; height: number; pixels: Uint8Array }> {
- const url = this.resolveUrl(ref);
- const resp = await fetch(url);
- const blob = await resp.blob();
- const bitmap = await createImageBitmap(blob);
- const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);
- const ctx = canvas.getContext('2d')!;
- ctx.drawImage(bitmap, 0, 0);
- const imageData = ctx.getImageData(0, 0, bitmap.width, bitmap.height);
- bitmap.close();
- return {
- width: imageData.width,
- height: imageData.height,
- pixels: new Uint8Array(imageData.data.buffer),
- };
+ const resp = await fetch(this.resolveUrl(ref));
+ return decodeImagePixels(await resp.blob());
}
resolvePath(ref: string): string {