Font Text Rendering, FreeType 2

Data Structures
struct	gdFTStringExtra
	Structure for passing additional parameters to FreeType 2 string rendering functions. More...

Functions
int	gdFontCacheSetup (void)
	Set up the font cache.
void	gdFontCacheShutdown (void)
	Shut down the font cache and free the allocated resources.
void	gdFreeFontCache (void)
	Alias of gdFontCacheShutdown.
char *	gdImageStringTTF (gdImagePtr im, int *brect, int fg, const char *fontlist, double ptsize, double angle, int x, int y, const char *string)
	Draws a string using FreeType 2 fonts. Alias of gdImageStringFT. Provided for backwards compatibility only.
char *	gdImageStringFT (gdImagePtr im, int *brect, int fg, const char *fontlist, double ptsize, double angle, int x, int y, const char *string)
	Render an UTF-8 string onto a gd image.
int	gdFTUseFontConfig (int flag)
	Enable or disable fontconfig by default.
char *	gdImageStringFTEx (gdImagePtr im, int *brect, int fg, const char *fontlist, double ptsize, double angle, int x, int y, const char *string, gdFTStringExtraPtr strex)
	Draws a string using FreeType 2 fonts with additional parameters.

gdFTStringExtra option flags
These flags are combined in gdFTStringExtra::flags and used by gdImageStringFTEx.
#define	gdFTEX_LINESPACE   1
#define	gdFTEX_CHARMAP   2
#define	gdFTEX_RESOLUTION   4
#define	gdFTEX_DISABLE_KERNING   8
#define	gdFTEX_XSHOW   16
#define	gdFTEX_FONTPATHNAME   32
#define	gdFTEX_FONTCONFIG   64
#define	gdFTEX_RETURNFONTPATHNAME   128

gdFTStringExtra character map values
These are not option flags. Set one value in gdFTStringExtra::charmap when gdFTStringExtra::flags includes gdFTEX_CHARMAP. Without gdFTEX_CHARMAP, GD prefers Unicode.
#define	gdFTEX_Unicode   0
#define	gdFTEX_Shift_JIS   1
#define	gdFTEX_Big5   2
#define	gdFTEX_Adobe_Custom   3
#define	gdFTEX_MacRoman   gdFTEX_Adobe_Custom

Detailed Description

Macro Definition Documentation

gdFTEX_Adobe_Custom

#define gdFTEX_Adobe_Custom   3

Prefer an Adobe Custom character map. GD may fall back to Apple Roman when no Adobe Custom map is available.

gdFTEX_Big5

#define gdFTEX_Big5   2

Prefer a Big5 character map.

gdFTEX_CHARMAP

#define gdFTEX_CHARMAP   2

Use gdFTStringExtra::charmap as the preferred FreeType character map. If the requested map is not available, GD attempts compatible fallback maps where possible.

gdFTEX_DISABLE_KERNING

#define gdFTEX_DISABLE_KERNING   8

Disable FreeType kerning adjustments between consecutive glyphs.

gdFTEX_FONTCONFIG

#define gdFTEX_FONTCONFIG   64

Interpret the fontlist argument as a fontconfig pattern for this call. This is not needed when fontconfig has already been enabled by default with gdFTUseFontConfig().

gdFTEX_FONTPATHNAME

#define gdFTEX_FONTPATHNAME   32

Interpret the fontlist argument as a full or partial font file path, even when fontconfig has been enabled by default with gdFTUseFontConfig().

gdFTEX_LINESPACE

#define gdFTEX_LINESPACE   1

Use gdFTStringExtra::linespacing for newline-separated text. The value is a multiple of the font height; without this flag, the default line spacing is 1.05.

gdFTEX_MacRoman

#define gdFTEX_MacRoman   gdFTEX_Adobe_Custom

Deprecated compatibility name used by bundled PHP's historical libgd.

gdFTEX_RESOLUTION

#define gdFTEX_RESOLUTION   4

Use gdFTStringExtra::hdpi and gdFTStringExtra::vdpi as the FreeType rendering resolution. Without this flag, GD uses GD_RESOLUTION for both axes.

gdFTEX_RETURNFONTPATHNAME

#define gdFTEX_RETURNFONTPATHNAME   128

Return a gd-allocated copy of the actual font file path used in gdFTStringExtra::fontpath. This is useful when fontconfig selects the font. The caller must free that string with gdFree().

gdFTEX_Shift_JIS

#define gdFTEX_Shift_JIS   1

Prefer a Shift_JIS character map.

gdFTEX_Unicode

#define gdFTEX_Unicode   0

Prefer a Unicode character map. GD may fall back to symbol or Adobe maps when no Unicode map is available.

gdFTEX_XSHOW

#define gdFTEX_XSHOW   16

Return a gd-allocated xshow advance string in gdFTStringExtra::xshow. The caller must free that string with gdFree().

Function Documentation

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.

gdFontCacheShutdown()

void gdFontCacheShutdown

(

void

)

Shut down the font cache and free the allocated resources.

Note

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.

gdFreeFontCache()

void gdFreeFontCache

(

void

)

Alias of gdFontCacheShutdown.

Deprecated:

gdFTUseFontConfig()

int gdFTUseFontConfig

(

int

flag

)

Enable or disable fontconfig by default.

If flag is nonzero, the fontlist parameter to gdImageStringFT and gdImageStringFTEx shall be assumed to be a fontconfig font pattern if fontconfig was compiled into gd. This function returns zero if fontconfig is not available, nonzero otherwise. If GD is built without libfontconfig support, this function is a NOP.

Parameters

flag	Zero to disable, nonzero to enable.

See also

gdImageStringFTEx

gdImageStringFT()

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

Render an UTF-8 string onto a gd image.

Parameters

im	The image to draw onto.
brect	The 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.
fg	The font color.
fontlist	The semicolon delimited list of font filenames to look for.
ptsize	The height of the font in typographical points (pt).
angle	The angle in radian to rotate the font counter-clockwise.
x	The x-coordinate of the basepoint (roughly the lower left corner) of the first letter.
y	The y-coordinate of the basepoint (roughly the lower left corner) of the first letter.
string	The string to render.

Variant gdImageStringFTEx

See also

gdImageString

gdImageStringFTEx()

char * gdImageStringFTEx	(	gdImagePtr	im,
		int *	brect,
		int	fg,
		const char *	fontlist,
		double	ptsize,
		double	angle,
		int	x,
		int	y,
		const char *	string,
		gdFTStringExtraPtr	strex
	)

Draws a string using FreeType 2 fonts with additional parameters.

gdImageStringFTEx() extends gdImageStringFT by accepting an optional gdFTStringExtra structure. Pass NULL for strex to use the same behavior as gdImageStringFT().

The gdFTStringExtra::flags field controls which extra fields are used:

• gdFTEX_LINESPACE uses gdFTStringExtra::linespacing for multiline text. The value is expressed as a multiple of the font height; 1.0 is the minimum spacing that normally prevents lines from colliding. Without this flag, or when strex is NULL, line spacing defaults to 1.05.

  strex.flags |= gdFTEX_LINESPACE;
  strex.linespacing = 1.2;

• gdFTEX_CHARMAP uses gdFTStringExtra::charmap as the preferred character map. Valid values are gdFTEX_Unicode, gdFTEX_Shift_JIS, gdFTEX_Big5, and gdFTEX_Adobe_Custom. Without this flag, GD tries Unicode first. If the preferred map is unavailable, GD attempts compatible fallback maps where possible.

  strex.flags |= gdFTEX_CHARMAP;
  strex.charmap = gdFTEX_Unicode;

• gdFTEX_RESOLUTION uses gdFTStringExtra::hdpi and gdFTStringExtra::vdpi as the FreeType rendering resolution in dots per inch. Without this flag, GD uses its default screen resolution.

  strex.flags |= gdFTEX_RESOLUTION;
  strex.hdpi = 300;
  strex.vdpi = 300;

• gdFTEX_DISABLE_KERNING disables FreeType kerning adjustments between consecutive glyphs.

  strex.flags |= gdFTEX_DISABLE_KERNING;

• gdFTEX_XSHOW returns a gd-allocated string of character advance values in gdFTStringExtra::xshow. The caller must free this string with gdFree().

  strex.flags |= gdFTEX_XSHOW;

• gdFTEX_RETURNFONTPATHNAME returns a gd-allocated copy of the actual font file path used in gdFTStringExtra::fontpath. The caller must free this string with gdFree().

  strex.flags |= gdFTEX_RETURNFONTPATHNAME;

Font selection normally treats fontlist as a semicolon-delimited list of font file names. When GD is built with fontconfig, gdFTEX_FONTCONFIG makes fontlist a fontconfig pattern for this call, and gdFTUseFontConfig() can make fontconfig patterns the default. If fontconfig has been enabled by default, gdFTEX_FONTPATHNAME forces fontlist to be interpreted as font path names for this call.

strex.flags |= gdFTEX_FONTCONFIG;
strex.flags |= gdFTEX_FONTPATHNAME;

If brect is not NULL, it must point to an array of 8 integers. On success, GD fills it with the lower-left, lower-right, upper-right, and upper-left corners of the rendered text bounding rectangle. Passing NULL for im computes the bounding rectangle without drawing.

Parameters

im	The image to draw onto, or NULL to compute brect only.
brect	Optional output array of 8 integers receiving the text bounding rectangle.
fg	The font color. Negative values select monochrome rendering using -fg as the color.
fontlist	The semicolon-delimited list of font file names, or a fontconfig pattern when fontconfig mode is active.
ptsize	The height of the font in typographical points.
angle	The angle in radians to rotate the font counter-clockwise.
x	The x-coordinate of the baseline starting point.
y	The y-coordinate of the baseline starting point.
string	The string to render.
strex	Optional pointer to a gdFTStringExtra structure containing additional rendering options, or NULL.

Returns

NULL on success, or a pointer to a static error message on failure.

gdImageStringTTF()

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

Draws a string using FreeType 2 fonts. Alias of gdImageStringFT. Provided for backwards compatibility only.

Deprecated: