FreeType-2.1.10 API Reference
Basic Data Types
Synopsis
#FT_Byte
FT_Byte
#FT_Tag
FT_Tag
#FT_Pixel_Mode
FT_Pixel_Mode
#FT_Bytes
FT_Bytes
#FT_Error
FT_Error
#ft_pixel_mode_xxx
ft_pixel_mode_xxx
#FT_Char
FT_Char
#FT_Fixed
FT_Fixed
#FT_Palette_Mode
FT_Palette_Mode
#FT_Int
FT_Int
#FT_Pointer
FT_Pointer
#FT_Bitmap
FT_Bitmap
#FT_UInt
FT_UInt
#FT_Pos
FT_Pos
#FT_IMAGE_TAG
FT_IMAGE_TAG
#FT_Short
FT_Short
#FT_Vector
FT_Vector
#FT_Glyph_Format
FT_Glyph_Format
#FT_UShort
FT_UShort
#FT_BBox
FT_BBox
#ft_glyph_format_xxx
ft_glyph_format_xxx
#FT_Long
FT_Long
#FT_Matrix
FT_Matrix
#FT_Data
FT_Data
#FT_ULong
FT_ULong
#FT_FWord
FT_FWord
#FT_Generic_Finalizer
FT_Generic_Finalizer
#FT_Bool
FT_Bool
#FT_UFWord
FT_UFWord
#FT_Generic
FT_Generic
#FT_Offset
FT_Offset
#FT_F2Dot14
FT_F2Dot14
#FT_MAKE_TAG
FT_MAKE_TAG
#FT_PtrDist
FT_PtrDist
#FT_UnitVector
FT_UnitVector
#FT_String
FT_String
#FT_F26Dot6
FT_F26Dot6
This section contains the basic data types defined by FreeType 2, ranging from simple scalar types to bitmap descriptors. More font-specific structures are defined in a different section.
FT_Byte
typedef
unsigned
char
FT_Byte
;
A simple typedef for the
unsigned
char type.
FT_Bytes
typedef
const
ft2-basic_types.html#FT_Byte
FT_Byte
*
FT_Bytes
;
A typedef for constant memory areas.
FT_Char
typedef
signed
char
FT_Char
;
A simple typedef for the
signed
char type.
FT_Int
typedef
signed
int
FT_Int
;
A typedef for the int type.
FT_UInt
typedef
unsigned
int
FT_UInt
;
A typedef for the unsigned int type.
FT_Short
typedef
signed
short
FT_Short
;
A typedef for signed short.
FT_UShort
typedef
unsigned
short
FT_UShort
;
A typedef for unsigned short.
FT_Long
typedef
signed
long
FT_Long
;
A typedef for signed long.
FT_ULong
typedef
unsigned
long
FT_ULong
;
A typedef for unsigned long.
FT_Bool
typedef
unsigned
char
FT_Bool
;
A typedef of unsigned char, used for simple booleans.
FT_Offset
typedef
size_t
FT_Offset
;
This is equivalent to the ANSI C `size_t' type, i.e. the largest
unsigned
integer type used to express a file size or position, or a memory block size.
FT_PtrDist
typedef
ft_ptrdiff_t
FT_PtrDist
;
This is equivalent to the ANSI C `ptrdiff_t' type, i.e. the largest
signed
integer type used to express the distance between two pointers.
FT_String
typedef
char
FT_String
;
A simple typedef for the char type, usually used for strings.
FT_Tag
typedef
FT_UInt32
FT_Tag
;
A typedef for 32bit tags (as used in the SFNT format).
FT_Error
typedef
int
FT_Error
;
The FreeType error code type. A value of 0 is always interpreted as a successful operation.
FT_Fixed
typedef
signed
long
FT_Fixed
;
This type is used to store 16.16 fixed float values, like scales or matrix coefficients.
FT_Pointer
typedef
void
*
FT_Pointer
;
A simple typedef for a typeless pointer.
FT_Pos
typedef
signed
long
FT_Pos
;
The type FT_Pos is a 32-bit integer used to store vectorial coordinates. Depending on the context, these can represent distances in integer font units, or 16,16, or 26.6 fixed float pixel coordinates.
FT_Vector
typedef
struct
FT_Vector_
{
ft2-basic_types.html#FT_Pos
FT_Pos
x;
ft2-basic_types.html#FT_Pos
FT_Pos
y;
}
FT_Vector
;
A simple structure used to store a 2D vector; coordinates are of the FT_Pos type.
fields
x
The horizontal coordinate.
y
The vertical coordinate.
FT_BBox
typedef
struct
FT_BBox_
{
ft2-basic_types.html#FT_Pos
FT_Pos
xMin, yMin;
ft2-basic_types.html#FT_Pos
FT_Pos
xMax, yMax;
}
FT_BBox
;
A structure used to hold an outline's bounding box, i.e., the coordinates of its extrema in the horizontal and vertical directions.
fields
xMin
The horizontal minimum (left-most).
yMin
The vertical minimum (bottom-most).
xMax
The horizontal maximum (right-most).
yMax
The vertical maximum (top-most).
FT_Matrix
typedef
struct
FT_Matrix_
{
ft2-basic_types.html#FT_Fixed
FT_Fixed
xx, xy;
ft2-basic_types.html#FT_Fixed
FT_Fixed
yx, yy;
}
FT_Matrix
;
A simple structure used to store a 2x2 matrix. Coefficients are in 16.16 fixed float format. The computation performed is:
x' = x*xx + y*xy
y' = x*yx + y*yy
fields
xx
Matrix coefficient.
xy
Matrix coefficient.
yx
Matrix coefficient.
yy
Matrix coefficient.
FT_FWord
typedef
signed
short
FT_FWord
;   /* distance in FUnits */
A signed 16-bit integer used to store a distance in original font units.
FT_UFWord
typedef
unsigned
short
FT_UFWord
;  /*
unsigned
distance */
An unsigned 16-bit integer used to store a distance in original font units.
FT_F2Dot14
typedef
signed
short
FT_F2Dot14
;
A signed 2.14 fixed float type used for unit vectors.
FT_UnitVector
typedef
struct
FT_UnitVector_
{
ft2-basic_types.html#FT_F2Dot14
FT_F2Dot14
x;
ft2-basic_types.html#FT_F2Dot14
FT_F2Dot14
y;
}
FT_UnitVector
;
A simple structure used to store a 2D vector unit vector. Uses FT_F2Dot14 types.
fields
x
Horizontal coordinate.
y
Vertical coordinate.
FT_F26Dot6
typedef
signed
long
FT_F26Dot6
;
A signed 26.6 fixed float type used for vectorial pixel coordinates.
FT_Pixel_Mode
typedef
enum
FT_Pixel_Mode_
{
ft2-basic_types.html#FT_Pixel_Mode
FT_PIXEL_MODE_NONE
= 0,
ft2-basic_types.html#FT_Pixel_Mode
FT_PIXEL_MODE_MONO
,
ft2-basic_types.html#FT_Pixel_Mode
FT_PIXEL_MODE_GRAY
,
ft2-basic_types.html#FT_Pixel_Mode
FT_PIXEL_MODE_GRAY2
,
ft2-basic_types.html#FT_Pixel_Mode
FT_PIXEL_MODE_GRAY4
,
ft2-basic_types.html#FT_Pixel_Mode
FT_PIXEL_MODE_LCD
,
ft2-basic_types.html#FT_Pixel_Mode
FT_PIXEL_MODE_LCD_V
,
FT_PIXEL_MODE_MAX      /* do not remove */
}
FT_Pixel_Mode
;
An enumeration type used to describe the format of pixels in a given bitmap. Note that additional formats may be added in the future.
values
FT_PIXEL_MODE_NONE
Value 0 is reserved.
FT_PIXEL_MODE_MONO
A monochrome bitmap, using 1 bit per pixel. Note that pixels are stored in most-significant order (MSB), which means that the left-most pixel in a byte has value 128.
FT_PIXEL_MODE_GRAY
An 8-bit bitmap, generally used to represent anti-aliased glyph images. Each pixel is stored in one byte. Note that the number of value "gray" levels is stored in the `num_bytes' field of the
ft2-basic_types.html#FT_Bitmap
FT_Bitmap
structure (it generally is 256).
FT_PIXEL_MODE_GRAY2
A 2-bit/pixel bitmap, used to represent embedded anti-aliased bitmaps in font files according to the OpenType specification. We haven't found a single font using this format, however.
FT_PIXEL_MODE_GRAY4
A 4-bit/pixel bitmap, used to represent embedded anti-aliased bitmaps in font files according to the OpenType specification. We haven't found a single font using this format, however.
FT_PIXEL_MODE_LCD
An 8-bit bitmap, used to represent RGB or BGR decimated glyph images used for display on LCD displays; the bitmap's width is three times wider than the original glyph image. See also
ft2-base_interface.html#FT_Render_Mode
FT_RENDER_MODE_LCD
.
FT_PIXEL_MODE_LCD_V
An 8-bit bitmap, used to represent RGB or BGR decimated glyph images used for display on rotated LCD displays; the bitmap's height is three times taller than the original glyph image. See also
ft2-base_interface.html#FT_Render_Mode
FT_RENDER_MODE_LCD_V
.
ft_pixel_mode_xxx
#define
ft2-basic_types.html#ft_pixel_mode_xxx
ft_pixel_mode_none
ft2-basic_types.html#FT_Pixel_Mode
FT_PIXEL_MODE_NONE
#define
ft2-basic_types.html#ft_pixel_mode_xxx
ft_pixel_mode_mono
ft2-basic_types.html#FT_Pixel_Mode
FT_PIXEL_MODE_MONO
#define
ft2-basic_types.html#ft_pixel_mode_xxx
ft_pixel_mode_grays
ft2-basic_types.html#FT_Pixel_Mode
FT_PIXEL_MODE_GRAY
#define
ft2-basic_types.html#ft_pixel_mode_xxx
ft_pixel_mode_pal2
ft2-basic_types.html#FT_Pixel_Mode
FT_PIXEL_MODE_GRAY2
#define
ft2-basic_types.html#ft_pixel_mode_xxx
ft_pixel_mode_pal4
ft2-basic_types.html#FT_Pixel_Mode
FT_PIXEL_MODE_GRAY4
A list of deprecated constants. Use the corresponding
ft2-basic_types.html#FT_Pixel_Mode
FT_Pixel_Mode
values instead.
values
ft_pixel_mode_none
see
ft2-basic_types.html#FT_Pixel_Mode
FT_PIXEL_MODE_NONE
ft_pixel_mode_mono
see
ft2-basic_types.html#FT_Pixel_Mode
FT_PIXEL_MODE_MONO
ft_pixel_mode_grays
see
ft2-basic_types.html#FT_Pixel_Mode
FT_PIXEL_MODE_GRAY
ft_pixel_mode_pal2
see
ft2-basic_types.html#FT_Pixel_Mode
FT_PIXEL_MODE_GRAY2
ft_pixel_mode_pal4
see
ft2-basic_types.html#FT_Pixel_Mode
FT_PIXEL_MODE_GRAY4
FT_Palette_Mode
typedef
enum
FT_Palette_Mode_
{
ft_palette_mode_rgb = 0,
ft_palette_mode_rgba,
ft_palettte_mode_max   /* do not remove */
}
FT_Palette_Mode
;
THIS TYPE IS DEPRECATED. DO NOT USE IT!
An enumeration type used to describe the format of a bitmap palette, used with ft_pixel_mode_pal4 and ft_pixel_mode_pal8.
fields
ft_palette_mode_rgb
The palette is an array of 3-bytes RGB records.
ft_palette_mode_rgba
The palette is an array of 4-bytes RGBA records.
note
As ft_pixel_mode_pal2, pal4 and pal8 are currently unused by FreeType, these types are not handled by the library itself.
FT_Bitmap
typedef
struct
FT_Bitmap_
{
int
rows;
int
width;
int
pitch;
unsigned
char
*  buffer;
short
num_grays;
char
pixel_mode;
char
palette_mode;
void
*           palette;
}
FT_Bitmap
;
A structure used to describe a bitmap or pixmap to the raster. Note that we now manage pixmaps of various depths through the `pixel_mode' field.
fields
rows
The number of bitmap rows.
width
The number of pixels in bitmap row.
pitch
The pitch's absolute value is the number of bytes taken by one bitmap row, including padding. However, the pitch is positive when the bitmap has a `down' flow, and negative when it has an `up' flow. In all cases, the pitch is an offset to add to a bitmap pointer in order to go down one row.
buffer
A typeless pointer to the bitmap buffer. This value should be aligned on 32-bit boundaries in most cases.
num_grays
This field is only used with `FT_PIXEL_MODE_GRAY'; it gives the number of gray levels used in the bitmap.
pixel_mode
The pixel mode, i.e., how pixel bits are stored. See
ft2-basic_types.html#FT_Pixel_Mode
FT_Pixel_Mode
for possible values.
palette_mode
This field is intended for paletted pixel modes; it indicates how the palette is stored. Not used currently.
palette
A typeless pointer to the bitmap palette; this field is intended for paletted pixel modes. Not used currently.
note
For now, the only pixel modes supported by FreeType are mono and grays. However, drivers might be added in the future to support more `colorful' options.
FT_IMAGE_TAG
#ifndef
FT_IMAGE_TAG
#define
FT_IMAGE_TAG
( value, _x1, _x2, _x3, _x4 )  \
value = ( ( (
unsigned
long
)_x1 << 24 ) | \
( (
unsigned
long
)_x2 << 16 ) | \
( (
unsigned
long
)_x3 << 8  ) | \
(
unsigned
long
)_x4         )
#endif /*
FT_IMAGE_TAG
*/
This macro converts four letter tags into an unsigned long.
note
Since many 16bit compilers don't like 32bit enumerations, you should redefine this macro in case of problems to something like this:
#define FT_IMAGE_TAG( value, _x1, _x2, _x3, _x4 ) value
to get a simple enumeration without assigning special numbers.
FT_Glyph_Format
typedef
enum
FT_Glyph_Format_
{
ft2-basic_types.html#FT_IMAGE_TAG
FT_IMAGE_TAG
(
ft2-basic_types.html#FT_Glyph_Format
FT_GLYPH_FORMAT_NONE
, 0, 0, 0, 0 ),
ft2-basic_types.html#FT_IMAGE_TAG
FT_IMAGE_TAG
(
ft2-basic_types.html#FT_Glyph_Format
FT_GLYPH_FORMAT_COMPOSITE
, 'c', 'o', 'm', 'p' ),
ft2-basic_types.html#FT_IMAGE_TAG
FT_IMAGE_TAG
(
ft2-basic_types.html#FT_Glyph_Format
FT_GLYPH_FORMAT_BITMAP
,    'b', 'i', 't', 's' ),
ft2-basic_types.html#FT_IMAGE_TAG
FT_IMAGE_TAG
(
ft2-basic_types.html#FT_Glyph_Format
FT_GLYPH_FORMAT_OUTLINE
,   'o', 'u', 't', 'l' ),
ft2-basic_types.html#FT_IMAGE_TAG
FT_IMAGE_TAG
(
ft2-basic_types.html#FT_Glyph_Format
FT_GLYPH_FORMAT_PLOTTER
,   'p', 'l', 'o', 't' )
}
FT_Glyph_Format
;
An enumeration type used to describe the format of a given glyph image. Note that this version of FreeType only supports two image formats, even though future font drivers will be able to register their own format.
values
FT_GLYPH_FORMAT_NONE
The value 0 is reserved and does describe a glyph format.
FT_GLYPH_FORMAT_COMPOSITE
The glyph image is a composite of several other images. This format is
only
used with
ft2-base_interface.html#FT_LOAD_XXX
FT_LOAD_NO_RECURSE
, and is used to report compound glyphs (like accented characters).
FT_GLYPH_FORMAT_BITMAP
The glyph image is a bitmap, and can be described as an
ft2-basic_types.html#FT_Bitmap
FT_Bitmap
. You generally need to access the `bitmap' field of the
ft2-base_interface.html#FT_GlyphSlotRec
FT_GlyphSlotRec
structure to read it.
FT_GLYPH_FORMAT_OUTLINE
The glyph image is a vertorial outline made of line segments and Bezier arcs; it can be described as an
ft2-outline_processing.html#FT_Outline
FT_Outline
; you generally want to access the `outline' field of the
ft2-base_interface.html#FT_GlyphSlotRec
FT_GlyphSlotRec
structure to read it.
FT_GLYPH_FORMAT_PLOTTER
The glyph image is a vectorial path with no inside/outside contours. Some Type 1 fonts, like those in the Hershey family, contain glyphs in this format. These are described as
ft2-outline_processing.html#FT_Outline
FT_Outline
, but FreeType isn't currently capable of rendering them correctly.
ft_glyph_format_xxx
#define
ft2-basic_types.html#ft_glyph_format_xxx
ft_glyph_format_none
ft2-basic_types.html#FT_Glyph_Format
FT_GLYPH_FORMAT_NONE
#define
ft2-basic_types.html#ft_glyph_format_xxx
ft_glyph_format_composite
ft2-basic_types.html#FT_Glyph_Format
FT_GLYPH_FORMAT_COMPOSITE
#define
ft2-basic_types.html#ft_glyph_format_xxx
ft_glyph_format_bitmap
ft2-basic_types.html#FT_Glyph_Format
FT_GLYPH_FORMAT_BITMAP
#define
ft2-basic_types.html#ft_glyph_format_xxx
ft_glyph_format_outline
ft2-basic_types.html#FT_Glyph_Format
FT_GLYPH_FORMAT_OUTLINE
#define
ft2-basic_types.html#ft_glyph_format_xxx
ft_glyph_format_plotter
ft2-basic_types.html#FT_Glyph_Format
FT_GLYPH_FORMAT_PLOTTER
A list of decprecated constants. Use the corresponding
ft2-basic_types.html#FT_Glyph_Format
FT_Glyph_Format
values instead.
values
ft_glyph_format_none
see
ft2-basic_types.html#FT_Glyph_Format
FT_GLYPH_FORMAT_NONE
ft_glyph_format_composite
see
ft2-basic_types.html#FT_Glyph_Format
FT_GLYPH_FORMAT_COMPOSITE
ft_glyph_format_bitmap
see
ft2-basic_types.html#FT_Glyph_Format
FT_GLYPH_FORMAT_BITMAP
ft_glyph_format_outline
see
ft2-basic_types.html#FT_Glyph_Format
FT_GLYPH_FORMAT_OUTLINE
ft_glyph_format_plotter
see
ft2-basic_types.html#FT_Glyph_Format
FT_GLYPH_FORMAT_PLOTTER
FT_Data
typedef
struct
FT_Data_
{
const
ft2-basic_types.html#FT_Byte
FT_Byte
*  pointer;
ft2-basic_types.html#FT_Int
FT_Int
length;
}
FT_Data
;
Read-only binary data represented as a pointer and a length.
fields
pointer
The data.
length
The length of the data in bytes.
FT_Generic_Finalizer
typedef
void
(*
FT_Generic_Finalizer
)(
void
*  object);
Describes a function used to destroy the `client' data of any FreeType object. See the description of the FT_Generic type for details of usage.
input
The address of the FreeType object which is under finalization. Its client data is accessed through its `generic' field.
FT_Generic
typedef
struct
FT_Generic_
{
void
*                 data;
ft2-basic_types.html#FT_Generic_Finalizer
FT_Generic_Finalizer
finalizer;
}
FT_Generic
;
Client applications often need to associate their own data to a variety of FreeType core objects. For example, a text layout API might want to associate a glyph cache to a given size object.
Most FreeType object contains a `generic' field, of type FT_Generic, which usage is left to client applications and font servers.
It can be used to store a pointer to client-specific data, as well as the address of a `finalizer' function, which will be called by FreeType when the object is destroyed (for example, the previous client example would put the address of the glyph cache destructor in the `finalizer' field).
fields
data
A typeless pointer to any client-specified data. This field is completely ignored by the FreeType library.
finalizer
A pointer to a `generic finalizer' function, which will be called when the object is destroyed. If this field is set to NULL, no code will be called.
FT_MAKE_TAG
#define
FT_MAKE_TAG
( _x1, _x2, _x3, _x4 ) \
( ( (
ft2-basic_types.html#FT_ULong
FT_ULong
)_x1 << 24 ) |     \
( (
ft2-basic_types.html#FT_ULong
FT_ULong
)_x2 << 16 ) |     \
( (
ft2-basic_types.html#FT_ULong
FT_ULong
)_x3 <<  8 ) |     \
(
ft2-basic_types.html#FT_ULong
FT_ULong
)_x4         )
This macro converts four letter tags which are used to label TrueType tables into an unsigned long to be used within FreeType.
note
The produced values
must
be 32bit integers. Don't redefine this macro.
