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 place an image becomes a texture, and a canvas that can be re-taken

yhh5f85d87d822b
diff --git a/sdk/src/asset/canvasTexture.ts b/sdk/src/asset/canvasTexture.ts
new file mode 100644
index 000000000..40455064d
--- /dev/null
+++ b/sdk/src/asset/canvasTexture.ts
@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file canvasTexture.ts
+ * @brief A texture whose content is a live canvas, re-uploaded on demand.
+ *
+ * Every other texture in the engine is uploaded once from a file. This one is
+ * drawn by something else while the game runs — today the open data context's
+ * shared canvas, which is a second JS runtime the main domain cannot read any
+ * other way — so its content has to be re-taken, and the handle it is behind
+ * must not change when it is (a component holding the handle keeps holding it).
+ *
+ * It rides the same seam a file texture does: a JS-created GL texture handed to
+ * the ResourceManager with {@link registerExternalTexture}, and the SAME upload
+ * conventions (orientation, color space, sampling) as `TextureLoader` — see
+ * {@link ./glTextureUpload}. What differs is only what a moving image needs:
+ * no mipmaps (a chain regenerated every frame is pure waste), clamped wrap
+ * (nothing tiles a leaderboard), and `update()`.
+ */
+import { requireResourceManager } from '../wasm/resourceManager';
+import type { ESEngineModule } from '../wasm';
+import { findWebGL2Context } from './loaders/TextureLoader';
+import { uploadBoundTextureImage, applyBoundTextureSampling, type GlImageSource } from './glTextureUpload';
+
+/** A texture backed by a canvas someone else draws on. */
+export interface CanvasTexture {
+ /** The engine texture handle — stable across every {@link update}. */
+ readonly handle: number;
+ /** Size of the last upload. Follows the source when it is resized. */
+ readonly width: number;
+ readonly height: number;
+ /** Re-take the source's current content. Cheap to call, not free: one
+ * `texImage2D` of the whole surface. Callers gate on visibility. */
+ update(): void;
+ /** Release the GL texture. The handle is dead afterwards. */
+ destroy(): void;
+}
+
+/**
+ * Wrap `source` in an engine texture and take its content once.
+ *
+ * Returns null where there is no WebGL2 context to upload through — the native
+ * backend and any host still booting. That is a real answer, not a failure: the
+ * only caller is a leaderboard, which has already asked whether this platform
+ * has an open data context at all.
+ */
+export function createCanvasTexture(
+ module: ESEngineModule | null | undefined,
+ source: GlImageSource,
+): CanvasTexture | null {
+ const gl = findWebGL2Context(module?.GL);
+ if (!gl || !module) return null;
+
+ const texture = gl.createTexture();
+ if (!texture) return null;
+
+ // A canvas is an element source, so orientation is the pixel-store flag's
+ // to apply — the same `flip` a raw <img> upload takes, and for the same
+ // reason: the engine's texture space is bottom-up and the source is not.
+ const take = (): { width: number; height: number } => {
+ gl.bindTexture(gl.TEXTURE_2D, texture);
+ uploadBoundTextureImage(gl, source, true);
+ return { width: source.width, height: source.height };
+ };
+
+ let size: { width: number; height: number };
+ try {
+ size = take();
+ applyBoundTextureSampling(gl, { filter: 'linear', wrap: 'clamp', mipmaps: false });
+ } catch (err) {
+ gl.deleteTexture(texture);
+ throw err;
+ }
+
+ const glObj = module.GL;
+ const glTextureId = glObj.getNewId(glObj.textures);
+ glObj.textures[glTextureId] = texture;
+ const rm = requireResourceManager();
+ const handle = rm.registerExternalTexture(glTextureId, size.width, size.height);
+
+ let alive = true;
+ return {
+ handle,
+ get width() { return size.width; },
+ get height() { return size.height; },
+ update() {
+ if (!alive) return;
+ size = take();
+ },
+ destroy() {
+ if (!alive) return;
+ alive = false;
+ gl.deleteTexture(texture);
+ delete glObj.textures[glTextureId];
+ },
+ };
+}
diff --git a/sdk/src/asset/compressed.ts b/sdk/src/asset/compressed.ts
index e55f90fbd..d500f4b81 100644
--- a/sdk/src/asset/compressed.ts
+++ b/sdk/src/asset/compressed.ts
@@ -16,7 +16,7 @@
*/
import type { ESEngineModule } from '../wasm';
import { requireResourceManager } from '../wasm/resourceManager';
-import { glWrapMode } from './glTexParams';
+import { applyBoundTextureSampling } from './glTextureUpload';
// =============================================================================
// Format vocabulary
@@ -177,14 +177,10 @@ export interface UploadedTexture {
}
function applyParams(gl: WebGL2RenderingContext, opts?: CompressedUploadOptions): void {
- // Single-level textures: never select a mipmap min-filter (would be incomplete).
- const mag = opts?.filter === 'nearest' ? gl.NEAREST : gl.LINEAR;
- const min = mag;
- const wrap = glWrapMode(gl, opts?.wrap);
- gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, min);
- gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, mag);
- gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, wrap);
- gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, wrap);
+ // Single-level textures: never select a mipmap min-filter (would be
+ // incomplete) and never generate a chain — which is exactly what the shared
+ // sampler state does when told there are no mipmaps.
+ applyBoundTextureSampling(gl, { filter: opts?.filter, wrap: opts?.wrap, mipmaps: false });
}
/**
diff --git a/sdk/src/asset/glTexParams.ts b/sdk/src/asset/glTexParams.ts
index 6ee08dafc..7e91b0d03 100644
--- a/sdk/src/asset/glTexParams.ts
+++ b/sdk/src/asset/glTexParams.ts
@@ -4,9 +4,12 @@
* @file glTexParams.ts
* @brief Shared WebGL texture-parameter mapping. The wrap-mode → GL enum was
* duplicated byte-for-byte in the RGBA (TextureLoader) and compressed
- * (compressed.ts) upload paths; this is its single source. (Filter →
- * GL stays per-path: the RGBA path chooses mipmap min-filters, the
- * single-level compressed path never does.)
+ * (compressed.ts) upload paths; this is its single source.
+ *
+ * Filter used to stay per-path, because only the RGBA path chose
+ * mipmap min-filters. It no longer does: whole sampler state is
+ * {@link ../glTextureUpload#applyBoundTextureSampling}, which takes
+ * "has mipmaps" as the one input the two paths actually differed on.
*/
export type TextureWrap = 'repeat' | 'clamp' | 'mirror';
diff --git a/sdk/src/asset/glTextureUpload.ts b/sdk/src/asset/glTextureUpload.ts
new file mode 100644
index 000000000..b3aba3fa1
--- /dev/null
+++ b/sdk/src/asset/glTextureUpload.ts
@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file glTextureUpload.ts
+ * @brief The one place an image-like source becomes GL texture content in the
+ * engine's conventions: vertical orientation, color-space encoding and
+ * sampler state.
+ *
+ * Extracted for the same reason {@link ./glTexParams} was — a second uploader
+ * arrived (the open data context's shared canvas, re-uploaded every frame it is
+ * on screen) and these three conventions are exactly the ones that go wrong
+ * silently when they are written twice. A texture uploaded with the wrong
+ * `UNPACK_FLIP_Y_WEBGL` is upside down; with the wrong internal format it is
+ * subtly washed out in linear mode; with the wrong wrap it bleeds at the edge.
+ * None of the three throws.
+ *
+ * Everything here acts on the CURRENTLY BOUND `TEXTURE_2D`, which is what lets
+ * one function serve both a first upload and a re-upload into a live texture.
+ */
+import { linearColorSpace } from '../ecs/env';
+import { glWrapMode, type TextureWrap } from './glTexParams';
+import type { PlatformCanvas, PlatformImage } from '../platform/types';
+
+/** Anything WebGL will take directly as texture content. */
+export type GlImageSource = PlatformImage | PlatformCanvas | ImageBitmap;
+
+/** How a source should be sampled once it is on the GPU. */
+export interface TextureSampling {
+ readonly filter?: 'linear' | 'nearest';
+ readonly wrap?: TextureWrap;
+ readonly mipmaps?: boolean;
+}
+
+/**
+ * Upload `source` into the bound texture.
+ *
+ * `flip` is for element and pixel sources only: an `ImageBitmap` bakes its
+ * orientation at decode (Chromium/ANGLE ignore the pixel-store flag for
+ * bitmaps), so its caller passes false — see `TextureLoader.createTextureFromImage`.
+ *
+ * `srgb` is the AUTHORED flag — whether the source stores sRGB-encoded color
+ * (default) or authored-linear data such as a normal map. Whether that becomes
+ * an sRGB internal format is this function's decision, not the caller's, so the
+ * linear-pipeline rule lives in one place.
+ */
+export function uploadBoundTextureImage(
+ gl: WebGL2RenderingContext,
+ source: GlImageSource,
+ flip: boolean,
+ srgb?: boolean,
+): void {
+ gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, flip ? 1 : 0);
+ gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, 0);
+ // Linear pipeline: color textures store sRGB-encoded — the sampler
+ // linearizes in hardware. Data textures (normal maps) opt out.
+ const internalFormat = linearColorSpace() && (srgb ?? true) ? gl.SRGB8_ALPHA8 : gl.RGBA;
+ gl.texImage2D(gl.TEXTURE_2D, 0, internalFormat, gl.RGBA, gl.UNSIGNED_BYTE, source as TexImageSource);
+ // Left where every other upload expects it, not where this one wanted it.
+ gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, 0);
+}
+
+/**
+ * Give the bound texture its sampler state, generating mipmaps when it is to
+ * have them — one call, because "has mipmaps" and "uses a mipmap min-filter"
+ * are the same decision and a texture that disagrees with itself samples black.
+ */
+export function applyBoundTextureSampling(gl: WebGL2RenderingContext, sampling?: TextureSampling): void {
+ const filter = sampling?.filter ?? 'linear';
+ const useMipmaps = sampling?.mipmaps ?? true;
+ const glMinFilter = filter === 'nearest'
+ ? (useMipmaps ? gl.NEAREST_MIPMAP_NEAREST : gl.NEAREST)
+ : (useMipmaps ? gl.LINEAR_MIPMAP_LINEAR : gl.LINEAR);
+ gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, glMinFilter);
+ gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, filter === 'nearest' ? gl.NEAREST : gl.LINEAR);
+ const glWrap = glWrapMode(gl, sampling?.wrap);
+ gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, glWrap);
+ gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, glWrap);
+ if (useMipmaps) gl.generateMipmap(gl.TEXTURE_2D);
+}
diff --git a/sdk/src/asset/loaders/TextureLoader.ts b/sdk/src/asset/loaders/TextureLoader.ts
index 74e471f31..c12920be9 100644
--- a/sdk/src/asset/loaders/TextureLoader.ts
+++ b/sdk/src/asset/loaders/TextureLoader.ts
@@ -9,7 +9,7 @@ import { requireResourceManager } from '../../wasm/resourceManager';
import type { ESEngineModule } from '../../wasm';
import { withMalloc } from '../../wasm/wasmScratch';
import { isKtx2, isKtx2Path, loadCompressedTexture, type BasisTranscoder } from '../compressed';
-import { glWrapMode } from '../glTexParams';
+import { uploadBoundTextureImage, applyBoundTextureSampling } from '../glTextureUpload';
import { createTextureFromPixels, type TextureParams } from '../../runtime/runtimeAssets';
/**
@@ -290,15 +290,6 @@ export class TextureLoader implements AssetLoader<TextureResult> {
width: number, height: number, flip: boolean,
settings?: TextureImportSettings,
): TextureResult {
- const filter = settings?.filter ?? 'linear';
- const wrap = settings?.wrap ?? 'repeat';
- const useMipmaps = settings?.mipmaps ?? true;
- const glMinFilter = filter === 'nearest'
- ? (useMipmaps ? gl.NEAREST_MIPMAP_NEAREST : gl.NEAREST)
- : (useMipmaps ? gl.LINEAR_MIPMAP_LINEAR : gl.LINEAR);
- const glMagFilter = filter === 'nearest' ? gl.NEAREST : gl.LINEAR;
- const glWrap = glWrapMode(gl, wrap);
-
// createTexture returns null on a lost context — don't `!`-assert it
// into the calls below.
const texture = gl.createTexture();
@@ -307,22 +298,8 @@ export class TextureLoader implements AssetLoader<TextureResult> {
}
try {
gl.bindTexture(gl.TEXTURE_2D, texture);
- gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, flip ? 1 : 0);
- gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, 0);
- // Linear pipeline: color textures store sRGB-encoded — the sampler
- // linearizes in hardware. Data textures (normal maps) opt out via
- // the importer's sRGB flag.
- const internalFormat = linearColorSpace() && (settings?.srgb ?? true)
- ? gl.SRGB8_ALPHA8 : gl.RGBA;
- gl.texImage2D(gl.TEXTURE_2D, 0, internalFormat, gl.RGBA, gl.UNSIGNED_BYTE, img as any);
- gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, glMinFilter);
- gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, glMagFilter);
- gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, glWrap);
- gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, glWrap);
- if (useMipmaps) {
- gl.generateMipmap(gl.TEXTURE_2D);
- }
- gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, 0);
+ uploadBoundTextureImage(gl, img, flip, settings?.srgb);
+ applyBoundTextureSampling(gl, settings);
} catch (err) {
// Upload threw (e.g. context lost mid-call); release the GL texture
// instead of leaking it.
diff --git a/sdk/tests/canvas-texture.test.ts b/sdk/tests/canvas-texture.test.ts
new file mode 100644
index 000000000..e7d6fe388
--- /dev/null
+++ b/sdk/tests/canvas-texture.test.ts
@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file A texture whose content is a live canvas, over a fake WebGL2 context:
+ * the conventions it shares with a file texture (orientation, color
+ * space) and the ones it deliberately does not (no mipmaps, clamped),
+ * plus the property the whole thing exists for — the handle survives
+ * every re-take, because a component is holding it.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { initResourceManager, shutdownResourceManager } from '../src/wasm/resourceManager';
+import { setLinearColorSpace } from '../src/ecs/env';
+import { createCanvasTexture } from '../src/asset/canvasTexture';
+import type { ESEngineModule } from '../src/wasm';
+
+const SRGB8_ALPHA8 = 0x8c43;
+const RGBA = 0x1908;
+const UNPACK_FLIP_Y_WEBGL = 0x9240;
+const CLAMP_TO_EDGE = 0x812f;
+const TEXTURE_MIN_FILTER = 0x2801;
+const LINEAR = 0x2601;
+const LINEAR_MIPMAP_LINEAR = 0x2703;
+
+function makeGl() {
+ return {
+ TEXTURE_2D: 0x0de1, RGBA, UNSIGNED_BYTE: 0x1401, SRGB8_ALPHA8,
+ NEAREST: 0x2600, LINEAR, LINEAR_MIPMAP_LINEAR, NEAREST_MIPMAP_NEAREST: 0x2700,
+ CLAMP_TO_EDGE, MIRRORED_REPEAT: 0x8370, REPEAT: 0x2901,
+ TEXTURE_MIN_FILTER, TEXTURE_MAG_FILTER: 0x2800,
+ TEXTURE_WRAP_S: 0x2802, TEXTURE_WRAP_T: 0x2803,
+ UNPACK_FLIP_Y_WEBGL, UNPACK_PREMULTIPLY_ALPHA_WEBGL: 0x9241,
+ // isWebGL2's duck test.
+ texStorage2D: vi.fn(),
+ createTexture: vi.fn(() => ({}) as WebGLTexture),
+ deleteTexture: vi.fn(),
+ bindTexture: vi.fn(),
+ texImage2D: vi.fn(),
+ texParameteri: vi.fn(),
+ pixelStorei: vi.fn(),
+ generateMipmap: vi.fn(),
+ };
+}
+
+/** A module whose GL registry hands out ids, with `gl` as the live context. */
+function makeModule(gl: ReturnType<typeof makeGl>): ESEngineModule {
+ return {
+ GL: {
+ currentContext: { GLctx: gl },
+ contexts: [],
+ getNewId: vi.fn(() => 7),
+ textures: {} as Record<number, WebGLTexture>,
+ },
+ } as unknown as ESEngineModule;
+}
+
+/** A stand-in for the shared canvas: something with a size that can change. */
+function makeSource(width: number, height: number) {
+ return { width, height, getContext: () => ({}) } as never;
+}
+
+let registerExternalTexture: ReturnType<typeof vi.fn>;
+beforeEach(() => {
+ registerExternalTexture = vi.fn(() => 42);
+ initResourceManager({ registerExternalTexture } as never);
+});
+afterEach(() => {
+ shutdownResourceManager();
+ setLinearColorSpace(false);
+});
+
+describe('createCanvasTexture', () => {
+ it('takes the source once and registers it as an engine texture', () => {
+ const gl = makeGl();
+ const tex = createCanvasTexture(makeModule(gl), makeSource(256, 128))!;
+ expect(tex.handle).toBe(42);
+ expect(tex.width).toBe(256);
+ expect(tex.height).toBe(128);
+ expect(gl.texImage2D).toHaveBeenCalledTimes(1);
+ expect(registerExternalTexture).toHaveBeenCalledWith(7, 256, 128);
+ });
+
+ it('keeps the handle across a re-take — a component is holding it', () => {
+ const gl = makeGl();
+ const tex = createCanvasTexture(makeModule(gl), makeSource(64, 64))!;
+ const before = tex.handle;
+ tex.update();
+ tex.update();
+ expect(tex.handle).toBe(before);
+ expect(gl.texImage2D).toHaveBeenCalledTimes(3); // create + two updates
+ expect(registerExternalTexture).toHaveBeenCalledTimes(1);
+ });
+
+ it('follows the source when it is resized', () => {
+ const gl = makeGl();
+ const source = makeSource(64, 64) as { width: number; height: number };
+ const tex = createCanvasTexture(makeModule(gl), source as never)!;
+ source.width = 320;
+ source.height = 200;
+ tex.update();
+ expect(tex.width).toBe(320);
+ expect(tex.height).toBe(200);
+ });
+
+ it('uploads in the engine\'s orientation, un-premultiplied, and leaves the flag off', () => {
+ const gl = makeGl();
+ createCanvasTexture(makeModule(gl), makeSource(8, 8));
+ const flips = gl.pixelStorei.mock.calls.filter((c) => c[0] === UNPACK_FLIP_Y_WEBGL);
+ // Set for the upload, then restored — every other uploader shares this
+ // context and none of them asks for a flip they did not set.
+ expect(flips.map((c) => c[1])).toEqual([1, 0]);
+ });
+
+ it('is sRGB-encoded in the linear pipeline and plain RGBA in gamma', () => {
+ const gamma = makeGl();
+ createCanvasTexture(makeModule(gamma), makeSource(8, 8));
+ expect(gamma.texImage2D.mock.calls[0][2]).toBe(RGBA);
+
+ setLinearColorSpace(true);
+ const linear = makeGl();
+ createCanvasTexture(makeModule(linear), makeSource(8, 8));
+ expect(linear.texImage2D.mock.calls[0][2]).toBe(SRGB8_ALPHA8);
+ });
+
+ it('has no mipmaps and does not tile — a chain per frame is waste, and nothing tiles a panel', () => {
+ const gl = makeGl();
+ createCanvasTexture(makeModule(gl), makeSource(8, 8));
+ expect(gl.generateMipmap).not.toHaveBeenCalled();
+ const minFilter = gl.texParameteri.mock.calls.find((c) => c[1] === TEXTURE_MIN_FILTER);
+ expect(minFilter?.[2]).toBe(LINEAR);
+ expect(minFilter?.[2]).not.toBe(LINEAR_MIPMAP_LINEAR);
+ const wraps = gl.texParameteri.mock.calls.filter((c) => c[2] === CLAMP_TO_EDGE);
+ expect(wraps).toHaveLength(2);
+ });
+
+ it('sets sampler state once, not on every re-take', () => {
+ const gl = makeGl();
+ const tex = createCanvasTexture(makeModule(gl), makeSource(8, 8))!;
+ const afterCreate = gl.texParameteri.mock.calls.length;
+ tex.update();
+ expect(gl.texParameteri.mock.calls.length).toBe(afterCreate);
+ });
+
+ it('answers null where there is no WebGL2 to upload through', () => {
+ expect(createCanvasTexture(null, makeSource(8, 8))).toBeNull();
+ expect(createCanvasTexture(undefined, makeSource(8, 8))).toBeNull();
+ });
+
+ it('releases the GL texture on destroy, and a re-take afterwards is a no-op', () => {
+ const gl = makeGl();
+ const module = makeModule(gl);
+ const tex = createCanvasTexture(module, makeSource(8, 8))!;
+ tex.destroy();
+ expect(gl.deleteTexture).toHaveBeenCalledTimes(1);
+ expect((module.GL as unknown as { textures: Record<number, unknown> }).textures[7]).toBeUndefined();
+ const uploads = gl.texImage2D.mock.calls.length;
+ tex.update();
+ tex.destroy();
+ expect(gl.texImage2D.mock.calls.length).toBe(uploads);
+ expect(gl.deleteTexture).toHaveBeenCalledTimes(1);
+ });
+});