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(render): SDF glyph-quad batch submit path (REARCH_GUI P1.3a)

esengine09a65a7d46b3
diff --git a/docs/REARCH_GUI.md b/docs/REARCH_GUI.md
index 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.ts
new file mode 100644
index 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.ts
index 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 cache
invalidateMaterialCache(materialId: number): void;
diff --git a/sdk/tests/ui-text-submit.test.ts b/sdk/tests/ui-text-submit.test.ts
new file mode 100644
index 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.cpp
index 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.hpp
index 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_PARTICLES
void renderer_submitParticles(ecs::Registry& registry);
#endif
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 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.hpp
index 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_SPINE
void submitSpineBatch(
const f32* vertices, i32 vertexCount,
diff --git a/src/esengine/renderer/RenderFrameSubmit.cpp b/src/esengine/renderer/RenderFrameSubmit.cpp
index 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_SPINE
void RenderFrame::submitSpineBatch(
const f32* vertices, i32 vertexCount,