summaryrefslogtreecommitdiff
path: root/Build/source/libs/freetype/freetype-1.5/docs/apiref.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/libs/freetype/freetype-1.5/docs/apiref.txt')
-rw-r--r--Build/source/libs/freetype/freetype-1.5/docs/apiref.txt1918
1 files changed, 0 insertions, 1918 deletions
diff --git a/Build/source/libs/freetype/freetype-1.5/docs/apiref.txt b/Build/source/libs/freetype/freetype-1.5/docs/apiref.txt
deleted file mode 100644
index b40e66d93d1..00000000000
--- a/Build/source/libs/freetype/freetype-1.5/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 ---