1fcft_from_name(3) fcft fcft_from_name(3)
2
6 fcft_from_name - instantiate a new font
7
9 #include <fcft/fcft.h>
10 struct fcft_font *fcft_from_name(
12 size_t count, const char *names[static count], const char
13 *attributes);
14
16 fcft_from_name() instantiates a new fcft font object from the FontCon‐
17 fig formatted font names. The first element in names is the primary
18 font, and the remaining elements (if any) are fallback fonts.
19 You must supply at least one font name.
21 All aspects of the font (size, DPI, variant etc) are configured through
23 the font name, using colon separated attribute=value pairs (e.g.
24 "Serif:size=26:slant=italic").
25 attributes is a convenient way to apply a set of attributes to all
27 fonts in names. attributes may be NULL, in which case no extra
28 attributes are appended to the strings in names.
29 The primary font will be instantiated immediately, and any failure to
31 do so will result in an error. Fallback fonts are instantiated on
32 demand, and any failure to do so will result in the that fallback font
33 being ignored, and the next one in the list is tried instead.
34
36 On success, fcft_from_name() returns a pointer to an allocated
37 fcft_font object. On error, NULL is returned.
38 struct fcft_font {
40 int height;
41 int descent;
42 int ascent;
43 struct {
45 int x;
46 int y;
47 } max_advance;
48 struct {
50 int x;
51 int y;
52 } space_advance;
53 struct {
55 int position;
56 int thickness;
57 } underline;
58 struct {
60 int position;
61 int thickness;
62 } strikeout;
63 };
64 height is the line height, in pixels.
66 descent is the distance between the baseline and the font's lowest
68 descending glyph, in pixels. In fcft's case, it is generally positive
69 (a negative value means the descent stretches up from the baseline).
70 ascent is the distance between the baseline and the font's highest
72 ascending glyph, in pixels. Generally a positive number (a negative
73 value means the ascent stretches down below the baseline).
74 ascent + descent is often the same as height, but not necessarily.
76 height may be larger, meaning the font intentionally adds extra (verti‐
77 cal) space between lines. Or it may be smaller, in which case lines
78 overlap.
79 max_advance is the amount, in pixels, the font's widest glyph advances
81 the pen position; x for a horizontal layout, and y for a vertical lay‐
82 out.
83 space_advance is the amount, in pixels, the glyph for space (0x20)
85 advances the pen position; x for a horizontal layout, and y for a ver‐
86 tical layout.
87 underline describes how to render underlines. position is the distance,
89 in pixels, from the baseline. A positive value means above the base‐
90 line, and a negative value means below the baseline. thickness is the
91 line's thickness, in pixels.
92 strikeout describes how to render strikeouts. See underline for a
94 description of its members.
95
97 In this example, we instantiate Times New Roman at a point size of 8 as
98 the primary font.
99 We also tell it to use Serif Bold (point size 10) as a fallback font
101 (note that it is usually better to let FontConfig handle fallback to
102 generic fonts like this).
103 Furthermore, both fonts will be Italic, and will be using DPI=140.
105 We then proceed to render the string hello world. You are assumed to
107 know how to create and use a pixman image. This example only shows how
108 one can use fcft to instantiate a font, rasterize glyphs and then blend
109 them onto a target pixman image.
110 #include <stdlib.h>
112 #include <wchar.h>
113 #include <fcft/fcft.h>
114 int
116 main(void)
117 {
118 if (!fcft_set_scaling_filter(FCFT_SCALING_FILTER_LANCZOS3))
119 return EXIT_FAILURE;
120 struct fcft_font *font = fcft_from_name(
122 2,
123 (const char *[]){
124 "Times New Roman:size=8",
125 "Serif:size=10:weight=bold",
126 },
127 "slant=italic:dpi=140");
128 if (font == NULL)
130 return EXIT_FAILURE;
131 /* Here you need to instantiate a 'target' pixman image, to blend
133 with */
134 pixman_image_t *canvas = ...;
135 /* String to print */
137 static const wchar_t *const hello = L"hello world";
138 /*
140 * Pen position in canvas. The numbers chosen here are more or less
141 * random. Note however, that the composite calls below assume 'y'
142 * is the font's baseline (and thus the glyphs will be rendered
143 * above 'y')
144 */
145 struct {
146 int x;
147 int y;
148 } pen = {.x = 25, .y = 50};
149 /* Glyphs will be rendered in white */
151 pixman_image_t *color = pixman_image_create_solid_fill(
152 &(struct pixman_color_t){
153 .red = 0xffff,
154 .green = 0xffff,
155 .blue = 0xffff,
156 .alpha = 0xffff,
157 });
158 for (size_t i = 0; i < wcslen(hello); i++) {
160 const struct fcft_glyph *glyph = fcft_glyph_rasterize(
161 font, hello[i], FCFT_SUBPIXEL_DEFAULT);
162 if (glyph == NULL)
164 continue;
165 /* Kerning */
167 long x_kern = 0;
168 if (i > 0) {
169 fcft_kerning(font, hello[i - 1], hello[i], &x_kern, NULL);
170 pen.x += x_kern;
172 if (pixman_image_get_format(glyph->pix) == PIXMAN_a8r8g8b8) {
174 /* Glyph is a pre-rendered image; typically a color emoji */
175 pixman_image_composite32(
176 PIXMAP_OP_OVER, glyph->pix, NULL, canvas, 0, 0, 0, 0,
177 pen.x + glyph->x, pen.y + font->ascent - glyph->y,
178 glyph->width, glyph->height);
179 }
180 else {
182 /* Glyph is an alpha mask */
183 pixman_image_composite32(
184 PIXMAN_OP_OVER, color, glyph->pix, canvas, 0, 0, 0, 0,
185 pen.x + glyph->x, pen.y + font->ascent - glyph->y,
186 glyph->width, glyph->height);
187 }
188 /* Advance pen position */
190 pen.x += glyph->advance.x;
191 }
192 pixman_image_unref(src);
194 fcft_destroy(font);
196 return EXIT_SUCCESS;
197 }
198
200 fcft_clone(3), fcft_destroy(3), fcft_glyph_rasterize(3), fcft_kern‐
201 ing(3), fcft_size_adjust(3)
2022.3.2 2021-03-08 fcft_from_name(3)