The FreeType Engine Core Library Reference ----------------------------------- Table of Contents: Introduction I. Types II. Functions III. Error codes -------------------- Introduction ============ This reference presents the types, functions, and error codes defined in the high-level API header file `freetype.h'. Note that all symbols defined in this file are prefixed by `TT_', to avoid name conflicts with other packages at link time. The reference for extensions of the FreeType library can be found in the file apirefx.txt. -------------------------------------------------------------------- -------------------------------------------------------------------- I. Types ======== Here is the list of all the types defined in the core FreeType API. Their exact definition can be found in the file `freetype.h' which should be included by every client application. TT_Bool Can be either non-zero (true) or zero (false). .................................................................. TT_Fixed A signed 16.16 fixed float integer type used to specify transform coefficients and other important data. .................................................................. TT_FWord A signed 16-bit type used to express a distance measured in the font's original EM units. These are also called `FUnits' in the TrueType specification. .................................................................. TT_UFWord An unsigned 16-bit type. .................................................................. TT_String TT_Char TT_Byte These types represent various 8-bit integer values (for strings, signed, and unsigned values, respectively). .................................................................. TT_Short TT_UShort TT_Long TT_ULong These four types are aliases for 16-bit integer (signed and unsigned) and 32-bit integer types (signed and unsigned). .................................................................. TT_F2Dot14 A 2.14 fixed float integer type used for unary vectors and some scaling coefficients. Its layout is: s : 1 -- sign bit m : 1 -- mantissa bit f : 14 -- unsigned fractional value where `s:m' is the 2-bit signed integer value to which the always positive fractional part `f' should be added. .................................................................. TT_F26Dot6 A 26.6 fixed float integer format used to define fractional pixel coordinates. Here, 1 unit = 1/64 pixel. .................................................................. TT_Pos This type is used to store point coordinates, either in fractional pixels (26.6 fixed floats) or in EM units (simple integers). The meaning of the value depends on the context. For example, all distances relative to a scaled glyph are expressed in fractional pixels (including bearings, advances, etc). However, the same distances are in notional font units when the glyph was loaded unscaled. .................................................................. TT_UnitVector A simple structure used to store a unit vector. The vector's coordinates are expressed in fixed float format (2.14). struct { TT_F2Dot14 x; TT_F2Dot14 y; } .................................................................. TT_Vector A simple structure used to store a single vector. Its coordinates are expressed in fixed float format (26.6). struct { TT_F26Dot6 x; TT_F26Dot6 y; } .................................................................. TT_Matrix A simple structure used to store a single 2x2 matrix. Its coefficients are expressed in 16.16 fixed float format. This matrix is used to perform linear transformations on the glyph outline, such as slanting or rotation. struct { TT_Fixed xx, xy; TT_Fixed yx, yy; }; The computation performed is: x' = xx * x + xy * y y' = yx * x + yy * y .................................................................. TT_BBox A simple type to hold a glyph's bounding box. Used by the TT_Get_Outline_BBox() API. struct { TT_Pos xMin, yMin; TT_Pos xMax, yMax; } .................................................................. TT_Outline Outlines are now full-class citizens, with their own API. This structure is used to describe a vectorial glyph representation to the rasterizer. It is made of several fields described below. Note however that: ***** THIS STRUCTURE MAY CHANGE IN THE FUTURE. We thus ***** encourage you to use the outlines APIs described below to ***** process your outlines, i.e., create/copy/translate/ ***** transform them as well as rendering bitmaps and pixmaps. ***** THE STRUCTURE CHANGED BETWEEN 1.0 and 1.1! Now that you have been warned, the fields are: - An array of points: The `n_points' field gives the number of points in the outline, while their coordinates are found in the single vector array `points'. The `flag' array holds for each point a flag indicating its type. Currently, only the first bit (bit 0, the least significant bit) of each byte is meaningful to the rasterizer. If set, it indicates that the point is _on_ the curve. If not set, the point is said to be _off_ the curve. It is then a Bezier control point. For more information about point states, read the TrueType specification or the scan-line documentation `raster.txt'. - An array of contours' end-point indexes: The `n_contours' field gives the number of contours, while the `contours' array holds the indexes of each contour's last point. Note that the first contour always begin at point 0. Hence, contours[0] holds the index of the last point of the first contour. The second contour starting at point number `contours[0]+1' and ending a point number `contours[1]'. ** IMPORTANT NOTE: ** ********************* The last table entry _must_ always give the total number of points used to draw the contours, i.e.: contours[n_contours - 1] == n_points If this value is bigger than `n_points' when calling the scan-line converter, the component will immediately return an error (TT_Err_Too_Many_Points). If the value is smaller, only the points contained in the described contours will be used in the conversion process. - An owner field: This flag should **NEVER** be changed by the user. It indicates whether the pointer fields own the arrays they refer to (when the flag is set), or if they simply alias them (flag unset). - A high precision flag: If this boolean is set (i.e. not zero), the scan-line converter uses a higher precision to compute segment and Bezier coordinates (more precisely, it uses 1/1024 precision, instead of the normal 1/64). This is of course slower but can be important for glyphs rendered at small sizes. - A second pass flag: If this boolean is set, the scan-line converter performs a second sweep on the bitmap/pixmap to detect vertical drop-out. Only horizontal drop-outs are detected in the first pass. This is slower, but important for glyphs rendered at small sizes. - A dropout mode: Used to specify the method to apply for drop-out control (also called `continuity testing' in other environments). The mode value must be one of the values defined by the TrueType specification. The recent modes 4 and 5 introduced in the newest TrueType specification (Version 1.66) are fully supported. An invalid value (i.e., not 0, 1, 2, 4, or 5) is taken as no dropout control (equivalent to mode 0). NOTE 1: The outline returned by TT_Get_Glyph_Outline() only alias the data that is part of a glyph container (see below). However, it is possible to create and process your own outlines with the new API functions TT_New_Outline(), TT_Done_Outline(), TT_Copy_Outline(), TT_Translate_Outline(), etc. TT_Done_Outline() will only discard an outline's array if it owns them. NOTE 2: The outlines created by TT_New_Outline() are _not_ released by the engine on TT_Done_FreeType(), they must be discarded explicitly by the user who has created them! NOTE 3: The glyph loader sets the fields `high_precision', `dropout_mode' and `second_pass' automatically. NOTE 4: This structure was called TT_Glyph_Outline in beta versions of FreeType. .................................................................. TT_Glyph_Metrics A structure used to return simple glyph metrics, usable for either horizontal or vertical layout. The values are expressed in fractional pixels (26.6 format) if scaling was active, and in FUnits otherwise. The main idea was to accomodate vertical text layouts by getting rid of the two explicit `leftSideBearing' and `advanceWidth' names. The meaning of the fields varies with the text layout: bearingX: Also known as the `left side bearing'. For horizontal metrics, this value gives the horizontal distance from the pen position to the glyph's bbox xmin, otherwise it specifies the vertical distance. bearingY: Also known as the `top side bearing', this is the vertical distance from the baseline to the glyph's bbox ymax for horizontal metrics, the horizontal distance otherwise. struct { TT_BBox bbox; /* the glyph's bbox */ TT_Pos bearingX; /* left-side bearing */ TT_Pos bearingY; /* top-side bearing */ TT_Pos advance; /* advance width or height */ }; ** IMPORTANT NOTE ** Because of the convention used by the TrueType engine, the outlines generated at glyph-load time are all placed so that the pen is at position (0,0). This means that you don't need to increase the pen position by `bearingX' and/or `bearingY' before writing a glyph. Text output can be performed with simple lines like: for (glyphs in text) { TT_Load_Glyph( ... ); TT_Get_Glyph_Outline( glyph, &outline ); TT_Translate_Outline( outline, cur_pos_x * 64, cur_pos_y * 64 ); TT_Get_Outline_Bitmap( outline, bitmap ); /* blit bitmap to surface */ cur_pos_x += (metrics.advance + 32) / 64 } See the file `test/ftstring.c' for an example. NOTE 2: This structure has changed from the beta version of FreeType. NOTE 3: FreeType implements only TT_Get_Glyph_Metrics() to return horizontal metrics. For extracting vertical metrics you should use TT_Get_Glyph_Big_Metrics(). .................................................................. TT_Big_Glyph_Metrics This structure is used to return the metrics of a glyph for both horizontal and vertical layout. The `linearXXX' fields represent unhinted scaled metrics values. They can be useful for applications which need to compute device independent placement of glyphs. Applying these metrics to hinted glyphs will in most cases ruin the grid fitting performed by the bytecode interpreter. struct { TT_BBox bbox; /* the glyph's bounding box */ TT_Pos horiBearingX; /* horizontal left-side bearing */ TT_Pos horiBearingY; /* horizontal top-side bearing */ TT_Pos vertBearingX; /* vertical left-side bearing */ TT_Pos vertBearingY; /* vertical top-side bearing */ TT_Pos horiAdvance; /* horizontal advance */ TT_Pos vertAdvance; /* vertical advance */ TT_Pos linearHoriBearingX; /* lin. scaled hor. lsb. */ TT_Pos linearHoriAdvance; /* lin. scaled hor. adv. */ TT_Pos linearVertBearingY; /* lin. scaled vert. tsb. */ TT_Pos linearVertAdvance; /* lin. scaled vert. adv. */ } .................................................................. TT_Instance_Metrics A structure used to return instance (point size) metrics. struct { int pointSize; /* point size in points (1 point = 1/72 inch) */ TT_UShort x_ppem; /* horizontal pixels per EM square */ TT_UShort y_ppem; /* vertical pixels per EM square */ TT_Fixed x_scale; /* 16.16 scale for EM -> frac pixels */ TT_Fixed y_scale; /* 16.16 scale for EM -> frac pixels */ TT_UShort x_resolution; /* device hor. res. in dpi */ TT_UShort y_resolution; /* device vert. res. in dpi */ }; The fields `x_scale' and `y_scale' can be used by clients to convert from notional units (in funits) to fractional pixels (in 26.6 fixed float format), e.g.: TT_FUnit em_distance; TT_F26Dot6 frac_distance; TT_Fixed x_scale; frac_distance = (em_distance * x_scale) / 0x10000; .................................................................. TT_Raster_Map This structure is used to describe a target bitmap (or pixmap) to the scan-line converter. It _must_ be set up by the client application. - The `rows' field contains the total number of rows in the bitmap. - The `width' field gives the number of pixels per row (a bit or a byte, depending on the map's nature). - The `cols' field gives the number of columns, i.e. bytes, taken by each row in the map buffer. ** IMPORTANT: ** The `cols' field must be a multiple of 4 for pixmaps! Typically, its value should be `(width+7)/8' for bitmaps, and `(width+3) & -4' for pixmaps. - The `flow' field gives the map's vertical orientation. If the first bytes of the bitmap buffer pertain to its upper row, the flow is said to be going `down', and the field should take the value `TT_Flow_Down'. If these bytes pertain to its lowest row, the flow is going `up', and the value is `TT_Flow_Up'. As an example, the PC video modes use a `down' flow, where the first VRAM byte corresponds to the upper and leftmost corner of the screen. - The `bitmap' field is a typeless pointer to the map's buffer. - The `size' field contains the buffer's size in bytes. It is usually computed as follows: size = rows * cols; NOTE 1: For bitmaps, the leftmost-pixel is related to the highest (i.e. most significant) bit of its byte. There is currently no support for the opposite convention found in some systems. (It can be easily added if you really need it, just ask the development team.) struct { int rows; /* number of rows */ int cols; /* number of columns (bytes) per row */ int width; /* number of pixels per line */ int flow; /* bitmap orientation */ void* bitmap; /* bit/pixmap buffer */ long size; /* bit/pixmap size in bytes */ } TT_Raster_Map; NOTE 2: TT_Get_Outline_Bitmap() resp. TT_Get_Glyph_Bitmap() are used to render bitmaps into a TT_Raster_Map. The convention used is 0 for the background, and 1 for the foreground. The glyph is simply `or-ed' to the bitmap buffer. NOTE 3: TT_Get_Outline_Pixmap() and TT_Get_Glyph_Pixmap() are used to render pixmaps into a TT_Raster_Map. Note that pixels are drawn in spans of 4 successive bytes, only if needed. This means that you must ALWAYS pass a clean pixmap buffer to these functions. Otherwise, garbage could accumulate! .................................................................. TT_Header This structure is used to hold the font's header. Its layout and meaning are defined in the TrueType specification, in the `head' section. .................................................................. TT_Horizontal_Header This structure is used to hold the font's horizontal header. Its layout and meaning are defined in the TrueType specification, in the `hhead' section. .................................................................. TT_OS2 This structure is used to hold the font's OS/2 table. Its layout and meaning are defined in the TrueType specification, in the `OS/2' section. Note that since FreeType 1.3, we support fonts without an OS/2 table (mainly old but popular Mac fonts). In this case, the table's `version' field will be set to 0xFFFF by the loader, and all other fields will be zeroed. .................................................................. TT_Postscript This structure is used to hold the font's PostScript table. Its layout and meaning are defined in the TrueType specification, in the `post' section. .................................................................. TT_Face_Properties This structure is used to return an opened face's properties. These are: - The total number of glyphs in the font, given by the field `num_Glyphs'. - The maximum number of points for the font's glyphs. This value is used to allocate the points tables of a glyph container's outline. It can be fairly large (like 256 points for Roman fonts). - The maximum number of contours for the font's glyphs. This value is used to allocate the contours tables of a glyph container's outline. It can be fairly large (over 16, even in Roman fonts). - The number of character mappings and name records within the font. These values can still be retrieved through the APIs TT_Get_CharMapCount() and TT_Get_Num_Names(), though these have been _seriously_ deprecated. - The number of associated faces. This number is always 1 for a normal TrueType font file. However, when the face object was opened from a TrueType collection, it contains the total number of embedded fonts. - Pointers to the face's header, horizontal header, OS/2, and PostScript tables. struct { TT_UShort num_Glyphs; /* number of glyphs in face */ TT_UShort max_Points; /* max. numb. of points in a glyph */ TT_Short max_Contours; /* maximum number of contours in a glyph */ TT_ULong num_Faces; /* 1 for normal TrueType files resp. */ /* the number of embedded faces for TT */ /* collections */ TT_Header* header; /* TrueType header table */ TT_Horizontal_Header* horizontal; /* TrueType horizontal header */ TT_Vertical_Header* vertical; /* TrueType vertical header */ TT_OS2* os2; /* TrueType OS/2 table */ TT_Postscript* postscript; /* TrueType PostScript table */ } TT_Face_Properties; - Note that the `vertical' field is set to NULL if the font file does not contain any vertical metrics. - Note also that since version 1.3 we support font files without an OS/2 table. See the definition of TT_OS2 for more details. .................................................................. TT_Stream This handle type defines a stream used to access a font file's data. A client application should never deal with streams directly, but some engine extensions need it to support more advanced features like sbit support. .................................................................. TT_Face This type defines a handle used to reference a face object. The objects are never accessed directly by a client application; it can only obtain handles to new objects, and use them to query specific information or processes. See also: TT_Open_Face(), TT_Open_Collection(), TT_Close_Face(), TT_Get_Face_Properties(), etc. .................................................................. TT_Instance This type defines a handle used to reference an instance object (also called a `pointsize' in other type engines). An instance is always created from a valid face object, and is destroyed with it by the engine. See also: TT_New_Instance(), TT_Close_Instance(), TT_Set_Instance_Pointsize(), TT_Set_Instance_Resolutions(), etc. .................................................................. TT_Glyph This type defines a handle used to reference a glyph container object. A glyph container is an object owning tables sized to the font's maximum profile to hold any glyph of a given font file. It contains an outline, some metrics, as well as some data related to the way it should be processed by the scan-line converter. Note that a glyph container doesn't contain any bitmap or pixmap! See also: TT_New_Glyph(), TT_Close_Glyph(), TT_Get_Glyph_Metrics(), TT_Get_Glyph_Big_Metrics(), TT_New_Outline(), TT_Get_Glyph_Outline(), TT_Get_Glyph_Bitmap(), TT_Get_Glyph_Pixmap() .................................................................. TT_Error This is the type of all error codes returned by the API. Nearly all functions return an error code, set to 0 in case of success. A list of all error codes is given in section III. .................................................................. TT_Engine For the sake of re-entrancy it is possible to distinguish `engines' to separate several running instances of the library. For example, it could be used as a DLL shared by several client applications. Each client program must begin by creating its own engine, through a call to TT_Init_FreeType(). The engine must also be passed as the first argument of the following functions: TT_Open_Face() TT_Open_Collection() TT_Set_Raster_Gray_Palette() TT_Get_Outline_Bitmap() TT_Get_Outline_Pixmap() TT_Done_FreeType() Note that any FreeType object pertains to one single engine (there is no sharing). Closing an engine with TT_Done_FreeType() will delete all the objects that have been allocated within its instance. -------------------------------------------------------------------- -------------------------------------------------------------------- II. Functions ============= Here is a list of the core library's API. NOTE: A function's default result is an error code of type TT_Error; a list of error codes is given in section III below. Some functions return other types, in which case the result type is documented with its description. .................................................................. TT_FreeType_Version( int* major, int* minor ); Queries the major and minor version of the library. .................................................................. TT_Init_FreeType( TT_Engine* engine ); Creates and initializes a new engine. Returns a handle to the engine in the `*engine' variable. This call must be performed before any other function of FreeType is invoked. The engine handle must be passed to the following functions: TT_Open_Face() TT_Open_Collection() TT_Set_Raster_Gray_Palette() TT_Done_FreeType() .................................................................. TT_Done_FreeType( TT_Engine engine ); Finalizes and destroys an engine. This call destroys _all_ objects that were previously created and used with the engine. .................................................................. TT_Open_Face( TT_Engine engine, TT_Text* fontPathName, TT_face* face ); This call opens a font file, located by `fontPathName', and returns a handle to the newly corresponding face object in the handle `*face'. The object is part of the `engine' instance. Example: error = TT_Open_Face( engine, "c:\ttf\wingding.ttf", &face ); if ( error ) fprintf( stderr, "Could not open face.\n" ); NOTE 1: The font file can be a TrueType collection; in this case, the engine will always open the first embedded font found in the file. NOTE 2: `TT_Text' is usually defined as `char' by a typedef declaration. It may be a 16-bit quantity (or even wider) for some operating systems; see ttconfig.h for details. .................................................................. TT_Open_Collection( TT_Engine engine, TT_Text* collectionPathName, TT_ULong fontIndex, TT_Face* face ); This call opens one of the fonts found in a TrueType collection. The font is selected through the `fontIndex' argument. The first font has index 0. Note that to know a collection's number of embedded fonts, you will have to: 1 - open the first collection font with TT_Open_Face(). 2 - query the face's properties through TT_Get_Face_Properties(). The number of embedded faces is then `properties->num_Faces'. Example: TT_Face face; TT_Face_Properties properties; /* Open first embedded collection font */ error = TT_Open_Face( engine, "c:\ttf\sample.ttc", &face ); if ( error ) { ...error... } /* Get face properties */ error = TT_Get_Face_Properties( face, &properties ); if ( error ) { ...error... } printf( "There are %d fonts in this collection.\n", properties->num_Faces ); TT_Close_Face( face ); /* Open second font in collection */ error = TT_Open_Collection( engine, "c:\ttf\sample.ttc", 1, &face ); if ( error ) { ...error... } NOTE 1: If the file isn't a collection, `fontIndex' must be zero. Otherwise, an error will be returned. NOTE 2: `TT_Text' is usually defined as `char' by a typedef declaration. It may be a 16-bit quantity (or even wider) for some operating systems; see ttconfig.h for details. .................................................................. TT_Set_Raster_Gray_Palette( TT_Engine engine, TT_Byte* palette ); Sets the gray-level palette for an engine. The palette is used to create pixmaps through the TT_Get_Glyph_Pixmap() function. It is an array of five bytes, following the convention: palette[0] = background (white) palette[1] = light palette[2] = medium palette[3] = dark palette[4] = foreground (black) .................................................................. TT_Get_Face_Properties( TT_Face face, TT_Face_Properties* properties ); Returns the `face' object's `*properties'. This structure contains various data like the total number of glyphs and pointers to some mandatory TrueType tables. See the definition of TT_Face_Properties in section I for more details. Note that since version 1.3, FreeType supports fonts with no OS/2 table, like many old Mac fonts. See the definition of TT_OS2 for more details. .................................................................. TT_Get_Face_Metrics( TT_Face face, TT_UShort firstGlyph, TT_UShort lastGlyph, TT_Short* leftBearings, TT_UShort* widths, TT_Short* topBearings, TT_UShort* heights ); This function returns the original horizontal AND vertical metrics for a given face `face' and a given glyph range specified by `firstGlyph' and `lastGlyph' as found in the `hmtx' and `vmtx' tables. These are the glyphs' left-side bearings (in `leftBearings') and horizontal advance widths (in `widths'), as well as top-side bearings (in `topBearings') and vertical advance heights (in `heights'). If you aren't interested in any of the metrics fields, simply set its value to NULL. All are expressed in font units, a.k.a. EM units. The metrics arrays must be allocated by the client program. IMPORTANT NOTE: As vertical metrics are optional in a TrueType font, this function will return an error (TT_Err_No_Vertical_Data) if this function is called on such a face with non-NULL `topBearings' or `heights' arguments. If a font has no vertical data, the `vertical' field in its properties structure is set to NULL. .................................................................. TT_Set_Face_Pointer( TT_Face face, void* data ); For convenience purposes, each face object has a `generic' pointer which value is unused by the engine, but that can be set freely by client applications through this function. Do what you want with it; it is here to give you a chance to link a face object to your own structures and data. .................................................................. void* TT_Get_Face_Pointer( TT_Face face ); ^^^^ Returns a face object's generic pointer. See TT_Set_Face_Pointer() above. .................................................................. TT_Flush_Face( TT_Face face ); Closes a given face object's file handler or descriptor. This is useful to save system resources if your application opens dozens or even hundreds of fonts. The face object is still valid, and its file will be re-opened automatically on the next request which requires disk access. .................................................................. TT_Close_Face( TT_Face face ); Closes a given `face' object. This function will also destroy all the face's child instances. The face's glyphs will not be destroyed, however. .................................................................. TT_New_Instance( TT_Face face, TT_Instance* instance ); Creates a new instance object related to the `face' object. A handle to the newly created instance is returned in `instance'. The default instance resolution is 96dpi in both vertical and horizontal direction; the default point size is 10pt. .................................................................. TT_Set_Instance_Resolutions( TT_Instance instance, TT_UShort xResolution, TT_UShort yResolution ); Sets the target device resolutions for a given instance. The values are expressed in dots per inch (dpi). A value of 96dpi is typical for an SVGA display, 72dpi for a Macintosh one, and 300 to 6000dpi for printers. Default value (before a call to this function) is 96dpi. .................................................................. TT_Set_Instance_CharSize( TT_Instance instance, TT_F26Dot6 charsize ); Sets the point size for a given instance. The size is expressed in fractional (26.6) `points', where 1 point = 1/72 inch. The default value is 10pt (before a call to this function). For example, to use a char size of 12pt, call the function with: TT_Set_Instance_CharSize( instance, 12 * 64 ); Fractional point sizes are thus possible. .................................................................. TT_Set_Instance_CharSizes( TT_Instance instance, TT_F26Dot6 charWidth, TT_F26Dot6 charHeight ); Sets an instance's glyph width and height independently in fractional (26.6) points. Similar to Set_Instance_CharSize() with the exception that the horizontal and vertical glyph dimensions can differ. .................................................................. TT_Set_Instance_PixelSizes( TT_Instance instance, TT_UShort pixelWidth, TT_UShort pixelHeight, TT_F26Dot6 pointSize ); This function can be used to specify directly the pixel sizes and point size of a given instance, independently of device resolutions. This is not the recommended way to do it, but can be used for debugging or simplicity in some special cases. Note that you _must_ provide a point size! .................................................................. TT_Set_Instance_Transform_Flags( TT_Instance instance, TT_Bool rotated, TT_Bool stretched ); Sets the transform flags for a given instance. These flags are passed to the interpreter each time a glyph is loaded within the instance. Their role is to notify the glyph hinting mechanism that the resulting glyph will be transformed in a special way. Setting one of these flags to true usually disables hinting, though this behaviour varies with each font file. NOTE: The glyph loader doesn't perform the rotation or the stretching automatically; this must be done explicitly by the client application. Use the function TT_Transform_Outline() for that purpose. .................................................................. TT_Get_Instance_Metrics( TT_Instance instance, TT_Instance_Metrics* imetrics ); This call returns a given instance's current metrics. They are returned in the `imetrics' structure, which contains, among other things, the current point size, ppem, and device resolution (horizontal and vertical). .................................................................. TT_Set_Instance_Pointer( TT_Instance instance, void* data ); For convenience purposes, each instance object has a `generic' pointer which value is unused by the engine, but that can be set freely by client applications through this function. Do what you want with it, it is here to give you a chance to link a face object to your own structures and data. .................................................................. void* TT_Get_Instance_Pointer( TT_Instance instance ) ^^^^ This function returns an instance object's generic pointer set through TT_Set_Instance_Pointer(). .................................................................. TT_Done_Instance( TT_Instance instance ); Closes a given instance object, destroying its associated data. Note that this is performed automatically when a face is closed on all its child instances. However, explicit deallocation can help in freeing the memory used by the application earlier. .................................................................. TT_New_Glyph( TT_Face face, TT_Glyph* glyph ); Creates a new glyph container for the glyphs of the font described by the `face' handle. A pointer to the container is returned in `glyph'. The face is said to be the glyph's parent. NOTE: A glyph is destroyed with its parent face object. However, it is possible to delete it explicitly with TT_Done_Glyph(). .................................................................. TT_Done_Glyph( TT_Glyph glyph ); Discards a glyph container. This is also done automatically for all glyphs when closing its parent face object. .................................................................. TT_Load_Glyph( TT_Instance instance, TT_Glyph glyph, TT_UShort glyphIndex, TT_UShort loadFlags ); Loads and processes (scales and/or hints) a glyph at a given `instance' into the `glyph' container. Note that `glyph' and `instance' must have the _same_ parent face object, otherwise an error message will be returned. `glyph_index' is the glyph's index as found in the TrueType font. It is _not_ a character code (see the charmap functions below). `load_flags' is an integer that specifies which operations are to be performed on the loaded glyph. The following values/bits are used: TTLOAD_SCALE_GLYPH Indicates that the glyph must be scaled to the instance's resolution. The pixel coordinates returned in the glyph outline structure (see below) are then expressed in fractional pixels represented in the 26.6 fixed point floating format (F26Dot6). If scaling is disabled, the coordinates returned in the outline structure are integer font units, also called `FUnits' by the TrueType specification. TTLOAD_HINT_GLYPH This flag is only valid when scaling is on. It informs the loader that the glyph must be hinted (i.e., grid-fitted for optimal display). Note that hinting will occur only if the instance's transformations and metrics allow it (for example, most font programs disable hinting automatically in case of rotation or stretching). When loading a hinted glyph, the metrics computed by the loader, including the bounding box, will also be grid-fitted. TTLOAD_PEDANTIC Starting with FreeType version 1.3, the bytecode interpreter can ignore even more errors (like out-of-bound array accesses). Using this flag it is possible to force TrueType compliant interpretation of font programs. TTLOAD_IGNORE_GLOBAL_ADVANCE_WIDTH A flag to handle monospaced fonts with an incorrect global advance width in the `hhea' table. If set, the actual advance width value of a particular glyph will be used; if unset, the advance widths for all glyphs are forced to be equal to the global value. NOTE: You can also use the constant TTLOAD_DEFAULT, which is simply the union of TTLOAD_SCALE_GLYPH and TTLOAD_HINT_GLYPH for most `typical' loads. .................................................................. TT_Get_Glyph_Outline( TT_Glyph glyph, TT_Outline* outline ); This call returns the glyph's `outline'. This is a simple structure which contains pointers to the data used to describe an outline to the rasterizer. See the definition of TT_Outline in section I. .................................................................. TT_Get_Glyph_Metrics( TT_Glyph glyph, TT_Glyph_Metrics* metrics ); Extracts the glyph's metrics and copies them to the `*metrics' structure. Its format is described in section I. If the glyph has been loaded without scaling, the values are expressed in FUnits (integers relative to the original font grid called the EM Square). If the glyph has been loaded _with_ scaling, which is the default, the values are expressed in fractional pixels in 26.6 fixed point float format (F26Dot6; 1 unit = 1/64th of a pixel). If the glyph has been loaded with hinting, the metrics are also grid-fitted, including the bounding box. To get the un-fitted bbox, call TT_Get_Outline_BBox() on the glyph's outline. NOTE: BBox fitting occurs according to the following scheme: #define FLOOR( x ) ( (x) & -64 ) #define CEILING( x ) ( ( (x) + 63 ) & -64 ) xMin = FLOOR( xMin ); yMin = FLOOR( yMin ); xMax = CEILING( xMax ); yMax = CEILING( yMax ); This means that the outline's width and height in pixels can be computed simply from the fitted bbox, namely (xMax-xMin)/64 and (yMax-yMin)/64 .................................................................. TT_Get_Glyph_Big_Metrics( TT_Glyph glyph, TT_Big_Glyph_Metrics* metrics ); Extracts the glyph's big metrics and copies them to the `*metrics' structure. Its format is described in section I. If the glyph has been loaded without scaling, the values are expressed in FUnits (integers relative to the original font grid called the EM Square). If the glyph has been loaded _with_ scaling, which is the default, the values are expressed in fractional pixels in 26.6 fixed point float format (F26Dot6; 1 unit = 1/64th of a pixel). If the glyph has been loaded with hinting, the metrics are also grid-fitted, including the bounding box. To get the un-fitted bbox, just call TT_Get_Outline_BBox() on the glyph's outline. NOTE 1: BBox fitting occurs according to the following scheme: #define FLOOR( x ) ( (x) & -64 ) #define CEILING( x ) ( ( (x) + 63 ) & -64 ) xMin = FLOOR( xMin ); yMin = FLOOR( yMin ); xMax = CEILING( xMax ); yMax = CEILING( yMax ); This means that the outline's width and height in pixels can be computed simply from the fitted bounding box, namely (xMax-xMin)/64 and (yMax-yMin)/64 NOTE 2: The vertBearingX value in `metrics' cannot be extracted for outline glyphs -- it is defined for embedded bitmaps only. Instead, it is set to (xMin-xMax)/2; this will center the bounding box on the vertical `baseline'. .................................................................. TT_Get_Glyph_Bitmap( TT_Glyph glyph, TT_Raster_Map* bitmap, TT_F26Dot6 xOffset, TT_F26Dot6 yOffset ); This call converts the vectorial glyph representation contained in the object handled by `glyph' into a bitmap. The target bitmap is described by the `bitmap' pointer. Clipping will be done if necessary. You can also specify an offset to be applied before the scan-line conversion; `xOffset' and `yOffset' must be expressed in fractional pixels (where 1 unit = 1/64th pixel). NOTE 1: Choosing non integer pixel offsets, i.e., values of `xOffset' and `yOffset' that are not multiples of 64, will ruin the hinting performed by the interpreter, and result in bad rendering at small sizes. NOTE 2: The glyph's point coordinates must be scaled before calling this function. Never call this function with a glyph that were loaded with no scaling! NOTE 3: FreeType always shifts the glyph horizontally so that the left side bearing is equal to the left side of the bounding box. .................................................................. TT_Get_Glyph_Pixmap( TT_Glyph glyph, TT_Raster_Map* pixmap, TT_F26Dot6 xOffset, TT_F26Dot6 yOffset ); This call converts the vectorial glyph representation contained in the object handled by `glyph' into a pixmap (i.e., an 8-bit/pixel map). The result is an anti-aliased version of the glyph (`anti-aliasing' is also known as `font-smoothing'). The target pixmap is described by the `pixmap' pointer. Note that its width _must_ be a multiple of 4. For the definition and description of a pixmap see Section I. As with TT_Get_Glyph_Bitmap(), you can specify offsets to be applied before the rendering (`xOffset' and `yOffset' must be expressed in fractional pixel coordinates). NOTE 1: You don't need to supply a temporary bitmap for the anti-aliaser. The rasterizer uses its own scheme to optimize memory usage. NOTE 2: The glyph's point coordinates must be scaled before calling this function. This means that you should never call it with a glyph which has been loaded without scaling! NOTE 3: The pixmap passed to this function should always be EMPTY (i.e., filled with zero bytes) before the call. If not, garbage will accumulate! NOTE 4: FreeType always shifts the glyph horizontally so that the left side bearing is equal to the left side of the bounding box. .................................................................. TT_New_Outline( TT_UShort numPoints, TT_UShort numContours, TT_Outline* outline ); Creates a new outline object. This function creates the arrays necessary to hold `numPoints' points and `numContours' contours, and set `outline's pointers to them. The new outline owns the arrays, and they will be destroyed with it through TT_Done_Outline(). NOTE 1: Outlines created with this function are called `user' outlines, in contrast with the outlines returned by TT_Get_Glyph_Outline(), which fields refer to the data contained within a glyph object (i.e., these outlines do not own the arrays they refer to). NOTE 2: User outlines aren't tracked by the engine, which means they are not destroyed by a TT_Done_FreeType(). You have to explicitly discard them through TT_Done_Outline() to avoid memory leaks. .................................................................. TT_Done_Outline( TT_Outline* outline ); Deletes an outline's data. Note that you need not destroy the outlines returned by TT_Get_Glyph_Outline(), only those created by TT_New_Outline(). .................................................................. TT_Copy_Outline( TT_Outline* source, TT_Outline* target ); Copies the content of the `source' outline into the content of the `target' outline. The two outlines must have been created with the same dimensions (num_points and num_contours), otherwise this function will return an error code. .................................................................. void TT_Transform_Outline( TT_Glyph_Outline* outline, ^^^^ TT_Matrix* matrix ); Applies a simple transformation matrix on a given outline. This will multiply each point coordinate vector by a 2x2 matrix, which coefficients are given in the 16.16 fixed float format. Rotation can be performed with this function. NOTE: This function takes an outline, and not a glyph handle, as a parameter. This `feature' lets you apply transformations on your own copies of glyphs. .................................................................. void TT_Translate_Outline( TT_Glyph_Outline* outline, ^^^^ TT_Pos xOffset, TT_Pos yOffset ); Applies a simple translation on a given outline. NOTE: This function takes an outline, and not a glyph handle, as a parameter. This `feature' lets you apply translation to your own copies of glyphs. .................................................................. TT_Get_Outline_Bitmap( TT_Outline* outline, TT_Raster_Map* bitmap ); Renders an outline into a bitmap. The latter must be setup by the user before the call (i.e., it is not created by this function, instead it must be provided by the user). .................................................................. TT_Get_Outline_Pixmap( TT_Outline* outline, TT_Raster_Map* pixmap ); Renders an outline into a pixmap. The latter must be setup by the user before the call (i.e., it is not created by this function, instead it must be provided by the user). NOTE: The pixmap passed to this function must always be EMPTY (i.e., filled with zero bytes) before the call. Otherwise, garbage may accumulate! .................................................................. TT_Get_Outline_BBox( TT_Outline* outline, TT_BBox* bbox ); Returns an outline's bounding box in the `bbox' structure. Note that the returned coordinates are not grid fitted! NOTE: The current release of FreeType (1.x) does compute the bounding box for the outline's control points, and not the `exact' box based on Bezier arcs extrema. Hence, the bbox returned by this function may be slightly larger than necessary if the glyph doesn't have control points at its extrema, or if it has been rotated. .................................................................. void TT_Transform_Vector( TT_Pos* x, ^^^^ TT_Pos* y, TT_Matrix* matrix ); Applies a 2x2 matrix to a vector. .................................................................. int TT_Get_CharMapCount( TT_Face face ); ^^^ Gets the number of character mappings present in the TrueType file described by the `face' handle. Returns -1 if the handle is invalid. IMPORTANT NOTE: ******** This function is deprecated. Get the number of character maps from the `num_CharMaps' field in the structure returned by TT_Get_Face_Property() instead. .................................................................. TT_Get_CharMap_ID( TT_Face face, TT_UShort charmapIndex, TT_UShort* platformID, TT_UShort* encodingID ); Returns the platform ID and platform-specific encoding ID for the charmap numbered `charmapIndex' in the `face' object. The total number of character mapping tables can be found in the `num_CharMaps' field in the structure returned by TT_Get_Face_Property(). .................................................................. TT_Get_CharMap( TT_Face face, TT_UShort charmapIndex, TT_CharMap* charMap ); Returns a handle for the character map number `charmapIndex' of `face'. The handle is placed in `*charMap' and can be used later for fast lookup with the TT_Char_Index() API function. Charmap objects are automatically destroyed when their face object is destroyed. .................................................................. TT_UShort TT_Char_Index( TT_CharMap charMap, ^^^^^^^^^ TT_UShort charCode ); Applies a charMap to translate `charCode' into a glyph index that can be used to load and address a glyph in the TrueType file. In case of error, the undefined glyph (index 0) is returned. The charmap handle can be obtained with TT_Get_CharMap(). .................................................................. int TT_Get_Name_Count( TT_Face face ); ^^^ Gets the number of name strings found in a face's name table. This function will return -1 if the face handle is invalid. IMPORTANT NOTE: ******** This function is deprecated. Get the number of name strings from the `num_Names' field in the structure returned by TT_Get_Face_Property() instead. .................................................................. TT_Get_Name_ID( TT_Face face, TT_UShort nameIndex, TT_UShort* platformID, TT_UShort* encodingID, TT_UShort* languageID, TT_UShort* nameID ); Returns the ID of a given name string, indexed by the number `nameIndex' in a given face. The name index ranges from 0 to `num_names' minus one; this value can be found in the structure returned by TT_Get_Face_Property(). Each string has a `platformID', `encodingID', `languageID' and `nameID', as defined by the TrueType specification. The platformID is typically in the range [0,3]. Some font files have unusual name table entries; these can be detected from their platformID which is larger than 3. .................................................................. TT_Get_Name_String( TT_Face face, TT_UShort nameIndex, TT_String** stringPtr, TT_UShort* length ); Returns a name string's address and length. Note that an invalid name table entry always returns NULL for `stringPtr' and zero for `length'. NOTE 1: The string belongs to the face object and should not be written to or freed by the client application. NOTE 2: The library does not care about endianess here! If you are using a little-endian machine and you have to interpret the string bytes as 16-bit-wide characters (e.g. Unicode encoded), you must byte-swap the data because 16-bit data is stored as big-endian in TrueType fonts, and FreeType reads in the whole name table bytewise. .................................................................. TT_Get_Font_Data( TT_face face, TT_Long tag, TT_Long offset, void* buffer, TT_Long* length ); Gets font or table data. Similar to the GetFontData() API of the Windows world. You can use the macro MAKE_TT_TAG() to generate TrueType table tags from character descriptions, like MAKE_TT_TAG( 'e', 'b', 'l', 'c' ) Use the value 0 instead for `tag' if you want to access the whole font file. `offset' specifies the starting offset in the table (or the offset in the file if tag == 0), `buffer' the address of target buffer. Depending on the value of length, various actions are performed. If `length' is NULL, the whole table will be loaded. An error will be returned if `offset' is not 0. If `*length' is zero, TT_Get_Font_Data() exits immediately, returning only the length of the given table (in the variable `length'), or of the font file, depending on the value of `tag'. Finally, if `*length' is not zero, the next `length' bytes of the table (resp. the font) are loaded into an array pointed to by `buffer', starting at offset `offset'. Note that the `buffer' array must be large enough to hold `length' bytes. -------------------------------------------------------------------- -------------------------------------------------------------------- III. Error Messages =================== Most functions return an error code, typed to TT_Error. A return value of zero indicates no error. The error values are defined in the file `freetype.h'. In the following table, the prefix `TT_Err_' is omitted, e.g. `Ok' -> `TT_Err_Ok'. Error Unprefixed Error Code Macro Name Description ------------------------------------------------------------------ 0x0000 Ok Successful function call. Always 0! ----------------- high-level API error codes --------------------- The following error codes are returned by the high-level API to indicate an invalid client request. 0x0001 Invalid_Face_Handle An invalid face object handle was passed to an API function. 0x0002 Invalid_Instance_Handle An invalid instance object handle was passed to an API function. 0x0003 Invalid_Glyph_Handle An invalid glyph container handle was passed to an API function. 0x0004 Invalid_CharMap_Handle An invalid charmap handle was passed to an API function. 0x0005 Invalid_Result_Address An output parameter (a result) was given a NULL address in an API call. 0x0006 Invalid_Glyph_Index An invalid glyph index was passed to an API function. 0x0007 Invalid_Argument An invalid argument was passed to an API function. Usually, this means a simple out-of-bounds error. 0x0008 Could_Not_Open_File The pathname passed doesn't point to an existing or accessible file. 0x0009 File_Is_Not_Collection Returned by TT_Open_Collection while trying to open a file which isn't a collection. 0x000A Table_Missing The requested TrueType table is missing in the font file. 0x000B Invalid_Horiz_Metrics The font's HMTX table is invalid. Denotes a broken font. 0x000C Invalid_CharMap_Format A font's charmap entry has an invalid format. Some other entries may be valid though. 0x000D Invalid_PPem Invalid PPem values specified, i.e., you are accessing a scaled glyph without having called TT_Set_Instance_CharSize() or TT_Set_Instance_PixelSizes(). 0x0010 Invalid_File_Format The file isn't a TrueType font or collection. 0x0020 Invalid_Engine An invalid engine handle was passed to one of the API functions. 0x0021 Too_Many_Extensions The client application is trying to initialize too many extensions. The default max extensions number is 8 (this value can be changed at compile time). 0x0022 Extensions_Unsupported This build of the engine doesn't support extensions. 0x0023 Invalid_Extension_Id This error indicates that the client application is trying to use an extension that has not been initialized yet. 0x0080 Max_Profile_Missing The max profile table is missing. => broken font file 0x0081 Header_Table_Missing The font header table is missing. => broken font file 0x0082 Horiz_Header_Missing The horizontal header is missing. => broken font file 0x0083 Locations_Missing The locations table is missing. => broken font file 0x0084 Name_Table_Missing The name table is missing. => broken font file 0x0085 CMap_Table_Missing The character encoding tables are missing. => broken font file 0x0086 Hmtx_Table_Missing The hmtx table is missing. => broken font file 0x0087 OS2_Table_Missing The OS/2 table is missing. Mac fonts doesn't have it. 0x0088 Post_Table_Missing The PostScript table is missing. => broken font file 0x0089 Glyf_Table_Missing The glyph table is missing. => broken font file ----------------- memory component error codes ------------------- 0x0100 Out_Of_Memory An operation couldn't be performed due to memory exhaustion. ----------------- file component error codes --------------------- 0x0200 Invalid_File_Offset Trying to seek to an invalid portion of the font file. Denotes a broken file. 0x0201 Invalid_File_Read Trying to read an invalid portion of the font file. Denotes a broken file. 0x0202 Invalid_Frame_Access Trying to frame an invalid portion of the font file. Denotes a broken file. ----------------- glyph loader error codes ----------------------- These errors are produced by the glyph loader. They denote an invalid glyph record within the font file. 0x0300 Too_Many_Points The glyph has too many points to be valid for its font file. 0x0301 Too_Many_Contours The glyph has too many contours to be valid for its font file. 0x0302 Invalid_Composite_Glyph A composite glyph's description is broken. 0x0303 Too_Many_Ins The glyph has too many instructions to be valid for its font file. ----------------- byte-code interpreter error codes -------------- These error codes are produced by the TrueType byte-code interpreter. They usually indicate a broken font file or a broken glyph within a font. 0x0400 Invalid_Opcode Found an invalid opcode in a TrueType byte-code stream. 0x0401 Too_Few_Arguments An opcode was invoked with too few arguments on the stack. 0x0402 Stack_Overflow The interpreter's stack has been filled up and operations can't continue. 0x0403 Code_Overflow The byte-code stream runs out of its valid bounds. 0x0404 Bad_Argument A function received an invalid argument. 0x0405 Divide_By_Zero A division by 0 operation was queried by the interpreter program. 0x0406 Storage_Overflow The program tried to access data outside of its storage area. 0x0407 Cvt_Overflow The program tried to access data outside of its control value table. 0x0408 Invalid_Reference The program tried to reference an invalid point, zone, or contour. 0x0409 Invalid_Distance The program tried to use an invalid distance. 0x040A Interpolate_Twilight The program tried to interpolate twilight points. 0x040B Debug_Opcode The now invalid `debug' opcode was found in the byte-code stream. 0x040C ENDF_In_Exec_Stream A misplaced ENDF was encountered in the byte-code stream. 0x040D Out_Of_CodeRanges The program tried to allocate too much code ranges (this is really an engine internal error that should never happen). 0x040E Nested_DEFS Nested function definitions encountered. 0x040F Invalid_CodeRange The program tried to access an invalid code range. 0x0410 Invalid_Displacement The program tried to use an invalid displacement. 0x0411 Execution_Too_Long In order to get rid of `poison' fonts, the interpreter produces this error if more than one million opcodes have been interpreted in a single glyph program. This detects infinite loops softly. ----------------- internal failure error codes ------------------- These error codes are produced if an incoherent library state has been detected. All of these reflect a severe bug in the engine (or a severe memory corruption due to massive overwrites by your application into the library's data)! If you do encounter a font that makes one of the test programs produce such an error, please report it! 0x0500 Nested_Frame_Access 0x0501 Invalid_Cache_List 0x0502 Could_Not_Find_Context 0x0503 Unlisted_Object ----------------- scan-line converter error codes ---------------- These error codes are produced by the raster component. They indicate that an outline structure was incoherently set up, or that you are trying to render a horribly complex glyph. They should be _extremely_ rare, however. 0x0600 Raster_Pool_Overflow Render pool overflow. This should never happen in this release. 0x0601 Raster_Negative_Height A negative height was produced. 0x0602 Raster_Invalid_Value The outline data wasn't set properly. Check that: points >= endContours[contours] 0x0603 Raster_Not_Initialized You did not call TT_Init_FreeType()! --- end of apiref.txt ---