NAME

freetyp2.c - font support via the FreeType library version 2.

SYNOPSIS

if (!i_ft2_init()) { error }
FT2_Fonthandle *font;
font = i_ft2_new(name, index);
if (!i_ft2_setdpi(font, xdpi, ydpi)) { error }
if (!i_ft2_getdpi(font, &xdpi, &ydpi)) { error }
double matrix[6];
if (!i_ft2_settransform(font, matrix)) { error }
i_img_dim bbox[BOUNDING_BOX_COUNT];
if (!i_ft2_bbox(font, cheight, cwidth, text, length, bbox, utf8)) { error }
i_img *im = ...;
i_color cl;
if (!i_ft2_text(font, im, tx, ty, cl, cheight, cwidth, text, length, align,
                aa, vlayout, utf8)) { error }
if (!i_ft2_cp(font, im, tx, ty, channel, cheight, cwidth, text, length,
              align, aa)) { error }
i_ft2_destroy(font);

DESCRIPTION

Implements Imager font support using the FreeType2 library.

The FreeType2 library understands several font file types, including Truetype, Type1 and Windows FNT.

i_ft2_init(void)

Initializes the Freetype 2 library.

Returns ft2_state * on success or NULL on failure.

i_ft2_new(char *name, int index)

Creates a new font object, from the file given by name. index is the index of the font in a file with multiple fonts, where 0 is the first font.

Return NULL on failure.

i_ft2_destroy(FT2_Fonthandle *handle)

Destroys a font object, which must have been the return value of i_ft2_new().

i_ft2_setdpi(FT2_Fonthandle *handle, int xdpi, int ydpi)

Sets the resolution in dots per inch at which point sizes scaled, by default xdpi and ydpi are 72, so that 1 point maps to 1 pixel.

Both xdpi and ydpi should be positive.

Return true on success.

i_ft2_getdpi(FT2_Fonthandle *handle, int *xdpi, int *ydpi)

Retrieves the current horizontal and vertical resolutions at which point sizes are scaled.

i_ft2_settransform(FT2_FontHandle *handle, double *matrix)

Sets a transormation matrix for output.

This should be a 2 x 3 matrix like:

matrix[0]   matrix[1]   matrix[2]
matrix[3]   matrix[4]   matrix[5]

i_ft2_sethinting(FT2_Fonthandle *handle, int hinting)

If hinting is non-zero then glyph hinting is enabled, otherwise disabled.

i_ft2_settransform() disables hinting to prevent distortions in gradual text transformations.

i_ft2_bbox(FT2_Fonthandle *handle, double cheight, double cwidth, char *text, size_t len, i_img_dim *bbox)

Retrieves bounding box information for the font at the given character width and height. This ignores the transformation matrix.

Returns non-zero on success.

transform_box(FT2_FontHandle *handle, int bbox[4])

bbox contains coorinates of a the top-left and bottom-right of a bounding box relative to a point.

This is then transformed and the values in bbox[4] are the top-left and bottom-right of the new bounding box.

This is meant to provide the bounding box of a transformed character box. The problem is that if the character was round and is rotated, the real bounding box isn't going to be much different from the original, but this function will return a _bigger_ bounding box. I suppose I could work my way through the glyph outline, but that's too much hard work.

expand_bounds(int bbox[4], int bbox2[4])

Treating bbox[] and bbox2[] as 2 bounding boxes, produces a new bounding box in bbox[] that encloses both.

i_ft2_bbox_r(FT2_Fonthandle *handle, double cheight, double cwidth, char *text, size_t len, int vlayout, int utf8, i_img_dim *bbox)

Retrieves bounding box information for the font at the given character width and height.

This version finds the rectangular bounding box of the glyphs, with the text as transformed by the transformation matrix. As with i_ft2_bbox (bbox[0], bbox[1]) will the the offset from the start of the topline to the top-left of the bounding box. Unlike i_ft2_bbox() this could be near the bottom left corner of the box.

(bbox[4], bbox[5]) is the offset to the start of the baseline. (bbox[6], bbox[7]) is the offset from the start of the baseline to the end of the baseline.

Returns non-zero on success.

i_ft2_text(FT2_Fonthandle *handle, i_img *im, int tx, int ty, i_color *cl, double cheight, double cwidth, char *text, size_t len, int align, int aa)

Renders text to (tx, ty) in im using color cl at the given cheight and cwidth.

If align is 0, then the text is rendered with the top-left of the first character at (tx, ty). If align is non-zero then the text is rendered with (tx, ty) aligned with the base-line of the characters.

If aa is non-zero then the text is anti-aliased.

Returns non-zero on success.

i_ft2_cp(FT2_Fonthandle *handle, i_img *im, int tx, int ty, int channel, double cheight, double cwidth, char *text, size_t len, int align, int aa, int vlayout, int utf8)

Renders text to (tx, ty) in im to channel at the given cheight and cwidth.

If align is 0, then the text is rendered with the top-left of the first character at (tx, ty). If align is non-zero then the text is rendered with (tx, ty) aligned with the base-line of the characters.

If utf8 is non-zero the text is treated as UTF-8 encoded

If aa is non-zero then the text is drawn anti-aliased.

Returns non-zero on success.

i_ft2_has_chars(handle, char *text, size_t len, int utf8, char *out)

Check if the given characters are defined by the font.

Returns the number of characters that were checked.

Internal Functions

These functions are used in the implementation of freetyp2.c and should not (usually cannot) be called from outside it.

ft2_push_message(int code)

Pushes an error message corresponding to code onto the error stack.

make_bmp_map(FT_Bitmap *bitmap, unsigned char *map)

Creates a map to convert grey levels from the glyphs bitmap into values scaled 0..255.

i_ft2_face_name(handle, name_buf, name_buf_size)

Fills the given buffer with the Postscript Face name of the font, if there is one.

Returns the number of bytes copied, including the terminating NUL.

AUTHOR

Tony Cook <tony@develop-help.com>, with a fair amount of help from reading the code in font.c.

SEE ALSO

font.c, Imager::Font(3), Imager(3)

http://www.freetype.org/