FreeType-2.1.10 API Reference
Basic Data Types
Synopsis
#FT_ByteFT_Byte #FT_TagFT_Tag #FT_Pixel_ModeFT_Pixel_Mode #FT_BytesFT_Bytes #FT_ErrorFT_Error #ft_pixel_mode_xxxft_pixel_mode_xxx #FT_CharFT_Char #FT_FixedFT_Fixed #FT_Palette_ModeFT_Palette_Mode #FT_IntFT_Int #FT_PointerFT_Pointer #FT_BitmapFT_Bitmap #FT_UIntFT_UInt #FT_PosFT_Pos #FT_IMAGE_TAGFT_IMAGE_TAG #FT_ShortFT_Short #FT_VectorFT_Vector #FT_Glyph_FormatFT_Glyph_Format #FT_UShortFT_UShort #FT_BBoxFT_BBox #ft_glyph_format_xxxft_glyph_format_xxx #FT_LongFT_Long #FT_MatrixFT_Matrix #FT_DataFT_Data #FT_ULongFT_ULong #FT_FWordFT_FWord #FT_Generic_FinalizerFT_Generic_Finalizer #FT_BoolFT_Bool #FT_UFWordFT_UFWord #FT_GenericFT_Generic #FT_OffsetFT_Offset #FT_F2Dot14FT_F2Dot14 #FT_MAKE_TAGFT_MAKE_TAG #FT_PtrDistFT_PtrDist #FT_UnitVectorFT_UnitVector #FT_StringFT_String #FT_F26Dot6FT_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_ByteFT_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_PosFT_Pos   x;
    
ft2-basic_types.html#FT_PosFT_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_PosFT_Pos   xMin, yMin;
    
ft2-basic_types.html#FT_PosFT_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_FixedFT_Fixed   xx, xy;
    
ft2-basic_types.html#FT_FixedFT_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_F2Dot14FT_F2Dot14   x;
    
ft2-basic_types.html#FT_F2Dot14FT_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_ModeFT_PIXEL_MODE_NONE  = 0,
    
ft2-basic_types.html#FT_Pixel_ModeFT_PIXEL_MODE_MONO ,
    
ft2-basic_types.html#FT_Pixel_ModeFT_PIXEL_MODE_GRAY ,
    
ft2-basic_types.html#FT_Pixel_ModeFT_PIXEL_MODE_GRAY2 ,
    
ft2-basic_types.html#FT_Pixel_ModeFT_PIXEL_MODE_GRAY4 ,
    
ft2-basic_types.html#FT_Pixel_ModeFT_PIXEL_MODE_LCD ,
    
ft2-basic_types.html#FT_Pixel_ModeFT_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_BitmapFT_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_ModeFT_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_ModeFT_RENDER_MODE_LCD_V .
ft_pixel_mode_xxx 
#define 
ft2-basic_types.html#ft_pixel_mode_xxxft_pixel_mode_none    ft2-basic_types.html#FT_Pixel_ModeFT_PIXEL_MODE_NONE #define 
ft2-basic_types.html#ft_pixel_mode_xxxft_pixel_mode_mono    ft2-basic_types.html#FT_Pixel_ModeFT_PIXEL_MODE_MONO #define 
ft2-basic_types.html#ft_pixel_mode_xxxft_pixel_mode_grays   ft2-basic_types.html#FT_Pixel_ModeFT_PIXEL_MODE_GRAY #define 
ft2-basic_types.html#ft_pixel_mode_xxxft_pixel_mode_pal2    ft2-basic_types.html#FT_Pixel_ModeFT_PIXEL_MODE_GRAY2 #define 
ft2-basic_types.html#ft_pixel_mode_xxxft_pixel_mode_pal4    ft2-basic_types.html#FT_Pixel_ModeFT_PIXEL_MODE_GRAY4 A list of deprecated constants. Use the corresponding ft2-basic_types.html#FT_Pixel_ModeFT_Pixel_Mode  values instead.
values ft_pixel_mode_none see ft2-basic_types.html#FT_Pixel_ModeFT_PIXEL_MODE_NONE 
ft_pixel_mode_mono see ft2-basic_types.html#FT_Pixel_ModeFT_PIXEL_MODE_MONO 
ft_pixel_mode_grays see ft2-basic_types.html#FT_Pixel_ModeFT_PIXEL_MODE_GRAY 
ft_pixel_mode_pal2 see ft2-basic_types.html#FT_Pixel_ModeFT_PIXEL_MODE_GRAY2 
ft_pixel_mode_pal4 see ft2-basic_types.html#FT_Pixel_ModeFT_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_ModeFT_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_TAGFT_IMAGE_TAG ( ft2-basic_types.html#FT_Glyph_FormatFT_GLYPH_FORMAT_NONE , 0, 0, 0, 0 ),
    
ft2-basic_types.html#FT_IMAGE_TAGFT_IMAGE_TAG ( ft2-basic_types.html#FT_Glyph_FormatFT_GLYPH_FORMAT_COMPOSITE , 'c', 'o', 'm', 'p' ),
    
ft2-basic_types.html#FT_IMAGE_TAGFT_IMAGE_TAG ( ft2-basic_types.html#FT_Glyph_FormatFT_GLYPH_FORMAT_BITMAP ,    'b', 'i', 't', 's' ),
    
ft2-basic_types.html#FT_IMAGE_TAGFT_IMAGE_TAG ( ft2-basic_types.html#FT_Glyph_FormatFT_GLYPH_FORMAT_OUTLINE ,   'o', 'u', 't', 'l' ),
    
ft2-basic_types.html#FT_IMAGE_TAGFT_IMAGE_TAG ( ft2-basic_types.html#FT_Glyph_FormatFT_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_XXXFT_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_BitmapFT_Bitmap . You generally need to access the `bitmap' field of the ft2-base_interface.html#FT_GlyphSlotRecFT_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_OutlineFT_Outline ; you generally want to access the `outline' field of the ft2-base_interface.html#FT_GlyphSlotRecFT_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_OutlineFT_Outline , but FreeType isn't currently capable of rendering them correctly.
ft_glyph_format_xxx 
#define 
ft2-basic_types.html#ft_glyph_format_xxxft_glyph_format_none        ft2-basic_types.html#FT_Glyph_FormatFT_GLYPH_FORMAT_NONE #define 
ft2-basic_types.html#ft_glyph_format_xxxft_glyph_format_composite   ft2-basic_types.html#FT_Glyph_FormatFT_GLYPH_FORMAT_COMPOSITE #define 
ft2-basic_types.html#ft_glyph_format_xxxft_glyph_format_bitmap      ft2-basic_types.html#FT_Glyph_FormatFT_GLYPH_FORMAT_BITMAP #define 
ft2-basic_types.html#ft_glyph_format_xxxft_glyph_format_outline     ft2-basic_types.html#FT_Glyph_FormatFT_GLYPH_FORMAT_OUTLINE #define 
ft2-basic_types.html#ft_glyph_format_xxxft_glyph_format_plotter     ft2-basic_types.html#FT_Glyph_FormatFT_GLYPH_FORMAT_PLOTTER A list of decprecated constants. Use the corresponding ft2-basic_types.html#FT_Glyph_FormatFT_Glyph_Format  values instead.
values ft_glyph_format_none see ft2-basic_types.html#FT_Glyph_FormatFT_GLYPH_FORMAT_NONE 
ft_glyph_format_composite see ft2-basic_types.html#FT_Glyph_FormatFT_GLYPH_FORMAT_COMPOSITE 
ft_glyph_format_bitmap see ft2-basic_types.html#FT_Glyph_FormatFT_GLYPH_FORMAT_BITMAP 
ft_glyph_format_outline see ft2-basic_types.html#FT_Glyph_FormatFT_GLYPH_FORMAT_OUTLINE 
ft_glyph_format_plotter see ft2-basic_types.html#FT_Glyph_FormatFT_GLYPH_FORMAT_PLOTTER 
FT_Data 
  
typedef struct  FT_Data_
  {
    
const ft2-basic_types.html#FT_ByteFT_Byte *  pointer;
    
ft2-basic_types.html#FT_IntFT_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_FinalizerFT_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_ULongFT_ULong )_x1 << 24 ) |     \
            ( (
ft2-basic_types.html#FT_ULongFT_ULong )_x2 << 16 ) |     \
            ( (
ft2-basic_types.html#FT_ULongFT_ULong )_x3 <<  8 ) |     \
              (
ft2-basic_types.html#FT_ULongFT_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.
