.\" 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" "2022-12-01" "3.1.5" "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 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.\&
.P
There is limited support for right-to-left
scripts.\& \fBhb_buffer_guess_segment_properties\fR() 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.\&
.P
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,
\fBhb_buffer_guess_segment_properties\fR() is only called once, on the
entire string.\& Meaning the entire string is subject to either LTR, or
RTL logic, but not both.\&
.P
If the (primary) font does not have glyphs for all characters, then
\fBhb_buffer_guess_segment_properties\fR() 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.\&
.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()