.\" 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_glyph_rasterize" "3" "2020-11-07" "2.3.1" "fcft"
.P
.SH NAME
.P
fcft_glyph_rasterize - rasterize a glyph for a wide character
.P
.SH SYNOPSIS
.P
\fB#include <fcft/fcft.h>\fR
.P
\fBconst struct fcft_glyph *fcft_glyph_rasterize(\fR
.RS 4
\fBstruct fcft_font *\fR\fIfont\fR\fB, wchar_t \fR\fIwc\fR\fB,
enum fcft_subpixel \fR\fIsubpixel\fR\fB);\fR
.P
.RE
.SH DESCRIPTION
.P
\fBfcft_glyph_rasterize\fR() rasterizes the wide character \fIwc\fR using the
primary font, or one of the fallback fonts, in \fIfont\fR.
.P
\fIwc\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(3)). 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 anything by \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(3)).
.P
.nf
.RS 4
struct fcft_glyph {
    wchar_t wc;
    int cols;

    pixman_image_t *pix;

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

    struct {
        int x;
        int y;
    } advance;
};
.fi
.RE
.P
\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,
\fBwcwidth\fR(\fIwc\fR\fB)\fR).
.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(3)
.P
.SH SEE ALSO
.P
\fBfcft_destroy\fR(3), \fBfcft_kerning\fR(3)