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
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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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);+ });+});