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
feat(cocos): recompileShaders makes the material take the permutation of its shader that has the macros applied, now, instead of only recording them
yhhf8a6513cb096
diff --git a/sdk/src/asset/loaders/MaterialShaderAssetLoader.ts b/sdk/src/asset/loaders/MaterialShaderAssetLoader.tsindex f40d1bc17..4650dd468 100644--- a/sdk/src/asset/loaders/MaterialShaderAssetLoader.ts+++ b/sdk/src/asset/loaders/MaterialShaderAssetLoader.ts@@ -18,6 +18,7 @@ export class MaterialShaderSource {const handle = Material.compileShader(this.source_, features);if (!handle) throw new Error(`Failed to compile material shader: ${this.path_}`);this.programs_.set(key, handle);+ Material.noteProgram(handle, features, this.source_, next => this.compile(next));return handle;}diff --git a/sdk/src/cocos/assets.ts b/sdk/src/cocos/assets.tsindex aee58d007..0b188b802 100644--- a/sdk/src/cocos/assets.ts+++ b/sdk/src/cocos/assets.ts@@ -110,12 +110,14 @@ export class Material extends Asset {}/**- * Switch the shader's macros. The engine keeps a material's switches on its record, and the permutation they pick is fixed when the shader is- * compiled, so the record answers now and the permutation changes where the engine next compiles the shader.+ * Switch the shader's macros. The engine material takes the permutation of its shader that has them applied, now: a macro the effect never+ * branched on has no permutation of its own, so it is kept on the record and changes nothing drawn.*/recompileShaders(defines: Record<string, unknown>, _passIndex?: number): void {if (this._handle <= 0) return;- for (const [name, value] of Object.entries(defines)) EngineMaterial.setSwitch(this._handle, name, !!value && value !== '0');+ const changes: Record<string, boolean> = {};+ for (const [name, value] of Object.entries(defines)) changes[name] = !!value && value !== '0';+ EngineMaterial.recompile(this._handle, changes);}/** What the property was last set to. @internal */diff --git a/sdk/src/render/material.ts b/sdk/src/render/material.tsindex c594cafcd..ee73c729f 100644--- a/sdk/src/render/material.ts+++ b/sdk/src/render/material.ts@@ -140,6 +140,8 @@ export interface MaterialData {* fields. Undefined on a base material.*/parent?: MaterialHandle;+ /** The permutation an instance switched to for itself; an instance otherwise draws with its parent's shader. */+ ownShader?: ShaderHandle;overrides: Set<string>;// Immediate-mode mesh uniform cache (draw.ts): the encoded uniform buffer is rebuilt// only when dirty_ (a uniform changed). Distinct from the batch render path's material UBO.@@ -199,6 +201,9 @@ const childrenOf = new Map<MaterialHandle, Set<MaterialHandle>>();// A shader built from raw GLSL (createShader) declares nothing and gets no entry: no// vocabulary, no verdict.const declaredParams = new Map<ShaderHandle, Set<string>>();+/** What a compiled permutation was made from, so a material can ask for the same source under other switches. */+interface ProgramOrigin { features: readonly string[]; declared: ReadonlySet<string>; compile(features: string[]): ShaderHandle }+const programOrigins = new Map<ShaderHandle, ProgramOrigin>();// One complaint per (shader, param). A uniform driven from a system is written every// frame, and a warning that repeats 60 times a second is a log nobody can read.const warnedParams = new Set<string>();@@ -223,7 +228,7 @@ export function shutdownMaterialAPI(): void {ownedTextures.clear();try { releaseTextures(textures); }finally {- materials.clear(); childrenOf.clear(); declaredParams.clear(); warnedParams.clear();+ materials.clear(); childrenOf.clear(); declaredParams.clear(); programOrigins.clear(); warnedParams.clear();nextMaterialId = 1; bridge.disconnect(); module = null;}}@@ -232,8 +237,9 @@ export function shutdownMaterialAPI(): void {function shaderOf(handle: MaterialHandle): ShaderHandle | undefined {let data = materials.get(handle);// Bounded: a cycle in the parent chain would otherwise hang a per-write check.+ const own = data?.ownShader;for (let depth = 0; data?.parent !== undefined && depth < 16; depth++) data = materials.get(data.parent);- return data?.shader;+ return own ?? data?.shader;}/**@@ -342,7 +348,7 @@ function resolveMaterial(handle: MaterialHandle, includeUniforms = true): Resolvconst uniforms = parent.uniforms; // fresh map from the recursive callif (includeUniforms) for (const [k, v] of data.uniforms) uniforms.set(k, v); // instance overrides winreturn {- shader: parent.shader, // instances inherit the shader+ shader: data.ownShader ?? parent.shader, // instances inherit the shader unless they switched permutationblendMode: data.overrides.has('blendMode') ? data.blendMode : parent.blendMode,depthTest: data.overrides.has('depthTest') ? data.depthTest : parent.depthTest,depthWrite: data.overrides.has('depthWrite') ? data.depthWrite : parent.depthWrite,@@ -419,6 +425,7 @@ export const Material = {releaseShader(shader: ShaderHandle): void {if (shader > 0) {declaredParams.delete(shader);+ programOrigins.delete(shader);requireResourceManager().releaseShader(shader);}},@@ -485,6 +492,39 @@ export const Material = {return found;},+ /**+ * Record what a compiled permutation was made from: the source's switches and how to compile it under others. The asset loader says so for+ * every shader it compiles, which is what lets `recompile` answer for a material that only holds the handle.+ */+ noteProgram(shader: ShaderHandle, features: readonly string[], esshaderSource: string, compile: (features: string[]) => ShaderHandle): void {+ const declared = new Set<string>();+ for (const m of esshaderSource.matchAll(/^[ \t]*#pragma[ \t]+switch[ \t]+(\w+)/gm)) declared.add(m[1]!);+ programOrigins.set(shader, { features, declared, compile });+ },++ /**+ * Switch a material to the permutation of its own shader source that has `changes` applied: a switch the shader does not declare is left out+ * (a project's macro the effect never branched on), and the material takes the permutation at once, with its parameters and textures+ * carried over. A material that inherits (an instance) switches for itself and leaves its parent as it is. Answers whether the shader changed.+ */+ recompile(material: MaterialHandle, changes: Record<string, boolean>): boolean {+ const data = materials.get(material);+ const current = shaderOf(material);+ const origin = current !== undefined ? programOrigins.get(current) : undefined;+ if (!data || !origin) return false;+ const on = new Set(origin.features);+ for (const [name, value] of Object.entries(changes)) {+ data.switches[name] = value;+ if (value) on.add(name); else on.delete(name);+ }+ const features = [...on].filter(name => origin.declared.has(name)).sort();+ const next = origin.compile(features);+ if (next === current || next <= 0) return false;+ if (data.parent === undefined) data.shader = next; else data.ownShader = next;+ flushMaterial(material);+ return true;+ },+/** Gets an enabled static switch (false when unset). */getSwitch(material: MaterialHandle, name: string): boolean {return materials.get(material)?.switches[name] ?? false;diff --git a/sdk/tests/asset-dependencies.test.ts b/sdk/tests/asset-dependencies.test.tsindex e6257391d..ec2bd3f4b 100644--- a/sdk/tests/asset-dependencies.test.ts+++ b/sdk/tests/asset-dependencies.test.ts@@ -88,6 +88,7 @@ const materialFake = vi.hoisted(() => {setUniform: vi.fn(),tex: vi.fn((handle: number) => ({ kind: 'tex', handle })),compileShader: vi.fn(() => 7),+ noteProgram: vi.fn(),releaseShader: vi.fn(),release: vi.fn((h: number) => { live.delete(h); }),},diff --git a/sdk/tests/hot-update-rebind.test.ts b/sdk/tests/hot-update-rebind.test.tsindex d464136f9..eb39d51f2 100644--- a/sdk/tests/hot-update-rebind.test.ts+++ b/sdk/tests/hot-update-rebind.test.ts@@ -89,6 +89,7 @@ const materialFake = vi.hoisted(() => {setUniform: vi.fn(),tex: vi.fn((handle: number) => ({ kind: 'tex', handle })),compileShader: vi.fn(() => 7),+ noteProgram: vi.fn(),releaseShader: vi.fn(),release: vi.fn(),},diff --git a/sdk/tests/material-asset-loader.test.ts b/sdk/tests/material-asset-loader.test.tsindex 383ccb9ab..17e0ce2dd 100644--- a/sdk/tests/material-asset-loader.test.ts+++ b/sdk/tests/material-asset-loader.test.ts@@ -8,6 +8,7 @@ vi.mock('../src/render/material', () => ({setUniform: vi.fn(),tex: vi.fn((handle: number) => ({ kind: 'tex', handle })),compileShader: vi.fn().mockReturnValue(7),+ noteProgram: vi.fn(),releaseShader: vi.fn(),release: vi.fn(),},diff --git a/sdk/tests/material-recompile.test.ts b/sdk/tests/material-recompile.test.tsnew file mode 100644index 000000000..6571ee3b6--- /dev/null+++ b/sdk/tests/material-recompile.test.ts@@ -0,0 +1,101 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';+import { Material, initMaterialAPI, shutdownMaterialAPI } from '../src/render/material';+import type { ESEngineModule } from '../src/wasm';+import { initResourceManager, shutdownResourceManager } from '../src/wasm/resourceManager';++const SOURCE = `#pragma switch USE_FOG+#pragma switch USE_RIM default(on)+#pragma param u_a float(1)+`;++describe('a material switching to another permutation of its shader', () => {+ let define: ReturnType<typeof vi.fn>;+ let compiled: string[][];++ beforeEach(() => {+ define = vi.fn();+ compiled = [];+ const resourceManager = { createShader: vi.fn().mockReturnValue(1), releaseShader: vi.fn() };+ initResourceManager(resourceManager as never);+ initMaterialAPI({+ getResourceManager: () => resourceManager,+ material_compileEsshader: vi.fn(),+ material_define: define,+ material_setUniform: vi.fn(),+ material_setTexture: vi.fn(),+ material_undefine: vi.fn(),+ } as unknown as ESEngineModule);+ });+ afterEach(() => {+ shutdownMaterialAPI();+ shutdownResourceManager();+ });++ /** A source whose permutations get a handle each, as the loader's does. */+ const program = (features: string[]) => {+ const handles = new Map<string, number>();+ const compile = (f: string[]): number => {+ const key = f.join(',');+ let h = handles.get(key);+ if (h === undefined) {+ h = 100 + handles.size;+ handles.set(key, h);+ compiled.push(f);+ Material.noteProgram(h, f, SOURCE, compile);+ }+ return h;+ };+ return compile(features);+ };++ it('takes the permutation with the switch applied, and keeps the parameters it had', () => {+ const base = program([]);+ const m = Material.create({ shader: base, uniforms: { u_a: 3 } });+ define.mockClear();+ expect(Material.recompile(m, { USE_FOG: true })).toBe(true);+ expect(compiled).toEqual([[], ['USE_FOG']]);+ expect(Material.get(m)!.shader).not.toBe(base);+ expect(define).toHaveBeenCalledTimes(1);+ expect(Material.getUniform(m, 'u_a')).toBe(3);+ expect(Material.getSwitch(m, 'USE_FOG')).toBe(true);+ });++ it('leaves out a switch the shader never declared, and changes nothing when that is all there was', () => {+ const base = program([]);+ const m = Material.create({ shader: base });+ define.mockClear();+ expect(Material.recompile(m, { USE_BATCHING: true })).toBe(false);+ expect(Material.get(m)!.shader).toBe(base);+ expect(define).not.toHaveBeenCalled();+ expect(Material.getSwitch(m, 'USE_BATCHING')).toBe(true);+ });++ it('builds on the permutation it is already in, and can switch back', () => {+ const m = Material.create({ shader: program([]) });+ Material.recompile(m, { USE_FOG: true });+ Material.recompile(m, { USE_RIM: true });+ expect(compiled.at(-1)).toEqual(['USE_FOG', 'USE_RIM']);+ const both = Material.get(m)!.shader;+ Material.recompile(m, { USE_FOG: false });+ expect(compiled.at(-1)).toEqual(['USE_RIM']);+ expect(Material.get(m)!.shader).not.toBe(both);+ });++ it('switches an instance for itself and leaves its parent and siblings on theirs', () => {+ const base = program([]);+ const parent = Material.create({ shader: base });+ const mine = Material.createInstance(parent);+ const sibling = Material.createInstance(parent);+ expect(Material.recompile(mine, { USE_FOG: true })).toBe(true);+ expect(Material.get(parent)!.shader).toBe(base);+ expect(Material.getRenderState(mine)!.shader).not.toBe(base);+ expect(Material.getRenderState(sibling)!.shader).toBe(base);+ });++ it('answers false for a material whose shader was not compiled from a source', () => {+ const m = Material.create({ shader: 1 });+ expect(Material.recompile(m, { USE_FOG: true })).toBe(false);+ });+});diff --git a/sdk/tests/material-shader-ownership.test.ts b/sdk/tests/material-shader-ownership.test.tsindex f2a2022ab..b28be40d9 100644--- a/sdk/tests/material-shader-ownership.test.ts+++ b/sdk/tests/material-shader-ownership.test.ts@@ -16,6 +16,7 @@ vi.mock('../src/render/material', () => ({ Material: {if (source === 'invalid') return 0;const handle = gpu.next++; gpu.live.add(handle); return handle;}),+ noteProgram: vi.fn(),releaseShader: vi.fn((handle: number) => { gpu.live.delete(handle); gpu.released.push(handle); }),createFromAsset: vi.fn(() => gpu.next++), release: vi.fn(), setUniform: vi.fn(), tex: vi.fn(),} }));