.\" Generated by scdoc 1.11.0
.\" 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_grapheme_rasterize" "3" "2020-11-07" "2.3.1" "fcft"
.P
.SH NAME
.P
fcft_grapheme_rasterize - rasterize a glyph for a grapheme cluster
.P
.SH SYNOPSIS
.P
\fB#include <fcft/fcft.h>\fR
.P
\fBconst struct fcft_grapheme *fcft_grapheme_rasterize(\fR
.RS 4
\fBstruct fcft_font *\fR\fIfont\fR\fB,\fR
\fBsize_t \fR\fIlen\fR\fB, const wchar_t \fR\fIgrapheme_cluster[static len]\fR\fB,\fR
\fBsize_t \fR\fItag_count\fR\fB, const struct fcft_layout_tag \fR\fItags\fR\fB[static tag_count],\fR
\fBenum fcft_subpixel \fR\fIsubpixel\fR\fB);\fR
.P
.RE
.SH DESCRIPTION
.P
\fBfcft_grapheme_rasterize\fR() rasterizes the grapheme cluster \fIcluster\fR
using the primary font, or one of the fallback fonts, in \fIfont\fR.
.P
The fonts are searched for \fIall\fR codepoints in the grapheme cluster,
starting with the primary font and then the custom fallback fonts, and
finally the FontConfig provided fallback fonts.
.P
\fItags\fR is an optional array of OTF tags that will be used when shaping
the grapheme:
.P
.nf
.RS 4
struct fcft_layout_tag {
    char tag[4];
    unsigned value;
};
.fi
.RE
.P
\fIsubpixel\fR allows you to specify which subpixel mode to use. See
\fBfcft_glyph_rasterize\fR(3) for details.
.P
.SH RETURN VALUE
.P
On error, NULL is returned.
.P
On success, a pointer to a rasterized grapheme is returned. The
grapheme is cached in fcft, making subsequent calls with the same
arguments very fast (i.e. there is no need for programs to cache
glyphs by themselves).
.P
The grapheme object is managed by \fIfont\fR. There is no need to
explicitly free it; it is freed when \fIfont\fR is destroyed (with
\fBfcft_destroy\fR(3)).
.P
.nf
.RS 4
struct fcft_grapheme {
    int cols;

    size_t count;
    const struct fcft_glyph **glyphs;
};
.fi
.RE
.P
\fIcols\fR is the number of "columns" the grapheme occupised (effectively)
\fIwc\fR is the same \fIwc\fR from the \fBfcft_glyph_rasterize\fR() call.
.P
\fIcols\fR is the number of "columns" the glyph occupies (effectively,
\fBwcswidth\fR(\fIcluster\fR\fB)\fR).
.P
\fIglyphs\fR is an array of rasterized glyphs. See
\fBfcft_glyph_rasterize\fR(3) for a description of \fBstruct fcft_glyph\fR.
.P
.SH SEE ALSO
.P
\fBfcft_destroy\fR(3), \fBfcft_glyph_rasterize\fR(3)