.\" 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_char_utf32" "3" "2024-02-01" "3.1.7" "fcft"
.P
.SH NAME
.P
fcft_rasterize_char_utf32 - rasterize a glyph for a single UTF-32 codepoint
.P
.SH SYNOPSIS
.P
\fB#include <fcft/fcft.\&h>\fR
.P
\fBconst struct fcft_glyph *fcft_rasterize_char_utf32(\fR
.RS 4
\fBstruct fcft_font *\fR\fIfont\fR\fB, uint32_t \fR\fIcp\fR\fB,
enum fcft_subpixel \fR\fIsubpixel\fR\fB);\fR
.P
.RE
.SH DESCRIPTION
.P
\fBfcft_rasterize_char_utf32\fR() rasterizes the UTF-32 encoded Unicode
codepoint \fIcp\fR using the primary font, or one of the fallback fonts,
in \fIfont\fR.\&
.P
\fIcp\fR is first searched for in the primary font.\& If not found, the
fallback fonts are searched (in the order they were specified in
\fBfcft_from_name\fR()).\& If not found in any of the fallback fonts, the
FontConfig fallback list for the primary font is searched.\&
.P
\fIsubpixel\fR allows you to specify which subpixel mode to use.\& It is one of:
.P
.nf
.RS 4
enum fcft_subpixel {
    FCFT_SUBPIXEL_DEFAULT,
    FCFT_SUBPIXEL_NONE,
    FCFT_SUBPIXEL_HORIZONTAL_RGB,
    FCFT_SUBPIXEL_HORIZONTAL_BGR,
    FCFT_SUBPIXEL_VERTICAL_RGB,
    FCFT_SUBPIXEL_VERTICAL_BGR,
};
.fi
.RE
.P
If \fBFCFT_SUBPIXEL_DEFAULT\fR is specified, the subpixel mode
configured in FontConfig is used.\& If \fBFCFT_SUBPIXEL_NONE\fR is
specified, grayscale antialiasing will be used.\& For all other values,
the specified mode is used.\&
.P
Note that if antialiasing has been disabled (in FontConfig, either
globally, or specifically for the current font), then \fIsubpixel\fR is
ignored.\&
.P
The intention is to enable programs to use per-monitor subpixel
modes.\& Incidentally, \fBenum fcft_subpixel\fR matches \fBenum
wl_output_subpixel\fR, the enum used in Wayland.\&
.P
Note: you probably do not want to use anything other than
\fBFCFT_SUBPIXEL_NONE\fR if blending with a transparent background.\&
.P
.SH RETURN VALUE
.P
On error, NULL is returned.\&
.P
On success, a pointer to a rasterized glyph is returned.\& The glyph 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 glyph 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()).\&
.P
.nf
.RS 4
struct fcft_glyph {
    uint32_t cp;
    int cols;

    pixman_image_t *pix;

    int x;
    int y;
    int width;
    int height;

    struct {
        int x;
        int y;
    } advance;
};
.fi
.RE
.P
\fIcp\fR is the same \fIcp\fR from the \fBfcft_rasterize_char_utf32\fR() call.\&
.P
\fIcols\fR is the number of "columns" the glyph occupies (effectively,
\fBwcwidth\fR(\fIcp\fR\fB)\fR).\& Note that this value will be incorrect if wide
characters (\fBwchar_t\fR) is not UTF-32 encoded in the current locale.\&
.P
\fIpix\fR is the rasterized glyph.\& Its format depends on a number of
factors, but will be one of \fBPIXMAN_a1\fR, \fBPIXMAN_a8\fR,
\fBPIXMAN_x8r8g8b8\fR, \fBPIXMAN_a8r8g8b8\fR.\& Use
\fBpixman_image_get_format\fR() to find out which one it is.\&
.P
.RS 4
\fBPIXMAN_a1\fR corresponds to \fBFT_PIXEL_MODE_MONO\fR.\& I.\&e.\& the
glyph is an un-antialiased bitmask.\& Use as a mask when blending.\&
.P
\fBPIXMAN_a8\fR corresponds to \fBFT_PIXEL_MODE_GRAY\fR.\& I.\&e.\& the
glyph is a grayscale antialiased bitmask.\& Use as a mask when
blending.\&
.P
\fBPIXMAN_x8r8g8b8\fR corresponds to either \fBFT_PIXEL_MODE_LCD\fR or
\fBFT_PIXEL_MODE_LCD_V\fR.\& \fBpixman_image_set_component_alpha\fR()
has been called by fcft for you.\& Use as a mask when blending.\&
.P
\fBPIXMAN_a8r8g8b8\fR corresponds to
\fBFT_PIXEL_MODE_BGRA\fR.\& I.\&e.\& the glyph is a plain RGBA image.\& Use
as source when blending.\&
.P
.RE
\fIx\fR is the glyph'\&s horizontal offset, in pixels.\& Add this to the
current pen position when blending.\&
.P
\fIy\fR is the glyph'\&s vertical offset, in pixels.\& Add this to the current
pen position when blending.\&
.P
\fIwidth\fR is the glyph'\&s width, in pixels.\& Use as '\&width'\& argument when
blending.\&
.P
\fIheight\fR is the glyph'\&s height, in pixels.\& Use as '\&height'\& argument
when blending.\&
.P
\fIadvance\fR is the glyph'\&s '\&advance'\&, in pixels.\& Add this to the pen
position after blending; \fIx\fR for a horizontal layout and \fIy\fR for a
vertical layout.\&
.P
.SH EXAMPLE
.P
See \fBfcft_from_name\fR()
.P
.SH SEE ALSO
.P
\fBfcft_destroy\fR(), \fBfcft_kerning\fR(), \fBfcft_rasterize_grapheme_utf32\fR(),
\fBfcft_rasterize_text_run_utf32\fR()