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(ui/text): device-resolution bitmap glyph path for crisp UI text
yhhe09b52f98296
diff --git a/sdk/src/ui/text/glyph-atlas.ts b/sdk/src/ui/text/glyph-atlas.tsindex 646cd66d0..dfeff4c0c 100644--- a/sdk/src/ui/text/glyph-atlas.ts+++ b/sdk/src/ui/text/glyph-atlas.ts@@ -37,9 +37,11 @@ export interface GlyphRasterizer {readonly renderSize: number;/*** Render one glyph to an upload-ready bitmap + metrics, or null if the glyph- * cannot be produced (unknown codepoint / no font).+ * cannot be produced (unknown codepoint / no font). `pixelSize` overrides the+ * rasterization size (bitmap mode rasterizes per display size); omitted → the+ * rasterizer's default renderSize.*/- rasterize(codepoint: number, fontFamily: string, style: number): RasterGlyph | null;+ rasterize(codepoint: number, fontFamily: string, style: number, pixelSize?: number): RasterGlyph | null;}export interface AtlasPageStore {@@ -68,6 +70,10 @@ export interface GlyphAtlasOptions {pageSize?: number;/** Gutter between glyphs to prevent bilinear bleed. Default 1. */padding?: number;+ /** SDF (one fixed source, scalable) vs bitmap (per-size, device density). Default true. */+ sdf?: boolean;+ /** Device pixel ratio for bitmap per-size rasterization. Default 1. */+ dpr?: number;}const STYLE_COUNT_HINT = 4; // plain / bold / italic / bold-italic — for key spread only@@ -78,6 +84,8 @@ const STYLE_COUNT_HINT = 4; // plain / bold / italic / bold-italic — for keyexport class GlyphAtlas {private readonly pageSize: number;private readonly padding: number;+ private readonly sdf: boolean;+ private readonly dpr: number;private readonly cache = new Map<string, GlyphEntry | null>();private readonly pages: number[] = [];private readonly packers: Packer[] = [];@@ -89,6 +97,8 @@ export class GlyphAtlas {) {this.pageSize = opts.pageSize ?? 1024;this.padding = opts.padding ?? 1;+ this.sdf = opts.sdf ?? true;+ this.dpr = opts.dpr ?? 1;}/** Number of atlas pages currently allocated. */@@ -97,8 +107,14 @@ export class GlyphAtlas {/** The px size glyphs are rasterized at; layout scales by displaySize/renderSize. */get renderSize(): number { return this.rasterizer.renderSize; }- private key(codepoint: number, fontFamily: string, style: number): string {- return `${fontFamily}|${codepoint}|${style % STYLE_COUNT_HINT}`;+ /** Rasterization size for a display size: SDF uses one fixed resolution-independent+ * source; bitmap rasterizes per size at device density for a crisp 1:1 blit. */+ pixelSizeFor(displaySize: number): number {+ return this.sdf ? this.renderSize : Math.max(1, Math.round(displaySize * this.dpr));+ }++ private key(codepoint: number, fontFamily: string, style: number, pixelSize: number): string {+ return `${fontFamily}|${codepoint}|${style % STYLE_COUNT_HINT}|${pixelSize}`;}/**@@ -106,12 +122,12 @@ export class GlyphAtlas {* null for glyphs the rasterizer cannot produce (caller skips / uses fallback).* The result is cached (including the null), so a miss is paid once.*/- getGlyph(codepoint: number, fontFamily: string, style = 0): GlyphEntry | null {- const k = this.key(codepoint, fontFamily, style);+ getGlyph(codepoint: number, fontFamily: string, style = 0, pixelSize = this.renderSize): GlyphEntry | null {+ const k = this.key(codepoint, fontFamily, style, pixelSize);const hit = this.cache.get(k);if (hit !== undefined) return hit;- const raster = this.rasterizer.rasterize(codepoint, fontFamily, style);+ const raster = this.rasterizer.rasterize(codepoint, fontFamily, style, pixelSize);if (!raster) {this.cache.set(k, null);return null;diff --git a/sdk/src/ui/text/glyph-rasterizer.ts b/sdk/src/ui/text/glyph-rasterizer.tsindex 6eb548a91..605585f9c 100644--- a/sdk/src/ui/text/glyph-rasterizer.ts+++ b/sdk/src/ui/text/glyph-rasterizer.ts@@ -44,6 +44,8 @@ export interface CanvasGlyphRasterizerOptions {renderSize?: number;/** SDF spread / padding around the glyph ink, in px. Default 6. */padding?: number;+ /** Produce an SDF (scalable) vs a plain-alpha bitmap (native AA). Default true. */+ sdf?: boolean;}type Canvas2D = HTMLCanvasElement | OffscreenCanvas;@@ -53,6 +55,7 @@ export class CanvasGlyphRasterizer implements GlyphRasterizer {readonly renderSize: number;private readonly module: ESEngineModule;private readonly pad: number;+ private readonly sdf: boolean;private readonly canvas: Canvas2D;private readonly ctx: Ctx2D | null;@@ -60,20 +63,21 @@ export class CanvasGlyphRasterizer implements GlyphRasterizer {this.module = module;this.renderSize = opts.renderSize ?? 48;this.pad = opts.padding ?? 6;+ this.sdf = opts.sdf ?? true;// Scratch canvas sized for the largest glyph (em + ascenders + padding).const dim = Math.ceil(this.renderSize * 2 + this.pad * 2);this.canvas = platformCreateCanvas(dim, dim);this.ctx = this.canvas.getContext('2d', { willReadFrequently: true }) as Ctx2D | null;}- rasterize(codepoint: number, fontFamily: string, style: number): RasterGlyph | null {+ rasterize(codepoint: number, fontFamily: string, style: number, pixelSize = this.renderSize): RasterGlyph | null {const ctx = this.ctx;if (!ctx) return null;const ch = String.fromCodePoint(codepoint);const weight = (style & FONT_STYLE_BOLD) ? 'bold ' : '';const italic = (style & FONT_STYLE_ITALIC) ? 'italic ' : '';- ctx.font = `${italic}${weight}${this.renderSize}px ${fontFamily}`;+ ctx.font = `${italic}${weight}${pixelSize}px ${fontFamily}`;ctx.textBaseline = 'alphabetic';ctx.textAlign = 'left';@@ -81,8 +85,8 @@ export class CanvasGlyphRasterizer implements GlyphRasterizer {const advance = m.width;const left = m.actualBoundingBoxLeft ?? 0;const right = m.actualBoundingBoxRight ?? advance;- const ascent = m.actualBoundingBoxAscent ?? this.renderSize * 0.8;- const descent = m.actualBoundingBoxDescent ?? this.renderSize * 0.2;+ const ascent = m.actualBoundingBoxAscent ?? pixelSize * 0.8;+ const descent = m.actualBoundingBoxDescent ?? pixelSize * 0.2;const inkW = Math.ceil(left + right);const inkH = Math.ceil(ascent + descent);@@ -102,11 +106,17 @@ export class CanvasGlyphRasterizer implements GlyphRasterizer {const img = ctx.getImageData(0, 0, w, h);const alpha = extractAlpha(img.data, w, h);- const sdf = sdfFromAlpha(this.module, alpha, w, h, pad);- if (!sdf) return null;+ // SDF: convert to a distance field (scalable). Bitmap: keep the native-AA+ // coverage as-is for a crisp 1:1 blit. Both pack as (RGB=255, A=coverage).+ let coverage = alpha;+ if (this.sdf) {+ const sdf = sdfFromAlpha(this.module, alpha, w, h, pad);+ if (!sdf) return null;+ coverage = sdf;+ }return {- pixels: sdfToAtlasRgba(sdf, w, h),+ pixels: sdfToAtlasRgba(coverage, w, h),width: w,height: h,advance,diff --git a/sdk/src/ui/text/layout.ts b/sdk/src/ui/text/layout.tsindex 07ab731a2..44091ac2e 100644--- a/sdk/src/ui/text/layout.ts+++ b/sdk/src/ui/text/layout.ts@@ -57,7 +57,8 @@ export function layoutLine(opts: TextLayoutOptions,style = 0,): TextLayout {- const scale = opts.fontSizePx / atlas.renderSize;+ const pixelSize = atlas.pixelSizeFor(opts.fontSizePx);+ const scale = opts.fontSizePx / pixelSize;const spacing = opts.letterSpacing ?? 0;const glyphs: LaidGlyph[] = [];let penX = 0;@@ -65,7 +66,7 @@ export function layoutLine(for (const ch of text) {const cp = ch.codePointAt(0);if (cp === undefined) continue;- const g = atlas.getGlyph(cp, fontFamily, style);+ const g = atlas.getGlyph(cp, fontFamily, style, pixelSize);if (!g) continue;if (g.width > 0 && g.height > 0) {@@ -159,12 +160,13 @@ export interface MultilineTextOptions extends TextLayoutOptions {export function measureWidth(text: string, atlas: GlyphAtlas, fontFamily: string, fontSizePx: number, style: number, letterSpacing = 0,): number {- const scale = fontSizePx / atlas.renderSize;+ const pixelSize = atlas.pixelSizeFor(fontSizePx);+ const scale = fontSizePx / pixelSize;let w = 0;for (const ch of text) {const cp = ch.codePointAt(0);if (cp === undefined) continue;- const g = atlas.getGlyph(cp, fontFamily, style);+ const g = atlas.getGlyph(cp, fontFamily, style, pixelSize);if (g) w += g.advance * scale + letterSpacing;}return w;@@ -275,7 +277,8 @@ export function layoutRichLine(for (const run of parseRichText(content)) {if (run.type !== 'text') continue; // embedded images: deferredconst runSize = run.fontSize ?? opts.fontSizePx;- const scale = runSize / atlas.renderSize;+ const pixelSize = atlas.pixelSizeFor(runSize);+ const scale = runSize / pixelSize;const style = baseStyle | (run.bold ? UI_TEXT_BOLD : 0) | (run.italic ? UI_TEXT_ITALIC : 0);const color: RGBA = run.color? [run.color.r, run.color.g, run.color.b, run.color.a]@@ -285,7 +288,7 @@ export function layoutRichLine(for (const ch of run.text) {const cp = ch.codePointAt(0);if (cp === undefined) continue;- const gph = atlas.getGlyph(cp, fontFamily, style);+ const gph = atlas.getGlyph(cp, fontFamily, style, pixelSize);if (!gph) continue;if (gph.width > 0 && gph.height > 0) {const x0 = penX + gph.bearingX * scale;diff --git a/sdk/src/ui/text/plugin.ts b/sdk/src/ui/text/plugin.tsindex 61b2c5e9a..7e5bc1e9a 100644--- a/sdk/src/ui/text/plugin.ts+++ b/sdk/src/ui/text/plugin.ts@@ -20,6 +20,11 @@ import { composeTRS, rectTextBox, UI_TEXT_BOLD, UI_TEXT_ITALIC } from './text-trimport { Text, type TextData } from '../core/text';import { UINode } from '../core/ui-node';import { getUINodeWidth, getUINodeHeight, ensureUIVisual } from '../util/helpers';+import { platformDevicePixelRatio } from '../../platform';++// Base glyph rasterization size in CSS px; the real source is this × DPR so text+// stays crisp on HiDPI displays. 64 covers common UI sizes at 1:1 or finer.+const GLYPH_BASE_SIZE = 64;// Matches C++ UIElementPlugin::UI_BASE_LAYER — UI quads use layer = base + uiOrder.const UI_BASE_LAYER = 1000;@@ -58,7 +63,13 @@ export class TextPlugin implements Plugin {if (!t.content) continue;if (!this.renderer_) {- this.renderer_ = new SdfTextRenderer(app.wasmModule as ESEngineModule);+ // Device-resolution bitmap text: glyphs rasterize per size at DPR+ // and blit 1:1, keeping Canvas's native AA — crisp like the DOM.+ // (SDF stays available via sdf:true for scalable / world text.)+ const dpr = platformDevicePixelRatio();+ this.renderer_ = new SdfTextRenderer(app.wasmModule as ESEngineModule, {+ sdf: false, dpr, renderSize: Math.round(GLYPH_BASE_SIZE * dpr),+ });}const tr = world.get(entity, Transform) as TransformData;composeTRS(this.matrix_, tr.worldPosition, tr.worldRotation, tr.worldScale);diff --git a/sdk/src/ui/text/submit.ts b/sdk/src/ui/text/submit.tsindex 2d082d35d..477c7f698 100644--- a/sdk/src/ui/text/submit.ts+++ b/sdk/src/ui/text/submit.ts@@ -28,6 +28,7 @@ export function submitTextBatch(entity: number,layer: number,depth: number,+ sdf: boolean,): void {if (!module.renderer_submitTextBatch) return;const vertexCount = (vertices.length / TEXT_VERTEX_FLOATS) | 0;@@ -46,7 +47,7 @@ export function submitTextBatch(module.HEAPU8.set(iBytes, iPtr);module.HEAPU8.set(tBytes, tPtr);module.renderer_submitTextBatch!(- vPtr, vertexCount, iPtr, indices.length, textureId, tPtr, entity, layer, depth,+ vPtr, vertexCount, iPtr, indices.length, textureId, tPtr, entity, layer, depth, sdf ? 1 : 0,);});}diff --git a/sdk/src/ui/text/text-renderer.ts b/sdk/src/ui/text/text-renderer.tsindex 81da66ded..ad46b087b 100644--- a/sdk/src/ui/text/text-renderer.ts+++ b/sdk/src/ui/text/text-renderer.ts@@ -117,16 +117,20 @@ export function drawTextWith(atlas: GlyphAtlas, sink: GlyphBatchSink, p: DrawTexexport interface TextRendererOptions extends CanvasGlyphRasterizerOptions {/** Atlas page size in texels. Default 1024. */pageSize?: number;+ /** Device pixel ratio for bitmap-mode per-size rasterization. Default 1. */+ dpr?: number;}export class SdfTextRenderer {readonly atlas: GlyphAtlas;+ private readonly sdf: boolean;constructor(private readonly module: ESEngineModule, opts: TextRendererOptions = {}) {+ this.sdf = opts.sdf ?? true;this.atlas = new GlyphAtlas(new CanvasGlyphRasterizer(module, opts),new EngineAtlasPageStore(module),- { pageSize: opts.pageSize },+ { pageSize: opts.pageSize, sdf: this.sdf, dpr: opts.dpr },);}@@ -142,7 +146,7 @@ export class SdfTextRenderer {depth: number,): void {drawTextWith(this.atlas, (vertices, indices, pageId) => {- submitTextBatch(this.module, vertices, indices, pageId, transform, entity, layer, depth);+ submitTextBatch(this.module, vertices, indices, pageId, transform, entity, layer, depth, this.sdf);}, p);}}diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex e25acebd4..b1c77ea18 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -150,14 +150,14 @@ export interface ESEngineModule {layer: number, depth: number): void;/**- * Submit pre-laid-out glyph quads against the dynamic SDF atlas.- * Vertex format x,y,u,v,r,g,b,a; routed through the SDF batch variant.+ * Submit pre-laid-out glyph quads. Vertex format x,y,u,v,r,g,b,a; `sdf` (1/0)+ * selects the SDF variant vs the plain textured batch (device bitmap atlas).*/renderer_submitTextBatch?(verticesPtr: number, vertexCount: number,indicesPtr: number, indexCount: number,textureId: number, transformPtr: number,- entity: number, layer: number, depth: number+ entity: number, layer: number, depth: number, sdf: number): void;// Material store (engine-side resolved render state, keyed by material handle).diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cppindex de01e19b1..6b7a83d75 100644--- a/src/esengine/bindings/RendererBindings.cpp+++ b/src/esengine/bindings/RendererBindings.cpp@@ -115,7 +115,7 @@ void renderer_submitTextBatch(uintptr_t verticesPtr, i32 vertexCount,uintptr_t indicesPtr, i32 indexCount,u32 textureId, uintptr_t transformPtr,- u32 entity, i32 layer, f32 depth+ u32 entity, i32 layer, f32 depth, i32 sdf) {if (!g_initialized || !g_renderFrame) return;auto* vertices = reinterpret_cast<const f32*>(verticesPtr);@@ -123,7 +123,7 @@ void renderer_submitTextBatch(auto* transform = reinterpret_cast<const f32*>(transformPtr);g_renderFrame->submitTextBatch(vertices, vertexCount, indices, indexCount,- textureId, transform, Entity::fromRaw(entity), layer, depth);+ textureId, transform, Entity::fromRaw(entity), layer, depth, sdf != 0);}void renderFrame(ecs::Registry& registry, i32 viewportWidth, i32 viewportHeight) {diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hppindex e18d500ee..f7da2343f 100644--- a/src/esengine/bindings/RendererBindings.hpp+++ b/src/esengine/bindings/RendererBindings.hpp@@ -76,7 +76,7 @@ void renderer_submitTextBatch(uintptr_t verticesPtr, i32 vertexCount,uintptr_t indicesPtr, i32 indexCount,u32 textureId, uintptr_t transformPtr,- u32 entity, i32 layer, f32 depth+ u32 entity, i32 layer, f32 depth, i32 sdf);#ifdef ES_ENABLE_PARTICLESvoid renderer_submitParticles(ecs::Registry& registry);diff --git a/src/esengine/data/shaders/batch.esshader b/src/esengine/data/shaders/batch.esshaderindex 3a879d7fe..793da15f5 100644--- a/src/esengine/data/shaders/batch.esshader+++ b/src/esengine/data/shaders/batch.esshader@@ -29,7 +29,9 @@ void main() {#pragma end#pragma fragment-precision mediump float;+// highp: the SDF text branch needs precise distance + fwidth derivatives, and+// sprite sampling is unaffected by the wider range.+precision highp float;in vec4 v_color;in vec2 v_texCoord;@@ -54,8 +56,9 @@ void main() {else texColor = texture(u_textures[7], v_texCoord);#ifdef SDF// The glyph atlas stores a signed distance in the alpha channel (RGB = 1).- // Recover ~1px screen-space coverage with a smoothstep around the 0.5 edge;- // fwidth tracks the on-screen scale so glyphs stay crisp at any size.+ // fwidth tracks the on-screen scale, so a full-fwidth smoothstep band keeps a+ // stable ~1px antialiased edge at any size (this is the scalable SDF path;+ // crisp UI text uses the device-resolution bitmap batch instead).float dist = texColor.a;float aa = fwidth(dist);float coverage = smoothstep(0.5 - aa, 0.5 + aa, dist);diff --git a/src/esengine/renderer/RenderFrame.hpp b/src/esengine/renderer/RenderFrame.hppindex 383e8f473..200a7fcba 100644--- a/src/esengine/renderer/RenderFrame.hpp+++ b/src/esengine/renderer/RenderFrame.hpp@@ -88,16 +88,17 @@ public:);/**- * Submit a batch of pre-laid-out glyph quads from TS (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`.+ * Submit a batch of pre-laid-out glyph quads from TS. Same vertex format as+ * submitSpineBatch (x,y,u,v,r,g,b,a per vertex), RenderType::Text, atlas page+ * = `textureId`. `sdf` picks the shader: true → the SDF variant (scalable SDF+ * atlas); false → the plain textured batch (device-resolution bitmap atlas+ * carrying native-AA coverage in alpha).*/void submitTextBatch(const f32* vertices, i32 vertexCount,const u16* indices, i32 indexCount,u32 textureId, const f32* transform16,- Entity entity, i32 layer, f32 depth+ Entity entity, i32 layer, f32 depth, bool sdf);#ifdef ES_ENABLE_SPINEdiff --git a/src/esengine/renderer/RenderFrameSubmit.cpp b/src/esengine/renderer/RenderFrameSubmit.cppindex d58a48ff6..6f04496c5 100644--- a/src/esengine/renderer/RenderFrameSubmit.cpp+++ b/src/esengine/renderer/RenderFrameSubmit.cpp@@ -43,7 +43,7 @@ void RenderFrame::submitTextBatch(const f32* vertices, i32 vertexCount,const u16* indices, i32 indexCount,u32 textureId, const f32* transform16,- Entity entity, i32 layer, f32 depth+ Entity entity, i32 layer, f32 depth, bool sdf) {if (vertexCount <= 0 || indexCount <= 0) return;@@ -61,13 +61,13 @@ void RenderFrame::submitTextBatch(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.+ // sdf: the SDF variant derives coverage from the distance field; otherwise the+ // featureless batch multiplies the atlas alpha (native-AA bitmap coverage) directly.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"}),+ .shaderId = sdf ? batchProgram({"SDF"}) : batchProgram({}),.blend = BlendMode::Normal,.textureId = textureId,.depth = depth,diff --git a/src/esengine/renderer/ShaderEmbeds.generated.hpp b/src/esengine/renderer/ShaderEmbeds.generated.hppindex dce606d2f..930b0d175 100644--- a/src/esengine/renderer/ShaderEmbeds.generated.hpp+++ b/src/esengine/renderer/ShaderEmbeds.generated.hpp@@ -33,7 +33,9 @@ void main() {#pragma end#pragma fragment-precision mediump float;+// highp: the SDF text branch needs precise distance + fwidth derivatives, and+// sprite sampling is unaffected by the wider range.+precision highp float;in vec4 v_color;in vec2 v_texCoord;@@ -58,8 +60,9 @@ void main() {else texColor = texture(u_textures[7], v_texCoord);#ifdef SDF// The glyph atlas stores a signed distance in the alpha channel (RGB = 1).- // Recover ~1px screen-space coverage with a smoothstep around the 0.5 edge;- // fwidth tracks the on-screen scale so glyphs stay crisp at any size.+ // fwidth tracks the on-screen scale, so a full-fwidth smoothstep band keeps a+ // stable ~1px antialiased edge at any size (this is the scalable SDF path;+ // crisp UI text uses the device-resolution bitmap batch instead).float dist = texColor.a;float aa = fwidth(dist);float coverage = smoothstep(0.5 - aa, 0.5 + aa, dist);