fcft_rasterize_char_utf32(3)

💅 fcft_rasterize_char_utf32 — a whole glyph, from one little codepoint

okay so real quick, this page lives in the fcft manual and the function is literally called fcft_rasterize_char_utf32. say that five times fast, i dare you 😭

---

✨ SYNOPSIS ✨

#include <fcft/fcft.h>

const struct fcft_glyph *fcft_rasterize_char_utf32(
    struct fcft_font *font, uint32_t cp, enum fcft_subpixel subpixel);

---

🎀 DESCRIPTION 🎀

so fcft_rasterize_char_utf32() takes a UTF-32 encoded Unicode codepoint cp and rasterizes it for you, using the primary font in font, or one of the fallback fonts. bestie it does the searching for you, you're welcome 💖

here's the search order, no cap:

• first it looks for cp in the primary font
• not there? it goes through the fallback fonts, in the order they were specified in fcft_from_name()
• still not found in any of the fallback fonts? the FontConfig fallback list for the primary font gets searched

then subpixel lets you pick which subpixel mode you want. it's one of these, exactly:

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,
};

what each one means, lowkey:

• FCFT_SUBPIXEL_DEFAULT → the subpixel mode configured in FontConfig is used
• FCFT_SUBPIXEL_NONE → grayscale antialiasing, that's the vibe
• every other value → the mode you specified is used, periodt

⚠️ heads up: if antialiasing has been disabled (in FontConfig — either globally, or specifically for the current font), then subpixel is just ignored. like, it doesn't even matter. 💀

the whole intention here is to let programs use per-monitor subpixel modes. and fun lil fact: enum fcft_subpixel matches enum wl_output_subpixel, the enum used in Wayland. iykyk 🦋

🙈 also: you probably do not want to use anything other than FCFT_SUBPIXEL_NONE if you're blending with a transparent background. just saying.

---

⭐ RETURN VALUE ⭐

on error, NULL is returned. that's it, that's the error handling 😭

on success, you get a pointer to a rasterized glyph. and the glyph is cached in fcft, so calling it again with the same arguments is super fast — meaning programs don't need to cache glyphs by themselves at all. she ate 🔥

the glyph object is managed by font. there is no need to explicitly free it; it gets freed when font is destroyed (with fcft_destroy()). so like, don't go freeing things you don't own, bestie 🫶

struct fcft_glyph {
    uint32_t cp;
    int cols;

    const char *font_name;
    pixman_image_t *pix;

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

    struct {
        int x;
        int y;
    } advance;

    bool is_color_glyph;
};

okay let's go through the fields one by one, main character energy only 👑

cp is the same cp from the fcft_rasterize_char_utf32() call. literally the same one. no cap.

cols is the number of "columns" the glyph occupies (effectively, wcwidth(cp)). note that this value will be incorrect if wide characters (wchar_t) is not UTF-32 encoded in the current locale. yeah. that's a real caveat, not me being dramatic 💀

pix is the rasterized glyph. its format depends on a number of factors, but will be one of PIXMAN_a1, PIXMAN_a8, PIXMAN_x8r8g8b8, PIXMAN_a8r8g8b8. use pixman_image_get_format() to find out which one it is, okay?

• PIXMAN_a1 corresponds to FT_PIXEL_MODE_MONO. i.e. the glyph is an un-antialiased bitmask. use as a mask when blending.
• PIXMAN_a8 corresponds to FT_PIXEL_MODE_GRAY. i.e. the glyph is a grayscale antialiased bitmask. use as a mask when blending.
• PIXMAN_x8r8g8b8 corresponds to either FT_PIXEL_MODE_LCD or FT_PIXEL_MODE_LCD_V. pixman_image_set_component_alpha() has been called by fcft for you. use as a mask when blending.
• PIXMAN_a8r8g8b8 corresponds to FT_PIXEL_MODE_BGRA. i.e. the glyph is a plain RGBA image. use as source when blending. (yes, source, not mask — different vibe 🌸)

x is the glyph's horizontal offset, in pixels. add this to the current pen position when blending.

y is the glyph's vertical offset, in pixels. add this to the current pen position when blending.

width is the glyph's width, in pixels. use as the 'width' argument when blending.

height is the glyph's height, in pixels. use as the 'height' argument when blending.

advance is the glyph's 'advance', in pixels. add this to the pen position after blending; x for a horizontal layout and y for a vertical layout. don't mix those up 🙈

is_color_glyph is true if the glyph is a color glyph, typically an emoji. when true, the glyph should be composited OVER the destination surface, instead of being used as a mask. emoji gang rise up 🍓

---

🌈 EXAMPLE 🌈

see fcft_from_name(). that's the whole example section, she's shy 💜

---

🦋 SEE ALSO 🦋

• fcft_destroy()
• fcft_kerning()
• fcft_rasterize_grapheme_utf32()
• fcft_rasterize_text_run_utf32()

---

and that's the page!! this version dropped in 3.3.3 on 2026-04-09 — go forth and rasterize, bestie, you're literally so good at this ✨🎀👑