.\" 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_from_name" "3" "2020-11-07" "2.3.1" "fcft" .P .SH NAME .P fcft_from_name - instantiate a new font .P .SH SYNOPSIS .P \fB#include \fR .P \fBstruct fcft_font *fcft_from_name( .RS 4 size_t\fR \fIcount\fR\fB, const char *\fR\fInames\fR\fB[static\fR \fIcount\fR\fB], const char *\fR\fIattributes\fR\fB);\fR .P .RE .SH DESCRIPTION .P \fBfcft_from_name\fR() instantiates a new fcft font object from the FontConfig formatted font names. The first element in \fInames\fR is the primary font, and the remaining elements (if any) are fallback fonts. .P You \fBmust\fR supply at least one font name. .P All aspects of the font (size, DPI, variant etc) are configured through the font \fIname\fR, using colon separated \fBattribute=value\fR pairs (e.g. \fB"Serif:size=26:slant=italic"\fR). .P \fIattributes\fR is a convenient way to apply a set of attributes to all fonts in \fInames\fR. \fIattributes\fR may be NULL, in which case no extra attributes are appended to the strings in \fInames\fR. .P The primary font will be instantiated immediately, and any failure to do so will result in an error. Fallback fonts are instantiated on demand, and any failure to do so will result in the that fallback font being ignored, and the next one in the list is tried instead. .P .SH RETURN VALUE .P On success, \fBfcft_from_name\fR() returns a pointer to an allocated \fBfcft_font\fR object. On error, NULL is returned. .P .nf .RS 4 struct fcft_font { int height; int descent; int ascent; struct { int x; int y; } max_advance; struct { int x; int y; } space_advance; struct { int position; int thickness; } underline; struct { int position; int thickness; } strikeout; }; .fi .RE .P \fIheight\fR is the line height, in pixels. .P \fIdescent\fR is the distance between the baseline and the font's lowest descending glyph, in pixels. In fcft's case, it is generally positive (a negative value means the \fIdescent\fR stretches \fBup\fR from the baseline). .P \fIascent\fR is the distance between the baseline and the font's highest ascending glyph, in pixels. Generally a positive number (a negative value means the \fIascent\fR stretches \fBdown\fR below the baseline). .P \fIascent\fR + \fIdescent\fR is often the same as \fIheight\fR, but not necessarily. \fIheight\fR may be larger, meaning the font intentionally adds extra (vertical) space between lines. Or it may be smaller, in which case lines overlap. .P \fImax_advance\fR is the amount, in pixels, the font's widest glyph advances the pen position; \fIx\fR for a horizontal layout, and \fIy\fR for a vertical layout. .P \fIspace_advance\fR is the amount, in pixels, the glyph for \fBspace\fR (0x20) advances the pen position; \fIx\fR for a horizontal layout, and \fIy\fR for a vertical layout. .P \fIunderline\fR describes how to render underlines. \fIposition\fR is the distance, in pixels, from the baseline. A positive value means \fBabove\fR the baseline, and a negative value means \fBbelow\fR the baseline. \fIthickness\fR is the line's thickness, in pixels. .P \fIstrikeout\fR describes how to render strikeouts. See \fIunderline\fR for a description of its members. .P .SH EXAMPLE .P In this example, we instantiate \fITimes New Roman\fR at a point size of 8 as the primary font. .P We also tell it to use \fISerif Bold\fR (point size 10) as a fallback font (note that it is usually better to let FontConfig handle fallback to generic fonts like this). .P Furthermore, both fonts will be \fIItalic\fR, and will be using DPI=140. .P We then proceed to render the string \fIhello world\fR. You are assumed to know how to create and use a pixman image. This example only shows how one can use fcft to instantiate a font, rasterize glyphs and then blend them onto a target pixman image. .P .P .nf .RS 4 #include #include #include int main(void) { if (!fcft_set_scaling_filter(FCFT_SCALING_FILTER_LANCZOS3)) return EXIT_FAILURE; struct fcft_font *font = fcft_from_name( 2, (const char *[]){ "Times New Roman:size=8", "Serif:size=10:weight=bold", }, "slant=italic:dpi=140"); if (font == NULL) return EXIT_FAILURE; /* Here you need to instantiate a 'target' pixman image, to blend with */ pixman_image_t *canvas = \&.\&.\&.; /* String to print */ static const wchar_t *const hello = L"hello world"; /* * Pen position in canvas\&. The numbers chosen here are more or less * random\&. Note however, that the composite calls below assume 'y' * is the font's baseline (and thus the glyphs will be rendered * above 'y') */ struct { int x; int y; } pen = {\&.x = 25, \&.y = 50}; /* Glyphs will be rendered in white */ pixman_image_t *color = pixman_image_create_solid_fill( &(struct pixman_color_t){ \&.red = 0xffff, \&.green = 0xffff, \&.blue = 0xffff, \&.alpha = 0xffff, }); for (size_t i = 0; i < wcslen(hello); i++) { const struct fcft_glyph *glyph = fcft_glyph_rasterize( font, hello[i], FCFT_SUBPIXEL_DEFAULT); if (glyph == NULL) continue; /* Kerning */ long x_kern = 0; if (i > 0) { fcft_kerning(font, hello[i - 1], hello[i], &x_kern, NULL); pen\&.x += x_kern; if (pixman_image_get_format(glyph->pix) == PIXMAN_a8r8g8b8) { /* Glyph is a pre-rendered image; typically a color emoji */ pixman_image_composite32( PIXMAP_OP_OVER, glyph->pix, NULL, canvas, 0, 0, 0, 0, pen\&.x + glyph->x, pen\&.y + font->ascent - glyph->y, glyph->width, glyph->height); } else { /* Glyph is an alpha mask */ pixman_image_composite32( PIXMAN_OP_OVER, color, glyph->pix, canvas, 0, 0, 0, 0, pen\&.x + glyph->x, pen\&.y + font->ascent - glyph->y, glyph->width, glyph->height); } /* Advance pen position */ pen\&.x += glyph->advance\&.x; } pixman_image_unref(src); fcft_destroy(font); return EXIT_SUCCESS; } .fi .RE .P .SH SEE ALSO .P \fBfcft_clone\fR(3), \fBfcft_destroy\fR(3), \fBfcft_glyph_rasterize\fR(3), \fBfcft_kerning\fR(3), \fBfcft_size_adjust\fR(3)