Skip to content

FreeType » Docs » Core API » Basic Data Types

# Basic Data Types

## Synopsis

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. Note that FreeType does not use floating-point data types. Fractional values are represented by fixed-point integers, with lower bits storing the fractional part.

## FT_Byte

Defined in FT_TYPES_H (freetype/fttypes.h).

      typedef unsigned char  FT_Byte;

A simple typedef for the unsigned char type.

## FT_Bytes

Defined in FT_TYPES_H (freetype/fttypes.h).

      typedef const FT_Byte*  FT_Bytes;

A typedef for constant memory areas.

## FT_Char

Defined in FT_TYPES_H (freetype/fttypes.h).

      typedef signed char  FT_Char;

A simple typedef for the signed char type.

## FT_Int

Defined in FT_TYPES_H (freetype/fttypes.h).

      typedef signed int  FT_Int;

A typedef for the int type.

## FT_UInt

Defined in FT_TYPES_H (freetype/fttypes.h).

      typedef unsigned int  FT_UInt;

A typedef for the unsigned int type.

## FT_Int16

      typedef signed short  FT_Int16;

A typedef for a 16bit signed integer type.

## FT_UInt16

      typedef unsigned short  FT_UInt16;

A typedef for a 16bit unsigned integer type.

## FT_Int32

      typedef signed XXX  FT_Int32;

A typedef for a 32bit signed integer type. The size depends on the configuration.

## FT_UInt32

      typedef unsigned XXX  FT_UInt32;

## FT_Int64

      typedef signed XXX  FT_Int64;

## FT_UInt64

      typedef unsigned XXX  FT_UInt64;

## FT_Short

Defined in FT_TYPES_H (freetype/fttypes.h).

      typedef signed short  FT_Short;

A typedef for signed short.

## FT_UShort

Defined in FT_TYPES_H (freetype/fttypes.h).

      typedef unsigned short  FT_UShort;

A typedef for unsigned short.

## FT_Long

Defined in FT_TYPES_H (freetype/fttypes.h).

      typedef signed long  FT_Long;

A typedef for signed long.

## FT_ULong

Defined in FT_TYPES_H (freetype/fttypes.h).

      typedef unsigned long  FT_ULong;

A typedef for unsigned long.

## FT_Bool

Defined in FT_TYPES_H (freetype/fttypes.h).

      typedef unsigned char  FT_Bool;

A typedef of unsigned char, used for simple booleans. As usual, values 1 and 0 represent true and false, respectively.

## FT_Offset

Defined in FT_TYPES_H (freetype/fttypes.h).

      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

Defined in FT_TYPES_H (freetype/fttypes.h).

      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

Defined in FT_TYPES_H (freetype/fttypes.h).

      typedef char  FT_String;

A simple typedef for the char type, usually used for strings.

## FT_Tag

Defined in FT_TYPES_H (freetype/fttypes.h).

      typedef FT_UInt32  FT_Tag;

A typedef for 32-bit tags (as used in the SFNT format).

## FT_Error

Defined in FT_TYPES_H (freetype/fttypes.h).

      typedef int  FT_Error;

The FreeType error code type. A value of 0 is always interpreted as a successful operation.

## FT_Fixed

Defined in FT_TYPES_H (freetype/fttypes.h).

      typedef signed long  FT_Fixed;

This type is used to store 16.16 fixed-point values, like scaling values or matrix coefficients.

## FT_Pointer

Defined in FT_TYPES_H (freetype/fttypes.h).

      typedef void*  FT_Pointer;

A simple typedef for a typeless pointer.

## FT_Pos

Defined in FT_IMAGE_H (freetype/ftimage.h).

      typedef signed long  FT_Pos;

The type FT_Pos is used to store vectorial coordinates. Depending on the context, these can represent distances in integer font units, or 16.16, or 26.6 fixed-point pixel coordinates.

## FT_Vector

Defined in FT_IMAGE_H (freetype/ftimage.h).

      typedef struct  FT_Vector_
      {
        FT_Pos  x;
        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

Defined in FT_IMAGE_H (freetype/ftimage.h).

      typedef struct  FT_BBox_
      {
        FT_Pos  xMin, yMin;
        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).

#### note

The bounding box is specified with the coordinates of the lower left and the upper right corner. In PostScript, those values are often called (llx,lly) and (urx,ury), respectively.

If `yMin` is negative, this value gives the glyph's descender. Otherwise, the glyph doesn't descend below the baseline. Similarly, if `ymax` is positive, this value gives the glyph's ascender.

`xMin` gives the horizontal distance from the glyph's origin to the left edge of the glyph's bounding box. If `xMin` is negative, the glyph extends to the left of the origin.

## FT_Matrix

Defined in FT_TYPES_H (freetype/fttypes.h).

      typedef struct  FT_Matrix_
      {
        FT_Fixed  xx, xy;
        FT_Fixed  yx, yy;

      } FT_Matrix;

A simple structure used to store a 2x2 matrix. Coefficients are in 16.16 fixed-point 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

Defined in FT_TYPES_H (freetype/fttypes.h).

      typedef signed short  FT_FWord;   /* distance in FUnits */

A signed 16-bit integer used to store a distance in original font units.

## FT_UFWord

Defined in FT_TYPES_H (freetype/fttypes.h).

      typedef unsigned short  FT_UFWord;  /* unsigned distance */

An unsigned 16-bit integer used to store a distance in original font units.

## FT_F2Dot14

Defined in FT_TYPES_H (freetype/fttypes.h).

      typedef signed short  FT_F2Dot14;

A signed 2.14 fixed-point type used for unit vectors.

## FT_UnitVector

Defined in FT_TYPES_H (freetype/fttypes.h).

      typedef struct  FT_UnitVector_
      {
        FT_F2Dot14  x;
        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

Defined in FT_TYPES_H (freetype/fttypes.h).

      typedef signed long  FT_F26Dot6;

A signed 26.6 fixed-point type used for vectorial pixel coordinates.

## FT_Data

Defined in FT_TYPES_H (freetype/fttypes.h).

      typedef struct  FT_Data_
      {
        const FT_Byte*  pointer;
        FT_UInt         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_MAKE_TAG

Defined in FT_TYPES_H (freetype/fttypes.h).

    #define FT_MAKE_TAG( _x1, _x2, _x3, _x4 )                  \
              ( ( FT_STATIC_BYTE_CAST( FT_Tag, _x1 ) << 24 ) | \
                ( FT_STATIC_BYTE_CAST( FT_Tag, _x2 ) << 16 ) | \
                ( FT_STATIC_BYTE_CAST( FT_Tag, _x3 ) <<  8 ) | \
                  FT_STATIC_BYTE_CAST( FT_Tag, _x4 )         )

This macro converts four-letter tags that are used to label TrueType tables into an `FT_Tag` type, to be used within FreeType.

#### note

The produced values must be 32-bit integers. Don't redefine this macro.

## FT_Generic

Defined in FT_TYPES_H (freetype/fttypes.h).

      typedef struct  FT_Generic_
      {
        void*                 data;
        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.

Some 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_Generic_Finalizer

Defined in FT_TYPES_H (freetype/fttypes.h).

      typedef void  (*FT_Generic_Finalizer)( void*  object );

Describe 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 that is under finalization. Its client data is accessed through its `generic` field.

## FT_Bitmap

Defined in FT_IMAGE_H (freetype/ftimage.h).

      typedef struct  FT_Bitmap_
      {
        unsigned int    rows;
        unsigned int    width;
        int             pitch;
        unsigned char*  buffer;
        unsigned short  num_grays;
        unsigned char   pixel_mode;
        unsigned 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. Note that ‘padding’ means the alignment of a bitmap to a byte border, and FreeType functions normally align to the smallest possible integer value. For the B/W rasterizer, `pitch` is always an even number. To change the pitch of a bitmap (say, to make it a multiple of 4), use `FT_Bitmap_Convert`. Alternatively, you might use callback functions to directly render to the application's surface; see the file `example2.cpp` in the tutorial for a demonstration.
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 `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

`width` and `rows` refer to the physical size of the bitmap, not the logical one. For example, if `FT_Pixel_Mode` is set to `FT_PIXEL_MODE_LCD`, the logical width is a just a third of the physical one.

An empty bitmap with a NULL `buffer` is valid, with `rows` and/or `pitch` also set to 0. Such bitmaps might be produced while rendering empty or degenerate outlines.

## FT_Pixel_Mode

Defined in FT_IMAGE_H (freetype/ftimage.h).

      typedef enum  FT_Pixel_Mode_
      {
        FT_PIXEL_MODE_NONE = 0,
        FT_PIXEL_MODE_MONO,
        FT_PIXEL_MODE_GRAY,
        FT_PIXEL_MODE_GRAY2,
        FT_PIXEL_MODE_GRAY4,
        FT_PIXEL_MODE_LCD,
        FT_PIXEL_MODE_LCD_V,
        FT_PIXEL_MODE_BGRA,

        FT_PIXEL_MODE_MAX      /* do not remove */

      } FT_Pixel_Mode;

      /* these constants are deprecated; use the corresponding `FT_Pixel_Mode` */
      /* values instead.                                                       */
    #define ft_pixel_mode_none   FT_PIXEL_MODE_NONE
    #define ft_pixel_mode_mono   FT_PIXEL_MODE_MONO
    #define ft_pixel_mode_grays  FT_PIXEL_MODE_GRAY
    #define ft_pixel_mode_pal2   FT_PIXEL_MODE_GRAY2
    #define ft_pixel_mode_pal4   FT_PIXEL_MODE_GRAY4

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 ‘gray’ levels is stored in the `num_grays` field of the `FT_Bitmap` structure (it generally is 256).
FT_PIXEL_MODE_GRAY2 | A 2-bit per 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 per pixel bitmap, representing 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, representing RGB or BGR decimated glyph images used for display on LCD displays; the bitmap is three times wider than the original glyph image. See also `FT_RENDER_MODE_LCD`.
FT_PIXEL_MODE_LCD_V | An 8-bit bitmap, representing RGB or BGR decimated glyph images used for display on rotated LCD displays; the bitmap is three times taller than the original glyph image. See also `FT_RENDER_MODE_LCD_V`.
FT_PIXEL_MODE_BGRA | [Since 2.5] An image with four 8-bit channels per pixel, representing a color image (such as emoticons) with alpha channel. For each pixel, the format is BGRA, which means, the blue channel comes first in memory. The color channels are pre-multiplied and in the sRGB colorspace. For example, full red at half-translucent opacity will be represented as ‘00,00,80,80’, not ‘00,00,FF,80’. See also `FT_LOAD_COLOR`.

## FT_Glyph_Format

Defined in FT_IMAGE_H (freetype/ftimage.h).

      typedef enum  FT_Glyph_Format_
      {
        FT_IMAGE_TAG( FT_GLYPH_FORMAT_NONE, 0, 0, 0, 0 ),

        FT_IMAGE_TAG( FT_GLYPH_FORMAT_COMPOSITE, 'c', 'o', 'm', 'p' ),
        FT_IMAGE_TAG( FT_GLYPH_FORMAT_BITMAP,    'b', 'i', 't', 's' ),
        FT_IMAGE_TAG( FT_GLYPH_FORMAT_OUTLINE,   'o', 'u', 't', 'l' ),
        FT_IMAGE_TAG( FT_GLYPH_FORMAT_PLOTTER,   'p', 'l', 'o', 't' ),
        FT_IMAGE_TAG( FT_GLYPH_FORMAT_SVG,       'S', 'V', 'G', ' ' )

      } FT_Glyph_Format;

      /* these constants are deprecated; use the corresponding */
      /* `FT_Glyph_Format` values instead.                     */
    #define ft_glyph_format_none       FT_GLYPH_FORMAT_NONE
    #define ft_glyph_format_composite  FT_GLYPH_FORMAT_COMPOSITE
    #define ft_glyph_format_bitmap     FT_GLYPH_FORMAT_BITMAP
    #define ft_glyph_format_outline    FT_GLYPH_FORMAT_OUTLINE
    #define ft_glyph_format_plotter    FT_GLYPH_FORMAT_PLOTTER

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.
FT_GLYPH_FORMAT_COMPOSITE | The glyph image is a composite of several other images. This format is only used with `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 `FT_Bitmap`. You generally need to access the `bitmap` field of the `FT_GlyphSlotRec` structure to read it.
FT_GLYPH_FORMAT_OUTLINE | The glyph image is a vectorial outline made of line segments and Bezier arcs; it can be described as an `FT_Outline`; you generally want to access the `outline` field of the `FT_GlyphSlotRec` structure to read it.
FT_GLYPH_FORMAT_PLOTTER | The glyph image is a vectorial path with no inside and outside contours. Some Type 1 fonts, like those in the Hershey family, contain glyphs in this format. These are described as `FT_Outline`, but FreeType isn't currently capable of rendering them correctly.
FT_GLYPH_FORMAT_SVG | [Since 2.12] The glyph is represented by an SVG document in the ‘SVG ’ table.

## FT_IMAGE_TAG

Defined in FT_IMAGE_H (freetype/ftimage.h).

    #ifndef FT_IMAGE_TAG

    #define FT_IMAGE_TAG( value, _x1, _x2, _x3, _x4 )                         \
              value = ( ( FT_STATIC_BYTE_CAST( unsigned long, _x1 ) << 24 ) | \
                        ( FT_STATIC_BYTE_CAST( unsigned long, _x2 ) << 16 ) | \
                        ( FT_STATIC_BYTE_CAST( unsigned long, _x3 ) << 8  ) | \
                          FT_STATIC_BYTE_CAST( unsigned long, _x4 )         )

    #endif /* FT_IMAGE_TAG */

This macro converts four-letter tags to an unsigned long type.

#### note

Since many 16-bit compilers don't like 32-bit 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.