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(draw): custom-draw goes reflected - editor grid renders on WebGPU (last GL-only path closed)

yhhcc1012d90e26
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 7b7316b17..3421d72ad 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -194,6 +194,9 @@ jobs:
env "$@" xvfb-run -a pnpm exec electron scripts/headless-verify.mjs
}
run_scene sprite-default
+ # Editor grid on/off pixel diff — guards the custom-draw reflected
+ # material path (drawMeshWithMaterial + MaterialConstants UBO).
+ run_scene editor-grid ESTELLA_VERIFY_GRID=64 ESTELLA_VERIFY_STEPS=3
run_scene mesh2d \
ESTELLA_VERIFY_SCENE=/scenes/mesh2d.esscene \
ESTELLA_VERIFY_MANIFEST=/scenes/mesh2d.textures.json \
diff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjs
index 947ca7781..1fbbae8f8 100644
--- a/desktop/scripts/headless-verify.mjs
+++ b/desktop/scripts/headless-verify.mjs
@@ -17,6 +17,7 @@
* ESTELLA_VERIFY_MANIFEST texture manifest url
* ESTELLA_VERIFY_W / _H capture size (default 640×480)
* ESTELLA_VERIFY_STEPS fixed-dt frames to advance before capture (default 30)
+ * ESTELLA_VERIFY_GRID editor-grid on/off pixel-diff assertion (value = spacing)
*/
import { app, BrowserWindow } from 'electron';
import http from 'node:http';
@@ -75,7 +76,7 @@ function serveDist() {
function finish(result, server) {
const ok = result.ok && result.capture?.rendered && (result.expect?.ok ?? true) &&
- (result.resize?.ok ?? true) && (result.preview?.ok ?? true);
+ (result.resize?.ok ?? true) && (result.preview?.ok ?? true) && (result.grid?.ok ?? true);
console.log(`\n[verify:render] ${ok ? 'PASS' : 'FAIL'} — ${SCENE} (${BACKEND})`);
console.log('DRIVE_RESULT ' + JSON.stringify(result));
process.exitCode = ok ? 0 : 1;
@@ -267,7 +268,62 @@ app.whenReady().then(async () => {
return { ok: got.every((g, k) => Math.abs(g - cfg.rgb[k]) <= tol), want: cfg.rgb, got, w, h };
})()`);
}
- finish({ ok: true, entityCount, drawCalls, capture, expect, resize, preview }, server);
+ // Optional editor-grid assertion (ESTELLA_VERIFY_GRID = minor spacing, world
+ // units): flip the grid on (this activates the editor view it draws through),
+ // capture, flip it off, and assert the frames differ — proving the custom-draw
+ // drawMeshWithMaterial path rasterizes on this backend. Run standalone:
+ // activating the editor view reframes the camera for any later capture.
+ let grid = null;
+ if (process.env.ESTELLA_VERIFY_GRID) {
+ const spacing = Number(process.env.ESTELLA_VERIFY_GRID) || 64;
+ await exec(`window.__estellaHeadless.api.setGrid(true, ${spacing})`);
+ await exec('window.__estellaHeadless.api.step(2, 1 / 60)');
+ // Optional PNG of the grid-on frame (ESTELLA_VERIFY_GRID_OUT) for eyeballing.
+ // Same per-backend readback split as ESTELLA_VERIFY_OUT (GL page capture of a
+ // hidden window never composites — read the framebuffer in-page instead).
+ if (process.env.ESTELLA_VERIFY_GRID_OUT && BACKEND === 'webgpu') {
+ const image = await win.webContents.capturePage({ x: 0, y: 0, width: W, height: H });
+ await writeFile(process.env.ESTELLA_VERIFY_GRID_OUT, image.toPNG());
+ } else if (process.env.ESTELLA_VERIFY_GRID_OUT) {
+ const dataUrl = await exec(`(() => {
+ const c = window.__estellaHeadless.api.captureViewport();
+ const cv = document.createElement('canvas'); cv.width = c.width; cv.height = c.height;
+ const ctx = cv.getContext('2d'); const img = ctx.createImageData(c.width, c.height);
+ const w = c.width, h = c.height, src = c.rgba;
+ for (let y = 0; y < h; y++) { const sy = (h - 1 - y) * w * 4; img.data.set(src.subarray(sy, sy + w * 4), y * w * 4); }
+ ctx.putImageData(img, 0, 0);
+ return cv.toDataURL('image/png');
+ })()`);
+ await writeFile(process.env.ESTELLA_VERIFY_GRID_OUT, Buffer.from(dataUrl.split(',')[1], 'base64'));
+ }
+ if (BACKEND === 'webgpu') {
+ const on = (await grabWebGPU()).rgba;
+ await exec('window.__estellaHeadless.api.setGrid(false)');
+ await exec('window.__estellaHeadless.api.step(2, 1 / 60)');
+ const off = (await grabWebGPU()).rgba;
+ let differing = 0;
+ for (let i = 0; i < on.length; i += 4) {
+ const d = Math.abs(on[i] - off[i]) + Math.abs(on[i + 1] - off[i + 1]) + Math.abs(on[i + 2] - off[i + 2]);
+ if (d > 12) differing++;
+ }
+ grid = { differingPixels: differing, ok: differing > 300 };
+ } else {
+ await exec('window.__estellaGridOn = window.__estellaHeadless.api.captureViewport().rgba.slice()');
+ await exec('window.__estellaHeadless.api.setGrid(false)');
+ await exec('window.__estellaHeadless.api.step(2, 1 / 60)');
+ grid = await exec(`(() => {
+ const off = window.__estellaHeadless.api.captureViewport().rgba;
+ const on = window.__estellaGridOn;
+ let differing = 0;
+ for (let i = 0; i < on.length; i += 4) {
+ const d = Math.abs(on[i] - off[i]) + Math.abs(on[i + 1] - off[i + 1]) + Math.abs(on[i + 2] - off[i + 2]);
+ if (d > 12) differing++;
+ }
+ return { differingPixels: differing, ok: differing > 300 };
+ })()`);
+ }
+ }
+ finish({ ok: true, entityCount, drawCalls, capture, expect, resize, preview, grid }, server);
} catch (e) {
finish({ ok: false, error: String((e && e.stack) || e) }, server);
}
diff --git a/desktop/src/engine/EditorControlSurface.ts b/desktop/src/engine/EditorControlSurface.ts
index 7d60887b1..c968dbd1d 100644
--- a/desktop/src/engine/EditorControlSurface.ts
+++ b/desktop/src/engine/EditorControlSurface.ts
@@ -295,6 +295,16 @@ export class EditorControlSurfaceImpl {
canvas.style.height = `${height}px`;
}
+ /**
+ * Enable/disable the editor reference grid (headless verification + MCP).
+ * Enabling also seeds + activates the editor view — the edit-mode camera the
+ * grid draws through — since the headless host boots with it inactive.
+ */
+ setGrid(enabled: boolean, spacing?: number): void {
+ if (enabled) EngineHost.syncEditorViewToScene();
+ EngineHost.setGrid(enabled, spacing);
+ }
+
captureViewport(): ViewportCapture {
const canvas = EngineHost.canvas;
if (!canvas) {
diff --git a/docs/REARCHITECTURE.md b/docs/REARCHITECTURE.md
index e97f5b326..bde5b582b 100644
--- a/docs/REARCHITECTURE.md
+++ b/docs/REARCHITECTURE.md
@@ -184,7 +184,12 @@ TS 驱动的主 pass clear 退出边界,`clear` 家族退出公共 RHI:
- **方法论教训(已入记忆)**:排查期间多次实验跑在陈旧 wasm 上导致结论互相矛盾;现在的协议是每轮 bisect 在源里嵌标记字符串、grep 部署产物 + 比对双份 md5 后才采信结果。
- 验证(全部本地、BelowNormal):13 个 headless 场景全 PASS(含 postprocess-effects/lut-grade 两个后处理场景、mesh2d、ui-mask、lit×2);6 套 MockGfxDevice harness、SDK 241 测试文件(renderer/renderPipeline 测试更新为 load-op 契约)、desktop 63 文件、双侧 tsc、24 examples 全绿。**WebGPU 前仅剩一片**:GLSL-only `createProgram` → WGSL 通路。
-### WGSL/WebGPU 通路 — 🟡 进行中:Phase 2 切片 1-4 已落地——**首帧点亮、批多纹理、离屏与区域 clear 全部工作**(2026-07-07)
+### WGSL/WebGPU 通路 — 🟡 Phase 0-3 全部完结 + SDK 启动 + custom-draw 现代化;剩 Phase 4 cook 期用户材质(2026-07-08)
+**Phase 2 收官(切片 5a/5b)**:深度/模板全通(surface 伴随 DS 纹理、管线按 pass DS 形状惰性变体、clearStencil 中帧仿真、采样器参数缓存 + group-1 纹理/采样器 8+8 配对);引擎初始化流接入(`EstellaContext::init(Unique<GfxDevice>)`,后端选择留在平台边界零 #ifdef)+ `webgpu_engine_bringup` 真 ECS 场景两后端逐点 diff=0。
+**Phase 3 完结(切片 1-6,2026-07-07 单日)**:显式绑定布局(掩码缓存 BGL + 哑资源回填,纹理槽 8→16);`.esshader` `#pragma vertex/fragment wgsl` 孪生段 + 注入头双语发射(块变量移植规则 tc/mc/lc、std140≡WGSL 布局、feature 迷你预处理器);batch/shape/particle 内嵌归位单路径;7 模板 + 3 滤镜 + 13 后处理效果全部双语(PP 参数迁反射 MaterialConstants per-pass UBO,`u_resolution` 退役);materialGraph 单 DAG 双语发射。
+**SDK 启动 + resize(campaign coda)**:web 变体带 WebGPU 后端(wechat/playable 保持 GL 零胶水体积)、`WebAppOptions.backend`、`ESTELLA_VERIFY_BACKEND=webgpu` 场景断言像素精确相等、`GfxDevice::resizeBackbuffer` 每帧契约(WebGPU swapchain 重配)。
+**Custom-draw/Draw API 现代化(2026-07-08,最后一个 GL-only 通路闭合)**:新绑定 `draw_meshWithMaterial`——反射材质(compileEsshader)经 `MaterialStore::bindForDraw` 走 MaterialConstants(binding 1)+ 材质记录供给全部管线态,两后端同路零散装 uniform;TS 侧 18 名字 loose 表退为 raw-GLSL `createShader` 兼容路径。编辑器网格迁双语 `.esshader`(`u_model`→`u_rect` 参数 + authored vertex 声明 FrameConstants)——**WebGPU 下编辑器网格首次渲染**,GL/WebGPU 帧一致;`ESTELLA_VERIFY_GRID` 双后端 on/off 像素 diff 断言入 harness。
+**剩余**:Phase 4 用户手写 `.esshader` 的 cook 期 naga 转换(归 RC6 资产管线;实测边界——mat-lit 等场景资产 shader 无孪生,WebGPU 下按设计描述性跳过);WebGPU 异步 readback seam(`readPixels` stub,材质预览断言跳过);CI 无 WebGPU 适配器(webgpu verify 仅本地)。
见 `REARCH_WGSL.md`(本地 gitignore,同 RC6/2D_PARITY 约定):着色器版图盘点(uniform 数据已全后端中立,剩程序文本)、岔路拍板(有限集人工孪生 / 图材质 AST 双发射 / 用户材质 cook 期转换——拒绝运行时翻译器的 MB 级体积代价)、四期计划(源语言接缝 → WebGPUDevice 原型 → 双语发射 → cook 期用户材质)。**Phase 0 已落地**:最后 3 个 GLSL ES 1.00 残留(SDK outline/drop-shadow/color-matrix 滤镜)重写为 fragment-only `.esshader` 反射路径——顺带修复其设计性破损(raw 形态无 `u_projection` 来源、无属性绑定、mat4 超 `setMaterialUniform` 的 vec4 上限**从未能传入**;色彩矩阵改为 4×vec4 行 + 偏移列,新增 `Filters.colorMatrixUniforms` 助手)。全仓每个程序自此都在现代缝上(300 es + UBO 反射)。
**Phase 1(源语言接缝)已落地**:RHI 补上最后一块后端中立拼图——`createProgram` 收语言标签的 `GfxShaderSource`,新增 `supportsShaderLanguage` 能力查询(GL = 仅 GLSL ES 300;`Shader::compile` 在任何 GPU 调用前对不支持的语言快速失败);语言贯穿 Shader/ResourceManager(DrawParams 重写仅对 GLSL 生效);`ShaderParser::assembleStage` 获得 `ShaderTargetLanguage` 参数(WGSL 发射 = Phase 3)。MockGfxDevice 新增 `wgslSupported` 开关 + 语言门用例;行为零变化(8 harness + 场景抽样等价)。
**Phase 2 切片 1(WebGPU 后端启动)已落地**:emdawnwebgpu 端口(Dawn)集成为测试目标独立依赖(主构建零影响);`renderer/webgpu/` 新增纯映射层(GfxEnums→WGPU 全翻译,blend/模板表镜像 GLDevice 语义,load-op 规则与 RenderPassDesc 契约一致)+ 空设备安全的 `WebGPUDevice` 骨架(缓冲/纹理/WGSL 模块真实现,布局/管线描述符保留待惰性构建,pass/draw 为切片 2 结构化桩);`test_webgpu_device` 用真 Dawn 头编译验证全部描述符拼写,入 CI。
diff --git a/sdk/src/camera/editorGridRenderer.ts b/sdk/src/camera/editorGridRenderer.ts
index 2c5a1fead..acf01851d 100644
--- a/sdk/src/camera/editorGridRenderer.ts
+++ b/sdk/src/camera/editorGridRenderer.ts
@@ -10,13 +10,18 @@
* paints minor / major / axis lines in WORLD space. Because it runs in the
* pre-scene pass, scene entities occlude the grid (UE5 / Unity behaviour).
*
- * The quad is a unit quad scaled+translated by `u_model` to cover the camera's
- * visible world rect (centre = EditorView.x/y, half-extent = orthoSize * aspect
- * by orthoSize), so the fragment's interpolated world position is exact and no
+ * The quad is a unit quad placed by the `u_rect` param (centre = EditorView.x/y,
+ * half-extents = orthoSize * aspect by orthoSize) to cover the camera's visible
+ * world rect, so the fragment's interpolated world position is exact and no
* inverse view-projection is needed. Line width and minor-line density fade are
* driven by `worldPerPixel` (= 2·orthoSize / viewportHeight), so the grid stays
* crisp and moiré-free at every zoom without relying on GLSL derivatives.
*
+ * The shader is a dual-language `.esshader` (GLSL + WGSL twins) on the reflected
+ * `#pragma param` seam: parameters ride the MaterialConstants UBO and the draw
+ * goes through `Draw.drawMeshWithMaterial`'s reflected path, so the grid renders
+ * on every backend.
+ *
* Frontends just install this once and flip the `EditorGrid` resource — the web
* editor and the headless render host (pixel verification) get the grid for free.
*/
@@ -29,93 +34,163 @@ import { registerPreSceneDrawCallback } from '../customDraw';
import { EditorView } from './EditorView';
import { EditorGrid, DEFAULT_EDITOR_GRID } from './EditorGrid';
-// GLSL ES 3.0, so the engine lifts the loose uniforms into its std140
-// DrawParams block — this draw's parameters ride the UBO seam, not per-program
-// uniform uploads.
-const GRID_VERT = `#version 300 es
-in vec2 a_position;
-uniform mat4 u_projection;
-uniform mat4 u_model;
+/** The grid's dual-language material shader (exported for the twins structure guard). */
+export const GRID_ESSHADER = `#pragma shader "EditorGrid"
+#pragma version 300 es
+
+#pragma param u_rect vec4 default(0,0,1,1)
+#pragma param u_gridParams vec4 default(32,10,1,0)
+#pragma param u_minorColor color default(1,1,1,0.05)
+#pragma param u_majorColor color default(1,1,1,0.1)
+#pragma param u_axisXColor color default(0.812,0.357,0.325,0.55)
+#pragma param u_axisYColor color default(0.502,0.725,0.29,0.55)
+
+#pragma vertex
+layout(location = 0) in vec2 a_position;
+
+layout(std140) uniform FrameConstants {
+ mat4 u_projection;
+};
+
out vec2 v_world;
+
void main() {
- vec4 wp = u_model * vec4(a_position, 0.0, 1.0);
- v_world = wp.xy;
- gl_Position = u_projection * wp;
+ // u_rect: xy = view centre, zw = half extents — the unit quad covers the
+ // camera's visible world rect, so v_world interpolates exact world coords.
+ vec2 world = u_rect.xy + a_position * u_rect.zw;
+ v_world = world;
+ gl_Position = u_projection * vec4(world, 0.0, 1.0);
}
-`;
+#pragma end
-const GRID_FRAG = `#version 300 es
+#pragma fragment
precision highp float;
+
in vec2 v_world;
-uniform float u_param0; // minor spacing (world units)
-uniform float u_param1; // major every Nth line
-uniform float u_param2; // worldPerPixel
-uniform vec4 u_color; // minor line color
-uniform vec4 u_vec0; // major line color
-uniform vec4 u_vec1; // X axis (world y=0) color
-uniform vec4 u_vec2; // Y axis (world x=0) color
out vec4 fragColor;
float lineCov(float coord, float sp, float lw, float aa) {
- float d = abs(mod(coord + sp * 0.5, sp) - sp * 0.5);
- return 1.0 - smoothstep(lw, lw + aa, d);
+ float d = abs(mod(coord + sp * 0.5, sp) - sp * 0.5);
+ return 1.0 - smoothstep(lw, lw + aa, d);
}
vec4 over(vec4 top, vec4 bot) {
- float a = top.a + bot.a * (1.0 - top.a);
- if (a <= 0.0) return vec4(0.0);
- vec3 rgb = (top.rgb * top.a + bot.rgb * bot.a * (1.0 - top.a)) / a;
- return vec4(rgb, a);
+ float a = top.a + bot.a * (1.0 - top.a);
+ if (a <= 0.0) return vec4(0.0);
+ vec3 rgb = (top.rgb * top.a + bot.rgb * bot.a * (1.0 - top.a)) / a;
+ return vec4(rgb, a);
}
void main() {
- float sp = u_param0;
- float major = sp * u_param1;
- float aa = u_param2; // ~1px in world units
- float lw = aa * 0.5; // ~1px line
-
- // Fade minor lines out as they crowd below a few pixels apart (anti-moiré).
- float minorFade = smoothstep(3.0, 9.0, sp / max(u_param2, 1e-6));
- float minorC = max(lineCov(v_world.x, sp, lw, aa), lineCov(v_world.y, sp, lw, aa)) * minorFade;
- float majorC = max(lineCov(v_world.x, major, lw, aa), lineCov(v_world.y, major, lw, aa));
- float axisXC = 1.0 - smoothstep(lw, lw + aa, abs(v_world.y)); // world y=0
- float axisYC = 1.0 - smoothstep(lw, lw + aa, abs(v_world.x)); // world x=0
-
- vec4 c = vec4(0.0);
- c = over(vec4(u_color.rgb, u_color.a * minorC), c);
- c = over(vec4(u_vec0.rgb, u_vec0.a * majorC), c);
- c = over(vec4(u_vec1.rgb, u_vec1.a * axisXC), c);
- c = over(vec4(u_vec2.rgb, u_vec2.a * axisYC), c);
- if (c.a <= 0.0) discard;
- fragColor = c;
+ float sp = u_gridParams.x; // minor spacing (world units)
+ float major = sp * u_gridParams.y;
+ float aa = u_gridParams.z; // worldPerPixel, ~1px in world units
+ float lw = aa * 0.5; // ~1px line
+
+ // Fade minor lines out as they crowd below a few pixels apart (anti-moiré).
+ float minorFade = smoothstep(3.0, 9.0, sp / max(aa, 1e-6));
+ float minorC = max(lineCov(v_world.x, sp, lw, aa), lineCov(v_world.y, sp, lw, aa)) * minorFade;
+ float majorC = max(lineCov(v_world.x, major, lw, aa), lineCov(v_world.y, major, lw, aa));
+ float axisXC = 1.0 - smoothstep(lw, lw + aa, abs(v_world.y)); // world y=0
+ float axisYC = 1.0 - smoothstep(lw, lw + aa, abs(v_world.x)); // world x=0
+
+ vec4 c = vec4(0.0);
+ c = over(vec4(u_minorColor.rgb, u_minorColor.a * minorC), c);
+ c = over(vec4(u_majorColor.rgb, u_majorColor.a * majorC), c);
+ c = over(vec4(u_axisXColor.rgb, u_axisXColor.a * axisXC), c);
+ c = over(vec4(u_axisYColor.rgb, u_axisYColor.a * axisYC), c);
+ if (c.a <= 0.0) discard;
+ fragColor = c;
}
+#pragma end
+
+#pragma vertex wgsl
+struct FrameConstants { projection : mat4x4f };
+@group(0) @binding(0) var<uniform> frame : FrameConstants;
+
+struct VSIn { @location(0) a_position : vec2f };
+struct VSOut {
+ @builtin(position) pos : vec4f,
+ @location(0) v_world : vec2f,
+};
+
+@vertex fn vs_main(v : VSIn) -> VSOut {
+ var out : VSOut;
+ let world = mc.u_rect.xy + v.a_position * mc.u_rect.zw;
+ out.v_world = world;
+ out.pos = frame.projection * vec4f(world, 0.0, 1.0);
+ return out;
+}
+#pragma end
+
+#pragma fragment wgsl
+struct VSOut {
+ @builtin(position) pos : vec4f,
+ @location(0) v_world : vec2f,
+};
+
+// GLSL mod(): floor-based remainder (result follows the divisor's sign) — WGSL's
+// % is trunc-based, which would misplace grid lines on the negative world half.
+fn gmod(x : f32, y : f32) -> f32 { return x - y * floor(x / y); }
+
+fn lineCov(coord : f32, sp : f32, lw : f32, aa : f32) -> f32 {
+ let d = abs(gmod(coord + sp * 0.5, sp) - sp * 0.5);
+ return 1.0 - smoothstep(lw, lw + aa, d);
+}
+
+fn over(top : vec4f, bot : vec4f) -> vec4f {
+ let a = top.a + bot.a * (1.0 - top.a);
+ if (a <= 0.0) { return vec4f(0.0, 0.0, 0.0, 0.0); }
+ let rgb = (top.rgb * top.a + bot.rgb * bot.a * (1.0 - top.a)) / a;
+ return vec4f(rgb, a);
+}
+
+@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
+ let sp = mc.u_gridParams.x;
+ let major = sp * mc.u_gridParams.y;
+ let aa = mc.u_gridParams.z;
+ let lw = aa * 0.5;
+
+ let minorFade = smoothstep(3.0, 9.0, sp / max(aa, 1e-6));
+ let minorC = max(lineCov(v.v_world.x, sp, lw, aa), lineCov(v.v_world.y, sp, lw, aa)) * minorFade;
+ let majorC = max(lineCov(v.v_world.x, major, lw, aa), lineCov(v.v_world.y, major, lw, aa));
+ let axisXC = 1.0 - smoothstep(lw, lw + aa, abs(v.v_world.y));
+ let axisYC = 1.0 - smoothstep(lw, lw + aa, abs(v.v_world.x));
+
+ var c = vec4f(0.0, 0.0, 0.0, 0.0);
+ c = over(vec4f(mc.u_minorColor.rgb, mc.u_minorColor.a * minorC), c);
+ c = over(vec4f(mc.u_majorColor.rgb, mc.u_majorColor.a * majorC), c);
+ c = over(vec4f(mc.u_axisXColor.rgb, mc.u_axisXColor.a * axisXC), c);
+ c = over(vec4f(mc.u_axisYColor.rgb, mc.u_axisYColor.a * axisYC), c);
+ if (c.a <= 0.0) { discard; }
+ return c;
+}
+#pragma end
`;
let quad_: GeometryHandle = 0;
let material_: MaterialHandle = 0;
-// Reused column-major translate·scale model matrix (no per-frame allocation).
-const model_ = new Float32Array(16);
+
+// Per-param last-set cache: Material.setUniform re-flushes the whole material on
+// every call, so skipping unchanged values keeps an idle frame at zero pushes.
+const lastSet_ = new Map<string, [number, number, number, number]>();
+
+function setParam(name: string, x: number, y: number, z: number, w: number): void {
+ const prev = lastSet_.get(name);
+ if (prev && prev[0] === x && prev[1] === y && prev[2] === z && prev[3] === w) return;
+ lastSet_.set(name, [x, y, z, w]);
+ Material.setUniform(material_, name, { x, y, z, w });
+}
function ensureResources(): boolean {
if (material_) return true;
- const shader = Material.createShader(GRID_VERT, GRID_FRAG);
+ const shader = Material.compileShader(GRID_ESSHADER);
if (!shader) return false;
quad_ = Geometry.createQuad(2, 2); // [-1, 1] unit quad
material_ = Material.create({ shader, blendMode: BlendMode.Normal, depthTest: false });
return true;
}
-// translate(tx,ty) · scale(sx,sy) as a column-major 4x4.
-function setModel(m: Float32Array, tx: number, ty: number, sx: number, sy: number): void {
- m.fill(0);
- m[0] = sx;
- m[5] = sy;
- m[10] = 1;
- m[15] = 1;
- m[12] = tx;
- m[13] = ty;
-}
-
/**
* Register the editor grid renderer on this App. Idempotent per App: inserts the
* default `EditorGrid` resource if absent and registers the pre-scene draw pass.
@@ -135,16 +210,14 @@ export function installEditorGrid(app: App): void {
const halfH = view.orthoSize;
const halfW = halfH * (width / height);
const worldPerPixel = (2 * halfH) / height;
- setModel(model_, view.x, view.y, halfW, halfH);
- Material.setUniform(material_, 'u_param0', grid.spacing);
- Material.setUniform(material_, 'u_param1', grid.majorEvery);
- Material.setUniform(material_, 'u_param2', worldPerPixel);
- Material.setUniform(material_, 'u_color', grid.color);
- Material.setUniform(material_, 'u_vec0', grid.majorColor);
- Material.setUniform(material_, 'u_vec1', grid.axisX);
- Material.setUniform(material_, 'u_vec2', grid.axisY);
+ setParam('u_rect', view.x, view.y, halfW, halfH);
+ setParam('u_gridParams', grid.spacing, grid.majorEvery, worldPerPixel, 0);
+ setParam('u_minorColor', grid.color[0], grid.color[1], grid.color[2], grid.color[3]);
+ setParam('u_majorColor', grid.majorColor[0], grid.majorColor[1], grid.majorColor[2], grid.majorColor[3]);
+ setParam('u_axisXColor', grid.axisX[0], grid.axisX[1], grid.axisX[2], grid.axisX[3]);
+ setParam('u_axisYColor', grid.axisY[0], grid.axisY[1], grid.axisY[2], grid.axisY[3]);
- Draw.drawMeshWithMaterial(quad_, material_, model_);
+ Draw.drawMeshWithMaterial(quad_, material_);
});
}
diff --git a/sdk/src/draw.ts b/sdk/src/draw.ts
index 3fa3c0109..314c7525a 100644
--- a/sdk/src/draw.ts
+++ b/sdk/src/draw.ts
@@ -32,6 +32,9 @@ let uniformsPtr: number = 0;
const UNIFORMS_BUFFER_SIZE = 256;
const uniformBuffer = new Float32Array(UNIFORMS_BUFFER_SIZE);
+// Identity model matrix for legacy material draws that omit `transform`.
+const IDENTITY_TRANSFORM = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+
// =============================================================================
// Initialization
// =============================================================================
@@ -190,11 +193,19 @@ export interface DrawAPI {
/**
* Draws a custom mesh with a material.
+ *
+ * A material whose shader was compiled from a `.esshader` (Material.compileShader)
+ * draws through the reflected MaterialConstants path: its `#pragma param` values and
+ * render state come straight from the engine material store, the shader positions
+ * itself via the injected FrameConstants (and params), and `transform` is unused —
+ * this path runs on every backend. A raw-GLSL material (Material.createShader) uses
+ * the legacy loose-uniform stream with `u_projection`/`u_model` and `transform`
+ * (identity when omitted).
* @param geometry Geometry handle
* @param material Material handle
- * @param transform Transform matrix (4x4, column-major)
+ * @param transform Transform matrix (4x4, column-major) — legacy raw-GLSL path only
*/
- drawMeshWithMaterial(geometry: GeometryHandle, material: MaterialHandle, transform: Float32Array): void;
+ drawMeshWithMaterial(geometry: GeometryHandle, material: MaterialHandle, transform?: Float32Array): void;
}
// =============================================================================
@@ -359,22 +370,28 @@ export const Draw: DrawAPI = {
}
},
- drawMeshWithMaterial(geometry: GeometryHandle, material: MaterialHandle, transform: Float32Array): void {
+ drawMeshWithMaterial(geometry: GeometryHandle, material: MaterialHandle, transform?: Float32Array): void {
try {
const m = getModule();
const matData = Material.get(material);
if (!matData) return;
+ // Reflected path first: a compileEsshader material draws entirely from the
+ // engine material store (params + render state + pipeline), backend-neutral.
+ // False means the shader has no #pragma-param layout — legacy stream below.
+ if (m.draw_meshWithMaterial(geometry, material)) return;
+
Draw.setBlendMode(matData.blendMode);
Draw.setDepthTest(matData.depthTest);
+ if (transform) m.HEAPF32.set(transform, transformPtr / 4);
+ else m.HEAPF32.set(IDENTITY_TRANSFORM, transformPtr / 4);
+
if (matData.uniforms.size === 0) {
- Draw.drawMesh(geometry, matData.shader, transform);
+ m.draw_mesh(geometry, matData.shader, transformPtr);
return;
}
- m.HEAPF32.set(transform, transformPtr / 4);
-
let idx: number;
if (!matData.dirty_ && matData.cachedBuffer_) {
idx = matData.cachedIdx_;
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index c791f8b6c..87c0150af 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -235,6 +235,9 @@ export interface ESEngineModule {
draw_mesh(geometryHandle: number, shaderHandle: number, transformPtr: number): void;
draw_meshWithUniforms(geometryHandle: number, shaderHandle: number, transformPtr: number,
uniformsPtr: number, uniformCount: number): void;
+ /** Reflected-material mesh draw (MaterialConstants UBO); false = shader has no
+ * #pragma-param layout, caller falls back to the loose uniform stream. */
+ draw_meshWithMaterial(geometryHandle: number, materialId: number): boolean;
// Geometry API
geometry_create(): number;
diff --git a/sdk/tests/draw.test.ts b/sdk/tests/draw.test.ts
index f7912ea68..28734c7ed 100644
--- a/sdk/tests/draw.test.ts
+++ b/sdk/tests/draw.test.ts
@@ -65,6 +65,9 @@ function createDrawMockModule() {
draw_getPrimitiveCount: vi.fn(() => 128),
draw_mesh: vi.fn(),
draw_meshWithUniforms: vi.fn(),
+ // Reflected-material route: false = no #pragma-param layout, use the
+ // legacy uniform stream (most cases below exercise the legacy encoding).
+ draw_meshWithMaterial: vi.fn(() => false),
};
return mock;
@@ -451,6 +454,68 @@ describe('Draw API', () => {
expect(mock.draw_meshWithUniforms).not.toHaveBeenCalled();
});
+ it('routes through the reflected material path when the engine reports a layout', () => {
+ const materials = (Material as any)._materials;
+ materials.set(21, {
+ shader: 10,
+ uniforms: new Map([['u_rect', { x: 1, y: 2, z: 3, w: 4 }]]),
+ blendMode: BlendMode.Additive,
+ depthTest: true,
+ dirty_: true,
+ cachedBuffer_: null,
+ cachedIdx_: 0,
+ });
+ mock.draw_meshWithMaterial.mockReturnValueOnce(true);
+
+ Draw.drawMeshWithMaterial(geometry, 21 as any);
+
+ expect(mock.draw_meshWithMaterial).toHaveBeenCalledWith(geometry, 21);
+ // The engine material store owns render state + params on this path —
+ // no legacy session-state writes, no uniform-stream encoding.
+ expect(mock.draw_setBlendMode).not.toHaveBeenCalled();
+ expect(mock.draw_setDepthTest).not.toHaveBeenCalled();
+ expect(mock.draw_mesh).not.toHaveBeenCalled();
+ expect(mock.draw_meshWithUniforms).not.toHaveBeenCalled();
+ });
+
+ it('falls back to the legacy stream when there is no reflected layout', () => {
+ const materials = (Material as any)._materials;
+ materials.set(22, {
+ shader: 10,
+ uniforms: new Map([['u_time', 1.5]]),
+ blendMode: BlendMode.Normal,
+ depthTest: false,
+ dirty_: true,
+ cachedBuffer_: null,
+ cachedIdx_: 0,
+ });
+
+ Draw.drawMeshWithMaterial(geometry, 22 as any, transform);
+
+ expect(mock.draw_meshWithMaterial).toHaveBeenCalledWith(geometry, 22);
+ expect(mock.draw_meshWithUniforms).toHaveBeenCalled();
+ });
+
+ it('legacy draw uses the identity transform when omitted', () => {
+ const materials = (Material as any)._materials;
+ materials.set(23, {
+ shader: 10,
+ uniforms: new Map(),
+ blendMode: BlendMode.Normal,
+ depthTest: false,
+ dirty_: true,
+ cachedBuffer_: null,
+ cachedIdx_: 0,
+ });
+
+ Draw.drawMeshWithMaterial(geometry, 23 as any);
+
+ expect(mock.draw_mesh).toHaveBeenCalled();
+ const transformP = mock.draw_mesh.mock.calls[0][2];
+ const t = mock.HEAPF32.subarray(transformP / 4, transformP / 4 + 16);
+ expect(Array.from(t)).toEqual([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+ });
+
it('should call drawMesh when material has no uniforms', () => {
const materials = (Material as any)._materials;
materials.set(1, {
diff --git a/sdk/tests/shader-twins.test.ts b/sdk/tests/shader-twins.test.ts
index a146fa8ab..25290e68b 100644
--- a/sdk/tests/shader-twins.test.ts
+++ b/sdk/tests/shader-twins.test.ts
@@ -45,13 +45,16 @@ const CASES: Array<{ name: string; source: string }> = [
...embeddedEsshaders('spriteFilter.ts').map((source, i) => ({ name: `spriteFilter.ts[${i}]`, source })),
...embeddedEsshaders('postprocess/postProcessEffects.ts').map(
(source, i) => ({ name: `postProcessEffects.ts[${i}]`, source })),
+ ...embeddedEsshaders('camera/editorGridRenderer.ts').map(
+ (source, i) => ({ name: `editorGridRenderer.ts[${i}]`, source })),
];
describe('embedded .esshader structure', () => {
- it('found the filter and effect sources', () => {
+ it('found the filter, effect and grid sources', () => {
expect(CASES.filter((c) => c.name.startsWith('filters.ts')).length).toBe(1);
expect(CASES.filter((c) => c.name.startsWith('spriteFilter.ts')).length).toBe(2);
expect(CASES.filter((c) => c.name.startsWith('postProcessEffects.ts')).length).toBe(13);
+ expect(CASES.filter((c) => c.name.startsWith('editorGridRenderer.ts')).length).toBe(1);
});
for (const { name, source } of CASES) {
@@ -64,5 +67,15 @@ describe('embedded .esshader structure', () => {
const wgsl = source.slice(source.indexOf('#pragma fragment wgsl'));
expect(wgsl).toContain('fn fs_main(');
});
+
+ // A shader that authors its own vertex stage (no canonical injection)
+ // must also carry the WGSL vertex twin, or it cannot link on WebGPU.
+ if (/^#pragma vertex\s*$/m.test(source)) {
+ it(`${name}: authored vertex carries a WGSL twin with the vs_main entry point`, () => {
+ expect(source).toContain('#pragma vertex wgsl');
+ const wgsl = source.slice(source.indexOf('#pragma vertex wgsl'));
+ expect(wgsl).toContain('fn vs_main(');
+ });
+ }
}
});
diff --git a/src/esengine/bindings/GeometryBindings.cpp b/src/esengine/bindings/GeometryBindings.cpp
index fafd61823..98daa876d 100644
--- a/src/esengine/bindings/GeometryBindings.cpp
+++ b/src/esengine/bindings/GeometryBindings.cpp
@@ -8,6 +8,7 @@
#include "../renderer/GfxDevice.hpp"
#include "../renderer/CustomGeometry.hpp"
#include "../renderer/Buffer.hpp"
+#include "../renderer/MaterialStore.hpp"
#include "../renderer/RenderContext.hpp"
#include "../renderer/RenderFrame.hpp"
#include "../renderer/ImmediateDraw.hpp"
@@ -30,6 +31,7 @@ static EstellaContext& ctx() { return activeCtx(); }
#define g_immediateDraw (ctx().tryGet<ImmediateDraw>())
#define g_immediateDrawActive (ctx().state().immediate_draw_active)
#define g_currentViewProjection (ctx().state().current_view_projection)
+#define g_renderContext (ctx().tryGet<RenderContext>())
static void flushImmediateDrawIfActive() {
if (g_immediateDrawActive && g_immediateDraw) {
@@ -37,6 +39,20 @@ static void flushImmediateDrawIfActive() {
}
}
+// Bind + submit a custom geometry through the device (indexed or arrays).
+static void drawGeometry(GfxDevice& device, CustomGeometry& geom) {
+ geom.bind(device);
+ if (geom.hasIndices()) {
+ auto* ib = geom.indexBuffer();
+ if (ib) {
+ auto type = ib->is16Bit() ? GfxDataType::UnsignedShort : GfxDataType::UnsignedInt;
+ device.drawElements(geom.getIndexCount(), type, 0);
+ }
+ } else {
+ device.drawArrays(0, geom.getVertexCount());
+ }
+}
+
// A mesh draw's pipeline: the requested shader + this geometry's vertex layout,
// with blend/depth taken from the immediate-draw session state (Draw.setBlendMode /
// setDepthTest apply to mesh draws too). The pipeline cache dedupes repeats.
@@ -159,17 +175,46 @@ void draw_mesh(u32 geometryHandle, u32 shaderHandle, uintptr_t transformPtr) {
shader->setUniform("u_model", transform);
shader->commitParams();
- geom->bind(ctx().require<GfxDevice>());
+ drawGeometry(*g_device, *geom);
+}
+
+bool draw_meshWithMaterial(u32 geometryHandle, u32 materialId) {
+ if (!g_initialized || !g_geometryManager) return false;
+ auto* rc = g_renderContext;
+ if (!rc) return false;
- if (geom->hasIndices()) {
- auto* ib = geom->indexBuffer();
- if (ib) {
- auto type = ib->is16Bit() ? GfxDataType::UnsignedShort : GfxDataType::UnsignedInt;
- g_device->drawElements(geom->getIndexCount(), type, 0);
- }
- } else {
- g_device->drawArrays(0, geom->getVertexCount());
- }
+ // Route through the reflected path only when the material's shader registered a
+ // #pragma-param layout (compileEsshader). A raw-GLSL createShader program has no
+ // layout — return false so the SDK falls back to the legacy uniform-stream path.
+ const MaterialRecord* rec = rc->materials().find(materialId);
+ if (!rec || !rc->materials().layoutFor(rec->shader)) return false;
+
+ auto* geom = g_geometryManager->get(geometryHandle);
+ if (!geom || !geom->isValid()) return true; // routed modern; nothing to draw
+
+ flushImmediateDrawIfActive();
+
+ // The material record supplies the full pipeline state (same resolve as
+ // DrawList::execute); positioning comes from FrameConstants + params in the
+ // shader — no per-draw loose uniforms, so the draw is backend-neutral.
+ GfxDevice& device = *g_device;
+ PipelineDesc desc{};
+ desc.program = ShaderHandle{rec->shader};
+ desc.vertexLayout = geom->layoutHandle();
+ desc.blend = rec->blend;
+ desc.blendEnabled = true;
+ desc.depthTest = rec->depthTest;
+ desc.depthWrite = rec->depthWrite;
+ desc.cullEnabled = rec->cull != CullMode::None;
+ desc.cullFront = rec->cull == CullMode::Front;
+ device.invalidatePipelineCache();
+ device.setPipeline(device.createPipeline(desc));
+
+ // Per-material constants (binding 1): upload-if-dirty + bind, plus texture params.
+ rc->materials().bindForDraw(materialId);
+
+ drawGeometry(device, *geom);
+ return true;
}
void draw_meshWithUniforms(u32 geometryHandle, u32 shaderHandle, uintptr_t transformPtr,
@@ -256,17 +301,7 @@ void draw_meshWithUniforms(u32 geometryHandle, u32 shaderHandle, uintptr_t trans
// shader's DrawParams block; flush + bind them for this draw.
shader->commitParams();
- geom->bind(ctx().require<GfxDevice>());
-
- if (geom->hasIndices()) {
- auto* ib = geom->indexBuffer();
- if (ib) {
- auto type = ib->is16Bit() ? GfxDataType::UnsignedShort : GfxDataType::UnsignedInt;
- g_device->drawElements(geom->getIndexCount(), type, 0);
- }
- } else {
- g_device->drawArrays(0, geom->getVertexCount());
- }
+ drawGeometry(*g_device, *geom);
}
} // namespace esengine
diff --git a/src/esengine/bindings/GeometryBindings.hpp b/src/esengine/bindings/GeometryBindings.hpp
index 8b4c9d463..79235994c 100644
--- a/src/esengine/bindings/GeometryBindings.hpp
+++ b/src/esengine/bindings/GeometryBindings.hpp
@@ -19,6 +19,7 @@ bool geometry_isValid(u32 handle);
void draw_mesh(u32 geometryHandle, u32 shaderHandle, uintptr_t transformPtr);
void draw_meshWithUniforms(u32 geometryHandle, u32 shaderHandle, uintptr_t transformPtr,
uintptr_t uniformsPtr, u32 uniformCount);
+bool draw_meshWithMaterial(u32 geometryHandle, u32 materialId);
} // namespace esengine
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index fdefd10ef..0bbc1ae9a 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -511,6 +511,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("draw_setDepthTest", &esengine::draw_setDepthTest);
emscripten::function("draw_mesh", &esengine::draw_mesh);
emscripten::function("draw_meshWithUniforms", &esengine::draw_meshWithUniforms);
+ emscripten::function("draw_meshWithMaterial", &esengine::draw_meshWithMaterial);
emscripten::function("geometry_create", &esengine::geometry_create);
emscripten::function("geometry_init", &esengine::geometry_init);