diff --git a/ChangeLog b/ChangeLog index e60fd6a3c..6921afb28 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,9 +1,9 @@ -2006-04-01 David Turner +2006-04-01 David Turner - * docs/CHANGES: update + * docs/CHANGES: Updated. - * include/freetype/ftcache.h, include/freetype/config/ftheader.h: - updating documentation comments + * include/freetype/ftcache.h, include/freetype/config/ftheader.h: + Update documentation comments. 2006-04-01 Werner Lemberg diff --git a/docs/CHANGES b/docs/CHANGES index f86b52067..7b1146fee 100644 --- a/docs/CHANGES +++ b/docs/CHANGES @@ -42,8 +42,8 @@ LATEST CHANGES BETWEEN 2.2 and 2.1.10 - The LIGHT hinting algorithm produces more pleasant results. Also, using the FT_LOAD_TARGET_LIGHT flags within FT_Load_Glyph - always forces auto-hinting, as a special exception. This allows - you to experiment with it even if you have enabled the TrueType + always forces auto-hinting, as a special exception. This allows + you to experiment with it even if you have enabled the TrueType bytecode interpreter in your build. - The auto hinter now employs a new algorithm for CJK fonts, based @@ -77,7 +77,7 @@ LATEST CHANGES BETWEEN 2.2 and 2.1.10 bitmap strikes should be updated to use this function. - A new API `FT_Get_SubGlyph_Info' has been added to retrieve - subglyph data. This can be used by rogue clients which used to + subglyph data. This can be used by rogue clients which used to access the internal headers to get the corresponding data. - In 2.1.10, the behaviour of `FT_Set_Pixel_Sizes' was changed for diff --git a/include/freetype/config/ftheader.h b/include/freetype/config/ftheader.h index 4cfa06028..f300ec635 100644 --- a/include/freetype/config/ftheader.h +++ b/include/freetype/config/ftheader.h @@ -623,9 +623,9 @@ * * @description: * A macro used in #include statements to name the file containing the - * FreeType 2 API used to stroke outline path + * FreeType 2 API used to stroke outline path. */ -#define FT_STROKER_H +#define FT_STROKER_H /************************************************************************* @@ -635,9 +635,9 @@ * * @description: * A macro used in #include statements to name the file containing the - * FreeType 2 API used to perform artificial obliquing and emboldening + * FreeType 2 API used to perform artificial obliquing and emboldening. */ -#define FT_SYNTHESIS_H +#define FT_SYNTHESIS_H /************************************************************************* @@ -648,9 +648,9 @@ * @description: * A macro used in #include statements to name the file containing the * FreeType 2 API used to provide functions specific to the XFree86 and - * X.Org X11 servers + * X.Org X11 servers. */ -#define FT_XFREE86_H +#define FT_XFREE86_H /************************************************************************* @@ -660,10 +660,10 @@ * * @description: * A macro used in #include statements to name the file containing the - * FreeType 2 API used to perform trigonometric computations (e.g. + * FreeType 2 API used to perform trigonometric computations (e.g., * cosines and arc tangents). */ -#define FT_TRIGONOMETRY_H +#define FT_TRIGONOMETRY_H /* */ diff --git a/include/freetype/ftcache.h b/include/freetype/ftcache.h index 2cd1957e0..c63b2b2fa 100644 --- a/include/freetype/ftcache.h +++ b/include/freetype/ftcache.h @@ -46,38 +46,39 @@ FT_BEGIN_HEADER * * Note that all types and functions begin with the FTC_ prefix. * - * the cache is highly portable and thus doesn't know anything about - * the fonts installed on your system, or how to access them. This implies + * The cache is highly portable and thus doesn't know anything about the + * fonts installed on your system, or how to access them. This implies * the following scheme: * - * first, available/installed font faces are uniquely identified by - * @FTC_FaceID values provided to the cache by the client. Note that the - * cache only stores and compares these values, and doesn't try to + * First, available or installed font faces are uniquely identified by + * @FTC_FaceID values, provided to the cache by the client. Note that + * the cache only stores and compares these values, and doesn't try to * interpret them in any way. * - * Second, the cache will call, only when needed, a client-provided - * function to convert a @FTC_FaceID into a new @FT_Face object. The latter - * will then be completely managed by the cache, including its termination + * Second, the cache calls, only when needed, a client-provided function + * to convert a @FTC_FaceID into a new @FT_Face object. The latter is + * then completely managed by the cache, including its termination * through @FT_Done_Face. * - * Clients are free to map face ids to anything. The most simple usage is - * to associate them to a (pathname,face_index) pair that is used to call - * @FT_New_Face. However, more complex schemes are also possible. + * Clients are free to map face IDs to anything else. The most simple + * usage is to associate them to a (pathname,face_index) pair that is + * used to call @FT_New_Face. However, more complex schemes are also + * possible. * - * Note that for the cache to work correctly, the face id values must be - * *persistent*, which means that the content they point to should not + * Note that for the cache to work correctly, the face ID values must be + * *persistent*, which means that the contents they point to should not * change at runtime, or that their value should not become invalid. * - * If this is unavoidable (e.g. when a font is uninstalled at runtime), + * If this is unavoidable (e.g., when a font is uninstalled at runtime), * you should call @FTC_Manager_RemoveFaceID as soon as possible, to let * the cache get rid of any references to the old @FTC_FaceID it may - * keep internally. Failure to do so will lead to incorrect behaviour + * keep internally. Failure to do so will lead to incorrect behaviour * or even crashes. * - * To use the cache, start by calling @FTC_Manager_New to create a new - * @FTC_Manager object, which models a single cache instance. You can - * then lookup @FT_Face and @FT_Size objects with @FTC_Manager_LookupFace - * and @FTC_Manager_LookupSize respectively. + * To use the cache, start with calling @FTC_Manager_New to create a new + * @FTC_Manager object, which models a single cache instance. You can + * then look up @FT_Face and @FT_Size objects with + * @FTC_Manager_LookupFace and @FTC_Manager_LookupSize, respectively. * * If you want to use the charmap caching, call @FTC_CMapCache_New, then * later use @FTC_CMapCache_Lookup to perform the equivalent of @@ -87,14 +88,13 @@ FT_BEGIN_HEADER * later use @FTC_ImageCache_Lookup to retrieve the corresponding * @FT_Glyph objects from the cache. * - * If you need lots of small bitmaps, it is much more memory efficient to - * call @FTC_SBitCache_New, then later @FTC_SBitCache_Lookup, this returns - * @FTC_SBitRec structures, which are used to store small bitmaps directly. - * (a small bitmap is one whose metrics and dimensions all fit in 8-bit - * integers). + * If you need lots of small bitmaps, it is much more memory efficient + * to call @FTC_SBitCache_New followed by @FTC_SBitCache_Lookup. This + * returns @FTC_SBitRec structures, which are used to store small + * bitmaps directly. (A small bitmap is one whose metrics and + * dimensions all fit into 8-bit integers). * - * We hope to also provide a kerning cache in the near future. Stay - * tuned. + * We hope to also provide a kerning cache in the near future. * * * @@ -139,65 +139,70 @@ FT_BEGIN_HEADER /*************************************************************************/ - /************************************************************************* - * - * @type: FTC_FaceID - * - * @description: - * An opaque pointer type that is used to identity face objects. The - * contents of such objects is application-dependent. - * - * these pointers are typically used to point to a user-defined - * structure containing a font file path, and face index. - * - * @note: - * never use NULL as a valid @FTC_FaceID - * - * Face ids are passed by the client to the cache manager, which will - * call, when needed, the @FTC_Face_Requester to translate them into - * new @FT_Face objects - * - * if the content of a given face id changes at runtime, or if the - * value becomes invalid (e.g. when uninstalling a font), you should - * immediately call @FTC_Manager_RemoveFaceID before any other cache - * function. - * - * Failure to do so will result in incorrect behaviour or even - * memory leaks and crashes ! - **/ + /************************************************************************* + * + * @type: FTC_FaceID + * + * @description: + * An opaque pointer type that is used to identity face objects. The + * contents of such objects is application-dependent. + * + * These pointers are typically used to point to a user-defined + * structure containing a font file path, and face index. + * + * @note: + * Never use NULL as a valid @FTC_FaceID. + * + * Face IDs are passed by the client to the cache manager, which calls, + * when needed, the @FTC_Face_Requester to translate them into new + * @FT_Face objects. + * + * If the content of a given face ID changes at runtime, or if the value + * becomes invalid (e.g., when uninstalling a font), you should + * immediately call @FTC_Manager_RemoveFaceID before any other cache + * function. + * + * Failure to do so will result in incorrect behaviour or even + * memory leaks and crashes. + */ typedef struct FTC_FaceIDRec_* FTC_FaceID; - /************************************************************************ - * - * @functype: FTC_Face_Requester - * - * @description: - * A callback function provided by client applications. It is used - * by the cache manager to translate a given @FTC_FaceID into a new - * valid @FT_Face object, on demand. - * - * - * face_id :: The face ID to resolve. - * - * library :: A handle to a FreeType library object. - * - * req_data :: Application-provided request data (see note below). - * - * - * aface :: A new @FT_Face handle. - * - * - * FreeType error code. 0 means success. - * - * - * The third parameter 'req_data' is the same than the one passed - * by the client when @FTC_Manager_New is called. - * - * The face requester should not perform funny things on the returned - * face object, like creating a new @FT_Size for it, or setting a - * transformation through @FT_Set_Transform! - **/ + /************************************************************************ + * + * @functype: + * FTC_Face_Requester + * + * @description: + * A callback function provided by client applications. It is used by + * the cache manager to translate a given @FTC_FaceID into a new valid + * @FT_Face object, on demand. + * + * + * face_id :: + * The face ID to resolve. + * + * library :: + * A handle to a FreeType library object. + * + * req_data :: + * Application-provided request data (see note below). + * + * + * aface :: + * A new @FT_Face handle. + * + * + * FreeType error code. 0 means success. + * + * + * The third parameter `req_data' is the same as the one passed by the + * client when @FTC_Manager_New is called. + * + * The face requester should not perform funny things on the returned + * face object, like creating a new @FT_Size for it, or setting a + * transformation through @FT_Set_Transform! + */ typedef FT_Error (*FTC_Face_Requester)( FTC_FaceID face_id, FT_Library library, @@ -234,12 +239,12 @@ FT_BEGIN_HEADER /* It is used to cache one or more @FT_Face objects, along with */ /* corresponding @FT_Size objects. */ /* */ - /* the manager intentionally limits the total number of opened */ - /* @FT_Face and @FT_Size objects to limit memory usage. See the */ - /* 'max_faces' and 'max_sizes' parameters of @FTC_Manager_New. */ + /* The manager intentionally limits the total number of opened */ + /* @FT_Face and @FT_Size objects to control memory usage. See the */ + /* `max_faces' and `max_sizes' parameters of @FTC_Manager_New. */ /* */ - /* the manager is also used to cache 'nodes' of various types */ - /* while limiting their total memory usage. */ + /* The manager is also used to cache `nodes' of various types while */ + /* limiting their total memory usage. */ /* */ /* All limitations are enforced by keeping lists of managed objects */ /* in most-recently-used order, and flushing old nodes to make room */ @@ -277,24 +282,23 @@ FT_BEGIN_HEADER /* Creates a new cache manager. */ /* */ /* */ - /* library :: The parent FreeType library handle to use. */ + /* library :: The parent FreeType library handle to use. */ /* */ - /* max_faces :: Maximum number of opened @FT_Face objects managed */ - /* by this cache instance. */ + /* max_faces :: Maximum number of opened @FT_Face objects managed by */ + /* this cache instance. */ /* */ - /* max_sizes :: Maximum number of opened @FT_Size objects managed */ - /* by this cache instance. */ + /* max_sizes :: Maximum number of opened @FT_Size objects managed by */ + /* this cache instance. */ /* */ - /* max_bytes :: Maximum number of bytes to use for cached data */ - /* nodes. Use 0 for defaults. Note that this value */ - /* does not account for managed FT_Face and FT_Size */ - /* objects. */ + /* max_bytes :: Maximum number of bytes to use for cached data nodes. */ + /* Use 0 for defaults. Note that this value does not */ + /* account for managed FT_Face and FT_Size objects. */ /* */ - /* requester :: An application-provided callback used to translate */ - /* face IDs into real @FT_Face objects. */ + /* requester :: An application-provided callback used to translate */ + /* face IDs into real @FT_Face objects. */ /* */ - /* req_data :: A generic pointer that is passed to the requester */ - /* each time it is called (see @FTC_Face_Requester). */ + /* req_data :: A generic pointer that is passed to the requester */ + /* each time it is called (see @FTC_Face_Requester). */ /* */ /* */ /* amanager :: A handle to a new manager object. 0 in case of */ @@ -376,7 +380,6 @@ FT_BEGIN_HEADER /* the @FT_Set_Transform function) on a returned face! If you need */ /* to transform glyphs, do it yourself after glyph loading. */ /* */ - /* */ /* When you perform a lookup, out-of-memory errors are detected */ /* _within_ the lookup and force incremental flushes of the cache */ /* until enough memory is released for the lookup to succeed. */