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.

2.7 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    ui/text/text-transform.ts
 * @brief   Pure placement helpers for SDF text: the entity
 *          world matrix and the rect→text-box mapping. No component here — the
 *          canonical text component is core/text.ts `Text`, rendered by the SDF
 *          text plugin.
 */
import type { Vec3, Quat } from '../../types';

/**
 * How far the first baseline sits below the top of its line, as a fraction of the font size, for a font that does not say.
 * An outline font's real ascent is not known here (the platform's text stack rasterizes it); a bitmap font's is, and
 * {@link fontAscent} asks it.
 */
export const DEFAULT_ASCENT = 0.8;

/** Style bit flags — bold | italic (the atlas cache-key + rasterizer style arg). */
export const UI_TEXT_BOLD = 1;
export const UI_TEXT_ITALIC = 2;

/**
 * Compose a column-major mat4 into `out` from translation, rotation quaternion,
 * and scale — the entity world transform applied to glyph local positions at
 * submit. Pure (gl-matrix fromRotationTranslationScale), unit-testable.
 */
export function composeTRS(out: Float32Array, t: Vec3, q: Quat, s: Vec3): Float32Array {
    const { x, y, z, w } = q;
    const x2 = x + x, y2 = y + y, z2 = z + z;
    const xx = x * x2, xy = x * y2, xz = x * z2;
    const yy = y * y2, yz = y * z2, zz = z * z2;
    const wx = w * x2, wy = w * y2, wz = w * z2;
    const sx = s.x, sy = s.y, sz = s.z;

    out[0] = (1 - (yy + zz)) * sx; out[1] = (xy + wz) * sx; out[2] = (xz - wy) * sx; out[3] = 0;
    out[4] = (xy - wz) * sy; out[5] = (1 - (xx + zz)) * sy; out[6] = (yz + wx) * sy; out[7] = 0;
    out[8] = (xz + wy) * sz; out[9] = (yz - wx) * sz; out[10] = (1 - (xx + yy)) * sz; out[11] = 0;
    out[12] = t.x; out[13] = t.y; out[14] = t.z; out[15] = 1;
    return out;
}

/**
 * Place a text block inside a UINode box. The entity Transform sits at the box's
 * pivot (UI layout positions the pivot), so glyph local positions (baseline y=0,
 * y-up) are offset to the box's top-left; the box width is the wrap/align area
 * and `boxHeight` lets the renderer apply vertical alignment. Top-vertical by
 * default: the first line's baseline is one ascent below the box top
 * (ascent ≈ fontSize × 0.8). Pure.
 */
export function rectTextBox(
    pivotX: number, pivotY: number, width: number, height: number, fontSizePx: number, ascent = DEFAULT_ASCENT,
): { originX: number; originY: number; maxWidth: number; boxHeight: number } {
    return {
        originX: -pivotX * width,
        originY: (1 - pivotY) * height - fontSizePx * ascent,
        maxWidth: width,
        boxHeight: height,
    };
}