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(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.ts
index 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 key
export 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.ts
index 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.ts
index 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: deferred
const 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.ts
index 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-tr
import { 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.ts
index 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.ts
index 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: DrawTex
export 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.ts
index 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.cpp
index 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.hpp
index 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_PARTICLES
void renderer_submitParticles(ecs::Registry& registry);
diff --git a/src/esengine/data/shaders/batch.esshader b/src/esengine/data/shaders/batch.esshader
index 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.hpp
index 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_SPINE
diff --git a/src/esengine/renderer/RenderFrameSubmit.cpp b/src/esengine/renderer/RenderFrameSubmit.cpp
index 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.hpp
index 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);