summaryrefslogtreecommitdiff
path: root/Build/source/libs/freetype/freetype-1.5/docs/apirefx.txt
diff options
context:
space:
mode:
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.txt1223
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 ---