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
/**
* @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, textureRefill } from '../src/wasm/resourceManager';
import { setLinearColorSpace } from '../src/ecs/env';
import { createCanvasTexture } from '../src/asset/canvasTexture';
import { TextureContent, type ESEngineModule } from '../src/wasm';
import type { App } from '../src/app/app';
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() {
// What the unit holds, so the bridge's restore of it can be checked: the device
// remembers its bindings, and one left changed is one it never makes again.
const ENGINE_BOUND = { tag: 'the device\'s own' } as unknown as WebGLTexture;
let bound: WebGLTexture | null = ENGINE_BOUND;
return {
ENGINE_BOUND,
TEXTURE_2D: 0x0de1, TEXTURE_BINDING_2D: 0x8069, 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(() => ({ tag: 'first' }) as unknown as WebGLTexture),
deleteTexture: vi.fn(),
bindTexture: vi.fn((_target: number, texture: WebGLTexture | null) => { bound = texture; }),
getParameter: vi.fn((name: number) => (name === 0x8069 ? bound : null)),
texImage2D: vi.fn(),
texParameteri: vi.fn(),
pixelStorei: vi.fn(),
generateMipmap: vi.fn(),
};
}
/** An App whose module's GL registry hands out ids, with `gl` as the live
* context — the App is what a caller has, so it is what this takes. */
function makeApp(gl: ReturnType<typeof makeGl>): App {
const module = {
GL: {
currentContext: { GLctx: gl },
contexts: [],
getNewId: vi.fn(() => 7),
textures: {} as Record<number, WebGLTexture>,
},
} as unknown as ESEngineModule;
return { wasmModule: module } as unknown as App;
}
/** 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>;
let releaseTexture: ReturnType<typeof vi.fn>;
let restoreTextureContent: ReturnType<typeof vi.fn>;
beforeEach(() => {
registerExternalTexture = vi.fn(() => 42);
releaseTexture = vi.fn();
restoreTextureContent = vi.fn();
// getTextureGLId is how every re-take finds the texture the DEVICE has: the
// id it hands back is the one the bridge registered, until a loss replaces it.
initResourceManager({
registerExternalTexture, releaseTexture, restoreTextureContent,
getTextureNativeId: vi.fn(() => 7),
} 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(makeApp(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, TextureContent.Canvas);
});
it('keeps the handle across a re-take — a component is holding it', () => {
const gl = makeGl();
const tex = createCanvasTexture(makeApp(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(makeApp(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(makeApp(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(makeApp(gamma), makeSource(8, 8));
expect(gamma.texImage2D.mock.calls[0][2]).toBe(RGBA);
setLinearColorSpace(true);
const linear = makeGl();
createCanvasTexture(makeApp(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(makeApp(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(makeApp(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('gives the texture back to the device on destroy, and a re-take afterwards is a no-op', () => {
const gl = makeGl();
const tex = createCanvasTexture(makeApp(gl), makeSource(8, 8))!;
const handle = tex.handle;
tex.destroy();
// The device owns the object since the hand-over, so ending it is one
// release — deleting the GL texture here would pull it out from under it.
expect(releaseTexture).toHaveBeenCalledWith(handle);
expect(gl.deleteTexture).not.toHaveBeenCalled();
expect(textureRefill(handle)).toBeUndefined();
const uploads = gl.texImage2D.mock.calls.length;
tex.update();
tex.destroy();
expect(gl.texImage2D.mock.calls.length).toBe(uploads);
expect(releaseTexture).toHaveBeenCalledTimes(1);
});
it('leaves the unit bound to what the device bound there, on the first take and every re-take', () => {
// The device skips a bind it believes is made. A texture left on its unit (15,
// the per-instance records, when that was the last one it used) was read as
// every instanced mesh's transforms, and once freed the whole scene drew black.
const gl = makeGl();
const tex = createCanvasTexture(makeApp(gl), makeSource(8, 8))!;
expect(gl.getParameter(gl.TEXTURE_BINDING_2D)).toBe(gl.ENGINE_BOUND);
tex.update();
expect(gl.getParameter(gl.TEXTURE_BINDING_2D)).toBe(gl.ENGINE_BOUND);
});
it('takes the canvas again into the texture the device rebuilt, and says the debt is paid', () => {
const gl = makeGl();
const app = makeApp(gl);
const tex = createCanvasTexture(app, makeSource(8, 8))!;
const pool = (app.wasmModule!.GL as unknown as { textures: Record<number, WebGLTexture> }).textures;
const beforeLoss = pool[7];
// What a device loss leaves: the same handle, a different native texture.
const rebuilt = { tag: 'after-loss' } as unknown as WebGLTexture;
pool[7] = rebuilt;
expect(textureRefill(tex.handle)!()).toBe(true);
const writes = gl.bindTexture.mock.calls.map((c) => c[1]).slice(-2);
expect(writes[0]).toBe(rebuilt);
expect(writes[0]).not.toBe(beforeLoss);
// ...and the unit is left holding what the device bound there.
expect(writes[1]).toBe(gl.ENGINE_BOUND);
expect(gl.texImage2D).toHaveBeenCalledTimes(2);
expect(restoreTextureContent).toHaveBeenCalledWith(tex.handle);
});
it('leaves the content owed when there is no context to take it with', () => {
const gl = makeGl();
const app = makeApp(gl);
const tex = createCanvasTexture(app, makeSource(8, 8))!;
const pool = (app.wasmModule!.GL as unknown as { textures: Record<number, WebGLTexture> }).textures;
delete pool[7];
expect(textureRefill(tex.handle)!()).toBe(false);
expect(restoreTextureContent).not.toHaveBeenCalled();
});
});