fcft_rasterize_text_run_utf32(3)

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()