diff options
Diffstat (limited to 'Build/source/libs/freetype/docs/apiref.txt')
-rw-r--r-- | Build/source/libs/freetype/docs/apiref.txt | 1918 |
1 files changed, 0 insertions, 1918 deletions
diff --git a/Build/source/libs/freetype/docs/apiref.txt b/Build/source/libs/freetype/docs/apiref.txt deleted file mode 100644 index b40e66d93d1..00000000000 --- a/Build/source/libs/freetype/docs/apiref.txt +++ /dev/null @@ -1,1918 +0,0 @@ - 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 - conflict of names 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 types defined in the core FreeType API. - Their exact definition can be found in the file `freetype.h' which - should be included in 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_Int - - A signed type, either 16-bit or 32-bit, whichever is the most - efficient for the target platform. - - .................................................................. - - 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' denotes a 2-bit signed integer value to which the - positive fractional part `f' should always 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 interpretation 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 measured in notional font units - when the glyph has been 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 represented from now on as a class in itself, with - their own API. - - This structure is used to describe a vectorial glyph - representation to the rasterizer. It consists of several fields - as 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 called `points'. The `flags' array holds a flag - for each point 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 indices: - - The `n_contours' field gives the number of contours, while the - `contours' array holds the indices of each contour's last - point. Note that the first contour always begins at point 0. - - Hence, `contours[0]' holds the index of the last point of the - first contour. The second contour starts at point number - `contours[0]+1', and ends at 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 greater 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 which method applies 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 more 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 while executing TT_Done_FreeType(), they must be - explicitly discarded 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, applicable for - either horizontal or vertical layout. The values are expressed - in fractional pixels (26.6 format) if scaling was active, - otherwise in FUnits. - - The main idea was to accomodate vertical text layouts by - eradicating the two explicit `leftSideBearing' and - `advanceWidth' names. - - The interpretation of the fields varies with the text layout: - - bearingX: Also known as the `left side bearing'. In - 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 in horizontal metrics, otherwise the - horizontal distance. - - 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 conventions inherent to 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 it is not - necessary to increase the pen position by `bearingX' and/or - `bearingY' before writing a glyph. Text output can be - performed with simple lines such as: - - 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 - } - - For an example see the file `test/ftstring.c'. - - NOTE 2: - - This structure has changed from the beta version of FreeType. - - NOTE 3: - - FreeType only implements 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 notional units (in funits) in 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 specify a target bitmap (or pixmap) - for 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! - - Usually, 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', otherwise the flow is going - `up', and the value is `TT_Flow_Up'. - - To cite 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_Hdmx - - This structure is used to hold the font's horizontal device - metrics. Its layout and meaning are defined in the in the - `hdmx' section of the TrueType specification. - - .................................................................. - - 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 and horizontal header, the OS/2 - and PostScript tables, and the horizontal device metrics. - - 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_Hdmx* hdmx; /* TrueType hdmx 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_Done_Instance(), - TT_Set_Instance_CharSizes(), 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_Done_Glyph(), TT_Load_Glyph(), - TT_Get_Glyph_Metrics(), TT_Get_Glyph_Big_Metrics(), - TT_Get_Glyph_Outline(), TT_Get_Glyph_Bitmap(), - TT_Get_Glyph_Pixmap() - - .................................................................. - - TT_CharMap - - This type defines a handle used to reference a charMap object. - A charMap is an object owning the tables needed to perform the - mapping from characters code to glyphs numbers. A charMap is - always created from a valid face object, and is destroyed with - it by the engine. - - See also: - - TT_Get_CharMap(), TT_Char_Index(). - - .................................................................. - - 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. - - Call this function after TT_Set_Instance_Resolutions(). - - .................................................................. - - 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. - - Call this function after TT_Set_Instance_Resolutions(). - - .................................................................. - - 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! - - Call this function after TT_Set_Instance_Resolutions(). - - .................................................................. - - 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_Engine engine, - 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_Engine engine, - 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_ULong 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. - - Note: Since FT 1.5, the `charCode' is an unsigned long instead - of an unsigned short. - - 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. - - 0x0011 Invalid_Vert_Metrics The font's VMTX table is invalid. - Denotes a broken font. - - 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. - - 0x0030 No_Vertical_Data There is no vertical data, but - you are requesting it. Instead, - call TT_Get_Face_Metrics() with - NULL pointers for `topBearings' - and `heights'. - - 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. - Some Mac fonts don'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 --- |