diff options
Diffstat (limited to 'Build/source/libs/freetype/freetype-1.5/docs/apirefx.txt')
-rw-r--r-- | Build/source/libs/freetype/freetype-1.5/docs/apirefx.txt | 1223 |
1 files changed, 0 insertions, 1223 deletions
diff --git a/Build/source/libs/freetype/freetype-1.5/docs/apirefx.txt b/Build/source/libs/freetype/freetype-1.5/docs/apirefx.txt deleted file mode 100644 index 19bc7d9feb3..00000000000 --- a/Build/source/libs/freetype/freetype-1.5/docs/apirefx.txt +++ /dev/null @@ -1,1223 +0,0 @@ - The FreeType Engine - - Extension Library Reference - - - ----------------------------------- - - - Table of Contents: - - I. Engine extensions - 1. kerning (ftxkern) - 2. PostScript names (ftxpost) - 3. TrueType Open (ftxopen) - a. The `BASE' table (baseline data) - b. The `GDEF' table (glyph definitions) - c. The `GPOS' table (glyph positions) - d. The `GSUB' table (glyph substitions) - e. The `JSTF' table (justification data) - f. auxiliary functions - 4. embedded bitmaps (ftxsbit) - - II. API extensions - 1. cmap iteration (ftxcmap) - 2. internationalized error messages (ftxerr18) - 3. access to the `gasp' table (ftxgasp) - 4. fast retrieval of glyph widths and heights (ftxwidth) - - III. Error codes - - - -------------------- - - -Please read the file `user.txt' for an introduction into FreeType's -extension mechanism and the difference between engine and API -extensions. - - -I. Engine extensions -==================== - -To use engine extensions you have to compile the library with the -macro TT_CONFIG_OPTION_EXTEND_ENGINE. By default, this macro is set -and all engine extensions are linked to the FreeType library. - - - 1. kerning (ftxkern) - -------------------- - - TT_Init_Kerning_Extension( TT_Engine engine ) - - Initializes the kerning extension for a given engine. This must - be called just after the engine creation, and before any face - object allocation. Example: - - TT_Init_FreeType( &engine ); - TT_Init_Kerning_Extension( engine ); - - .................................................................. - - TT_Get_Kerning_Directory( TT_Face face, - TT_Kerning* directory ) - - Queries the kerning directory found in a face object. If no - kerning table is found in the TrueType file, the error - TT_Err_Table_Is_Missing will be returned. - - You can access the subtables through the pointers of the - directory. However, by default, the directory is only loaded if - a face object is created. You must load the subtables that - interest you with a call to TT_Load_Kerning_Table(). - - The layout of all kerning structures is defined in the file - `lib/extend/ftxkern.h'. Formats 0 and 2 (as defined in the - Microsoft TrueType specification) are exposed by this API. - - NOTE: - - This function must be called after the kerning extension has - been initialized. - - .................................................................. - - TT_Load_Kerning_Table( TT_Face face, - TT_UShort kernIndex ) - - Loads the kerning subtable number `kern_index' into memory. The - subtable can be accessed through the pointers provided by the - kerning directory, obtained from a call to the function - TT_Get_Kerning_Directory(). - - Note that the interpretation of the kerning data is left to the - client application. Read the TrueType specification for more - information on kerning encoding. - - NOTE 1: - - This function must be called after the kerning extension were - initialized. - - NOTE 2: - - An example can be found in the file `test/ftstrtto.c'. - - -==================================================================== - - - 2. PostScript names (ftxpost) - ----------------------------- - - TT_Init_Post_Extension( TT_Engine engine ) - - Initializes the PostScript name extension to load the PostScript - glyph names given in the `post' table. This must be called just - after creation of the engine, and before any face object - allocation. See description of TT_Get_PS_Name() for an example. - - .................................................................. - - TT_Load_PS_Names( TT_Face face, - TT_Post* post ) - - Loads the PostScript glyph names into memory. This must be done - before TT_Get_PS_Name() is called. In case of error, either - TT_Err_Invalid_Post_Table or TT_Err_Invalid_Post_Table_Format is - returned. See description of TT_Get_PS_Name() for an example. - - .................................................................. - - TT_Get_PS_Name( TT_Face face, - TT_UShort index, - TT_String** PSname ) - - Get the PostScript glyph name for a given glyph index. A - pointer to the name is returned in `PSname'. Example: - - ... - TT_Post post; - char* PSname; - - ... - TT_Init_Post_Extension( engine ); - TT_Load_PS_Names( face, &post ); - - ... - TT_Get_PS_Name( face, index, &PSname ); - - - NOTE 1: - - You must not alter the PostScript glyph name string returned - in `PSname'. - - NOTE 2: - - Some standard names sometimes present some variations, as: - - Omega vs. Ohm - Delta vs. increment - macron vs. overscore - mu vs. mu1 - periodcentered vs. middot - - We always return the first listed name, which correspond to - the last version of the TrueType specifications (which did - vary in the past on this respect). You may have to adjust the - source (in lib/extend/ftxpost.c) in order to interface with - some old applications. - - -==================================================================== - - - 3. TrueType Open (ftxopen) - -------------------------- - - Please note that TrueType Open specific error codes have the - prefix `TTO_Err_' instead of `TT_Err_'. - - a. The `BASE' table (baseline data) - - Not yet supported. - - b. The `GDEF' table (glyph definitions) - - TT_Init_GDEF_Extension( TT_Engine engine ) - - Initializes the GDEF extension to load the glyph definition - data given in the `GDEF' table. This must be called just - after creation of the engine, and before any face object - allocation. See the file `ftstrtto.c' for an example. - - ................................................................ - - TT_Load_GDEF_Table( TT_Face face, - TTO_GDEFHeader* gdef ) - - Loads the GDEF table into `gdef' for a given face `face'. - This must be done before any queries about glyph properties - with TT_GSUB_Get_Property(). Returns TT_Err_Table_Missing if - there is no GDEF table in the font. - - ................................................................ - - TT_GDEF_Get_Glyph_Property( TTO_GDEFHeader* gdef, - TT_UShort glyphID, - TT_UShort* property ) - - Use this function to get glyph properties in the variable - `property' for the glyph with index `glyphID' stored in the - `gdef' table. This data is essential for many fonts to - correctly apply contextual substitution (both GSUB and GPOS). - As a special case, zero is assigned to `property' if `gdef' is - NULL or the glyph has no special glyph property assigned to - it. The other return values of `property' are TTO_BASE, - TTO_LIGATURE, TTO_MARK, and TTO_COMPONENT; you can directly - apply the `LookupFlag' mask to check for certain properties: - - TTO_GDEFHeader* gdef; - TTO_Lookup* lo; - TT_UShort glyph_ID; - TT_UShort p; - - - TT_GDEF_Get_Property( gdef, glyph_ID, &p ); - - if ( p & lo->LookupFlag ) - return TTO_Err_Not_Covered; - - Usually, you don't need to take care of glyph properties by - yourself since TT_GSUB_Apply_String() will do this for you by - calling TT_GDEF_Get_Property(). - - Some fonts need GDEF-like data even if no GDEF table is - provided (for example, the Arabic script needs information - which glyphs are base glyphs and which are mark glyphs). In - such cases, you should use TT_GDEF_Build_ClassDefinition() to - build the necessary structures so that TT_GDEF_Get_Property() - returns meaningful values. - - See also TT_Load_GSUB_Table() and TT_Load_GPOS_Table(). - - ................................................................ - - TT_GDEF_Build_ClassDefinition( TTO_GDEFHeader* gdef, - TT_UShort num_glyphs, - TT_UShort glyph_count, - TT_UShort* glyph_array, - TT_UShort* class_array ) - - Fills a `gdef' structure with data to make - TT_GDEF_Get_Property() work in case no GDEF table is - available. `num_glyphs' is the number of glyphs in the font. - - `glyph_count' is the number of glyphs resp. class values (as - specified in the GDEF specification) given in the arrays - `glyph_array' and `class_array', respectively. The glyph - indices in `glyph_array' must be all different and sorted in - ascending order; the function expects that glyph index - `glyph_array[n]' has its class value in `class_array[n]'. - - Note that mark attach classes as defined in OpenType 1.2 are - not supported for constructed GDEF tables. - - See `arabic.c' for an example. - - - c. The `GPOS' table (glyph positionings) - - For glyph positioning, a data object of type TTO_GPOS_Data is - used. The `x_pos' and `y_pos' fields contain offsets to be - added to the glyph's position; `x_advance' and `y_advance' hold - values to be added to the horizonal and vertical advance widths, - respectively. If `new_advance' is TRUE, `x_advance' and - `y_advance' are absolute, i.e., they won't be added to the - original glyph's value but rather replace them. All offset - values are given as fractional pixels. - - To position marks, `back' holds the number of glyphs to go back - for applying `x_pos' and `y_pos' (advance values are always zero - in this case). If the target glyph itself has a non-zero `back' - value, it is necessary to repeat this process -- the offset - values have to be accumulated then. - - As a consequence, it is necessary to track glyph positions. - - struct TTO_GPOS_Data_ - { - TT_Pos x_pos; - TT_Pos y_pos; - TT_Pos x_advance; - TT_Pos y_advance; - TT_UShort back; - TT_Bool new_advance; - }; - - typedef struct TTO_GPOS_Data_ TTO_GPOS_Data; - - Here some pseudo code to demonstrate the needed algorithm: - - TT_GSUB_Apply_String() - TT_GPOS_Apply_String() - collect_glyph_positions() /* don't advance for marks */ - /* take care of kerning */ - /* apply GPOS data */ - - for all glyphs do - { - if `back' == 0 - render_glyph_at_current_position() - else - { - search_base_glyph() - render_glyph_at_base_glyph_position() - } - } - - A real example can be found in ftstrtto.c. Please note that the - code in this test program is not optimized; using a glyph cache - could improve speed considerably. - - Contrary to GSUB handling, GPOS needs data from the glyphs - itself. Some formats of anchor tables (used e.g. to attach mark - glyphs to base glyphs) and device tables refer to contour - points, and cursive connections need advance values and - dimensions of the glyphs if used vertically (vertical cursive - connections have not been implemented yet -- this is the only - omission of GPOS support currently). - - Two hooks are defined to get this data: TTO_GlyphFunction and - TTO_MMFunction. The former defaults to TT_Load_Glyph() and - should be replaced with a similar function which caches data if - necessary, the latter (to access data from Multiple Master - fonts) defaults to an error message. - - GPOS handling must always be done *after* GSUB handling! - - ................................................................ - - TT_Init_GPOS_Extension( TT_Engine engine ) - - Initializes the GPOS extension to load the glyph positioning - data given in the `GPOS' table. This must be called just - after creation of the engine, and before any face object - allocation. See the files `ftstrtto.c' and `ftdump.c' for - detailed examples. - - ................................................................ - - TT_Load_GPOS_Table( TT_Face face, - TTO_GPOSHeader* gpos, - TTO_GDEFHeader* gdef ) - - Loads the GPOS table into `gpos' for a given face `face'. - This must be done before any queries about or selection of - scripts, languages, and features. Returns - TT_Err_Table_Missing if there is no GPOS table in the font. - - `gdef' should contain a pointer to an associated GDEF table, - either a native one loaded with TT_Load_GDEF_Table() or - emulated with TT_GDEF_Build_ClassDefinition(). If `gdef' is - set to NULL, no GDEF data will be used. - - ................................................................ - - TT_GPOS_Select_Script( TTO_GPOSHeader* gpos, - TT_ULong script_tag, - TT_UShort* script_index ) - - This function sets the script index of a given script tag - `script_tag' in the variable `script_index' for the GPOS table - `gpos'. Returns TTO_Err_Not_Covered if the script tag cannot - be found. The available script tags can be queried with the - function TT_GPOS_Query_Scripts(). - - ................................................................ - - TT_GPOS_Select_Language( TTO_GPOSHeader* gpos, - TT_ULong language_tag, - TT_UShort script_index, - TT_UShort* language_index, - TT_UShort* req_feature_index ) - - This function sets the language index of a given language tag - `language_tag' and script index `script_index' in the variable - `language_index' for the GPOS table `gpos'. Returns - TTO_Err_Not_Covered if the language tag cannot be found. The - available language tags can be queried with the function - TT_GPOS_Query_Languages(). - - Additionally, the index of the required feature for this - language system is returned in `req_feature_index'; it must be - later registered for use with TT_GPOS_Add_Feature(). - - ................................................................ - - TT_GPOS_Select_Feature( TTO_GPOSHeader* gpos, - TT_ULong feature_tag, - TT_UShort script_index, - TT_UShort language_index, - TT_UShort* feature_index ) - - This function sets the feature index of a feature tag - `feature_tag', script index `script_index', and language index - `language_index' in the variable `feature_index' for the GPOS - table `gpos'. Returns TTO_Err_Not_Covered if the feature tag - cannot be found. The available feature tags can be queried - with the function TT_GPOS_Query_Features(). Setting - language_index to 0xFFFF selects the default language system. - - ................................................................ - - TT_GPOS_Query_Scripts( TTO_GPOSHeader* gpos, - TT_ULong** script_tag_list ) - - Returns the available script tags for a given GPOS table - `gpos' in the array `script_tag_list'. The array can be later - deallocated with free(). - - ................................................................ - - TT_GPOS_Query_Languages( TTO_GPOSHeader* gpos, - TT_UShort script_index, - TT_ULong** language_tag_list ) - - Returns the available language tags for a given GPOS table - `gpos' and script index `script_index' in the array - `language_tag_list'. The array can be later deallocated with - free(). - - ................................................................ - - TT_GPOS_Query_Features( TTO_GPOSHeader* gpos, - TT_UShort script_index, - TT_UShort language_index, - TT_ULong** feature_tag_list ) - - Returns the available feature tags for a given GPOS table - `gpos', script index `script_index', and language index - `language_index' in the array `feature_tag_list'. If language - index is set to 0xFFFF, the values for the default language - system are returned. The array can be later deallocated with - free(). - - ................................................................ - - TT_GPOS_Add_Feature( TTO_GPOSHeader* gpos, - TT_UShort feature_index, - TT_UShort property ) - - To prepare a call to TT_GPOS_Apply_String() which should - process a given feature with index `feature_index' and the - property `property', you must use this function. Its task is - to mark the lookup tables used by the feature for further - processing. - - `property' defines a relationship between the input string - object and the specific feature. The client must handle this - variable as a bit field, i.e., up to 16 user properties can be - defined. If `property' is set to ALL_GLYPHS (0xFFFF, the only - predefined value), or if the input string object has no set - bits in the `properties' field, the feature applies to all - glyphs. If bit `x' is set in `property', the feature applies - only to glyphs which have bit `x' not set in glyph's - `properties' field in the input string object. See - TT_GPOS_Apply_String() for an example. - - Returns TT_Err_Invalid_Argument in case of error. - - ................................................................ - - TT_GPOS_Clear_Features( TTO_GPOSHeader* gpos ) - - Clears the list of used features and properties. No lookup - tables will be processed. - - ................................................................ - - TT_GPOS_Register_Glyph_Function( TTO_GPOSHeader* gpos, - TTO_GlyphFunction gfunc ); - - Installs a function `gfunc' which loads a glyph. Its - parameters are the same as in a call to TT_Load_Glyph() -- if - no glyph loading function will be registered with - TTO_GPOS_Register_Glyph_Function(), TT_Load_Glyph() will be - called indeed. The purpose of this function is to provide a - hook for caching glyph outlines and sbits (using the - instance's generic pointer to hold the data). - - If for some reason no outline data is available (e.g. for an - embedded bitmap glyph), _glyph->outline.n_points should be set - to zero. _glyph can be computed with - - _glyph = HANDLE_Glyph( glyph ) - - `gfunc' is defined as - - typedef TT_Error - (*TTO_GlyphFunction)(TT_Instance instance, - TT_Glyph glyph, - TT_UShort glyphIndex, - TT_UShort loadFlags ); - - ................................................................ - - TT_GPOS_Register_MM_Function( TTO_GPOSHeader* gpos, - TTO_MMFunction mmfunc, - void* data ); - - Installs a function `mmfunc' which accesses the PostScript - interpreter. Multiple Master fonts need this interface to - convert a metric ID (as stored in an OpenType font version 1.2 - or higher) into a metric value. - - `data' points to a user-defined structure which will not be - used by the GPOS extension itself. It is passed directly to - `mmfunc', which is defined as - - typedef TT_Error - (*TTO_MMFunction)(TT_Instance instance, - TT_UShort metric_id, - TT_Pos* metric_value, - void* data ); - - `metric_value' must be returned as a scaled value (but - shouldn't be rounded). - - ................................................................ - - TT_GPOS_Apply_String( TT_Instance instance, - TT_Glyph glyph, - TTO_GPOSHeader* gpos, - TT_Bool load_flags, - TTO_GSUB_String* in, - TTO_GPOS_Data** out, - TT_Bool dvi, - TT_Bool r2l ) - - This is the very function which handles glyph positioning - according to the features set up with TT_GPOS_Add_Feature(), - using both GPOS and GDEF data (if defined). A TTO_GSUB_String - object `in' (see the next section for a complete description) - and a TTO_GPOS_Data object array pointer `out' (as described - above) are taken for input and output; after successful - excecution, the GPOS data can been found in `out'. Note that - the `out' array has in->length elements. - - `instance', `glyph', and `load_flags' are directly forwarded - to the glyph function registered with - TTO_GPOS_Register_Glyph_Function(). Note that glyphs are - always loaded as scaled. - - If `dvi' is TRUE, `glyph' is ignored completely. Use this to - get device independent positioning values. - - The parameter `r2l' should be set to TRUE if you process a - right-to-left script like Arabic. It is used for cursive - connections only to compute correct advance values. - - Example: - - /* We assume that the feature `xxxx' has index 5, and */ - /* feature `yyyy' has index 8, applying only to glyphs */ - /* with the property `FINAL_GLYPHS' set (0x1000 is an */ - /* ad-hoc value just for this example). */ - - /* The order of calls to TT_GPOS_Add_Feature() is not */ - /* significant. */ - - #define FINAL_GLYPHS 0x1000 - - TTO_GPOS_DATA* gd = NULL; - - - TT_GPOS_Clear_Features( &gpos ); - TT_GPOS_Add_Feature( &gpos, 8, FINAL_GLYPHS ); - TT_GPOS_Add_Feature( &gpos, 5, ALL_GLYPHS ); - - TT_GSUB_Apply_String( &gsub, &in, &out ); - TT_GPOS_Apply_String( instance, glyph, &gpos, - TTLOAD_HINT_GLYPH, - &out, &gd, 0, 0 ); - - You must initialize the `gd' pointer to NULL; allocation - necessary for the `gd' array will be handled automatically. - If necessary, you can use free() to deallocate `gd'. - - - d. The `GSUB' table (glyph substitions) - - For glyph substitution, a string object of type TTO_GSUB_String - is used. The field `length' holds the length of the string, - `pos' points to the actual position in the glyph string `string' - (for input strings) resp. the position where the substituted - glyphs should be placed at (for output strings). - - Within the `properties' array (which must always have the same - length as `string' if set), you can define properties for glyphs - -- `string[n]' is associated with `properties[n]'. The idea is - that some features apply to specific glyphs only. As an - example, the `fina' feature for Arabic applies only to glyphs - which appear at the end of a word (strictly speaking, this - feature is used only for glyphs which have a `final' property; - such glyphs can occur in the middle of a word also under certain - circumstances which is dependent on Arabic script rules). The - relationship between properties and features can be set up with - the function TT_GSUB_Add_Feature(). If `properties' is set to - NULL, all selected features apply to all glyphs in the given - string object. If `properties' is non-NULL, the elements of the - array are treated as bit fields. A set flag means that the - corresponding feature (as set with the TT_GSUB_Add_Feature() - function) should not be applied to the particular glyph. As a - consequence, a zero value for these 16 bits means that all - features should be applied, and a value of 0xFFFF implies that - no feature at all should be used for the glyph. - - The field `allocated' is for internal use only and must not be - modified. If its value is larger than zero, you should use - free() to deallocate the memory used by `string' (and - `properties' if set) in case you want to destroy a - TTO_GSUB_String object (memory for `string' and `properties' is - allocated automatically e.g. by TT_GSUB_Apply_String() for - output string objects). - - struct TTO_GSUB_String_ - { - TT_ULong length; - TT_ULong pos; - TT_ULong allocated; - TT_UShort* string; - TT_UShort* properties; - }; - - typedef struct TTO_GSUB_String_ TTO_GSUB_String; - - Note that the `string' field must contain glyph indices, not - character codes. - - For initializing an input string object, you should set the - `length', `string', and `properties' fields (the last one only - if necessary) to appropriate values. `pos' has to be set to the - position where the substitution lookups should start (usually - zero). The `allocated' field will be ignored. - - For initializing an output string object, all fields (except - `length' which will be ignored) must be set to zero. If you - want to reuse the object, set `pos' to the position where the - substituted glyphs should be placed at (usually zero), but don't - touch the `allocated', `string', and `properties' fields. - - ................................................................ - - TT_Init_GSUB_Extension( TT_Engine engine ) - - Initializes the GSUB extension to load the glyph substitution - data given in the `GSUB' table. This must be called just - after creation of the engine, and before any face object - allocation. See the files `ftstrtto.c' and `ftdump.c' for - detailed examples. - - ................................................................ - - TT_Load_GSUB_Table( TT_Face face, - TTO_GSUBHeader* gsub, - TTO_GDEFHeader* gdef ) - - Loads the GSUB table into `gsub' for a given face `face'. - This must be done before any queries about or selection of - scripts, languages, and features. Returns - TT_Err_Table_Missing if there is no GSUB table in the font. - - `gdef' should contain a pointer to an associated GDEF table, - either a native one loaded with TT_Load_GDEF_Table() or - emulated with TT_GDEF_Build_ClassDefinition(). If `gdef' is - set to NULL, no GDEF data will be used. - - ................................................................ - - TT_GSUB_Select_Script( TTO_GSUBHeader* gsub, - TT_ULong script_tag, - TT_UShort* script_index ) - - This function sets the script index of a given script tag - `script_tag' in the variable `script_index' for the GSUB table - `gsub'. Returns TTO_Err_Not_Covered if the script tag cannot - be found. The available script tags can be queried with the - function TT_GSUB_Query_Scripts(). - - ................................................................ - - TT_GSUB_Select_Language( TTO_GSUBHeader* gsub, - TT_ULong language_tag, - TT_UShort script_index, - TT_UShort* language_index, - TT_UShort* req_feature_index ) - - This function sets the language index of a given language tag - `language_tag' and script index `script_index' in the variable - `language_index' for the GSUB table `gsub'. Returns - TTO_Err_Not_Covered if the language tag cannot be found. The - available language tags can be queried with the function - TT_GSUB_Query_Languages(). - - Additionally, the index of the required feature for this - language system is returned in `req_feature_index'; it must be - later registered for use with TT_GSUB_Add_Feature(). - - ................................................................ - - TT_GSUB_Select_Feature( TTO_GSUBHeader* gsub, - TT_ULong feature_tag, - TT_UShort script_index, - TT_UShort language_index, - TT_UShort* feature_index ) - - This function sets the feature index of a feature tag - `feature_tag', script index `script_index', and language index - `language_index' in the variable `feature_index' for the GSUB - table `gsub'. Returns TTO_Err_Not_Covered if the feature tag - cannot be found. The available feature tags can be queried - with the function TT_GSUB_Query_Features(). Setting - language_index to 0xFFFF selects the default language system. - - ................................................................ - - TT_GSUB_Query_Scripts( TTO_GSUBHeader* gsub, - TT_ULong** script_tag_list ) - - Returns the available script tags for a given GSUB table - `gsub' in the array `script_tag_list'. The array can be later - deallocated with free(). - - ................................................................ - - TT_GSUB_Query_Languages( TTO_GSUBHeader* gsub, - TT_UShort script_index, - TT_ULong** language_tag_list ) - - Returns the available language tags for a given GSUB table - `gsub' and script index `script_index' in the array - `language_tag_list'. The array can be later deallocated with - free(). - - ................................................................ - - TT_GSUB_Query_Features( TTO_GSUBHeader* gsub, - TT_UShort script_index, - TT_UShort language_index, - TT_ULong** feature_tag_list ) - - Returns the available feature tags for a given GSUB table - `gsub', script index `script_index', and language index - `language_index' in the array `feature_tag_list'. If language - index is set to 0xFFFF, the values for the default language - system are returned. The array can be later deallocated with - free(). - - ................................................................ - - TT_GSUB_Add_Feature( TTO_GSUBHeader* gsub, - TT_UShort feature_index, - TT_UShort property ) - - To prepare a call to TT_GSUB_Apply_String() which should - process a given feature with index `feature_index' and the - property `property', you must use this function. Its task is - to mark the lookup tables used by the feature for further - processing. - - `property' defines a relationship between the input string - object and the specific feature. The client must handle this - variable as a bit field, i.e., up to 16 user properties can be - defined. If `property' is set to ALL_GLYPHS (0xFFFF, the only - predefined value), or if the input string object has no set - bits in the `properties' field, the feature applies to all - glyphs. If bit `x' is set in `property', the feature applies - only to glyphs which have bit `x' not set in glyph's - `properties' field in the input string object. See - TT_GSUB_Apply_String() for an example. - - Returns TT_Err_Invalid_Argument in case of error. - - ................................................................ - - TT_GSUB_Clear_Features( TTO_GSUBHeader* gsub ) - - Clears the list of used features and properties. No lookup - tables will be processed. - - ................................................................ - - TT_GSUB_Register_Alternate_Function( TTO_GSUBHeader* gsub, - TTO_AltFunction altfunc, - void* data ) - - Installs a callback function to handle alternate - substitutions. `data' is a generic pointer to a user-defined - structure which will be completely ignored by the ftxopen - extension. `altfunc' is a function pointer defined as - - typedef TT_UShort - (*TTO_AltFunction)(TT_ULong pos, - TT_UShort glyphID, - TT_UShort num_alternates, - TT_UShort* alternates, - void* data ); - - If TT_GSUB_Apply_String() encounters an alternate lookup while - processing the input string, it will call the function - `altfunc' to find out which alternate glyph it should use. - `pos' gives the position in the string, `glyphID' the glyph ID - of the glyph to be replaced with an alternate glyph, and - `num_alternates' the number of alternate glyphs in the - `alternates' array. A pointer to the user-defined `data' - structure is also available. `altfunc' must return an index - into `alternates'. - - If `altfunc' is NULL or if this function isn't called at all, - TT_GSUB_Apply_String() will always use the first alternate - glyph. - - Please note that theoretically an alternate lookup can happen - during any other lookup! For example, a lookup chain like - - single subst -> alternate subst -> ligature subst - - *is* possible (albeit rather unlikely). Thus be warned that - `pos' does not necessarily reflect the position of a glyph to - be displayed at all, nor does `glyphID' specifies a glyph - which will be in the final output string. - - ................................................................ - - TT_GSUB_Apply_String( TTO_GSUBHeader* gsub, - TTO_GSUB_String* in, - TTO_GSUB_String* out ) - - This is the very function which handles glyph substitution - according to the features set up with TT_GSUB_Add_Feature(), - using both GSUB and GDEF data (if defined). Two - TTO_GSUB_String objects `in' and `out' (as described above) - are taken for input and output; after successful excecution, - the converted glyph string can been found in `out', and - `out.length' gives the actual length of the output string - (counted from the begin of the array). - - Example: - - /* We assume that the feature `xxxx' has index 5, and */ - /* feature `yyyy' has index 8, applying only to glyphs */ - /* with the property `FINAL_GLYPHS' set (0x1000 is an */ - /* ad-hoc value just for this example). */ - - /* The order of calls to TT_GSUB_Add_Feature() is not */ - /* significant. */ - - #define FINAL_GLYPHS 0x1000 - - TT_GSUB_Clear_Features( &gsub ); - TT_GSUB_Add_Feature( &gsub, 8, FINAL_GLYPHS ); - TT_GSUB_Add_Feature( &gsub, 5, ALL_GLYPHS ); - - TT_GSUB_Apply_String( &gsub, &in, &out ); - - You must initialize both `in' and `out' structures; allocation - necessary for the `out' object will be handled automatically. - - In case you don't register a function to handle alternate - substitutions (GSUB lookup 3), always the first alternate - glyph will be used. See TT_GSUB_Register_Alternate_Function() - above for more details. - - - e. The `JSTF' table (justification data) - - Not yet supported. - - - f. auxiliary functions - - TT_GSUB_Add_String( TTO_GSUB_String* in, - TT_UShort num_in, - TTO_GSUB_String* out, - TT_UShort num_out, - TT_UShort* glyph_data, - TT_UShort component, - TT_UShort ligID ) - - This function copies `num_out' elements from `glyph_data' to - `out', advancing the array pointer in the `in' structure by - `num_in' elements, and in `out' by `num_out' elements. If the - string (resp. the properties) array in `out' is empty or too - small, it allocates resp. reallocates the string (and - properties) array. Finally, it sets the `length' field of - `out' equal to `pos' of the `out' structure. - - The properties (if defined) for all replaced glyphs are taken - from the glyph at position `in->pos'. - - If `component' is 0xFFFF, the value `in->component[in->pos]' - will be copied `num_out' times, otherwise `component' itself - will be used to fill `out->component'. - - If `ligID' is 0xFFFF, the value `in->lig_IDs[in->pos]' will be - copied `num_out' times, otherwise `ligID' itself will be used - to fill `out->ligIDs'. - - TT_GSUB_Add_String() is normally used in - TT_GSUB_Apply_String(); you will need it for the special case - to skip some glyphs (i.e., copy glyphs directly from the `in' - to the `out' object), bypassing a possible GSUB substitution. - - Here an example which copies one glyph: - - TT_GSUB_Add_String( in, 1, - out, 1, - &in->string[in->pos], - 0xFFFF, 0xFFFF ); - - -==================================================================== - - - 4. embedded bitmaps (ftxsbit) - ----------------------------- - - TT_Init_SBit_Extension( TT_Engine engine ) - - Initializes the embedded bitmap extension to load the bitmap - glyphs given in the various sbit tables: `EBLC', `bloc', `EBDT', - and `bdat' (`bloc' and `bdat' tables are only in Apple fonts; - the former is equivalent to `EBLC', the latter equivalent to - `EBDT'). This must be called just after creation of the engine, - and before any face object allocation. See description of - TT_Load_Glyph_Bitmap() for an example. - - .................................................................. - - TT_Get_Face_Bitmaps( TT_Face face, - TT_EBLC* eblc_table ) - - Loads the `EBLC' (resp. `bloc') table from a font file into the - `eblc_table' structure. Use this function for testing whether - embedded bitmaps are available or not. - - This function returns TT_Err_Table_Missing if the font contains - no embedded bitmaps. All fields in `eblc_table' will then be - set to 0. - - .................................................................. - - TT_New_SBit_Image( TT_SBit_Image** image ) - - Allocates a new embedded bitmap container, pointed to by - `image'. - - .................................................................. - - void TT_Done_SBit_Image( TT_SBit_Image* image ) - ^^^^ - - Releases the embedded bitmap container `image'. - - .................................................................. - - TT_Get_SBit_Strike( TT_Face face, - TT_Instance instance, - TT_SBit_Strike* strike ) - - Loads a suitable strike (i.e. bitmap sizetable) for the given - instance. Will return TT_Err_Invalid_PPem if there is no strike - for the current x_ppem and y_ppem values. - - .................................................................. - - TT_Load_Glyph_Bitmap( TT_Face face, - TT_Instance instance, - TT_UShort glyph_index, - TT_SBit_Image* bitmap ); - - Loads a glyph bitmap for a given glyph index `glyph_index' (in - face `face' and instance `instance') into `bitmap'. It calls - TT_Get_SBit_Strike() internally for checking the current x_ppem - and y_ppem values. - - This function returns an error if there is no embedded bitmap - for the glyph at the given instance. - - Example (omitting the error handling): - - ... - TT_SBit_Image* bitmap; - - ... - TT_Init_SBit_Extension( engine ); - TT_New_SBit_Image( &bitmap ); - ... - TT_Load_Glyph_Bitmap( face, instance, glyph_index, bitmap ); - - - --------------------------------------------------------------------- --------------------------------------------------------------------- - - - -II. API extensions -================== - -To use API extensions, simply compile the specific extension file -and link it to the library or your program. By default, all -extensions described below are linked to the library. - - - 1. cmap iteration (ftxcmap) - --------------------------- - - TT_Long TT_CharMap_First( TT_CharMap charMap, - ^^^^^^^ TT_UShort* glyph_index ) - - Returns the first valid character code in a given character map - `charMap'. Also returns the corresponding glyph index (in the - parameter `*glyph_index'). In case of failure, -1 is returned, - and `*glyph_index' is undefined. - - .................................................................. - - TT_Long TT_CharMap_Next( TT_CharMap charMap, - ^^^^^^^ TT_ULong last_char, - TT_UShort* glyph_index ) - - Returns the next valid character code in a given character map - `charMap' which follows `last_char'. Also returns the - corresponding glyph index (in the parameter `*glyph_index'). In - case of failure, -1 is returned, and `glyph_index' is undefined. - - .................................................................. - - TT_Long TT_CharMap_Last( TT_CharMap charMap, - ^^^^^^^ TT_UShort* glyph_index ) - - Returns the last valid character code in a given character map - `charMap'. Also returns the corresponding glyph index (in the - parameter `*glyph_index'). In case of failure, -1 is returned, - and `*glyph_index' is undefined. - - -==================================================================== - - - 2. internationalized error messages (ftxerr18) - ---------------------------------------------- - - This extension provides internationalized error strings from the - various error messages. It uses the `gettext' package if - available or returns English/American message strings if not. - Currently, the gettext package is only available on UNIX-like - systems like Linux (and on similarly inspired systems, like DJGPP - or MinGW); this means that for other platforms only English error - strings are returned. - - If the gettext package is found on your system, the configure - script automatically includes it by default. In case you don't - want to use it, or if you encounter some problems compiling this - file, try to disable nls support by configuring FreeType with - `./configure --disable-nls'. - - Please read the gettext info files for more information how to set - up your system for internationalized messages. A short - introduction is also given in the file `i18n.txt'. - - - TT_String* TT_ErrToString18( TT_Error i ) - ^^^^^^^^^^ - - This function returns an error string for a given error code - `i'. The type `TT_String' usually defaults to `char'; see - apiref.txt for more details. - - An example how to use this function (in connection with the - gettext interface) is given in test/ftdump.c or test/fterror.c. - - -==================================================================== - - - 3. access to the `gasp' table (ftxgasp) - --------------------------------------- - - The `gasp' table is currently loaded by the core engine, but the - standard API doesn't give access to it. - - - TT_Get_Face_Gasp_Flags( TT_Face face, - TT_UShort point_size, - TT_Bool* grid_fit, - TT_Bool* smooth_font ) - - This function returns for a given `point_size' the values of the - gasp flags `grid_fit' and `smooth_font'. The returned values - are booleans (where 0 = NO, and 1 = YES). - - Note that this function will return TT_Err_Table_Missing if the - font file doesn't contain any gasp table. - - -==================================================================== - - - 4. fast retrieval of glyph widths and heights (ftxwidth) - -------------------------------------------------------- - - This extension is used to parse the `glyf' table of a TrueType - file in order to extract the bounding box of a given range of - glyphs. - - The bounding box is then used to build font unit widths and - heights that are returned in two parallel arrays. - - This extension is needed by the FreeType/2 OS/2 Font Driver. - - - TT_Get_Face_Widths( TT_Face face, - TT_UShort first_glyph, - TT_UShort last_glyph, - TT_UShort* widths, - TT_UShort* heights ) - - Returns the widths (in array `widths') and heights (in array - `heights') of a glyph range which starts at `first_glyph' and - ends at `last_glyph'. All returned values are returned in font - units. If either `widths' or `heights' is set to a NULL - pointer, no data will be returned for that particular array. - - Note: TT_Get_Face_Widths() does *not* allocate the two arrays! - - - --------------------------------------------------------------------- --------------------------------------------------------------------- - - - -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 various extension header files (e.g. ftxkern.h). In the - following table, the prefix `TT_Err_' is omitted, e.g. `Ok' -> - `TT_Err_Ok'. - - - Error Unprefixed Error - Code Macro Name Description - ------------------------------------------------------------------ - - 0x0A00 Invalid_Kerning_Table_Format - An invalid kerning subtable - format was found in this font. - - 0x0A01 Invalid_Kerning_Table A kerning table contains illegal - glyph indices. - - 0x0B00 Invalid_Post_Table_Format - The post table format specified - in the font is invalid. - - 0x0B01 Invalid_Post_Table The post table contains illegal - entries. - - - Here the TrueType Open error codes. In the following table, the - prefix `TTO_Err_' is omitted. - - - Error Unprefixed Error - Code Macro Name Description - ------------------------------------------------------------------ - 0x1000 Invalid_SubTable_Format The TrueType Open subtable format - specified in the font is invalid. - - 0x1001 Invalid_SubTable A TrueType Open subtable contains - illegal entries. - - 0x1002 Not_Covered The requested feature, glyph, - etc. isn't covered by the actual - function. - - 0x1003 Too_Many_Nested_Contexts - A loop in the contextual lookup - tables (either GSUB or GPOS) has - been detected. - - 0x1004 No_MM_Interpreter The interface to a PostScript - interpreter with Multiple Master - font support is missing. - - 0x1010 Invalid_GSUB_SubTable_Format - The GSUB subtable format - specified in the font is invalid. - - 0x1011 Invalid_GSUB_SubTable The GSUB subtable contains - illegal entries. - - 0x1020 Invalid_GPOS_SubTable_Format - The GPOS subtable format - specified in the font is invalid. - - 0x1021 Invalid_GPOS_SubTable The GPOS subtable contains - illegal entries. - - 0x1030 Invalid_GDEF_SubTable_Format - The GDEF subtable format - specified in the font is invalid. - - 0x1031 Invalid_GDEF_SubTable The GDEF subtable contains - illegal entries. - - ---- end of apirefx.txt --- |