.. _stdlib_stbimage_ttf:

================================
TrueType font API (stbimage_ttf)
================================

.. das:module:: stbimage_ttf

High-level TrueType font loading and text rendering API. Loads fonts via stb_truetype packing API, stores atlas as ``Image``, and provides software text rendering with alpha blending. Built on ``stbimage_boost`` and ``stbtruetype``.


++++++++++
Structures
++++++++++

.. _struct-stbimage_ttf-Font:

.. das:attribute:: Font

Font loaded from a TTF file. Supports both atlas-based rendering
(via ``load_ttf``) and lightweight metrics/shape queries (via ``load_font``).

:Fields: * **fontinfo** :  :ref:`stbtt_fontinfo <handle-stbtruetype-stbtt_fontinfo>` - Initialized font info (for metrics queries).

         * **chardata** : array< :ref:`stbtt_packedchar <handle-stbtruetype-stbtt_packedchar>`> - Packed character data for the loaded range.

         * **bitmap** :  :ref:`Image <struct-stbimage_boost-Image>` - Font atlas as 1-channel uint8 Image.

         * **font_data** : array<uint8> - Raw TTF file data (must outlive fontinfo).

         * **pixel_height** : float - Font size in pixels (0 if loaded without atlas).

         * **char_range** : int2 - (first_char, num_chars) of the packed range.

         * **tex** : uint64 - Opaque texture handle (0 by default, set by graphics layer).




++++++++++++++++++++++++
Low-level initialization
++++++++++++++++++++++++

  *  :ref:`stbtt_init (var info: stbtt_fontinfo; var data: array\<uint8\>; font_index: int = 0) : bool <function-stbimage_ttf_stbtt_init_stbtt_fontinfo_array_ls_uint8_gr__int>`
  *  :ref:`stbtt_num_fonts (var data: array\<uint8\>) : int <function-stbimage_ttf_stbtt_num_fonts_array_ls_uint8_gr_>`

.. _function-stbimage_ttf_stbtt_init_stbtt_fontinfo_array_ls_uint8_gr__int:

.. das:function:: stbtt_init(info: stbtt_fontinfo; data: array<uint8>; font_index: int = 0) : bool

Initialize a ``stbtt_fontinfo`` from font data. Returns ``true`` on success.


:Arguments: * **info** :  :ref:`stbtt_fontinfo <handle-stbtruetype-stbtt_fontinfo>`

            * **data** : array<uint8>

            * **font_index** : int

.. _function-stbimage_ttf_stbtt_num_fonts_array_ls_uint8_gr_:

.. das:function:: stbtt_num_fonts(data: array<uint8>) : int

Returns the number of fonts in a TrueType collection (.ttc), or 1 for a single .ttf.


:Arguments: * **data** : array<uint8>


+++++++++++++++
Low-level scale
+++++++++++++++

  *  :ref:`stbtt_scale_for_em (info: stbtt_fontinfo; pixels: float) : float <function-stbimage_ttf_stbtt_scale_for_em_stbtt_fontinfo_float>`
  *  :ref:`stbtt_scale_for_pixel_height (info: stbtt_fontinfo; pixel_height: float) : float <function-stbimage_ttf_stbtt_scale_for_pixel_height_stbtt_fontinfo_float>`

.. _function-stbimage_ttf_stbtt_scale_for_em_stbtt_fontinfo_float:

.. das:function:: stbtt_scale_for_em(info: stbtt_fontinfo; pixels: float) : float

Compute scale factor for mapping em to pixels.


:Arguments: * **info** :  :ref:`stbtt_fontinfo <handle-stbtruetype-stbtt_fontinfo>`

            * **pixels** : float

.. _function-stbimage_ttf_stbtt_scale_for_pixel_height_stbtt_fontinfo_float:

.. das:function:: stbtt_scale_for_pixel_height(info: stbtt_fontinfo; pixel_height: float) : float

Compute scale factor for a given pixel height.


:Arguments: * **info** :  :ref:`stbtt_fontinfo <handle-stbtruetype-stbtt_fontinfo>`

            * **pixel_height** : float


+++++++++++++++++
Low-level metrics
+++++++++++++++++

  *  :ref:`stbtt_codepoint_box (info: stbtt_fontinfo; codepoint: int) : int4 <function-stbimage_ttf_stbtt_codepoint_box_stbtt_fontinfo_int>`
  *  :ref:`stbtt_codepoint_hmetrics (info: stbtt_fontinfo; codepoint: int) : tuple\<advance_width:int;left_side_bearing:int\> <function-stbimage_ttf_stbtt_codepoint_hmetrics_stbtt_fontinfo_int>`
  *  :ref:`stbtt_codepoint_kern (info: stbtt_fontinfo; ch1: int; ch2: int) : int <function-stbimage_ttf_stbtt_codepoint_kern_stbtt_fontinfo_int_int>`
  *  :ref:`stbtt_find_glyph (info: stbtt_fontinfo; codepoint: int) : int <function-stbimage_ttf_stbtt_find_glyph_stbtt_fontinfo_int>`
  *  :ref:`stbtt_font_bbox (info: stbtt_fontinfo) : int4 <function-stbimage_ttf_stbtt_font_bbox_stbtt_fontinfo>`
  *  :ref:`stbtt_font_vmetrics (info: stbtt_fontinfo) : tuple\<ascent:int;descent:int;line_gap:int\> <function-stbimage_ttf_stbtt_font_vmetrics_stbtt_fontinfo>`

.. _function-stbimage_ttf_stbtt_codepoint_box_stbtt_fontinfo_int:

.. das:function:: stbtt_codepoint_box(info: stbtt_fontinfo; codepoint: int) : int4

Returns glyph bounding box ``int4(x0, y0, x1, y1)`` in font units.
Returns ``int4(0)`` if the codepoint has no outline.


:Arguments: * **info** :  :ref:`stbtt_fontinfo <handle-stbtruetype-stbtt_fontinfo>`

            * **codepoint** : int

.. _function-stbimage_ttf_stbtt_codepoint_hmetrics_stbtt_fontinfo_int:

.. das:function:: stbtt_codepoint_hmetrics(info: stbtt_fontinfo; codepoint: int) : tuple<advance_width:int;left_side_bearing:int>

Returns horizontal metrics in font units for a codepoint.


:Arguments: * **info** :  :ref:`stbtt_fontinfo <handle-stbtruetype-stbtt_fontinfo>`

            * **codepoint** : int

.. _function-stbimage_ttf_stbtt_codepoint_kern_stbtt_fontinfo_int_int:

.. das:function:: stbtt_codepoint_kern(info: stbtt_fontinfo; ch1: int; ch2: int) : int

Returns kerning advance between two codepoints in font units.


:Arguments: * **info** :  :ref:`stbtt_fontinfo <handle-stbtruetype-stbtt_fontinfo>`

            * **ch1** : int

            * **ch2** : int

.. _function-stbimage_ttf_stbtt_find_glyph_stbtt_fontinfo_int:

.. das:function:: stbtt_find_glyph(info: stbtt_fontinfo; codepoint: int) : int

Returns glyph index for a codepoint. Returns 0 if not found.


:Arguments: * **info** :  :ref:`stbtt_fontinfo <handle-stbtruetype-stbtt_fontinfo>`

            * **codepoint** : int

.. _function-stbimage_ttf_stbtt_font_bbox_stbtt_fontinfo:

.. das:function:: stbtt_font_bbox(info: stbtt_fontinfo) : int4

Returns font bounding box ``int4(x0, y0, x1, y1)`` in font units.


:Arguments: * **info** :  :ref:`stbtt_fontinfo <handle-stbtruetype-stbtt_fontinfo>`

.. _function-stbimage_ttf_stbtt_font_vmetrics_stbtt_fontinfo:

.. das:function:: stbtt_font_vmetrics(info: stbtt_fontinfo) : tuple<ascent:int;descent:int;line_gap:int>

Returns vertical metrics in font units: ascent, descent, line gap.


:Arguments: * **info** :  :ref:`stbtt_fontinfo <handle-stbtruetype-stbtt_fontinfo>`


+++++++++++++++++++++
Low-level glyph shape
+++++++++++++++++++++

  *  :ref:`stbtt_codepoint_shape (info: stbtt_fontinfo; codepoint: int; blk: block\<(v:stbtt_vertex_das):void\>) <function-stbimage_ttf_stbtt_codepoint_shape_stbtt_fontinfo_int_block_ls_v_c_stbtt_vertex_das_c_void_gr_>`
  *  :ref:`stbtt_codepoint_shape_count (info: stbtt_fontinfo; codepoint: int) : int <function-stbimage_ttf_stbtt_codepoint_shape_count_stbtt_fontinfo_int>`

.. _function-stbimage_ttf_stbtt_codepoint_shape_stbtt_fontinfo_int_block_ls_v_c_stbtt_vertex_das_c_void_gr_:

.. das:function:: stbtt_codepoint_shape(info: stbtt_fontinfo; codepoint: int; blk: block<(v:stbtt_vertex_das):void>)

Iterate glyph shape vertices for a codepoint via callback.


:Arguments: * **info** :  :ref:`stbtt_fontinfo <handle-stbtruetype-stbtt_fontinfo>`

            * **codepoint** : int

            * **blk** : block<(v: :ref:`stbtt_vertex_das <handle-stbtruetype-stbtt_vertex_das>`):void>

.. _function-stbimage_ttf_stbtt_codepoint_shape_count_stbtt_fontinfo_int:

.. das:function:: stbtt_codepoint_shape_count(info: stbtt_fontinfo; codepoint: int) : int

Returns the number of shape vertices for a codepoint.


:Arguments: * **info** :  :ref:`stbtt_fontinfo <handle-stbtruetype-stbtt_fontinfo>`

            * **codepoint** : int


++++++++++++++++++++++++++
Low-level bitmap rendering
++++++++++++++++++++++++++

  *  :ref:`stbtt_codepoint_bitmap (info: stbtt_fontinfo; codepoint: int; scale_x: float; scale_y: float) : tuple\<image:Image;offset:int2\> <function-stbimage_ttf_stbtt_codepoint_bitmap_stbtt_fontinfo_int_float_float>`
  *  :ref:`stbtt_codepoint_bitmap_box (info: stbtt_fontinfo; codepoint: int; scale_x: float; scale_y: float) : int4 <function-stbimage_ttf_stbtt_codepoint_bitmap_box_stbtt_fontinfo_int_float_float>`
  *  :ref:`stbtt_codepoint_bitmap_box_subpixel (info: stbtt_fontinfo; codepoint: int; scale_x: float; scale_y: float; shift_x: float; shift_y: float) : int4 <function-stbimage_ttf_stbtt_codepoint_bitmap_box_subpixel_stbtt_fontinfo_int_float_float_float_float>`
  *  :ref:`stbtt_codepoint_bitmap_subpixel (info: stbtt_fontinfo; codepoint: int; scale_x: float; scale_y: float; shift_x: float; shift_y: float) : tuple\<image:Image;offset:int2\> <function-stbimage_ttf_stbtt_codepoint_bitmap_subpixel_stbtt_fontinfo_int_float_float_float_float>`
  *  :ref:`stbtt_make_codepoint_bitmap (info: stbtt_fontinfo; var buf: array\<uint8\>; out_w: int; out_h: int; out_stride: int; scale_x: float; scale_y: float; codepoint: int) <function-stbimage_ttf_stbtt_make_codepoint_bitmap_stbtt_fontinfo_array_ls_uint8_gr__int_int_int_float_float_int>`
  *  :ref:`stbtt_make_codepoint_bitmap_subpixel (info: stbtt_fontinfo; var buf: array\<uint8\>; out_w: int; out_h: int; out_stride: int; scale_x: float; scale_y: float; shift_x: float; shift_y: float; codepoint: int) <function-stbimage_ttf_stbtt_make_codepoint_bitmap_subpixel_stbtt_fontinfo_array_ls_uint8_gr__int_int_int_float_float_float_float_int>`

.. _function-stbimage_ttf_stbtt_codepoint_bitmap_stbtt_fontinfo_int_float_float:

.. das:function:: stbtt_codepoint_bitmap(info: stbtt_fontinfo; codepoint: int; scale_x: float; scale_y: float) : tuple<image:Image;offset:int2>

Renders a codepoint glyph bitmap at the given scale. Returns a 1-channel ``Image`` and pixel offset.
The returned Image owns the pixel data (copied from stb allocation).


:Arguments: * **info** :  :ref:`stbtt_fontinfo <handle-stbtruetype-stbtt_fontinfo>`

            * **codepoint** : int

            * **scale_x** : float

            * **scale_y** : float

.. _function-stbimage_ttf_stbtt_codepoint_bitmap_box_stbtt_fontinfo_int_float_float:

.. das:function:: stbtt_codepoint_bitmap_box(info: stbtt_fontinfo; codepoint: int; scale_x: float; scale_y: float) : int4

Returns pixel-space bounding box ``int4(ix0, iy0, ix1, iy1)`` for a codepoint bitmap at the given scale.


:Arguments: * **info** :  :ref:`stbtt_fontinfo <handle-stbtruetype-stbtt_fontinfo>`

            * **codepoint** : int

            * **scale_x** : float

            * **scale_y** : float

.. _function-stbimage_ttf_stbtt_codepoint_bitmap_box_subpixel_stbtt_fontinfo_int_float_float_float_float:

.. das:function:: stbtt_codepoint_bitmap_box_subpixel(info: stbtt_fontinfo; codepoint: int; scale_x: float; scale_y: float; shift_x: float; shift_y: float) : int4

Returns pixel-space bounding box with subpixel shift.


:Arguments: * **info** :  :ref:`stbtt_fontinfo <handle-stbtruetype-stbtt_fontinfo>`

            * **codepoint** : int

            * **scale_x** : float

            * **scale_y** : float

            * **shift_x** : float

            * **shift_y** : float

.. _function-stbimage_ttf_stbtt_codepoint_bitmap_subpixel_stbtt_fontinfo_int_float_float_float_float:

.. das:function:: stbtt_codepoint_bitmap_subpixel(info: stbtt_fontinfo; codepoint: int; scale_x: float; scale_y: float; shift_x: float; shift_y: float) : tuple<image:Image;offset:int2>

Renders a codepoint glyph bitmap with subpixel shift. Returns a 1-channel ``Image`` and pixel offset.


:Arguments: * **info** :  :ref:`stbtt_fontinfo <handle-stbtruetype-stbtt_fontinfo>`

            * **codepoint** : int

            * **scale_x** : float

            * **scale_y** : float

            * **shift_x** : float

            * **shift_y** : float

.. _function-stbimage_ttf_stbtt_make_codepoint_bitmap_stbtt_fontinfo_array_ls_uint8_gr__int_int_int_float_float_int:

.. das:function:: stbtt_make_codepoint_bitmap(info: stbtt_fontinfo; buf: array<uint8>; out_w: int; out_h: int; out_stride: int; scale_x: float; scale_y: float; codepoint: int)

Renders a codepoint glyph into a caller-provided buffer.
``buf`` must be at least ``out_h * out_stride`` bytes.


:Arguments: * **info** :  :ref:`stbtt_fontinfo <handle-stbtruetype-stbtt_fontinfo>`

            * **buf** : array<uint8>

            * **out_w** : int

            * **out_h** : int

            * **out_stride** : int

            * **scale_x** : float

            * **scale_y** : float

            * **codepoint** : int

.. _function-stbimage_ttf_stbtt_make_codepoint_bitmap_subpixel_stbtt_fontinfo_array_ls_uint8_gr__int_int_int_float_float_float_float_int:

.. das:function:: stbtt_make_codepoint_bitmap_subpixel(info: stbtt_fontinfo; buf: array<uint8>; out_w: int; out_h: int; out_stride: int; scale_x: float; scale_y: float; shift_x: float; shift_y: float; codepoint: int)

Renders a codepoint glyph with subpixel shift into a caller-provided buffer.


:Arguments: * **info** :  :ref:`stbtt_fontinfo <handle-stbtruetype-stbtt_fontinfo>`

            * **buf** : array<uint8>

            * **out_w** : int

            * **out_h** : int

            * **out_stride** : int

            * **scale_x** : float

            * **scale_y** : float

            * **shift_x** : float

            * **shift_y** : float

            * **codepoint** : int


+++++++++++++++++
Low-level packing
+++++++++++++++++

  *  :ref:`stbtt_pack (var data: array\<uint8\>; var pixels: array\<uint8\>; atlas_w: int; atlas_h: int; var chardata: array\<stbtt_packedchar\>; font_size: float; first_char: int; num_chars: int; oversampling: int = 1; font_index: int = 0) <function-stbimage_ttf_stbtt_pack_array_ls_uint8_gr__array_ls_uint8_gr__int_int_array_ls_stbtt_packedchar_gr__float_int_int_int_int>`
  *  :ref:`stbtt_packed_quad (chardata: array\<stbtt_packedchar\>; atlas_w: int; atlas_h: int; char_index: int; var xpos: float&; align_to_integer: bool = false) : stbtt_aligned_quad <function-stbimage_ttf_stbtt_packed_quad_array_ls_stbtt_packedchar_gr__int_int_int_float_ref__bool>`

.. _function-stbimage_ttf_stbtt_pack_array_ls_uint8_gr__array_ls_uint8_gr__int_int_array_ls_stbtt_packedchar_gr__float_int_int_int_int:

.. das:function:: stbtt_pack(data: array<uint8>; pixels: array<uint8>; atlas_w: int; atlas_h: int; chardata: array<stbtt_packedchar>; font_size: float; first_char: int; num_chars: int; oversampling: int = 1; font_index: int = 0)

Pack a character range into an atlas bitmap.
Wraps PackBegin + SetOversampling + PackFontRange + PackEnd.


:Arguments: * **data** : array<uint8>

            * **pixels** : array<uint8>

            * **atlas_w** : int

            * **atlas_h** : int

            * **chardata** : array< :ref:`stbtt_packedchar <handle-stbtruetype-stbtt_packedchar>`>

            * **font_size** : float

            * **first_char** : int

            * **num_chars** : int

            * **oversampling** : int

            * **font_index** : int

.. _function-stbimage_ttf_stbtt_packed_quad_array_ls_stbtt_packedchar_gr__int_int_int_float_ref__bool:

.. das:function:: stbtt_packed_quad(chardata: array<stbtt_packedchar>; atlas_w: int; atlas_h: int; char_index: int; xpos: float&; align_to_integer: bool = false) : stbtt_aligned_quad

Returns the packed quad for a character, advancing ``xpos``.
``char_index`` is relative to the first packed character.


:Arguments: * **chardata** : array< :ref:`stbtt_packedchar <handle-stbtruetype-stbtt_packedchar>`>

            * **atlas_w** : int

            * **atlas_h** : int

            * **char_index** : int

            * **xpos** : float\ &

            * **align_to_integer** : bool


++++++++++++
Font loading
++++++++++++

  *  :ref:`is_valid (font: Font) : bool <function-stbimage_ttf_is_valid_Font>`
  *  :ref:`load_font (fname: string) : Font <function-stbimage_ttf_load_font_string>`
  *  :ref:`load_ttf (fname: string; pixel_height: float = 32f; atlas_dim: int2 = int2(512,512); first_char: int = 32; num_chars: int = 96; oversampling: int = 1) : Font <function-stbimage_ttf_load_ttf_string_float_int2_int_int_int>`

.. _function-stbimage_ttf_is_valid_Font:

.. das:function:: is_valid(font: Font) : bool

Returns ``true`` if the font has been successfully loaded.


:Arguments: * **font** :  :ref:`Font <struct-stbimage_ttf-Font>`

.. _function-stbimage_ttf_load_font_string:

.. das:function:: load_font(fname: string) : Font

Load a TrueType font from file for metrics and shape queries (no atlas).

Returns a Font with ``pixel_height = 0`` and empty atlas fields.
Use ``scale_for_pixel_height`` to compute a scale factor for a desired size.


:Arguments: * **fname** : string

.. _function-stbimage_ttf_load_ttf_string_float_int2_int_int_int:

.. das:function:: load_ttf(fname: string; pixel_height: float = 32f; atlas_dim: int2 = int2(512,512); first_char: int = 32; num_chars: int = 96; oversampling: int = 1) : Font

Load a TrueType font from file and pack a character range into an atlas.

Returns a Font with bitmap stored as a 1-channel Image.
If loading fails, returns a Font with an invalid bitmap.


:Arguments: * **fname** : string

            * **pixel_height** : float

            * **atlas_dim** : int2

            * **first_char** : int

            * **num_chars** : int

            * **oversampling** : int


++++++++++
Font scale
++++++++++

  *  :ref:`scale_for_em (font: Font; pixels: float) : float <function-stbimage_ttf_scale_for_em_Font_float>`
  *  :ref:`scale_for_pixel_height (font: Font; pixel_height: float) : float <function-stbimage_ttf_scale_for_pixel_height_Font_float>`

.. _function-stbimage_ttf_scale_for_em_Font_float:

.. das:function:: scale_for_em(font: Font; pixels: float) : float

Compute scale factor for mapping em to pixels.


:Arguments: * **font** :  :ref:`Font <struct-stbimage_ttf-Font>`

            * **pixels** : float

.. _function-stbimage_ttf_scale_for_pixel_height_Font_float:

.. das:function:: scale_for_pixel_height(font: Font; pixel_height: float) : float

Compute scale factor for a given pixel height.


:Arguments: * **font** :  :ref:`Font <struct-stbimage_ttf-Font>`

            * **pixel_height** : float


++++++++++++
Font metrics
++++++++++++

  *  :ref:`codepoint_box (font: Font; codepoint: int) : int4 <function-stbimage_ttf_codepoint_box_Font_int>`
  *  :ref:`codepoint_hmetrics (font: Font; codepoint: int) : tuple\<advance_width:int;left_side_bearing:int\> <function-stbimage_ttf_codepoint_hmetrics_Font_int>`
  *  :ref:`codepoint_kern (font: Font; ch1: int; ch2: int) : int <function-stbimage_ttf_codepoint_kern_Font_int_int>`
  *  :ref:`find_glyph (font: Font; codepoint: int) : int <function-stbimage_ttf_find_glyph_Font_int>`
  *  :ref:`font_bounding_box (font: Font) : int4 <function-stbimage_ttf_font_bounding_box_Font>`
  *  :ref:`font_metrics (font: Font) : tuple\<ascent:float;descent:float;line_height:float\> <function-stbimage_ttf_font_metrics_Font>`
  *  :ref:`font_metrics (font: Font; pixel_height: float) : tuple\<ascent:float;descent:float;line_height:float\> <function-stbimage_ttf_font_metrics_Font_float>`
  *  :ref:`font_vmetrics (font: Font) : tuple\<ascent:int;descent:int;line_gap:int\> <function-stbimage_ttf_font_vmetrics_Font>`

.. _function-stbimage_ttf_codepoint_box_Font_int:

.. das:function:: codepoint_box(font: Font; codepoint: int) : int4

Returns glyph bounding box ``int4(x0, y0, x1, y1)`` in font units.


:Arguments: * **font** :  :ref:`Font <struct-stbimage_ttf-Font>`

            * **codepoint** : int

.. _function-stbimage_ttf_codepoint_hmetrics_Font_int:

.. das:function:: codepoint_hmetrics(font: Font; codepoint: int) : tuple<advance_width:int;left_side_bearing:int>

Returns horizontal metrics in font units for a codepoint.


:Arguments: * **font** :  :ref:`Font <struct-stbimage_ttf-Font>`

            * **codepoint** : int

.. _function-stbimage_ttf_codepoint_kern_Font_int_int:

.. das:function:: codepoint_kern(font: Font; ch1: int; ch2: int) : int

Returns kerning advance between two codepoints in font units.


:Arguments: * **font** :  :ref:`Font <struct-stbimage_ttf-Font>`

            * **ch1** : int

            * **ch2** : int

.. _function-stbimage_ttf_find_glyph_Font_int:

.. das:function:: find_glyph(font: Font; codepoint: int) : int

Returns glyph index for a codepoint. Returns 0 if not found.


:Arguments: * **font** :  :ref:`Font <struct-stbimage_ttf-Font>`

            * **codepoint** : int

.. _function-stbimage_ttf_font_bounding_box_Font:

.. das:function:: font_bounding_box(font: Font) : int4

Returns font bounding box ``int4(x0, y0, x1, y1)`` in font units.


:Arguments: * **font** :  :ref:`Font <struct-stbimage_ttf-Font>`


font_metrics
^^^^^^^^^^^^

.. _function-stbimage_ttf_font_metrics_Font:

.. das:function:: font_metrics(font: Font) : tuple<ascent:float;descent:float;line_height:float>

Returns font metrics in pixels using the font's ``pixel_height``.
Ascent is baseline to top, descent is baseline to bottom (negative),
line_height is recommended line spacing.


:Arguments: * **font** :  :ref:`Font <struct-stbimage_ttf-Font>`

.. _function-stbimage_ttf_font_metrics_Font_float:

.. das:function:: font_metrics(font: Font; pixel_height: float) : tuple<ascent:float;descent:float;line_height:float>

----

.. _function-stbimage_ttf_font_vmetrics_Font:

.. das:function:: font_vmetrics(font: Font) : tuple<ascent:int;descent:int;line_gap:int>

Returns vertical metrics in font units: ascent, descent, line gap.


:Arguments: * **font** :  :ref:`Font <struct-stbimage_ttf-Font>`


++++++++++++++++
Font glyph shape
++++++++++++++++

  *  :ref:`codepoint_shape (font: Font; codepoint: int; blk: block\<(v:stbtt_vertex_das):void\>) <function-stbimage_ttf_codepoint_shape_Font_int_block_ls_v_c_stbtt_vertex_das_c_void_gr_>`
  *  :ref:`codepoint_shape_count (font: Font; codepoint: int) : int <function-stbimage_ttf_codepoint_shape_count_Font_int>`

.. _function-stbimage_ttf_codepoint_shape_Font_int_block_ls_v_c_stbtt_vertex_das_c_void_gr_:

.. das:function:: codepoint_shape(font: Font; codepoint: int; blk: block<(v:stbtt_vertex_das):void>)

Iterate glyph shape vertices for a codepoint via callback.


:Arguments: * **font** :  :ref:`Font <struct-stbimage_ttf-Font>`

            * **codepoint** : int

            * **blk** : block<(v: :ref:`stbtt_vertex_das <handle-stbtruetype-stbtt_vertex_das>`):void>

.. _function-stbimage_ttf_codepoint_shape_count_Font_int:

.. das:function:: codepoint_shape_count(font: Font; codepoint: int) : int

Returns the number of shape vertices for a codepoint.


:Arguments: * **font** :  :ref:`Font <struct-stbimage_ttf-Font>`

            * **codepoint** : int


+++++++++++++++++++++
Font bitmap rendering
+++++++++++++++++++++

  *  :ref:`codepoint_bitmap (font: Font; codepoint: int; scale_x: float; scale_y: float) : tuple\<image:Image;offset:int2\> <function-stbimage_ttf_codepoint_bitmap_Font_int_float_float>`
  *  :ref:`codepoint_bitmap_box (font: Font; codepoint: int; scale_x: float; scale_y: float) : int4 <function-stbimage_ttf_codepoint_bitmap_box_Font_int_float_float>`
  *  :ref:`codepoint_bitmap_box_subpixel (font: Font; codepoint: int; scale_x: float; scale_y: float; shift_x: float; shift_y: float) : int4 <function-stbimage_ttf_codepoint_bitmap_box_subpixel_Font_int_float_float_float_float>`
  *  :ref:`codepoint_bitmap_subpixel (font: Font; codepoint: int; scale_x: float; scale_y: float; shift_x: float; shift_y: float) : tuple\<image:Image;offset:int2\> <function-stbimage_ttf_codepoint_bitmap_subpixel_Font_int_float_float_float_float>`

.. _function-stbimage_ttf_codepoint_bitmap_Font_int_float_float:

.. das:function:: codepoint_bitmap(font: Font; codepoint: int; scale_x: float; scale_y: float) : tuple<image:Image;offset:int2>

Renders a codepoint glyph bitmap at the given scale. Returns a 1-channel ``Image`` and pixel offset.


:Arguments: * **font** :  :ref:`Font <struct-stbimage_ttf-Font>`

            * **codepoint** : int

            * **scale_x** : float

            * **scale_y** : float

.. _function-stbimage_ttf_codepoint_bitmap_box_Font_int_float_float:

.. das:function:: codepoint_bitmap_box(font: Font; codepoint: int; scale_x: float; scale_y: float) : int4

Returns pixel-space bounding box ``int4(ix0, iy0, ix1, iy1)`` for a codepoint bitmap.


:Arguments: * **font** :  :ref:`Font <struct-stbimage_ttf-Font>`

            * **codepoint** : int

            * **scale_x** : float

            * **scale_y** : float

.. _function-stbimage_ttf_codepoint_bitmap_box_subpixel_Font_int_float_float_float_float:

.. das:function:: codepoint_bitmap_box_subpixel(font: Font; codepoint: int; scale_x: float; scale_y: float; shift_x: float; shift_y: float) : int4

Returns pixel-space bounding box with subpixel shift.


:Arguments: * **font** :  :ref:`Font <struct-stbimage_ttf-Font>`

            * **codepoint** : int

            * **scale_x** : float

            * **scale_y** : float

            * **shift_x** : float

            * **shift_y** : float

.. _function-stbimage_ttf_codepoint_bitmap_subpixel_Font_int_float_float_float_float:

.. das:function:: codepoint_bitmap_subpixel(font: Font; codepoint: int; scale_x: float; scale_y: float; shift_x: float; shift_y: float) : tuple<image:Image;offset:int2>

Renders a codepoint glyph bitmap with subpixel shift.


:Arguments: * **font** :  :ref:`Font <struct-stbimage_ttf-Font>`

            * **codepoint** : int

            * **scale_x** : float

            * **scale_y** : float

            * **shift_x** : float

            * **shift_y** : float


++++++++++++++++++++++++++++++
Text measurement and rendering
++++++++++++++++++++++++++++++

  *  :ref:`measure_text (font: Font; text: string; pixel_height: float) : float <function-stbimage_ttf_measure_text_Font_string_float>`
  *  :ref:`render_text (var dst: Image; font: Font; text: string; x: int; y: int; r: int; g: int; b: int) <function-stbimage_ttf_render_text_Image_Font_string_int_int_int_int_int>`

.. _function-stbimage_ttf_measure_text_Font_string_float:

.. das:function:: measure_text(font: Font; text: string; pixel_height: float) : float

Measure the width of a string in pixels at the given pixel height.


:Arguments: * **font** :  :ref:`Font <struct-stbimage_ttf-Font>`

            * **text** : string

            * **pixel_height** : float

.. _function-stbimage_ttf_render_text_Image_Font_string_int_int_int_int_int:

.. das:function:: render_text(dst: Image; font: Font; text: string; x: int; y: int; r: int; g: int; b: int)

Render text onto a 4-channel RGBA image using pixel-to-pixel alpha blit.

``x, y`` is the position of the text baseline origin.
Each glyph is blitted from the 1-channel font atlas with the given (r,g,b) color.
Uses packedchar fields directly for pixel-to-pixel blit.
Best results with oversampling=1 (the default for software rendering).
Clips to destination bounds automatically.


:Arguments: * **dst** :  :ref:`Image <struct-stbimage_boost-Image>`

            * **font** :  :ref:`Font <struct-stbimage_ttf-Font>`

            * **text** : string

            * **x** : int

            * **y** : int

            * **r** : int

            * **g** : int

            * **b** : int