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.

chore(ui): trim comment bloat from the text/scroll work + drop roadmap refs

yhh58b5aba1cd96
diff --git a/sdk/src/core-ui.ts b/sdk/src/core-ui.ts
index c42532f98..1f18da877 100644
--- a/sdk/src/core-ui.ts
+++ b/sdk/src/core-ui.ts
@@ -144,8 +144,8 @@ export {
createDropdown,
type DropdownOptions,
type DropdownHandle,
- // Data-driven virtualized list / grid (REARCH_UI_LIST): the ergonomic factory
- // plus the collection primitives it composes, as escape hatches.
+ // Data-driven virtualized list / grid: the ergonomic factory plus the
+ // collection primitives it composes, as escape hatches.
createListView,
type CreateListViewOptions,
type ListViewHandle,
diff --git a/sdk/src/ui/behavior/plugin.ts b/sdk/src/ui/behavior/plugin.ts
index c9889e514..a04933034 100644
--- a/sdk/src/ui/behavior/plugin.ts
+++ b/sdk/src/ui/behavior/plugin.ts
@@ -63,9 +63,8 @@ export class UIBehaviorPlugin implements Plugin {
}
/**
- * Attach a ScrollContainer to an entity. A wheel-driven system
- * applies mouse-wheel input to the container whenever the entity's
- * UIInteraction.hovered flag is true.
+ * Attach a ScrollContainer to an entity. Wheel and drag/touch input drive
+ * it while the entity's UIInteraction.hovered flag is true.
*/
attachScrollContainer(entity: Entity, container: ScrollContainer): void {
if (!this.scrollContainers_) {
@@ -112,10 +111,8 @@ export class UIBehaviorPlugin implements Plugin {
Schedule.Update,
defineSystem([], () => listViews.tick(), { name: 'ListViewSystem' }),
);
- // Kinetic (fling) state per scroll entity — shared between the wheel
- // and drag systems so either input source interrupts a coast. Kept in
- // a closure Map (the StateVisualsApplySystem precedent): runtime-only,
- // invisible to serialization, dropped with detach.
+ // Fling state per scroll entity, shared between the wheel and drag
+ // systems so either input source interrupts a coast.
const dynamics = new Map<Entity, KineticScroll>();
const dynamicsFor = (entity: Entity, container: ScrollContainer): KineticScroll => {
let d = dynamics.get(entity);
@@ -144,12 +141,9 @@ export class UIBehaviorPlugin implements Plugin {
}, { name: 'ScrollWheelSystem' }),
);
- // Drag/touch scrolling. The web platform layer already funnels the
- // primary touch into the pointer stream (touchstart → onPointerDown
- // etc.), so one pointer-based system covers mouse and touch alike.
- // Same pending → slop → active capture shape as DragSystem, but the
- // delta drives the ScrollContainer offset instead of the entity box,
- // and release hands the sampled velocity to KineticScroll to coast.
+ // Drag/touch scrolling — pointer-based (the platform layer funnels the
+ // primary touch into the pointer stream), same pending → slop → active
+ // capture shape as DragSystem.
let pendingEntity: Entity | null = null;
let activeEntity: Entity | null = null;
let grabStartWorld: Vec2 = { x: 0, y: 0 };
@@ -162,9 +156,8 @@ export class UIBehaviorPlugin implements Plugin {
if (!camera.valid) return;
const worldMouse = { x: camera.worldMouseX, y: camera.worldMouseY };
- // New press over a hovered container: catch it (stop any
- // coast) and arm the drag. Deepest hovered wins so a nested
- // list scrolls itself, not its ancestor.
+ // Press over a hovered container arms the drag; deepest hovered
+ // wins so a nested list scrolls itself, not its ancestor.
if (input.isMouseButtonPressed(0)) {
let best: Entity | null = null;
let bestDepth = -1;
@@ -212,11 +205,9 @@ export class UIBehaviorPlugin implements Plugin {
}
}
- // Active drag: the content follows the pointer 1:1 (absolute
- // mapping from the grab point, so clamped overshoot re-tracks
- // the finger on the way back). World-unit deltas divide by the
- // viewport's world scale to land in UI px; world y is up while
- // offset y is down, hence the sign split.
+ // Active drag: absolute mapping from the grab point so clamped
+ // overshoot re-tracks the finger. World deltas ÷ viewport scale
+ // = UI px; world y is up, offset y is down — hence the signs.
if (activeEntity !== null) {
const container = scrollContainers.get(activeEntity);
if (!container || !world.valid(activeEntity)) {
@@ -248,8 +239,7 @@ export class UIBehaviorPlugin implements Plugin {
}
}
- // Coast phase: tick each flung container, killing an axis the
- // moment the clamp stops it so the fling dies at the edge.
+ // Coast: tick flung containers; an axis the clamp stops is dead.
for (const [entity, dyn] of dynamics) {
if (!dyn.isCoasting()) continue;
const container = scrollContainers.get(entity);
diff --git a/sdk/src/ui/collection/kinetic-scroll.ts b/sdk/src/ui/collection/kinetic-scroll.ts
index a86651786..b488bf4ef 100644
--- a/sdk/src/ui/collection/kinetic-scroll.ts
+++ b/sdk/src/ui/collection/kinetic-scroll.ts
@@ -2,29 +2,18 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file ui/collection/kinetic-scroll.ts
- * @brief KineticScroll — the pure velocity model behind drag/touch scrolling.
- *
- * Tracks the pointer's velocity while a drag is held (EMA-smoothed so one
- * jittery frame doesn't dictate the fling) and, after release, decays it
- * exponentially so the content coasts to rest — the standard kinetic-scroll
- * feel (Unity ScrollRect / iOS). Like {@link ScrollContainer}, it has no
- * input or ECS knowledge: a behavior system pushes samples in and applies
- * the ticked deltas back to the container, keeping the model unit-testable.
+ * @brief KineticScroll — the pure velocity model behind drag/touch scrolling:
+ * EMA-smoothed sampling while held, exponential decay after release.
+ * Like {@link ScrollContainer}, it has no input or ECS knowledge.
*/
import type { Vec2 } from '../../types';
export interface KineticScrollOptions {
- /**
- * Fraction of the release velocity remaining after one second of
- * coasting (`v *= rate^dt`). Default 0.135 — Unity's ScrollRect default.
- */
+ /** Fling velocity left after 1s of coasting (`v *= rate^dt`). Default 0.135. */
decelerationRate?: number;
/** Speed floor (px/s) below which coasting stops. Default 4. */
restVelocity?: number;
- /**
- * Per-second EMA rate blending new velocity samples over the held drag
- * (`blend = 1 - e^(-rate·dt)`). Default 12 — ≈70% weight in 100ms.
- */
+ /** Per-second EMA rate for velocity samples (`1 - e^(-rate·dt)`). Default 12. */
sampleRate?: number;
}
diff --git a/sdk/src/ui/collection/scroll-container.ts b/sdk/src/ui/collection/scroll-container.ts
index a56115e88..bae3db447 100644
--- a/sdk/src/ui/collection/scroll-container.ts
+++ b/sdk/src/ui/collection/scroll-container.ts
@@ -13,10 +13,7 @@ export interface ScrollContainerOptions {
wheelSpeed?: number;
/** Drag/touch scrolling (pointer grab + kinetic fling). Default true. */
dragScroll?: boolean;
- /**
- * Fraction of the fling velocity remaining after one second of coasting.
- * Default 0.135 (Unity ScrollRect). Only meaningful with `dragScroll`.
- */
+ /** Fling velocity left after 1s of coasting. Default 0.135. */
decelerationRate?: number;
}
diff --git a/sdk/src/ui/core/text.ts b/sdk/src/ui/core/text.ts
index 9a2493c9c..9fd51f7a3 100644
--- a/sdk/src/ui/core/text.ts
+++ b/sdk/src/ui/core/text.ts
@@ -24,21 +24,13 @@ export const TextOverflow = {
} as const;
export type TextOverflow = (typeof TextOverflow)[keyof typeof TextOverflow];
-/**
- * Glyph pipeline for a Text (mirrors Unity's TMP-vs-UI-Text split, unified in
- * one component). Both pipelines share the atlas, layout, and batch path —
- * the difference is what the atlas stores and how the shader derives coverage.
- */
+/** Glyph pipeline for a Text. */
export const TextRenderMode = {
- /**
- * Per-frame choice: device-resolution bitmap when the text lands ~1:1 on
- * screen (crisp like the DOM), SDF whenever it's scaled — by the canvas
- * design-resolution fit, a zooming camera, or the entity transform.
- */
+ /** Hinted bitmap while the entity is unscaled, SDF once it scales. */
Auto: 0,
- /** Canvas2D native AA at device resolution. Sharpest at 1:1; blurs when scaled. */
+ /** Canvas2D native AA at the on-screen pixel size. Sharpest when static. */
Bitmap: 1,
- /** Signed-distance field, fwidth-smoothstep AA — a stable ~1px edge at any scale. */
+ /** Signed-distance field — a stable ~1px edge at any scale/zoom. */
Sdf: 2,
} as const;
export type TextRenderMode = (typeof TextRenderMode)[keyof typeof TextRenderMode];
@@ -62,7 +54,6 @@ export interface TextData {
shadowOffsetX: number;
shadowOffsetY: number;
richText: boolean;
- /** Glyph pipeline: Auto (default) picks bitmap at 1:1, SDF when scaled. */
renderMode: TextRenderMode;
}
@@ -87,8 +78,6 @@ export const Text = defineComponent<TextData>('Text', {
richText: false,
renderMode: TextRenderMode.Auto,
}, {
- // Editor dropdowns from the same constants the runtime switches on, so the
- // labels can never drift (the ParticleEmitter TS-enum precedent).
fields: {
align: { enum: enumOptions(TextAlign) },
verticalAlign: { enum: enumOptions(TextVerticalAlign) },
diff --git a/sdk/src/ui/text/glyph-atlas.ts b/sdk/src/ui/text/glyph-atlas.ts
index 30f1f70be..8e416de0b 100644
--- a/sdk/src/ui/text/glyph-atlas.ts
+++ b/sdk/src/ui/text/glyph-atlas.ts
@@ -109,20 +109,17 @@ export class GlyphAtlas {
get renderSize(): number { return this.rasterizer.renderSize; }
/**
- * On-screen device px per design px beyond DPR (the canvas design-resolution
- * fit / camera scale). Bitmap glyphs fold it into the rasterization size so
- * they land 1:1 on *screen* pixels — hinted at the final size, like DOM
- * text — instead of rasterizing at design px and being resampled by the
- * quad scale. Integer-px rounding in pixelSizeFor dedupes near-equal
- * scales, so a window resize re-rasterizes only when sizes actually change.
+ * On-screen device px per design px beyond DPR (the canvas design fit).
+ * Bitmap glyphs fold it into the rasterization size so they land 1:1 on
+ * screen pixels, hinted at the final size; integer rounding in
+ * pixelSizeFor dedupes near-equal scales.
*/
setContentScale(scale: number): void {
this.contentScale_ = Number.isFinite(scale) && scale > 0 ? scale : 1;
}
- /** Rasterization size for a display size: SDF uses one fixed resolution-independent
- * source; bitmap rasterizes per size at the effective on-screen density
- * (DPR × content scale) for a crisp 1:1 blit. */
+ /** Rasterization size for a display size: SDF uses one fixed source;
+ * bitmap rasterizes per size at the effective on-screen density. */
pixelSizeFor(displaySize: number): number {
return this.sdf
? this.renderSize
diff --git a/sdk/src/ui/text/glyph-rasterizer.ts b/sdk/src/ui/text/glyph-rasterizer.ts
index 2b3f6f61d..1205b9206 100644
--- a/sdk/src/ui/text/glyph-rasterizer.ts
+++ b/sdk/src/ui/text/glyph-rasterizer.ts
@@ -40,11 +40,9 @@ export function sdfToAtlasRgba(sdf: Uint8Array, width: number, height: number):
}
/**
- * Box-downsample a byte grid by an integer factor (averaging factor² texels
- * per output texel). Used to fold a supersampled SDF back to the stored
- * resolution: the field is computed at `factor²` the resolution — so edge
- * positions carry sub-(stored-)texel accuracy — and averaging a linearly
- * encoded field preserves that accuracy in the stored texels. Pure.
+ * Box-downsample a byte grid by an integer factor. Folds a supersampled SDF
+ * back to the stored resolution; averaging the linearly encoded field keeps
+ * the sub-texel edge accuracy. Pure.
*/
export function downsampleBytes(src: Uint8Array, width: number, height: number, factor: number): Uint8Array {
if (factor <= 1) return src;
@@ -79,11 +77,9 @@ export interface CanvasGlyphRasterizerOptions {
type Canvas2D = HTMLCanvasElement | OffscreenCanvas;
type Ctx2D = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
-// SDF supersampling: rasterize + distance-transform at SS× the stored
-// resolution, then box-downsample the field. Coverage seeding recovers the
-// edge only to ~⅓ texel; computing at 4× and averaging down stores distances
-// at ~1/12-texel accuracy, so magnified glyphs stop showing the source grid
-// as edge wobble. One-time per glyph; atlas memory is unchanged.
+// SDF supersampling: rasterize + distance-transform at 4× the stored
+// resolution, then box-downsample — magnified glyphs stop showing the source
+// grid as edge wobble. One-time per glyph; atlas memory is unchanged.
const SDF_SUPERSAMPLE = 4;
export class CanvasGlyphRasterizer implements GlyphRasterizer {
@@ -149,10 +145,8 @@ export class CanvasGlyphRasterizer implements GlyphRasterizer {
const img = ctx.getImageData(0, 0, wSS, hSS);
const alpha = extractAlpha(img.data, wSS, hSS);
- // SDF: distance-transform at the supersampled resolution (spread scales
- // with ss, so the downsampled encoding matches spread = pad in stored
- // texels exactly), then fold back down. Bitmap: keep the native-AA
- // coverage as-is for a crisp 1:1 blit. Both pack as (RGB=255, A=coverage).
+ // SDF: distance-transform at ss× (spread scales with ss, so the folded
+ // encoding matches spread = pad exactly). Bitmap: native-AA coverage as-is.
let coverage = alpha;
if (this.sdf) {
const sdf = sdfFromAlpha(this.module, alpha, wSS, hSS, pad * ss);
diff --git a/sdk/src/ui/text/plugin.ts b/sdk/src/ui/text/plugin.ts
index 2bd9ff049..49dc55e62 100644
--- a/sdk/src/ui/text/plugin.ts
+++ b/sdk/src/ui/text/plugin.ts
@@ -3,16 +3,11 @@
/**
* @file ui/text/plugin.ts
* @brief TextPlugin — renders the `Text` component via the dynamic glyph
- * atlas, replacing the legacy Canvas2D-per-entity path. A pre-flush
- * callback scans Text entities, composes the world transform, places
- * the text inside its UINode box (no auto-size — the UINode is the
- * box; rendering never mutates layout) and draws batched glyph quads,
- * layered to interleave with sibling UI elements.
- *
- * Two glyph pipelines, routed per Text by {@link resolveTextRenderMode}
- * (Text.renderMode, default Auto): device-resolution bitmaps when the
- * text lands 1:1 on screen, SDF + fwidth AA whenever it's scaled by
- * the design-resolution fit, a camera zoom, or the entity transform.
+ * atlas. A pre-flush callback scans Text entities, places the text
+ * inside its UINode box (rendering never mutates layout) and draws
+ * batched glyph quads, layered with sibling UI elements. Two glyph
+ * pipelines — hinted bitmap vs SDF — routed per Text by
+ * {@link resolveTextRenderMode}.
*/
import type { App, Plugin } from '../../app';
import { Transform, type TransformData, registerComponent } from '../../component';
@@ -40,13 +35,9 @@ const BITMAP_SCALE_EPSILON = 0.02;
/**
* Pure: which glyph pipeline a Text draws with. `effectiveScale` is the
- * residual scale the bitmap path CANNOT fold into rasterization — the entity's
- * own world scale. (The canvas design-fit / camera scale is compensated by
- * rasterizing bitmap glyphs at the effective on-screen size, see
- * {@link GlyphAtlas.setContentScale} — so a static UI stays on hinted,
- * pixel-exact bitmaps at any window size, like DOM/FGUI text.) Auto sends
- * genuinely scaled text to SDF, whose screen-px-ramp AA is stable at every
- * zoom. Non-finite or unknown scales keep the bitmap path.
+ * entity's own world scale — the residual the bitmap path can't fold into
+ * rasterization (the canvas fit is, via {@link GlyphAtlas.setContentScale}).
+ * Auto keeps unscaled text on hinted bitmaps and sends scaled text to SDF.
*/
export function resolveTextRenderMode(
mode: TextRenderMode | undefined,
@@ -87,11 +78,9 @@ export class TextPlugin implements Plugin {
const registry = world.getCppRegistry() as CppRegistry;
pipeline.addPreFlushCallback(() => {
- // Design→device scale of one design px this frame beyond DPR (vpW
- // is device px). The bitmap atlas folds it into rasterization so
- // static text is hinted at the final on-screen size regardless of
- // the window/design fit. Resolved per frame — the camera plugin
- // may build after this one.
+ // Design→device scale beyond DPR (vpW is device px); the bitmap
+ // atlas folds it into rasterization. Resolved per frame — the
+ // 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;
@@ -105,8 +94,6 @@ export class TextPlugin implements Plugin {
if (!t.content) continue;
const tr = world.get(entity, Transform) as TransformData;
- // Auto routes on the entity's own scale only — the canvas fit
- // is already compensated in the bitmap rasterization size.
const renderer = this.rendererFor(
app,
resolveTextRenderMode(t.renderMode, tr.worldScale.x),
@@ -187,14 +174,8 @@ export class TextPlugin implements Plugin {
});
}
- /**
- * The two glyph pipelines, created lazily and kept for the app's lifetime.
- * Bitmap: per-size rasterization at DPR, Canvas-native AA, blits 1:1.
- * SDF: one fixed-size rasterization per glyph, fwidth-AA in the shader —
- * resolution-independent, so scaled/zoomed text stays crisp. Both share
- * the same layout, page-store, and batch-submit path; only the atlas
- * contents and the shader's coverage derivation differ.
- */
+ /** The two glyph pipelines, created lazily; they share layout, page store,
+ * and batch submit — only the atlas contents and shader coverage differ. */
private rendererFor(app: App, kind: 'bitmap' | 'sdf', contentScale: number): SdfTextRenderer {
const module = app.wasmModule as ESEngineModule;
if (kind === 'sdf') {
diff --git a/sdk/src/ui/widgets/helpers.ts b/sdk/src/ui/widgets/helpers.ts
index 1ae50575c..e8b99b8aa 100644
--- a/sdk/src/ui/widgets/helpers.ts
+++ b/sdk/src/ui/widgets/helpers.ts
@@ -105,19 +105,13 @@ export function buildUIVisual(init: UIVisualInit = {}): UIVisualData {
};
}
-/**
- * Linear fill direction — the edge a partial fill grows toward. Shared
- * vocabulary for progress bars, slider fills, and any widget built on the
- * {@link UIVisualType.Filled} primitive.
- */
+/** The edge a partial fill grows toward, for widgets built on `Filled`. */
export type LinearFillDirection = 'right' | 'left' | 'up' | 'down';
/**
- * Map a {@link LinearFillDirection} to the `Filled` visual's crop axis
- * ({@link FillMethod}) and anchor edge ({@link FillOrigin}): the fill grows
- * along `direction`, cropped from the opposite edge. One canonical table so
- * progress, slider, and future Filled widgets reveal identically — no
- * per-widget re-derivation of "which axis, which origin".
+ * direction → the `Filled` visual's crop axis + anchor edge (grows along
+ * `direction`, cropped from the opposite edge). The one canonical table for
+ * progress, slider, and future Filled widgets.
*/
export const FILL_AXIS: Record<LinearFillDirection, readonly [FillMethod, FillOrigin]> = {
right: [FillMethod.Horizontal, FillOrigin.Left],
diff --git a/sdk/src/ui/widgets/list-view.ts b/sdk/src/ui/widgets/list-view.ts
index b5fdf4914..0015da3c3 100644
--- a/sdk/src/ui/widgets/list-view.ts
+++ b/sdk/src/ui/widgets/list-view.ts
@@ -8,14 +8,11 @@
* primitives (DataSource + LayoutProvider + ViewPool + ListView + ScrollContainer
* + UIMask) — matching the createButton/createDialog factory-and-handle shape.
*
- * Layout integration (REARCH_UI_LIST §3): items are positioned by UINode
- * Absolute inset (not Transform, which the UI layout owns); the content frame is
- * translated by the scroll offset; a Scissor UIMask on the viewport clips. Input
- * is handled by the behavior plugin once the viewport is a hovered raycast
- * target: ScrollWheelSystem applies wheel deltas, and ScrollDragSystem grabs
- * pointer drags (the primary touch is funneled into the pointer stream by the
- * platform layer, so touch scrolling rides the same path) with a kinetic fling
- * on release.
+ * Items are positioned by UINode Absolute inset (not Transform, which the UI
+ * layout owns); the content frame is translated by the scroll offset; a
+ * Scissor UIMask on the viewport clips. Wheel and drag/touch scrolling (with
+ * a kinetic fling) are handled by the behavior plugin once the viewport is a
+ * hovered raycast target.
*/
import { Transform } from '../../component';
import type { Entity, Vec2 } from '../../types';
@@ -148,7 +145,7 @@ function placeByInset(world: World, entity: Entity, rect: Rect): void {
}
/**
- * Build a virtualized list (or grid) in one call. See REARCH_UI_LIST.md.
+ * Build a virtualized list (or grid) in one call.
*
* @example
* const list = createListView<Player>({
diff --git a/sdk/src/ui/widgets/progress.ts b/sdk/src/ui/widgets/progress.ts
index 1f53ef485..94ab1c6ff 100644
--- a/sdk/src/ui/widgets/progress.ts
+++ b/sdk/src/ui/widgets/progress.ts
@@ -30,11 +30,7 @@ export interface ProgressOptions {
fill?: { color?: Color; sprite?: number };
/** Direction the fill grows (linear bars). Default: 'right'. */
direction?: LinearFillDirection;
- /**
- * Radial gauge instead of a linear bar: the fill is a clockwise wedge
- * sweeping the full circle from 12 o'clock (cooldown / ring meter).
- * When set, `direction` is ignored.
- */
+ /** Radial gauge: a clockwise wedge from 12 o'clock; `direction` is ignored. */
radial?: boolean;
/** Initial progress 0..1. Default 0. */
value?: number;
diff --git a/src/esengine/data/shaders/batch.esshader b/src/esengine/data/shaders/batch.esshader
index 1807293fc..c5e661a6b 100644
--- a/src/esengine/data/shaders/batch.esshader
+++ b/src/esengine/data/shaders/batch.esshader
@@ -56,10 +56,8 @@ 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).
- // Dividing the signed distance by its screen-space derivative converts it
- // to *screen pixels from the edge*; a ±0.5px clamp is then exactly one
- // pixel of linear coverage ramp — the msdfgen/TMP standard. (A full-fwidth
- // smoothstep band spans ~2px and reads as blur, not antialiasing.)
+ // Distance ÷ fwidth = screen px from the edge; the ±0.5px clamp is exactly
+ // one pixel of linear coverage ramp (the msdfgen standard).
float dist = texColor.a;
float screenPxDist = (dist - 0.5) / max(fwidth(dist), 1e-6);
float coverage = clamp(screenPxDist + 0.5, 0.0, 1.0);
diff --git a/src/esengine/renderer/ShaderEmbeds.generated.hpp b/src/esengine/renderer/ShaderEmbeds.generated.hpp
index 55cdb1c08..c87a6624c 100644
--- a/src/esengine/renderer/ShaderEmbeds.generated.hpp
+++ b/src/esengine/renderer/ShaderEmbeds.generated.hpp
@@ -60,10 +60,8 @@ 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).
- // Dividing the signed distance by its screen-space derivative converts it
- // to *screen pixels from the edge*; a ±0.5px clamp is then exactly one
- // pixel of linear coverage ramp — the msdfgen/TMP standard. (A full-fwidth
- // smoothstep band spans ~2px and reads as blur, not antialiasing.)
+ // Distance ÷ fwidth = screen px from the edge; the ±0.5px clamp is exactly
+ // one pixel of linear coverage ramp (the msdfgen standard).
float dist = texColor.a;
float screenPxDist = (dist - 0.5) / max(fwidth(dist), 1e-6);
float coverage = clamp(screenPxDist + 0.5, 0.0, 1.0);
diff --git a/src/esengine/text/SdfGenerator.cpp b/src/esengine/text/SdfGenerator.cpp
index 1ed3669f0..d2ee346ab 100644
--- a/src/esengine/text/SdfGenerator.cpp
+++ b/src/esengine/text/SdfGenerator.cpp
@@ -5,19 +5,10 @@
* @brief Exact signed distance field from an antialiased coverage bitmap.
*
* Felzenszwalb–Huttenlocher separable squared-distance transform with
- * coverage-derived fractional seeds (the tiny-sdf / Gustavson lineage): a
- * partially covered texel seeds the transform with its sub-texel distance to
- * the true edge, (0.5 − α)², so the reconstructed field carries the edge
- * position at sub-texel accuracy instead of quantizing it to the source grid.
- * The previous 8SSEDT binarized coverage at 0.5, which baked the rasterizer's
- * pixel staircase into the field — invisible at 1:1, but magnified glyphs
- * showed it as wobbling, aliased edges.
- *
- * Two fields are computed — squared distance to the glyph interior and to the
- * exterior — and their square roots subtracted for a signed distance that is
- * positive inside, negative outside, ~0 on the edge. The 1D transform is
- * exact and O(n); scratch buffers are reused across rows/columns, keeping the
- * on-demand per-glyph cost allocation-light.
+ * coverage-derived fractional seeds (tiny-sdf lineage): a partially covered
+ * texel seeds the transform with (0.5 − α)², placing the edge at sub-texel
+ * accuracy so magnified glyphs stay smooth. Interior and exterior fields are
+ * subtracted for the signed distance; the 1D transform is exact and O(n).
*/
#include "SdfGenerator.hpp"