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(render): SDF glyph-quad batch submit path (REARCH_GUI P1.3a)
esengine09a65a7d46b3
diff --git a/docs/REARCH_GUI.md b/docs/REARCH_GUI.mdindex eb850fd54..86efaba15 100644--- a/docs/REARCH_GUI.md+++ b/docs/REARCH_GUI.md@@ -159,9 +159,10 @@ PostUpdate: ScrollView → RenderOrder → Render(DrawList)3. **TS `GlyphAtlas` 管理器**:shelf/skyline 装箱 + 字形缓存(键=font/size-bucket/codepoint/style);miss→Canvas2D 栅格→C++ SDF→装箱→子上传→把字形 metrics 注册进 C++ DynamicFont。4. **C++ `DynamicFont`**:把 `BitmapFont` 泛化为运行时可加字形(id,x,y,w,h,offsets,advance)+ isSDF + pxRange。-### 7.3 管线接入-- TS **glyph-prepare 系统**(PreUpdate,布局前):扫可见 `UIText`,确保所需字形已在图集(栅格 miss),每帧限量栅格防卡顿(聊天爆发场景)。-- C++ `TextPlugin` 读 `UIText` + DynamicFont → 用 SDF 变体发字形 quad。+### 7.3 管线接入(决策:TS 中心,方案 B —— 实现期定)+两种接法:**A C++ 中心**(C++ TextPlugin 读组件 + DynamicFont,需逐字形 binding + 在 C++/TS 两处重复 metrics);**B TS 中心**(TS 已有 GlyphAtlas 持全 metrics → TS 布局 + 生成字形 quad → 经一个通用 `submitTextBatch` 提交,C++ 只批渲染)。**选 B**:复用已验证的 spine TS-提交模式、单一 metrics 事实源(DRY)、无 DynamicFont/无逐字形 binding、富文本天然在 TS。+- C++ `RenderFrame::submitTextBatch`(仿 `submitSpineBatch`,但走 `batchProgram({"SDF"})` + RenderType::Text;非门控)+ `renderer_submitTextBatch` binding + TS `ui/text/submit.ts`(HEAPU8 字节拷贝,因该 wasm 仅导出 HEAPU8)。+- TS **文本系统**(pre-flush 回调):扫可见文本实体 → glyph-prepare(GlyphAtlas 备字形,限量/帧)→ 布局 → 生成 quad → `submitTextBatch`。### 7.4 组件统一- **`UIText`**(并 BitmapText + `core/text.ts` Text):text/font/fontSize/color/align/wrap + outlineColor/Width + shadowColor/Offset/Blur + richText(flag)。替换两者。@@ -170,7 +171,7 @@ PostUpdate: ScrollView → RenderOrder → Render(DrawList)- **P1.0** 图集子区域基元(`Texture::updateSubRegion` + binding + TS 封装)。- **P1.1** GlyphAtlas 管理器 + SDF 生成(C++ 8SSEDT binding + TS 栅格/装箱/缓存)。- **P1.2** SDF shader 变体(median/smoothstep + pxRange + outline/shadow uniforms)。-- **P1.3** DynamicFont + `UIText` 简单路径 + glyph-prepare → 端到端清晰批量 CJK 简单文本;headless 验 draw call↓ + 清晰度。+- **P1.3** TS 中心(方案 B):①`submitTextBatch` 提交基元(C+++binding+TS,DONE)→ ②真 `CanvasGlyphRasterizer`+`EngineAtlasPageStore` 接 GlyphAtlas → ③ TS 文本系统(pre-flush:glyph-prepare+布局+生成 quad+提交)→ 端到端清晰批量 CJK 文本;headless 渲染验 draw call↓ + 清晰度。- **P1.4** 富文本(TS 布局 runs)+ SDF 描边/阴影;`core/text.ts` Text→`UIText`;退役 Canvas2D-每实体路径。- **P1.5** TextInput 接新路径(光标/选区/IME overlay)。- **P1.6** 退役 BitmapText(debug overlay 迁移或保留);shim 统一 P4 删。diff --git a/sdk/src/ui/text/submit.ts b/sdk/src/ui/text/submit.tsnew file mode 100644index 000000000..fc93263f0--- /dev/null+++ b/sdk/src/ui/text/submit.ts@@ -0,0 +1,50 @@+/**+ * @file ui/text/submit.ts+ * @brief TS → engine submission for pre-laid-out SDF glyph quads (REARCH_GUI+ * P1.3). The text system lays glyphs out against the dynamic atlas in+ * TS, then hands the batch here; the engine routes it through the SDF+ * batch-shader variant. Mirrors the proven spine mesh-submit path.+ */+import type { ESEngineModule } from '../../wasm';+import { withScratch } from '../../wasmScratch';++/** Floats per glyph vertex: position(2) + uv(2) + color(4). */+export const TEXT_VERTEX_FLOATS = 8;++/**+ * Submit a batch of glyph quads. `vertices` is `TEXT_VERTEX_FLOATS` floats per+ * vertex (x,y,u,v,r,g,b,a); `indices` reference those vertices; `transform` is a+ * column-major mat4 applied to vertex positions (pass identity if positions are+ * already world-space). No-op if the engine build lacks the binding.+ */+export function submitTextBatch(+ module: ESEngineModule,+ vertices: Float32Array,+ indices: Uint16Array,+ textureId: number,+ transform: Float32Array,+ entity: number,+ layer: number,+ depth: number,+): void {+ if (!module.renderer_submitTextBatch) return;+ const vertexCount = (vertices.length / TEXT_VERTEX_FLOATS) | 0;+ if (vertexCount <= 0 || indices.length <= 0 || transform.length < 16) return;++ // Copy through HEAPU8 (the one heap view emscripten reliably exports here)+ // as raw bytes; _malloc is ≥8-byte aligned so the C++ f32/u16 reads are fine.+ const vBytes = new Uint8Array(vertices.buffer, vertices.byteOffset, vertices.byteLength);+ const iBytes = new Uint8Array(indices.buffer, indices.byteOffset, indices.byteLength);+ const tBytes = new Uint8Array(transform.buffer, transform.byteOffset, 16 * 4);+ withScratch(module, alloc => {+ const vPtr = alloc(vBytes.byteLength);+ const iPtr = alloc(iBytes.byteLength);+ const tPtr = alloc(tBytes.byteLength);+ module.HEAPU8.set(vBytes, vPtr);+ module.HEAPU8.set(iBytes, iPtr);+ module.HEAPU8.set(tBytes, tPtr);+ module.renderer_submitTextBatch!(+ vPtr, vertexCount, iPtr, indices.length, textureId, tPtr, entity, layer, depth,+ );+ });+}diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex adc06ed8b..5d13a53d6 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -141,6 +141,16 @@ export interface ESEngineModule {entity: number, skelScale: number, flipX: boolean, flipY: boolean,layer: number, depth: number): void;+ /**+ * Submit pre-laid-out glyph quads against the dynamic SDF atlas (REARCH_GUI+ * P1.3). Vertex format x,y,u,v,r,g,b,a; routed through the SDF batch variant.+ */+ renderer_submitTextBatch?(+ verticesPtr: number, vertexCount: number,+ indicesPtr: number, indexCount: number,+ textureId: number, transformPtr: number,+ entity: number, layer: number, depth: number+ ): void;// Material cacheinvalidateMaterialCache(materialId: number): void;diff --git a/sdk/tests/ui-text-submit.test.ts b/sdk/tests/ui-text-submit.test.tsnew file mode 100644index 000000000..c2f632387--- /dev/null+++ b/sdk/tests/ui-text-submit.test.ts@@ -0,0 +1,31 @@+/**+ * @file REARCH_GUI P1.3a — verifies the SDF glyph-quad submit binding+ * (renderer_submitTextBatch) is registered on the engine module. The+ * actual batched draw needs a GL frame (covered end-to-end at P1.3c via+ * the headless render host); here we confirm the C++ submitTextBatch ++ * binding + registration compiled and is reachable from TS.+ *+ * Requires the built WASM SDK (build/wasm/web). Skips if absent.+ */+import { describe, it, expect, beforeAll } from 'vitest';+import type { ESEngineModule } from '../src/wasm';+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';++describe.skipIf(!HAS_WASM)('REARCH_GUI P1.3a: text batch submit binding', () => {+ let module: ESEngineModule;+ beforeAll(async () => { module = await loadWasmModule(); });++ it('module exposes renderer_submitTextBatch (embind registered, ungated)', () => {+ expect(typeof (module as unknown as { renderer_submitTextBatch?: unknown })+ .renderer_submitTextBatch).toBe('function');+ });++ it('the TS wrapper no-ops safely without a render frame (guards, no throw)', async () => {+ const { submitTextBatch } = await import('../src/ui/text/submit');+ const verts = new Float32Array(4 * 8); // one quad+ const idx = new Uint16Array([0, 1, 2, 0, 2, 3]);+ const xform = new Float32Array(16); xform[0] = xform[5] = xform[10] = xform[15] = 1;+ // No active render frame headless → binding guards (g_renderFrame null) → no draw, no throw.+ expect(() => submitTextBatch(module, verts, idx, 1, xform, 0, 0, 0)).not.toThrow();+ });+});diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cppindex 944d819f1..1261d6369 100644--- a/src/esengine/bindings/RendererBindings.cpp+++ b/src/esengine/bindings/RendererBindings.cpp@@ -105,6 +105,23 @@ void renderer_submitSpineBatchByEntity(#endif+// REARCH_GUI P1.3: TS lays out glyph quads against the dynamic SDF atlas and+// submits them here (ungated — text is core, unlike spine).+void renderer_submitTextBatch(+ uintptr_t verticesPtr, i32 vertexCount,+ uintptr_t indicesPtr, i32 indexCount,+ u32 textureId, uintptr_t transformPtr,+ u32 entity, i32 layer, f32 depth+) {+ if (!g_initialized || !g_renderFrame) return;+ auto* vertices = reinterpret_cast<const f32*>(verticesPtr);+ auto* indices = reinterpret_cast<const u16*>(indicesPtr);+ auto* transform = reinterpret_cast<const f32*>(transformPtr);+ g_renderFrame->submitTextBatch(+ vertices, vertexCount, indices, indexCount,+ textureId, transform, Entity::fromRaw(entity), layer, depth);+}+void renderFrame(ecs::Registry& registry, i32 viewportWidth, i32 viewportHeight) {if (!g_initialized || !g_renderFrame) return;diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hppindex 17b5248b3..14ec856dd 100644--- a/src/esengine/bindings/RendererBindings.hpp+++ b/src/esengine/bindings/RendererBindings.hpp@@ -70,6 +70,12 @@ void renderer_submitSpineBatchByEntity(i32 layer, f32 depth);#endif+void renderer_submitTextBatch(+ uintptr_t verticesPtr, i32 vertexCount,+ uintptr_t indicesPtr, i32 indexCount,+ u32 textureId, uintptr_t transformPtr,+ u32 entity, i32 layer, f32 depth+);#ifdef ES_ENABLE_PARTICLESvoid renderer_submitParticles(ecs::Registry& registry);#endifdiff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex 54a67c4d6..b210b6971 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -374,6 +374,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {emscripten::function("renderer_submitSpineBatch", &esengine::renderer_submitSpineBatch);emscripten::function("renderer_submitSpineBatchByEntity", &esengine::renderer_submitSpineBatchByEntity);#endif+ emscripten::function("renderer_submitTextBatch", &esengine::renderer_submitTextBatch);emscripten::function("invalidateMaterialCache", &esengine::invalidateMaterialCache);emscripten::function("clearMaterialCache", &esengine::clearMaterialCache);diff --git a/src/esengine/renderer/RenderFrame.hpp b/src/esengine/renderer/RenderFrame.hppindex a91343585..ca10d0f17 100644--- a/src/esengine/renderer/RenderFrame.hpp+++ b/src/esengine/renderer/RenderFrame.hpp@@ -85,6 +85,19 @@ public:Entity entity, i32 layer, f32 depth);+ /**+ * Submit a batch of pre-laid-out glyph quads from TS (REARCH_GUI P1.3, the+ * dynamic SDF glyph atlas). Same vertex format as submitSpineBatch+ * (x,y,u,v,r,g,b,a per vertex) but routed through the SDF batch variant+ * (batchProgram({"SDF"})) with RenderType::Text. The atlas page is `textureId`.+ */+ void submitTextBatch(+ const f32* vertices, i32 vertexCount,+ const u16* indices, i32 indexCount,+ u32 textureId, const f32* transform16,+ Entity entity, i32 layer, f32 depth+ );+#ifdef ES_ENABLE_SPINEvoid submitSpineBatch(const f32* vertices, i32 vertexCount,diff --git a/src/esengine/renderer/RenderFrameSubmit.cpp b/src/esengine/renderer/RenderFrameSubmit.cppindex 4763e426d..22b39020d 100644--- a/src/esengine/renderer/RenderFrameSubmit.cpp+++ b/src/esengine/renderer/RenderFrameSubmit.cpp@@ -37,6 +37,43 @@ void RenderFrame::submitTileQuad(});}+void RenderFrame::submitTextBatch(+ const f32* vertices, i32 vertexCount,+ const u16* indices, i32 indexCount,+ u32 textureId, const f32* transform16,+ Entity entity, i32 layer, f32 depth+) {+ if (vertexCount <= 0 || indexCount <= 0) return;++ constexpr i32 FLOATS_PER_VERTEX = 8; // x, y, u, v, r, g, b, a+ glm::mat4 model = glm::make_mat4(transform16);++ u32 vBytes = static_cast<u32>(vertexCount) * sizeof(BatchVertex);+ u32 vOff = pool_.allocVertices(LayoutId::Batch, vBytes);+ auto* dst = reinterpret_cast<BatchVertex*>(pool_.vertexData(LayoutId::Batch) + vOff);++ for (i32 i = 0; i < vertexCount; ++i) {+ const f32* v = vertices + i * FLOATS_PER_VERTEX;+ glm::vec4 worldPos = model * glm::vec4(v[0], v[1], 0.0f, 1.0f);+ u32 pc = packColor(glm::vec4(v[4], v[5], v[6], v[7]));+ dst[i] = { {worldPos.x, worldPos.y}, pc, {v[2], v[3]} };+ }++ // Glyph atlas is SDF — route through the SDF batch variant. Text uses normal+ // alpha blending; coverage comes from the shader, not the source alpha curve.+ pushBatchCommand(pool_, draw_list_, clip_state_, vOff, static_cast<u32>(vertexCount), indices,+ static_cast<u32>(indexCount), BatchDrawKey{+ .stage = current_stage_,+ .layer = layer,+ .shaderId = batchProgram({"SDF"}),+ .blend = BlendMode::Normal,+ .textureId = textureId,+ .depth = depth,+ .entity = entity,+ .type = RenderType::Text,+ });+}+#ifdef ES_ENABLE_SPINEvoid RenderFrame::submitSpineBatch(const f32* vertices, i32 vertexCount,