FreeType font rendering

Summary
FreeType font rendering
Functions
gdImageStringTTFAlias of gdImageStringFT.
gdFreeFontCacheAlias of gdFontCacheShutdown.
gdFontCacheShutdownShut down the font cache and free the allocated resources.
gdImageStringFTRender an UTF-8 string onto a gd image.
gdFontCacheSetupSet up the font cache.
gdImageStringFTExgdImageStringFTEx extends the capabilities of gdImageStringFT by providing a way to pass additional parameters.
gdFTUseFontConfigEnable or disable fontconfig by default.

Functions

gdImageStringTTF

char * gdImageStringTTF (gdImage *im,
int *brect,
int fg,
char *fontlist,
double ptsize,
double angle,
int x,
int y,
char *string)

Alias of gdImageStringFT.

gdFreeFontCache

void gdFreeFontCache ()

Alias of gdFontCacheShutdown.

gdFontCacheShutdown

void gdFontCacheShutdown ()

Shut down the font cache and free the allocated resources.

Important

This function has to be called whenever FreeType operations have been invoked, to avoid resource leaks.  It doesn’t harm to call this function multiple times.

gdImageStringFT

char * gdImageStringFT (gdImage *im,
int *brect,
int fg,
char *fontlist,
double ptsize,
double angle,
int x,
int y,
char *string)

Render an UTF-8 string onto a gd image.

Parameters

imThe image to draw onto.
brectThe bounding rectangle as array of 8 integers where each pair represents the x- and y-coordinate of a point.  The points specify the lower left, lower right, upper right and upper left corner.
fgThe font color.
fontlistThe semicolon delimited list of font filenames to look for.
ptsizeThe height of the font in typographical points (pt).
angleThe angle in radian to rotate the font counter-clockwise.
xThe x-coordinate of the basepoint (roughly the lower left corner) of the first letter.
yThe y-coordinate of the basepoint (roughly the lower left corner) of the first letter.
stringThe string to render.

Variant

See also

gdFontCacheSetup

int gdFontCacheSetup (void)

Set up the font cache.

This is called automatically from the string rendering functions, if it has not already been called.  So there’s no need to call this function explicitly.

gdImageStringFTEx

gdImageStringFTEx extends the capabilities of gdImageStringFT by providing a way to pass additional parameters.

If the strex parameter is not null, it must point to a gdFTStringExtra structure.  As of gd 2.0.5, this structure is defined as follows:

typedef struct {
    // logical OR of gdFTEX_ values
    int flags;

    // fine tune line spacing for '\n'
    double linespacing;

    // Preferred character mapping
    int charmap;

    // Rendering resolution
    int hdpi;
    int vdpi;
    char *xshow;
    char *fontpath;
} gdFTStringExtra, *gdFTStringExtraPtr;

To output multiline text with a specific line spacing, include gdFTEX_LINESPACE in the setting of flags:

flags |= gdFTEX_LINESPACE;

And also set linespacing to the desired spacing, expressed as a multiple of the font height.  Thus a line spacing of 1.0 is the minimum to guarantee that lines of text do not collide.

If gdFTEX_LINESPACE is not present, or strex is null, or gdImageStringFT is called, linespacing defaults to 1.05.

To specify a preference for Unicode, Shift_JIS Big5 character encoding, set or To output multiline text with a specific line spacing, include gdFTEX_CHARMAP in the setting of flags:

flags |= gdFTEX_CHARMAP;

And set charmap to the desired value, which can be any of gdFTEX_Unicode, gdFTEX_Shift_JIS, gdFTEX_Big5, or gdFTEX_Adobe_Custom.  If you do not specify a preference, Unicode will be tried first.  If the preferred character mapping is not found in the font, other character mappings are attempted.

GD operates on the assumption that the output image will be rendered to a computer screen.  By default, gd passes a resolution of 96 dpi to the freetype text rendering engine.  This influences the “hinting” decisions made by the renderer.  To specify a different resolution, set hdpi and vdpi accordingly (in dots per inch) and add gdFTEX_RESOLUTION to flags:

flags | gdFTEX_RESOLUTION;

GD 2.0.29 and later will normally attempt to apply kerning tables, if fontconfig is available, to adjust the relative positions of consecutive characters more ideally for that pair of characters.  This can be turn off by specifying the gdFTEX_DISABLE_KERNING flag:

flags | gdFTEX_DISABLE_KERNING;

GD 2.0.29 and later can return a vector of individual character position advances, occasionally useful in applications that must know exactly where each character begins.  This is returned in the xshow element of the gdFTStringExtra structure if the gdFTEX_XSHOW flag is set:

flags | gdFTEX_XSHOW;

The caller is responsible for calling gdFree() on the xshow element after the call if gdFTEX_XSHOW is set.

GD 2.0.29 and later can also return the path to the actual font file used if the gdFTEX_RETURNFONTPATHNAME flag is set.  This is useful because GD 2.0.29 and above are capable of selecting a font automatically based on a fontconfig font pattern when fontconfig is available.  This information is returned in the fontpath element of the gdFTStringExtra structure.

flags | gdFTEX_RETURNFONTPATHNAME;

The caller is responsible for calling gdFree() on the fontpath element after the call if gdFTEX_RETURNFONTPATHNAME is set.

GD 2.0.29 and later can use fontconfig to resolve font names, including fontconfig patterns, if the gdFTEX_FONTCONFIG flag is set.  As a convenience, this behavior can be made the default by calling gdFTUseFontConfig with a nonzero value.  In that situation it is not necessary to set the gdFTEX_FONTCONFIG flag on every call; however explicit font path names can still be used if the gdFTEX_FONTPATHNAME flag is set:

flags | gdFTEX_FONTPATHNAME;

Unless gdFTUseFontConfig has been called with a nonzero value, GD 2.0.29 and later will still expect the fontlist argument to the freetype text output functions to be a font file name or list thereof as in previous versions.  If you do not wish to make fontconfig the default, it is still possible to force the use of fontconfig for a single call to the freetype text output functions by setting the gdFTEX_FONTCONFIG flag:

flags | gdFTEX_FONTCONFIG;

GD 2.0.29 and above can use fontconfig to resolve font names, including fontconfig patterns, if the gdFTEX_FONTCONFIG flag is set.  As a convenience, this behavior can be made the default by calling gdFTUseFontConfig with a nonzero value.  In that situation it is not necessary to set the gdFTEX_FONTCONFIG flag on every call; however explicit font path names can still be used if the gdFTEX_FONTPATHNAME flag is set:

flags | gdFTEX_FONTPATHNAME;

For more information, see gdImageStringFT.

gdFTUseFontConfig

int gdFTUseFontConfig(int flag)

Enable or disable fontconfig by default.

If GD is built without libfontconfig support, this function is a NOP.

Parameters

flagZero to disable, nonzero to enable.

See also

char * gdImageStringTTF (gdImage *im,
int *brect,
int fg,
char *fontlist,
double ptsize,
double angle,
int x,
int y,
char *string)
Alias of gdImageStringFT.
char * gdImageStringFT (gdImage *im,
int *brect,
int fg,
char *fontlist,
double ptsize,
double angle,
int x,
int y,
char *string)
Render an UTF-8 string onto a gd image.
void gdFreeFontCache ()
Alias of gdFontCacheShutdown.
void gdFontCacheShutdown ()
Shut down the font cache and free the allocated resources.
int gdFontCacheSetup (void)
Set up the font cache.
int gdFTUseFontConfig(int flag)
Enable or disable fontconfig by default.
gdImageStringFTEx extends the capabilities of gdImageStringFT by providing a way to pass additional parameters.
void gdImageString (gdImagePtr im,
gdFontPtr f,
int x,
int y,
unsigned char *s,
int color)
Draws a character string.
Close