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.

fix(ui): glyphs are rasterized for the pixels they land on, not the design box

yhhdab378cd9ae1
diff --git a/sdk/src/ui/index.ts b/sdk/src/ui/index.ts
index 39ba6cbe9..e657c36f4 100644
--- a/sdk/src/ui/index.ts
+++ b/sdk/src/ui/index.ts
@@ -320,7 +320,7 @@ export { BUILTIN_UI_PREFABS, BUILTIN_UI_WIDGET_NAMES } from './widgets/prefabs/g
// All text — display (Text) and editable (TextInput) — now renders through the
// SDF glyph atlas; the Canvas2D TextRenderer was retired.
-export { TextPlugin, textPlugin, resolveTextRenderMode } from './text/plugin';
+export { TextPlugin, textPlugin, resolveTextRenderMode, glyphContentScale } from './text/plugin';
export { InlineImagePlugin, inlineImagePlugin } from './text/inline-image-plugin';
export { measureText, type MeasureTextOptions, type TextMetrics } from './text/measure-text';
diff --git a/sdk/src/ui/text/plugin.ts b/sdk/src/ui/text/plugin.ts
index 921ccbcd1..df07bf130 100644
--- a/sdk/src/ui/text/plugin.ts
+++ b/sdk/src/ui/text/plugin.ts
@@ -53,6 +53,32 @@ export function resolveTextRenderMode(
return Math.abs(effectiveScale - 1) <= BITMAP_SCALE_EPSILON ? 'bitmap' : 'sdf';
}
+/**
+ * Pure: how many device pixels one world unit covers, which is the size bitmap
+ * glyphs must be rasterized at to land on screen pixels.
+ *
+ * It comes from what the camera SHOWS, not from the box UI lays out in. Those
+ * agree in a shipped game — the camera frames the design box — and diverge in
+ * the editor, whose free-zoom view deliberately holds the layout box fixed so UI
+ * does not reflow while you zoom (see syncUICameraInfo). Taking the span from
+ * the layout box therefore rasterized glyphs for the design scale and left the
+ * camera to scale the result, so editor text went soft at every zoom but "fit" —
+ * and the sharper look of SDF there was really the bitmap path being asked for
+ * the wrong size.
+ *
+ * An orthographic view-projection's first element is 2 / the span it covers.
+ */
+export function glyphContentScale(
+ cam: Pick<UICameraData, 'valid' | 'vpW' | 'worldLeft' | 'worldRight' | 'viewProjection'> | undefined,
+ dpr: number,
+): number {
+ if (!cam?.valid || !(dpr > 0)) return 1;
+ const vpScaleX = cam.viewProjection?.[0] ?? 0;
+ const layoutSpan = cam.worldRight - cam.worldLeft;
+ const shownSpan = vpScaleX !== 0 ? Math.abs(2 / vpScaleX) : layoutSpan;
+ return shownSpan > 0 ? cam.vpW / (shownSpan * dpr) : 1;
+}
+
export class TextPlugin implements Plugin {
name = 'text';
@@ -99,10 +125,7 @@ export class TextPlugin implements Plugin {
// camera plugin may build after this one.
const uiCamera = app.getResource(UICameraInfo) as UICameraData | undefined;
const dpr = platformDevicePixelRatio();
- const span = uiCamera ? uiCamera.worldRight - uiCamera.worldLeft : 0;
- const contentScale = uiCamera?.valid && span > 0
- ? uiCamera.vpW / (span * dpr)
- : 1;
+ const contentScale = glyphContentScale(uiCamera, dpr);
const seen = new Set<number>();
for (const e of world.getEntitiesWithComponents([Text, Transform])) {
diff --git a/sdk/tests/ui-text-render-mode.test.ts b/sdk/tests/ui-text-render-mode.test.ts
index ac88c30a0..ee5e8890a 100644
--- a/sdk/tests/ui-text-render-mode.test.ts
+++ b/sdk/tests/ui-text-render-mode.test.ts
@@ -1,7 +1,7 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { describe, it, expect } from 'vitest';
-import { Text, TextRenderMode, resolveTextRenderMode, buildText } from '../src/ui';
+import { Text, TextRenderMode, resolveTextRenderMode, glyphContentScale, buildText } from '../src/ui';
describe('TextRenderMode', () => {
it('defines Auto / Bitmap / Sdf', () => {
@@ -81,3 +81,39 @@ describe('GlyphAtlas content scale (bitmap rasterization density)', () => {
expect(sdf.pixelSizeFor(13)).toBe(48); // SDF is one fixed source
});
});
+
+describe('glyphContentScale (what size to rasterize FOR)', () => {
+ const cam = (over: Record<string, unknown> = {}) => ({
+ valid: true, vpW: 1920, worldLeft: -960, worldRight: 960,
+ viewProjection: new Float32Array([2 / 1920, 0, 0, 0]),
+ ...over,
+ } as never);
+
+ it('is device pixels per world unit, so a 1:1 view rasterizes 1:1', () => {
+ expect(glyphContentScale(cam(), 1)).toBeCloseTo(1, 5);
+ expect(glyphContentScale(cam(), 2)).toBeCloseTo(0.5, 5); // dpr folded in by the atlas
+ });
+
+ // The editor holds the layout box at the design size on purpose, so UI does
+ // not reflow while the view zooms. Reading the span from that box asked for
+ // design-sized glyphs and let the camera scale them — the blur this fixes.
+ it('follows the camera when it shows less than the layout box (zoomed in)', () => {
+ const zoomed = cam({ viewProjection: new Float32Array([2 / 480, 0, 0, 0]) }); // 4× in
+ expect(glyphContentScale(zoomed, 1)).toBeCloseTo(4, 5);
+ });
+
+ it('follows the camera when it shows more than the layout box (zoomed out)', () => {
+ const wide = cam({ viewProjection: new Float32Array([2 / 3840, 0, 0, 0]) }); // 2× out
+ expect(glyphContentScale(wide, 1)).toBeCloseTo(0.5, 5);
+ });
+
+ it('falls back to the layout box when the projection says nothing', () => {
+ expect(glyphContentScale(cam({ viewProjection: new Float32Array(4) }), 1)).toBeCloseTo(1, 5);
+ });
+
+ it('is 1 when there is no valid camera, or a nonsense dpr', () => {
+ expect(glyphContentScale(undefined, 1)).toBe(1);
+ expect(glyphContentScale(cam({ valid: false }), 1)).toBe(1);
+ expect(glyphContentScale(cam(), 0)).toBe(1);
+ });
+});