From 2ee71f1f01d1a148a5fed9712e20c628ac9b4671 Mon Sep 17 00:00:00 2001 From: Werner Lemberg Date: Fri, 12 May 2006 13:55:04 +0000 Subject: [PATCH] More minor fixes. Move `version' section to the end of freetype.h so that the library compiles actually. --- include/freetype/freetype.h | 160 +++++++++++++++++----------------- include/freetype/ftchapters.h | 1 + include/freetype/ftgxval.h | 39 +++++---- include/freetype/ftgzip.h | 16 ++-- include/freetype/ftincrem.h | 2 +- include/freetype/ftlzw.h | 10 +-- include/freetype/ftmodapi.h | 22 +++-- include/freetype/ftotval.h | 8 +- include/freetype/ftrender.h | 12 +-- include/freetype/ftstroke.h | 18 ++-- include/freetype/ftsystem.h | 8 +- 11 files changed, 154 insertions(+), 142 deletions(-) diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h index 441f325f7..8f5755d63 100644 --- a/include/freetype/freetype.h +++ b/include/freetype/freetype.h @@ -30,6 +30,7 @@ /* The `raster' component duplicates some of the declarations in */ /* freetype.h for stand-alone use if _FREETYPE_ isn't defined. */ /* */ + /*************************************************************************/ #ifndef __FREETYPE_H__ @@ -45,85 +46,6 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /*
*/ - /* version */ - /* */ - /* */ - /* FreeType Version */ - /* */ - /* <Abstract> */ - /* Functions and macros related to FreeType versions. */ - /* */ - /* <Description> */ - /* Note that those functions and macros are of limited use because */ - /* even a new release of FreeType with only documentation changes */ - /* increases the version number. */ - /* */ - /*************************************************************************/ - - - /************************************************************************* - * - * @enum: - * FREETYPE_XXX - * - * @description: - * These three macros identify the FreeType source code version. - * Use @FT_Library_Version to access them at runtime. - * - * @values: - * FREETYPE_MAJOR :: The major version number. - * FREETYPE_MINOR :: The minor version number. - * FREETYPE_PATCH :: The patch level. - * - * @note: - * The version number of FreeType if built as a dynamic link library - * with the `libtool' package is _not_ controlled by these three - * macros. - */ -#define FREETYPE_MAJOR 2 -#define FREETYPE_MINOR 2 -#define FREETYPE_PATCH 1 - - - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Library_Version */ - /* */ - /* <Description> */ - /* Return the version of the FreeType library being used. This is */ - /* useful when dynamically linking to the library, since one cannot */ - /* use the macros @FREETYPE_MAJOR, @FREETYPE_MINOR, and */ - /* @FREETYPE_PATCH. */ - /* */ - /* <Input> */ - /* library :: A source library handle. */ - /* */ - /* <Output> */ - /* amajor :: The major version number. */ - /* */ - /* aminor :: The minor version number. */ - /* */ - /* apatch :: The patch version number. */ - /* */ - /* <Note> */ - /* The reason why this function takes a `library' argument is because */ - /* certain programs implement library initialization in a custom way */ - /* that doesn't use @FT_Init_FreeType. */ - /* */ - /* In such cases, the library version might not be available before */ - /* the library object has been created. */ - /* */ - FT_EXPORT( void ) - FT_Library_Version( FT_Library library, - FT_Int *amajor, - FT_Int *aminor, - FT_Int *apatch ); - - /*************************************************************************/ /* */ @@ -3344,6 +3266,86 @@ FT_BEGIN_HEADER FT_Vector_Transform( FT_Vector* vec, const FT_Matrix* matrix ); + + /*************************************************************************/ + /* */ + /* <Section> */ + /* version */ + /* */ + /* <Title> */ + /* FreeType Version */ + /* */ + /* <Abstract> */ + /* Functions and macros related to FreeType versions. */ + /* */ + /* <Description> */ + /* Note that those functions and macros are of limited use because */ + /* even a new release of FreeType with only documentation changes */ + /* increases the version number. */ + /* */ + /*************************************************************************/ + + + /************************************************************************* + * + * @enum: + * FREETYPE_XXX + * + * @description: + * These three macros identify the FreeType source code version. + * Use @FT_Library_Version to access them at runtime. + * + * @values: + * FREETYPE_MAJOR :: The major version number. + * FREETYPE_MINOR :: The minor version number. + * FREETYPE_PATCH :: The patch level. + * + * @note: + * The version number of FreeType if built as a dynamic link library + * with the `libtool' package is _not_ controlled by these three + * macros. + */ +#define FREETYPE_MAJOR 2 +#define FREETYPE_MINOR 2 +#define FREETYPE_PATCH 1 + + + /*************************************************************************/ + /* */ + /* <Function> */ + /* FT_Library_Version */ + /* */ + /* <Description> */ + /* Return the version of the FreeType library being used. This is */ + /* useful when dynamically linking to the library, since one cannot */ + /* use the macros @FREETYPE_MAJOR, @FREETYPE_MINOR, and */ + /* @FREETYPE_PATCH. */ + /* */ + /* <Input> */ + /* library :: A source library handle. */ + /* */ + /* <Output> */ + /* amajor :: The major version number. */ + /* */ + /* aminor :: The minor version number. */ + /* */ + /* apatch :: The patch version number. */ + /* */ + /* <Note> */ + /* The reason why this function takes a `library' argument is because */ + /* certain programs implement library initialization in a custom way */ + /* that doesn't use @FT_Init_FreeType. */ + /* */ + /* In such cases, the library version might not be available before */ + /* the library object has been created. */ + /* */ + FT_EXPORT( void ) + FT_Library_Version( FT_Library library, + FT_Int *amajor, + FT_Int *aminor, + FT_Int *apatch ); + + /* */ diff --git a/include/freetype/ftchapters.h b/include/freetype/ftchapters.h index 7b59ccf75..477daa5b9 100644 --- a/include/freetype/ftchapters.h +++ b/include/freetype/ftchapters.h @@ -29,6 +29,7 @@ /* Core API */ /* */ /* <Sections> */ +/* version */ /* basic_types */ /* base_interface */ /* glyph_management */ diff --git a/include/freetype/ftgxval.h b/include/freetype/ftgxval.h index 14942ca7d..c7ea861a0 100644 --- a/include/freetype/ftgxval.h +++ b/include/freetype/ftgxval.h @@ -80,8 +80,21 @@ FT_BEGIN_HEADER #define FT_VALIDATE_prop_INDEX 8 #define FT_VALIDATE_lcar_INDEX 9 #define FT_VALIDATE_GX_LAST_INDEX FT_VALIDATE_lcar_INDEX + + + /************************************************************************* + * + * @macro: + * FT_VALIDATE_GX_LENGTH + * + * @description: + * The number of tables checked in this module. Use it as a parameter + * for the `table-length' argument of function @FT_TrueTypeGX_Validate. + */ #define FT_VALIDATE_GX_LENGTH (FT_VALIDATE_GX_LAST_INDEX + 1) + /* */ + /* Up to 0x1000 is used by otvalid. Ox2xxx is reserved for feature OT extension. */ #define FT_VALIDATE_GX_START 0x4000 @@ -102,43 +115,33 @@ FT_BEGIN_HEADER * FT_VALIDATE_feat :: * Validate `feat' table. * - * @values: * FT_VALIDATE_mort :: * Validate `mort' table. * - * @values: * FT_VALIDATE_morx :: * Validate `morx' table. * - * @values: * FT_VALIDATE_bsln :: * Validate `bsln' table. * - * @values: * FT_VALIDATE_just :: * Validate `just' table. * - * @values: * FT_VALIDATE_kern :: * Validate `kern' table. * - * @values: * FT_VALIDATE_opbd :: * Validate `opbd' table. * - * @values: * FT_VALIDATE_trak :: * Validate `trak' table. * - * @values: * FT_VALIDATE_prop :: * Validate `prop' table. * - * @values: * FT_VALIDATE_lcar :: * Validate `lcar' table. * - * @values: * FT_VALIDATE_GX :: * Validate all TrueTypeGX tables (feat, mort, morx, bsln, just, kern, * opbd, trak, prop and lcar). @@ -190,7 +193,7 @@ FT_BEGIN_HEADER * @FT_VALIDATE_GXXXX for possible values. * * table_length :: - * The size of the `tables' array. Normally, `FT_VALIDATE_GX_LENGTH' + * The size of the `tables' array. Normally, @FT_VALIDATE_GX_LENGTH * should be passed. * * @output: @@ -206,7 +209,7 @@ FT_BEGIN_HEADER * otherwise. * * After use, the application should deallocate the buffers pointed to by - * each `tables' element, by calling FT_TrueTypeGX_Free(). A NULL value + * each `tables' element, by calling @FT_TrueTypeGX_Free. A NULL value * indicates that the table either doesn't exist in the font, the * application hasn't asked for validation, or the validator doesn't have * the ability to validate the sfnt table. @@ -234,11 +237,11 @@ FT_BEGIN_HEADER * * table :: * The pointer to the buffer allocated by - * FT_TrueTypeGX_Validate(). + * @FT_TrueTypeGX_Validate. * * @note: * This function must be used to free the buffer allocated by - * FT_TrueTypeGX_Validate() only. + * @FT_TrueTypeGX_Validate only. */ FT_EXPORT( void ) FT_TrueTypeGX_Free( FT_Face face, @@ -262,11 +265,9 @@ FT_BEGIN_HEADER * FT_VALIDATE_MS :: * Handle the `kern' table as a classic Microsoft kern table. * - * @values: * FT_VALIDATE_APPLE :: * Handle the `kern' table as a classic Apple kern table. * - * @values: * FT_VALIDATE_CKERN :: * Handle the `kern' as either classic Apple or Microsoft kern table. */ @@ -310,7 +311,7 @@ FT_BEGIN_HEADER * * @note: * After use, the application should deallocate the buffers pointed to by - * `ckern_table', by calling FT_ClassicKern_Free(). A NULL value + * `ckern_table', by calling @FT_ClassicKern_Free. A NULL value * indicates that the table doesn't exist in the font. */ FT_EXPORT( FT_Error ) @@ -335,11 +336,11 @@ FT_BEGIN_HEADER * * table :: * The pointer to the buffer that is allocated by - * FT_ClassicKern_Validate(). + * @FT_ClassicKern_Validate. * * @note: * This function must be used to free the buffer allocated by - * FT_ClassicKern_Validate() only. + * @FT_ClassicKern_Validate only. */ FT_EXPORT( void ) FT_ClassicKern_Free( FT_Face face, diff --git a/include/freetype/ftgzip.h b/include/freetype/ftgzip.h index ebf35a1ea..9893437bf 100644 --- a/include/freetype/ftgzip.h +++ b/include/freetype/ftgzip.h @@ -55,13 +55,15 @@ FT_BEGIN_HEADER * * @description: * Open a new stream to parse gzip-compressed font files. This is - * mainly used to support the compressed *.pcf.gz fonts that come + * mainly used to support the compressed `*.pcf.gz' fonts that come * with XFree86. * * @input: - * stream :: The target embedding stream. + * stream :: + * The target embedding stream. * - * source :: The source stream. + * source :: + * The source stream. * * @return: * FreeType error code. 0 means success. @@ -69,8 +71,8 @@ FT_BEGIN_HEADER * @note: * The source stream must be opened _before_ calling this function. * - * Calling the internal function FT_Stream_Close on the new stream will - * *not* call FT_Stream_Close on the source stream. None of the stream + * Calling the internal function `FT_Stream_Close' on the new stream will + * *not* call `FT_Stream_Close' on the source stream. None of the stream * objects will be released to the heap. * * The stream implementation is very basic and resets the decompression @@ -82,8 +84,8 @@ FT_BEGIN_HEADER * compressed file, the library will try to open a gzipped stream from * it and re-open the face with it. * - * This function may return `FT_Err_Unimplemented' if your build of - * FreeType was not compiled with zlib support. + * This function may return `FT_Err_Unimplemented_Feature' if your build + * of FreeType was not compiled with zlib support. */ FT_EXPORT( FT_Error ) FT_Stream_OpenGzip( FT_Stream stream, diff --git a/include/freetype/ftincrem.h b/include/freetype/ftincrem.h index f0859133b..d7f4427cb 100644 --- a/include/freetype/ftincrem.h +++ b/include/freetype/ftincrem.h @@ -67,7 +67,7 @@ FT_BEGIN_HEADER * @description: * An opaque type describing a user-provided object used to implement * `incremental' glyph loading within FreeType. This is used to support - * embedded fonts in certain environments (e.g. Postscript interpreters), + * embedded fonts in certain environments (e.g., Postscript interpreters), * where the glyph data isn't in the font file, or must be overridden by * different values. * diff --git a/include/freetype/ftlzw.h b/include/freetype/ftlzw.h index 18b573c13..d950653eb 100644 --- a/include/freetype/ftlzw.h +++ b/include/freetype/ftlzw.h @@ -54,7 +54,7 @@ FT_BEGIN_HEADER * * @description: * Open a new stream to parse LZW-compressed font files. This is - * mainly used to support the compressed *.pcf.Z fonts that come + * mainly used to support the compressed `*.pcf.Z' fonts that come * with XFree86. * * @input: @@ -68,8 +68,8 @@ FT_BEGIN_HEADER * @note: * The source stream must be opened _before_ calling this function. * - * Calling the internal function FT_Stream_Close on the new stream will - * *not* call FT_Stream_Close on the source stream. None of the stream + * Calling the internal function `FT_Stream_Close' on the new stream will + * *not* call `FT_Stream_Close' on the source stream. None of the stream * objects will be released to the heap. * * The stream implementation is very basic and resets the decompression @@ -81,8 +81,8 @@ FT_BEGIN_HEADER * compressed file, the library will try to open a LZW stream from it * and re-open the face with it. * - * This function may return `FT_Err_Unimplemented' if your build of - * FreeType was not compiled with LZW support. + * This function may return `FT_Err_Unimplemented_Feature' if your build + * of FreeType was not compiled with LZW support. */ FT_EXPORT( FT_Error ) FT_Stream_OpenLZW( FT_Stream stream, diff --git a/include/freetype/ftmodapi.h b/include/freetype/ftmodapi.h index ab9082f8f..4628bdf83 100644 --- a/include/freetype/ftmodapi.h +++ b/include/freetype/ftmodapi.h @@ -108,8 +108,9 @@ FT_BEGIN_HEADER /* module_version :: The version, as a 16.16 fixed number */ /* (major.minor). */ /* */ - /* module_requires :: The version of FreeType this module requires */ - /* (starts at version 2.0, i.e., 0x20000) */ + /* module_requires :: The version of FreeType this module requires, */ + /* as a 16.16 fixed number (major.minor). Starts */ + /* at version 2.0, i.e., 0x20000. */ /* */ /* module_init :: A function used to initialize (not create) a */ /* new module object. */ @@ -180,8 +181,8 @@ FT_BEGIN_HEADER /* A module handle. 0 if none was found. */ /* */ /* <Note> */ - /* You should better be familiar with FreeType internals to know */ - /* which module to look for :-) */ + /* FreeType's internal modules aren't documented very well, and you */ + /* should look up the source code for details. */ /* */ FT_EXPORT( FT_Module ) FT_Get_Module( FT_Library library, @@ -275,8 +276,8 @@ FT_BEGIN_HEADER /* */ /* <Input> */ /* hook_index :: The index of the debug hook. You should use the */ - /* values defined in ftobjs.h, e.g. */ - /* FT_DEBUG_HOOK_TRUETYPE. */ + /* values defined in `ftobjs.h', e.g., */ + /* `FT_DEBUG_HOOK_TRUETYPE'. */ /* */ /* debug_hook :: The function used to debug the interpreter. */ /* */ @@ -284,6 +285,10 @@ FT_BEGIN_HEADER /* Currently, four debug hook slots are available, but only two (for */ /* the TrueType and the Type 1 interpreter) are defined. */ /* */ + /* Since the internal headers of FreeType are no longer installed, */ + /* the symbol `FT_DEBUG_HOOK_TRUETYPE' isn't available publicly. */ + /* This is a bug and will be fixed in a forthcoming release. */ + /* */ FT_EXPORT( void ) FT_Set_Debug_Hook( FT_Library library, FT_UInt hook_index, @@ -298,7 +303,7 @@ FT_BEGIN_HEADER /* <Description> */ /* Adds the set of default drivers to a given library object. */ /* This is only useful when you create a library object with */ - /* FT_New_Library() (usually to plug a custom memory manager). */ + /* @FT_New_Library (usually to plug a custom memory manager). */ /* */ /* <InOut> */ /* library :: A handle to a new library object. */ @@ -307,6 +312,7 @@ FT_BEGIN_HEADER FT_Add_Default_Modules( FT_Library library ); + /************************************************************************** * * @section: @@ -331,7 +337,7 @@ FT_BEGIN_HEADER * FT_TrueTypeEngineType * * @description: - * A list of values describing which kind of truetype bytecode + * A list of values describing which kind of TrueType bytecode * engine is implemented in a given FT_Library instance. It is used * by the @FT_Get_TrueType_Engine_Type function. * diff --git a/include/freetype/ftotval.h b/include/freetype/ftotval.h index 5b3139840..2bddc6b58 100644 --- a/include/freetype/ftotval.h +++ b/include/freetype/ftotval.h @@ -4,7 +4,7 @@ /* */ /* FreeType API for validating OpenType tables (specification). */ /* */ -/* Copyright 2004, 2005 by */ +/* Copyright 2004, 2005, 2006 by */ /* David Turner, Robert Wilhelm, and Werner Lemberg. */ /* */ /* This file is part of the FreeType project, and may only be used, */ @@ -147,7 +147,7 @@ FT_BEGIN_HEADER * otherwise. * * After use, the application should deallocate the five tables with - * FT_OpenType_Free(). A NULL value indicates that the table either + * @FT_OpenType_Free. A NULL value indicates that the table either * doesn't exist in the font, or the application hasn't asked for * validation. */ @@ -176,11 +176,11 @@ FT_BEGIN_HEADER * * table :: * The pointer to the buffer that is allocated by - * FT_OpenType_Validate(). + * @FT_OpenType_Validate. * * @note: * This function must be used to free the buffer allocated by - * FT_OpenType_Validate() only. + * @FT_OpenType_Validate only. */ FT_EXPORT( void ) FT_OpenType_Free( FT_Face face, diff --git a/include/freetype/ftrender.h b/include/freetype/ftrender.h index 5a01da479..5b07f08c2 100644 --- a/include/freetype/ftrender.h +++ b/include/freetype/ftrender.h @@ -4,7 +4,7 @@ /* */ /* FreeType renderer modules public interface (specification). */ /* */ -/* Copyright 1996-2001, 2005 by */ +/* Copyright 1996-2001, 2005, 2006 by */ /* David Turner, Robert Wilhelm, and Werner Lemberg. */ /* */ /* This file is part of the FreeType project, and may only be used, */ @@ -124,7 +124,7 @@ FT_BEGIN_HEADER /* The renderer module class descriptor. */ /* */ /* <Fields> */ - /* root :: The root FT_Module_Class fields. */ + /* root :: The root @FT_Module_Class fields. */ /* */ /* glyph_format :: The glyph image format this renderer handles. */ /* */ @@ -133,10 +133,10 @@ FT_BEGIN_HEADER /* */ /* set_mode :: A method used to pass additional parameters. */ /* */ - /* raster_class :: For `FT_GLYPH_FORMAT_OUTLINE' renderers only, this */ + /* raster_class :: For @FT_GLYPH_FORMAT_OUTLINE renderers only. This */ /* is a pointer to its raster's class. */ /* */ - /* raster :: For `FT_GLYPH_FORMAT_OUTLINE' renderers only. this */ + /* raster :: For @FT_GLYPH_FORMAT_OUTLINE renderers only. This */ /* is a pointer to the corresponding raster object, */ /* if any. */ /* */ @@ -176,8 +176,8 @@ FT_BEGIN_HEADER /* An error will be returned if a module already exists by that name, */ /* or if the module requires a version of FreeType that is too great. */ /* */ - /* To add a new renderer, simply use FT_Add_Module(). To retrieve a */ - /* renderer by its name, use FT_Get_Module(). */ + /* To add a new renderer, simply use @FT_Add_Module. To retrieve a */ + /* renderer by its name, use @FT_Get_Module. */ /* */ FT_EXPORT( FT_Renderer ) FT_Get_Renderer( FT_Library library, diff --git a/include/freetype/ftstroke.h b/include/freetype/ftstroke.h index bf9d26dcb..4d13d0c67 100644 --- a/include/freetype/ftstroke.h +++ b/include/freetype/ftstroke.h @@ -142,8 +142,8 @@ FT_BEGIN_HEADER * * @note: * Applications are generally interested in the `inside' and `outside' - * borders. However, there is no direct mapping between these and - * the `left' / `right' ones, since this really depends on the glyph's + * borders. However, there is no direct mapping between these and the + * `left' and `right' ones, since this really depends on the glyph's * drawing orientation, which varies between font formats. * * You can however use @FT_Outline_GetInsideBorder and @@ -209,7 +209,7 @@ FT_BEGIN_HEADER * * @input: * library :: - * FreeType library handle + * FreeType library handle. * * @output: * astroker :: @@ -341,7 +341,7 @@ FT_BEGIN_HEADER * * @note: * This function is useful when you need to stroke a path that is - * not stored as a @FT_Outline object. + * not stored as an @FT_Outline object. */ FT_EXPORT( FT_Error ) FT_Stroker_BeginSubPath( FT_Stroker stroker, @@ -415,7 +415,7 @@ FT_BEGIN_HEADER * The target stroker handle. * * control :: - * A pointer to a Bézier control point. + * A pointer to a Bezier control point. * * to :: * A pointer to the destination point. @@ -439,7 +439,7 @@ FT_BEGIN_HEADER * FT_Stroker_CubicTo * * @description: - * `Draw' a single cubic Bézier in the stroker's current sub-path, + * `Draw' a single cubic Bezier in the stroker's current sub-path, * from the last position. * * @input: @@ -447,10 +447,10 @@ FT_BEGIN_HEADER * The target stroker handle. * * control1 :: - * A pointer to the first Bézier control point. + * A pointer to the first Bezier control point. * * control2 :: - * A pointer to second Bézier control point. + * A pointer to second Bezier control point. * * to :: * A pointer to the destination point. @@ -475,7 +475,7 @@ FT_BEGIN_HEADER * FT_Stroker_GetBorderCounts * * @description: - * Vall this function once you have finished parsing your paths + * Call this function once you have finished parsing your paths * with the stroker. It will return the number of points and * contours necessary to export one of the `border' or `stroke' * outlines generated by the stroker. diff --git a/include/freetype/ftsystem.h b/include/freetype/ftsystem.h index 373cf5b63..59cd01982 100644 --- a/include/freetype/ftsystem.h +++ b/include/freetype/ftsystem.h @@ -41,7 +41,7 @@ FT_BEGIN_HEADER /* This section contains various definitions related to memory */ /* management and i/o access. You need to understand this */ /* information if you want to use a custom memory manager or you own */ - /* input i/o streams. */ + /* i/o streams. */ /* */ /*************************************************************************/ @@ -59,7 +59,7 @@ FT_BEGIN_HEADER * FT_Memory * * @description: - * A handle to a given memory manager object, defined with a + * A handle to a given memory manager object, defined with an * @FT_MemoryRec structure. * */ @@ -203,7 +203,7 @@ FT_BEGIN_HEADER * * @description: * A union type used to store either a long or a pointer. This is used - * to store a file descriptor or a FILE* in an input stream. + * to store a file descriptor or a `FILE*' in an input stream. * */ typedef union FT_StreamDesc_ @@ -289,7 +289,7 @@ FT_BEGIN_HEADER * * descriptor :: * This field is a union that can hold an integer or a pointer. It is - * used by stream implementations to store file descriptors or FILE* + * used by stream implementations to store file descriptors or `FILE*' * pointers. * * pathname ::