.. _stdlib_stbtruetype: ====================================================== TrueType font loading and rasterization (stb_truetype) ====================================================== .. das:module:: stbtruetype Low-level TrueType font bindings for stb_truetype. Provides font loading, glyph packing into atlases, font metrics, codepoint metrics, and bitmap rasterization. Use ``stbimage_ttf`` for a high-level API. +++++++++ Constants +++++++++ .. _global-stbtruetype-STBTT_vmove: .. das:attribute:: STBTT_vmove = 1 Vertex type constant for a move-to command (start of a new contour). .. _global-stbtruetype-STBTT_vline: .. das:attribute:: STBTT_vline = 2 Vertex type constant for a line-to command (straight line segment). .. _global-stbtruetype-STBTT_vcurve: .. das:attribute:: STBTT_vcurve = 3 Vertex type constant for a quadratic Bezier curve segment. .. _global-stbtruetype-STBTT_vcubic: .. das:attribute:: STBTT_vcubic = 4 Vertex type constant for a cubic Bezier curve segment. ++++++++++++++++++ Handled structures ++++++++++++++++++ .. _handle-stbtruetype-stbtt_packedchar: .. das:attribute:: stbtt_packedchar Packed character data produced by PackFontRange. Contains atlas coordinates, screen offsets, and advance width. :Fields: * **x0** : uint16 - Atlas left edge (in pixels). * **y0** : uint16 - Atlas top edge (in pixels). * **x1** : uint16 - Atlas right edge (in pixels). * **y1** : uint16 - Atlas bottom edge (in pixels). * **xoff** : float - Screen-space left offset from cursor. * **yoff** : float - Screen-space top offset from baseline. * **xadvance** : float - Horizontal advance to next character. * **xoff2** : float - Screen-space right offset from cursor. * **yoff2** : float - Screen-space bottom offset from baseline. .. _handle-stbtruetype-stbtt_aligned_quad: .. das:attribute:: stbtt_aligned_quad Screen-space quad with texture coordinates, produced by GetPackedQuad. :Fields: * **x0** : float - Texture coordinate top (V). * **y0** : float - Screen-space right edge. * **s0** : float - Screen-space left edge. * **t0** : float - Texture coordinate bottom (V). * **x1** : float - Texture coordinate left (U). * **y1** : float - Screen-space top edge. * **s1** : float - Screen-space bottom edge. * **t1** : float - Texture coordinate right (U). .. _handle-stbtruetype-stbtt_vertex_das: .. das:attribute:: stbtt_vertex_das A glyph outline vertex with endpoint coordinates, control points, and a vertex type. :Fields: * **x** : int16 - Endpoint x coordinate. * **y** : int16 - Endpoint y coordinate. * **cx** : int16 - Quadratic Bezier control point x coordinate. * **cy** : int16 - Quadratic Bezier control point y coordinate. * **cx1** : int16 - Cubic Bezier control point x coordinate. * **cy1** : int16 - Cubic Bezier control point y coordinate. * **vtype** : uint8 - Vertex type: STBTT_vmove (1), STBTT_vline (2), STBTT_vcurve (3), or STBTT_vcubic (4). .. _handle-stbtruetype-stbtt_fontinfo: .. das:attribute:: stbtt_fontinfo Font info structure initialized by InitFont. Required by all metric and rasterization functions. :Fields: * **numGlyphs** : int - Number of glyphs in the font. .. _handle-stbtruetype-stbtt_pack_context: .. das:attribute:: stbtt_pack_context Opaque packing context used by PackBegin, PackFontRange, and PackEnd. ++++++++++++ Font loading ++++++++++++ * :ref:`stbtt_GetFontOffsetForIndex (data: uint8 const?; index: int) : int ` * :ref:`stbtt_GetNumberOfFonts (data: uint8 const?) : int ` * :ref:`stbtt_InitFont (info: stbtt_fontinfo?; data: uint8 const?; offset: int) : int ` .. _function-stbtruetype_stbtt_GetFontOffsetForIndex_uint8_const_q__int: .. das:function:: stbtt_GetFontOffsetForIndex(data: uint8 const?; index: int) : int Return the byte offset of the Nth font in a collection. For non-collection files, index 0 returns 0. :Arguments: * **data** : uint8? implicit * **index** : int .. _function-stbtruetype_stbtt_GetNumberOfFonts_uint8_const_q_: .. das:function:: stbtt_GetNumberOfFonts(data: uint8 const?) : int Return the number of fonts in a TrueType collection (.ttc) file. Returns 1 for ordinary .ttf files. :Arguments: * **data** : uint8? implicit .. _function-stbtruetype_stbtt_InitFont_stbtt_fontinfo_q__uint8_const_q__int: .. das:function:: stbtt_InitFont(info: stbtt_fontinfo?; data: uint8 const?; offset: int) : int Initialize a font info structure from raw font data at the given byte offset. Returns non-zero on success. :Arguments: * **info** : :ref:`stbtt_fontinfo `? implicit * **data** : uint8? implicit * **offset** : int ++++++++++++ Font packing ++++++++++++ * :ref:`stbtt_GetPackedQuad (chardata: stbtt_packedchar const?; pw: int; ph: int; char_index: int; xpos: float?; ypos: float?; q: stbtt_aligned_quad?; align_to_integer: int) ` * :ref:`stbtt_PackBegin (spc: stbtt_pack_context?; pixels: uint8?; width: int; height: int; stride_in_bytes: int; padding: int; alloc_context: void?) : int ` * :ref:`stbtt_PackEnd (spc: stbtt_pack_context?) ` * :ref:`stbtt_PackFontRange (spc: stbtt_pack_context?; fontdata: uint8 const?; font_index: int; font_size: float; first_unicode_char_in_range: int; num_chars_in_range: int; chardata_for_range: stbtt_packedchar?) : int ` * :ref:`stbtt_PackSetOversampling (spc: stbtt_pack_context?; h_oversample: uint; v_oversample: uint) ` * :ref:`stbtt_PackSetSkipMissingCodepoints (spc: stbtt_pack_context?; skip: int) ` .. _function-stbtruetype_stbtt_GetPackedQuad_stbtt_packedchar_const_q__int_int_int_float_q__float_q__stbtt_aligned_quad_q__int: .. das:function:: stbtt_GetPackedQuad(chardata: stbtt_packedchar const?; pw: int; ph: int; char_index: int; xpos: float?; ypos: float?; q: stbtt_aligned_quad?; align_to_integer: int) Get the screen-space quad and texture coordinates for a packed character. Advances the cursor position for the next character. :Arguments: * **chardata** : :ref:`stbtt_packedchar `? implicit * **pw** : int * **ph** : int * **char_index** : int * **xpos** : float? implicit * **ypos** : float? implicit * **q** : :ref:`stbtt_aligned_quad `? implicit * **align_to_integer** : int .. _function-stbtruetype_stbtt_PackBegin_stbtt_pack_context_q__uint8_q__int_int_int_int_void_q_: .. das:function:: stbtt_PackBegin(spc: stbtt_pack_context?; pixels: uint8?; width: int; height: int; stride_in_bytes: int; padding: int; alloc_context: void?) : int Initialize a packing context for packing font glyphs into an atlas bitmap. The bitmap must be pre-allocated. :Arguments: * **spc** : :ref:`stbtt_pack_context `? implicit * **pixels** : uint8? implicit * **width** : int * **height** : int * **stride_in_bytes** : int * **padding** : int * **alloc_context** : void? implicit .. _function-stbtruetype_stbtt_PackEnd_stbtt_pack_context_q_: .. das:function:: stbtt_PackEnd(spc: stbtt_pack_context?) Clean up a packing context after all fonts have been packed. :Arguments: * **spc** : :ref:`stbtt_pack_context `? implicit .. _function-stbtruetype_stbtt_PackFontRange_stbtt_pack_context_q__uint8_const_q__int_float_int_int_stbtt_packedchar_q_: .. das:function:: stbtt_PackFontRange(spc: stbtt_pack_context?; fontdata: uint8 const?; font_index: int; font_size: float; first_unicode_char_in_range: int; num_chars_in_range: int; chardata_for_range: stbtt_packedchar?) : int Pack a range of characters from a font into the atlas at the specified pixel height. Stores packed character data for later quad generation. :Arguments: * **spc** : :ref:`stbtt_pack_context `? implicit * **fontdata** : uint8? implicit * **font_index** : int * **font_size** : float * **first_unicode_char_in_range** : int * **num_chars_in_range** : int * **chardata_for_range** : :ref:`stbtt_packedchar `? implicit .. _function-stbtruetype_stbtt_PackSetOversampling_stbtt_pack_context_q__uint_uint: .. das:function:: stbtt_PackSetOversampling(spc: stbtt_pack_context?; h_oversample: uint; v_oversample: uint) Set horizontal and vertical oversampling for subsequent PackFontRange calls. Higher oversampling improves quality with GPU bilinear filtering but increases atlas size. :Arguments: * **spc** : :ref:`stbtt_pack_context `? implicit * **h_oversample** : uint * **v_oversample** : uint .. _function-stbtruetype_stbtt_PackSetSkipMissingCodepoints_stbtt_pack_context_q__int: .. das:function:: stbtt_PackSetSkipMissingCodepoints(spc: stbtt_pack_context?; skip: int) Control whether missing codepoints produce warning rectangles (default) or are silently skipped during packing. :Arguments: * **spc** : :ref:`stbtt_pack_context `? implicit * **skip** : int ++++++++++++ Font metrics ++++++++++++ * :ref:`stbtt_GetFontBoundingBox (info: stbtt_fontinfo const?; x0: int?; y0: int?; x1: int?; y1: int?) ` * :ref:`stbtt_GetFontVMetrics (info: stbtt_fontinfo const?; ascent: int?; descent: int?; lineGap: int?) ` * :ref:`stbtt_ScaleForMappingEmToPixels (info: stbtt_fontinfo const?; pixels: float) : float ` * :ref:`stbtt_ScaleForPixelHeight (info: stbtt_fontinfo const?; pixels: float) : float ` .. _function-stbtruetype_stbtt_GetFontBoundingBox_stbtt_fontinfo_const_q__int_q__int_q__int_q__int_q_: .. das:function:: stbtt_GetFontBoundingBox(info: stbtt_fontinfo const?; x0: int?; y0: int?; x1: int?; y1: int?) Get the bounding box of all glyphs in the font in unscaled coordinates. :Arguments: * **info** : :ref:`stbtt_fontinfo `? implicit * **x0** : int? implicit * **y0** : int? implicit * **x1** : int? implicit * **y1** : int? implicit .. _function-stbtruetype_stbtt_GetFontVMetrics_stbtt_fontinfo_const_q__int_q__int_q__int_q_: .. das:function:: stbtt_GetFontVMetrics(info: stbtt_fontinfo const?; ascent: int?; descent: int?; lineGap: int?) Get vertical metrics for the font: ascent, descent, and line gap in unscaled coordinates. Multiply by the scale factor for pixel values. :Arguments: * **info** : :ref:`stbtt_fontinfo `? implicit * **ascent** : int? implicit * **descent** : int? implicit * **lineGap** : int? implicit .. _function-stbtruetype_stbtt_ScaleForMappingEmToPixels_stbtt_fontinfo_const_q__float: .. das:function:: stbtt_ScaleForMappingEmToPixels(info: stbtt_fontinfo const?; pixels: float) : float Compute the scale factor to map font design units (em) to the given pixel size. :Arguments: * **info** : :ref:`stbtt_fontinfo `? implicit * **pixels** : float .. _function-stbtruetype_stbtt_ScaleForPixelHeight_stbtt_fontinfo_const_q__float: .. das:function:: stbtt_ScaleForPixelHeight(info: stbtt_fontinfo const?; pixels: float) : float Compute the scale factor to produce a font whose ascent-to-descent distance equals the given pixel height. :Arguments: * **info** : :ref:`stbtt_fontinfo `? implicit * **pixels** : float +++++++++++++++++ Codepoint metrics +++++++++++++++++ * :ref:`stbtt_FindGlyphIndex (info: stbtt_fontinfo const?; unicode_codepoint: int) : int ` * :ref:`stbtt_GetCodepointBox (info: stbtt_fontinfo const?; codepoint: int; x0: int?; y0: int?; x1: int?; y1: int?) : int ` * :ref:`stbtt_GetCodepointHMetrics (info: stbtt_fontinfo const?; codepoint: int; advanceWidth: int?; leftSideBearing: int?) ` * :ref:`stbtt_GetCodepointKernAdvance (info: stbtt_fontinfo const?; ch1: int; ch2: int) : int ` .. _function-stbtruetype_stbtt_FindGlyphIndex_stbtt_fontinfo_const_q__int: .. das:function:: stbtt_FindGlyphIndex(info: stbtt_fontinfo const?; unicode_codepoint: int) : int Return the glyph index for a Unicode codepoint. Returns 0 if the codepoint is not defined in the font. :Arguments: * **info** : :ref:`stbtt_fontinfo `? implicit * **unicode_codepoint** : int .. _function-stbtruetype_stbtt_GetCodepointBox_stbtt_fontinfo_const_q__int_int_q__int_q__int_q__int_q_: .. das:function:: stbtt_GetCodepointBox(info: stbtt_fontinfo const?; codepoint: int; x0: int?; y0: int?; x1: int?; y1: int?) : int Get the bounding box of a codepoint's glyph in unscaled coordinates. Returns non-zero if the glyph exists. :Arguments: * **info** : :ref:`stbtt_fontinfo `? implicit * **codepoint** : int * **x0** : int? implicit * **y0** : int? implicit * **x1** : int? implicit * **y1** : int? implicit .. _function-stbtruetype_stbtt_GetCodepointHMetrics_stbtt_fontinfo_const_q__int_int_q__int_q_: .. das:function:: stbtt_GetCodepointHMetrics(info: stbtt_fontinfo const?; codepoint: int; advanceWidth: int?; leftSideBearing: int?) Get horizontal metrics for a codepoint: advance width and left side bearing in unscaled coordinates. :Arguments: * **info** : :ref:`stbtt_fontinfo `? implicit * **codepoint** : int * **advanceWidth** : int? implicit * **leftSideBearing** : int? implicit .. _function-stbtruetype_stbtt_GetCodepointKernAdvance_stbtt_fontinfo_const_q__int_int: .. das:function:: stbtt_GetCodepointKernAdvance(info: stbtt_fontinfo const?; ch1: int; ch2: int) : int Get the kerning adjustment between two codepoints in unscaled coordinates. :Arguments: * **info** : :ref:`stbtt_fontinfo `? implicit * **ch1** : int * **ch2** : int +++++++++++++++++ Codepoint bitmaps +++++++++++++++++ * :ref:`stbtt_FreeBitmap (bitmap: uint8?; userdata: void?) ` * :ref:`stbtt_GetCodepointBitmap (info: stbtt_fontinfo const?; scale_x: float; scale_y: float; codepoint: int; width: int?; height: int?; xoff: int?; yoff: int?) : uint8? ` * :ref:`stbtt_GetCodepointBitmapBox (font: stbtt_fontinfo const?; codepoint: int; scale_x: float; scale_y: float; ix0: int?; iy0: int?; ix1: int?; iy1: int?) ` * :ref:`stbtt_GetCodepointBitmapBoxSubpixel (font: stbtt_fontinfo const?; codepoint: int; scale_x: float; scale_y: float; shift_x: float; shift_y: float; ix0: int?; iy0: int?; ix1: int?; iy1: int?) ` * :ref:`stbtt_GetCodepointBitmapSubpixel (info: stbtt_fontinfo const?; scale_x: float; scale_y: float; shift_x: float; shift_y: float; codepoint: int; width: int?; height: int?; xoff: int?; yoff: int?) : uint8? ` * :ref:`stbtt_MakeCodepointBitmap (info: stbtt_fontinfo const?; output: uint8?; out_w: int; out_h: int; out_stride: int; scale_x: float; scale_y: float; codepoint: int) ` * :ref:`stbtt_MakeCodepointBitmapSubpixel (info: stbtt_fontinfo const?; output: 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-stbtruetype_stbtt_FreeBitmap_uint8_q__void_q_: .. das:function:: stbtt_FreeBitmap(bitmap: uint8?; userdata: void?) Free a bitmap allocated by GetCodepointBitmap or GetCodepointBitmapSubpixel. :Arguments: * **bitmap** : uint8? implicit * **userdata** : void? implicit .. _function-stbtruetype_stbtt_GetCodepointBitmap_stbtt_fontinfo_const_q__float_float_int_int_q__int_q__int_q__int_q_: .. das:function:: stbtt_GetCodepointBitmap(info: stbtt_fontinfo const?; scale_x: float; scale_y: float; codepoint: int; width: int?; height: int?; xoff: int?; yoff: int?) : uint8? Render a codepoint glyph into a newly allocated 1-channel bitmap at the given scale. Returns the bitmap pointer, width, height, and offsets. :Arguments: * **info** : :ref:`stbtt_fontinfo `? implicit * **scale_x** : float * **scale_y** : float * **codepoint** : int * **width** : int? implicit * **height** : int? implicit * **xoff** : int? implicit * **yoff** : int? implicit .. _function-stbtruetype_stbtt_GetCodepointBitmapBox_stbtt_fontinfo_const_q__int_float_float_int_q__int_q__int_q__int_q_: .. das:function:: stbtt_GetCodepointBitmapBox(font: stbtt_fontinfo const?; codepoint: int; scale_x: float; scale_y: float; ix0: int?; iy0: int?; ix1: int?; iy1: int?) Get the bounding box of the bitmap that would be generated for a codepoint at the given scale. :Arguments: * **font** : :ref:`stbtt_fontinfo `? implicit * **codepoint** : int * **scale_x** : float * **scale_y** : float * **ix0** : int? implicit * **iy0** : int? implicit * **ix1** : int? implicit * **iy1** : int? implicit .. _function-stbtruetype_stbtt_GetCodepointBitmapBoxSubpixel_stbtt_fontinfo_const_q__int_float_float_float_float_int_q__int_q__int_q__int_q_: .. das:function:: stbtt_GetCodepointBitmapBoxSubpixel(font: stbtt_fontinfo const?; codepoint: int; scale_x: float; scale_y: float; shift_x: float; shift_y: float; ix0: int?; iy0: int?; ix1: int?; iy1: int?) Get the bounding box of the bitmap for a codepoint at the given scale with sub-pixel offsets. :Arguments: * **font** : :ref:`stbtt_fontinfo `? implicit * **codepoint** : int * **scale_x** : float * **scale_y** : float * **shift_x** : float * **shift_y** : float * **ix0** : int? implicit * **iy0** : int? implicit * **ix1** : int? implicit * **iy1** : int? implicit .. _function-stbtruetype_stbtt_GetCodepointBitmapSubpixel_stbtt_fontinfo_const_q__float_float_float_float_int_int_q__int_q__int_q__int_q_: .. das:function:: stbtt_GetCodepointBitmapSubpixel(info: stbtt_fontinfo const?; scale_x: float; scale_y: float; shift_x: float; shift_y: float; codepoint: int; width: int?; height: int?; xoff: int?; yoff: int?) : uint8? Render a codepoint glyph bitmap with sub-pixel positioning at the given scale and fractional offsets. :Arguments: * **info** : :ref:`stbtt_fontinfo `? implicit * **scale_x** : float * **scale_y** : float * **shift_x** : float * **shift_y** : float * **codepoint** : int * **width** : int? implicit * **height** : int? implicit * **xoff** : int? implicit * **yoff** : int? implicit .. _function-stbtruetype_stbtt_MakeCodepointBitmap_stbtt_fontinfo_const_q__uint8_q__int_int_int_float_float_int: .. das:function:: stbtt_MakeCodepointBitmap(info: stbtt_fontinfo const?; output: uint8?; out_w: int; out_h: int; out_stride: int; scale_x: float; scale_y: float; codepoint: int) Render a codepoint glyph into a pre-allocated buffer with the given dimensions and stride. :Arguments: * **info** : :ref:`stbtt_fontinfo `? implicit * **output** : uint8? implicit * **out_w** : int * **out_h** : int * **out_stride** : int * **scale_x** : float * **scale_y** : float * **codepoint** : int .. _function-stbtruetype_stbtt_MakeCodepointBitmapSubpixel_stbtt_fontinfo_const_q__uint8_q__int_int_int_float_float_float_float_int: .. das:function:: stbtt_MakeCodepointBitmapSubpixel(info: stbtt_fontinfo const?; output: uint8?; out_w: int; out_h: int; out_stride: int; scale_x: float; scale_y: float; shift_x: float; shift_y: float; codepoint: int) Render a codepoint glyph into a pre-allocated buffer with sub-pixel positioning. :Arguments: * **info** : :ref:`stbtt_fontinfo `? implicit * **output** : uint8? implicit * **out_w** : int * **out_h** : int * **out_stride** : int * **scale_x** : float * **scale_y** : float * **shift_x** : float * **shift_y** : float * **codepoint** : int +++++++++++ Glyph shape +++++++++++ * :ref:`stbtt_GetCodepointShape (info: stbtt_fontinfo const?; codepoint: int; block: block\<(stbtt_vertex_das):void\>) ` * :ref:`stbtt_GetCodepointShape_count (info: stbtt_fontinfo const?; codepoint: int) : int ` .. _function-stbtruetype_stbtt_GetCodepointShape_stbtt_fontinfo_const_q__int_block_ls_stbtt_vertex_das_c_void_gr_: .. das:function:: stbtt_GetCodepointShape(info: stbtt_fontinfo const?; codepoint: int; block: block<(stbtt_vertex_das):void>) Iterates over the vertices of a glyph outline for the given Unicode codepoint, invoking the block for each vertex. Each vertex describes a move, line, quadratic curve, or cubic curve segment. :Arguments: * **info** : :ref:`stbtt_fontinfo `? implicit * **codepoint** : int * **block** : block<( :ref:`stbtt_vertex_das `\ &):void> implicit .. _function-stbtruetype_stbtt_GetCodepointShape_count_stbtt_fontinfo_const_q__int: .. das:function:: stbtt_GetCodepointShape_count(info: stbtt_fontinfo const?; codepoint: int) : int Returns the number of vertices in the glyph outline for the given Unicode codepoint. :Arguments: * **info** : :ref:`stbtt_fontinfo `? implicit * **codepoint** : int