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.

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.ts
index 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.ts
index 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.ts
index 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): Resolv
const uniforms = parent.uniforms; // fresh map from the recursive call
if (includeUniforms) for (const [k, v] of data.uniforms) uniforms.set(k, v); // instance overrides win
return {
- shader: parent.shader, // instances inherit the shader
+ shader: data.ownShader ?? parent.shader, // instances inherit the shader unless they switched permutation
blendMode: 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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(),
} }));