NAME

       fcft_rasterize_text_run_utf32 - rasterize a series of glyphs for a text string

SYNOPSIS

       #include <fcft/fcft.h>

       struct fcft_text_run *fcft_rasterize_text_run_utf32(
           struct fcft_font *font, size_t len, const uint32_t text[static len], enum
           fcft_subpixel subpixel);

DESCRIPTION

       fcft_rasterize_text_run_utf32() shapes and rasterizes the UTF-32 encoded Unicode string
       text into a series of glyphs using the primary font, and possibly one or more fallback
       fonts, in font.

       subpixel allows you to specify which subpixel mode to use. See fcft_rasterize_char_utf32()
       for details.

       The string is passed to HarfBuzz for shaping, initially using the primary font. The
       shaping data is parsed, and when an unshaped codepoint is encountered, it is retried with
       the first fallback font. If that fails too, the next fallback font is tried. After
       successfully shaping the failed codepoint, the primary font is used to shape the rest of
       the string. This continues until the entire string has been shaped.

       There is limited support for right-to-left scripts. hb_buffer_guess_segment_properties()
       is used to guess whether to use left-to-right, or right-to-left, logic, and this is done
       each time we try to shape a part of the string.

       As a consequence, the result of mixed LTR and RTL strings depends on the font; if the font
       has glyphs for all characters in the string, hb_buffer_guess_segment_properties() is only
       called once, on the entire string. Meaning the entire string is subject to either LTR, or
       RTL logic, but not both.

       If the (primary) font does not have glyphs for all characters, then
       hb_buffer_guess_segment_properties() will be called for each segment where shaping failed.
       In this case, parts of the string may be treated as LTR while others are treated as RTL.

RETURN VALUE

       On error, NULL is returned.

       On success, a pointer to a dynamically allocated text-run is returned:

           struct fcft_text_run {
               const struct fcft_glyph **glyphs;
               int *cluster;
               size_t count;
           };

       Both glyphs and cluster are arrays with count elements. cluster contains the character
       offsets (in the original string) of each corresponding glyph.

       Note that the glyphs' cols member are invalid.

       The text-run is not cached in fcft. The calling application may cache it for as long as it
       likes, including after the font has been destroyed.

       The text-run must be free:d with fcft_text_run_destroy().

SEE ALSO

       fcft_text_run_destroy(), fcft_rasterize_char_utf32(), fcft_rasterize_grapheme_utf32()