Class Font

java.lang.Object
cloud.opencode.base.image.codec.font.Font
All Implemented Interfaces:
AutoCloseable
public final class Font extends Object implements AutoCloseable
TrueType / OpenType font handle backed by stb_truetype via FFM. 通过 FFM 调用 stb_truetype 的 TrueType / OpenType 字体句柄。

Created via load(byte[]) or load(Path); provides text measurement and alpha-bitmap rasterization replacing the java.awt Graphics2D / TextLayout / FontRenderContext pipeline. Must be closed via close() (try-with-resources recommended) — the underlying handle owns a copy of the TTF bytes plus an stbtt_fontinfo struct freed by opencode_stbtt_free_font.

通过 load(byte[]) 或 load(Path) 创建；提供文本测量与 alpha 位图光栅化，替代 java.awt 的 Graphics2D / TextLayout / FontRenderContext 管线。必须通过 close() 释放（建议 try-with-resources）— 底层 handle 拥有 TTF 字节副本和 stbtt_fontinfo 结构体，由 opencode_stbtt_free_font 释放。

Security | 安全性:

  • Thread-safe: No - external synchronization required for shared instances; each instance owns one native handle. - 线程安全: 否 — 共享实例需要外部同步；每个实例拥有一个 native handle。
  • Bounds-checked: input bytes / Paths validated; rasterization allocates exact-size buffers per glyph and string. - 边界检查：入参严格校验；按字形 / 字符串精确分配缓冲。
  • Resource-safe: temporary buffers held in confined Arena; no leaks on success or failure. - 资源安全：临时缓冲驻留受限 Arena，成功 / 失败均不泄漏。
  • Codepoint-aware: string traversal uses codePoints() so supplementary plane (e.g. emoji surrogate pairs) is handled correctly. - 代码点感知：字符串遍历使用 codePoints()， 正确处理辅助平面（例如 emoji 代理对）。
Since:
JDK 25, opencode-base-image-codec V1.0.4
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Closes this font via opencode_stbtt_free_font.
    GlyphMetrics
    glyphMetricsAt(int codepoint, float pixelHeight)
    Pixel-space metrics for a single codepoint at the given pixel height.
    boolean
    hasCodepoint(int codepoint)
    Returns whether this font has a glyph for codepoint (i.e. the stb_truetype glyph index is non-zero).
    static Font
    load(byte[] ttfBytes)
    Loads a font from a TTF / OTF byte array.
    static Font
    load(Path ttfPath)
    Loads a font from a filesystem path (TTF / OTF).
    TextMetrics
    measure(String text, float pixelHeight)
    Measures a string at the given pixel height.
    Bitmap
    rasterize(String text, float pixelHeight)
    Rasterizes a string into a single alpha bitmap at the given pixel height.
    Bitmap
    rasterizeCodepoint(int codepoint, float pixelHeight)
    Rasterizes a single codepoint into an alpha bitmap at the given pixel height.
    float
    scaleForPixelHeight(float pixelHeight)
    Pixel scale factor mapping unscaled font units to pixels at the given pixel height (per stb_truetype's stbtt_ScaleForPixelHeight).
    TextMetrics
    verticalMetricsAt(float pixelHeight)
    Vertical font metrics in pixels at the given pixel height.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • load

      public static Font load(byte[] ttfBytes)
      Loads a font from a TTF / OTF byte array. Bytes are copied internally by the native wrapper; the caller may discard them. 从 TTF / OTF 字节数组加载字体。native 包装层会内部复制；调用方可释放原数组。
      Parameters:
      ttfBytes - non-null, non-empty font bytes | 非空非零长字体字节
      Returns:
      open font, caller must close() | 已打开的字体，调用方需 close()
      Throws:
      IllegalArgumentException - if input is null or empty | 入参非法时
      OpenImageCodecException - if stb_truetype fails to parse | 解析失败时

    • load

      public static Font load(Path ttfPath)
      Loads a font from a filesystem path (TTF / OTF). The file bytes are read into memory and forwarded to load(byte[]). 从文件路径加载字体（TTF / OTF）。读取整文件字节后转交 load(byte[])。
      Parameters:
      ttfPath - non-null path to readable font file | 非空可读字体文件路径
      Returns:
      open font | 已打开的字体
      Throws:
      IllegalArgumentException - if path is null | 路径为 null 时
      OpenImageCodecException - on IO failure or parse failure | IO 失败或解析失败时

    • scaleForPixelHeight

      public float scaleForPixelHeight(float pixelHeight)
      Pixel scale factor mapping unscaled font units to pixels at the given pixel height (per stb_truetype's stbtt_ScaleForPixelHeight). 将未缩放字体单位映射到指定像素高度像素值的缩放因子（对应 stb_truetype 的 stbtt_ScaleForPixelHeight）。
      Parameters:
      pixelHeight - target ascent-to-descent height in pixels (must be > 0) | 目标 ascent 到 descent 像素高度（须 > 0）
      Returns:
      scale factor | 缩放因子
      Throws:
      IllegalStateException - if this font is closed | 已关闭时
      IllegalArgumentException - if pixelHeight is not positive | 入参非正时

    • verticalMetricsAt

      public TextMetrics verticalMetricsAt(float pixelHeight)
      Vertical font metrics in pixels at the given pixel height. The TextMetrics.width() component is 0 (not a string measurement); use measure(String, float) for string width. 给定像素高度下的垂直字体度量。TextMetrics.width() 为 0（这是字体 整体度量，不是字符串测量）；字符串宽度请用 measure(String, float)。
      Parameters:
      pixelHeight - target pixel height (must be > 0) | 目标像素高度（须 > 0）
      Returns:
      scaled vertical metrics (width = 0) | 缩放后的垂直度量（width = 0）
      Throws:
      IllegalStateException - if this font is closed | 已关闭时
      IllegalArgumentException - if pixelHeight is not positive | 入参非正时

    • hasCodepoint

      public boolean hasCodepoint(int codepoint)
      Returns whether this font has a glyph for codepoint (i.e. the stb_truetype glyph index is non-zero). 返回此字体是否含有 codepoint 的字形（即 stb_truetype 字形索引非 0）。
      Parameters:
      codepoint - Unicode code point | Unicode 代码点
      Returns:
      true if present | 存在时为 true
      Throws:
      IllegalStateException - if this font is closed | 已关闭时

    • glyphMetricsAt

      public GlyphMetrics glyphMetricsAt(int codepoint, float pixelHeight)
      Pixel-space metrics for a single codepoint at the given pixel height. 给定像素高度下，单个代码点的像素空间度量。
      Parameters:
      codepoint - Unicode code point | Unicode 代码点
      pixelHeight - target pixel height (must be > 0) | 目标像素高度（须 > 0）
      Returns:
      glyph metrics | 字形度量
      Throws:
      IllegalStateException - if this font is closed | 已关闭时
      IllegalArgumentException - if pixelHeight is not positive | 入参非正时

    • measure

      public TextMetrics measure(String text, float pixelHeight)
      Measures a string at the given pixel height. The returned width is the sum of per-codepoint advances including kerning, rounded up. 测量给定像素高度下的字符串。返回宽度为各代码点 advance 之和（含 kerning），向上取整。
      Parameters:
      text - non-null text (empty allowed) | 非空文本（允许空串）
      pixelHeight - target pixel height (must be > 0) | 目标像素高度（须 > 0）
      Returns:
      text metrics with full vertical metrics and computed width | 含完整垂直度量与计算宽度的文本度量
      Throws:
      IllegalStateException - if this font is closed | 已关闭时
      IllegalArgumentException - if text is null or pixelHeight invalid | 入参非法时

    • rasterizeCodepoint

      public Bitmap rasterizeCodepoint(int codepoint, float pixelHeight)
      Rasterizes a single codepoint into an alpha bitmap at the given pixel height. The bitmap size matches the glyph's bounding box (which may be 0×0 for whitespace / missing glyphs). 给定像素高度下，将单代码点光栅化为 alpha 位图。位图尺寸等于字形包围盒 （空白 / 缺失字形可能为 0×0）。
      Parameters:
      codepoint - Unicode code point | Unicode 代码点
      pixelHeight - target pixel height (must be > 0) | 目标像素高度（须 > 0）
      Returns:
      alpha bitmap (may be 0×0) | alpha 位图（可能 0×0）
      Throws:
      IllegalStateException - if this font is closed | 已关闭时
      IllegalArgumentException - if pixelHeight is not positive | 入参非正时

    • rasterize

      public Bitmap rasterize(String text, float pixelHeight)
      Rasterizes a string into a single alpha bitmap at the given pixel height. All glyphs are composited (max-alpha blended) into one bitmap sized width × (ascent - descent), with each glyph positioned at its baseline using the font's pen advance and kerning. 给定像素高度下将字符串光栅化为单一 alpha 位图。所有字形以 max-alpha 合成 到尺寸为 width × (ascent - descent) 的位图中，使用字体的笔位 advance 与 kerning 在基线上摆放。
      Parameters:
      text - non-null text (empty allowed) | 非空文本（允许空串）
      pixelHeight - target pixel height (must be > 0) | 目标像素高度（须 > 0）
      Returns:
      alpha bitmap; empty text yields 0 × 0 | alpha 位图； 空字符串返回 0 × 0
      Throws:
      IllegalStateException - if this font is closed | 已关闭时
      IllegalArgumentException - if input is invalid | 入参非法时

    • close

      public void close()
      Closes this font via opencode_stbtt_free_font. Idempotent — subsequent calls are no-ops. 通过 opencode_stbtt_free_font 关闭。幂等 — 多次调用为空操作。
      Specified by:
      close in interface AutoCloseable