.\" Generated by scdoc 1.11.2
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "fcft_rasterize_text_run_utf32" "3" "2024-02-01" "3.1.7" "fcft"
.P
.SH NAME
.P
fcft_rasterize_text_run_utf32 - rasterize a series of glyphs for a text string
.P
.SH SYNOPSIS
.P
\fB#include <fcft/fcft.\&h>\fR
.P
\fBstruct fcft_text_run *fcft_rasterize_text_run_utf32(\fR
.RS 4
\fBstruct fcft_font *\fR\fIfont\fR\fB, size_t \fR\fIlen\fR\fB,\fR
\fBconst uint32_t \fR\fItext\fR\fB[static len], enum fcft_subpixel \fR\fIsubpixel\fR\fB);\fR
.P
.RE
.SH DESCRIPTION
.P
\fBfcft_rasterize_text_run_utf32\fR() shapes and rasterizes the UTF-32
encoded Unicode string \fItext\fR into a series of glyphs using the
primary font, and possibly one or more fallback fonts, in \fIfont\fR.\&
.P
\fIsubpixel\fR allows you to specify which subpixel mode to use.\& See
\fBfcft_rasterize_char_utf32\fR() for details.\&
.P
The string is first segmented into grapheme clusters using
utf8proc.\& Each grapheme is assigned a font using the normal font
lookup rules (see \fBfcft_rasterize_char_utf32\fR()).\&
.P
Next, HarfBuzz is used to guess each grapheme'\&s script
(~language).\& Consecutiv graphemes that both have been assigned the
same font, and belong to the same script are merged into a "partial"
text run.\&
.P
Finally, each partial text run is shaped with HarfBuzz.\&
.P
.SH RETURN VALUE
.P
On error, NULL is returned.\&
.P
On success, a pointer to a dynamically allocated text-run is returned:
.P
.nf
.RS 4
struct fcft_text_run {
    const struct fcft_glyph **glyphs;
    int *cluster;
    size_t count;
};
.fi
.RE
.P
Both \fIglyphs\fR and \fIcluster\fR are arrays with \fIcount\fR
elements.\& \fIcluster\fR contains the character offsets (in the original
string) of each corresponding glyph.\&
.P
Note that the glyphs'\& \fIcols\fR member are invalid.\&
.P
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.\&
.P
The text-run must be free:d with \fBfcft_text_run_destroy\fR().\&
.P
.SH SEE ALSO
.P
\fBfcft_text_run_destroy\fR(), \fBfcft_rasterize_char_utf32\fR(),
\fBfcft_rasterize_grapheme_utf32\fR()