diff options
| author | Nikhil Ramakrishnan <ramakrishnan.nikhil@gmail.com> | 2018-08-24 22:22:30 +0530 |
|---|---|---|
| committer | Nikhil Ramakrishnan <ramakrishnan.nikhil@gmail.com> | 2018-08-25 16:16:56 +0530 |
| commit | ae5d1a4cec37557f31aec270332cfe886a62f9a0 (patch) | |
| tree | cf8f4ad5e1ccd82897b36e2cc41adc62de1ef6b2 | |
| parent | 77f0814a3162a945d6d6704f545827f883e451e5 (diff) | |
| download | freetype2-ae5d1a4cec37557f31aec270332cfe886a62f9a0.tar.gz | |
* include/*.*: Convert comments to markdown.
This commit was created by applying scripts `markify.py' and
`markdown-format.bash' to all C header files, followed by minor
clean-up.
No change in functionality, of course.
Scripts used:
https://github.com/nikramakrishnan/freetype-docs.git: Commit dfce31e.
http://lists.nongnu.org/archive/html/freetype-devel/2018-08/msg00013.html:
With patches applied.
69 files changed, 4031 insertions, 4549 deletions
diff --git a/include/freetype/config/ftconfig.h b/include/freetype/config/ftconfig.h index 3d127f8fa..7fabeb846 100644 --- a/include/freetype/config/ftconfig.h +++ b/include/freetype/config/ftconfig.h @@ -18,20 +18,19 @@ /************************************************************************** * - * This header file contains a number of macro definitions that are used - * by the rest of the engine. Most of the macros here are automatically - * determined at compile time, and you should not need to change it to - * port FreeType, except to compile the library with a non-ANSI - * compiler. + * This header file contains a number of macro definitions that are used by + * the rest of the engine. Most of the macros here are automatically + * determined at compile time, and you should not need to change it to port + * FreeType, except to compile the library with a non-ANSI compiler. * - * Note however that if some specific modifications are needed, we - * advise you to place a modified copy in your build directory. + * Note however that if some specific modifications are needed, we advise + * you to place a modified copy in your build directory. * - * The build directory is usually `builds/<system>', and contains - * system-specific files that are always included first when building - * the library. + * The build directory is usually 'builds/<system>', and contains + * system-specific files that are always included first when building the + * library. * - * This ANSI version should stay in `include/config/'. + * This ANSI version should stay in 'include/config/'. * */ @@ -50,10 +49,10 @@ FT_BEGIN_HEADER * * PLATFORM-SPECIFIC CONFIGURATION MACROS * - * These macros can be toggled to suit a specific system. The current - * ones are defaults used to compile FreeType in an ANSI C environment - * (16bit compilers are also supported). Copy this file to your own - * `builds/<system>' directory, and edit it to port the engine. + * These macros can be toggled to suit a specific system. The current ones + * are defaults used to compile FreeType in an ANSI C environment (16bit + * compilers are also supported). Copy this file to your own + * 'builds/<system>' directory, and edit it to port the engine. * */ @@ -192,8 +191,8 @@ FT_BEGIN_HEADER * FT_Int32 * * @description: - * A typedef for a 32bit signed integer type. The size depends on - * the configuration. + * A typedef for a 32bit signed integer type. The size depends on the + * configuration. */ typedef signed XXX FT_Int32; @@ -203,8 +202,8 @@ FT_BEGIN_HEADER * @type: * FT_UInt32 * - * A typedef for a 32bit unsigned integer type. The size depends on - * the configuration. + * A typedef for a 32bit unsigned integer type. The size depends on the + * configuration. */ typedef unsigned XXX FT_UInt32; @@ -214,8 +213,8 @@ FT_BEGIN_HEADER * @type: * FT_Int64 * - * A typedef for a 64bit signed integer type. The size depends on - * the configuration. Only defined if there is real 64bit support; + * A typedef for a 64bit signed integer type. The size depends on the + * configuration. Only defined if there is real 64bit support; * otherwise, it gets emulated with a structure (if necessary). */ typedef signed XXX FT_Int64; @@ -226,8 +225,8 @@ FT_BEGIN_HEADER * @type: * FT_UInt64 * - * A typedef for a 64bit unsigned integer type. The size depends on - * the configuration. Only defined if there is real 64bit support; + * A typedef for a 64bit unsigned integer type. The size depends on the + * configuration. Only defined if there is real 64bit support; * otherwise, it gets emulated with a structure (if necessary). */ typedef unsigned XXX FT_UInt64; @@ -276,10 +275,10 @@ FT_BEGIN_HEADER /************************************************************************** * - * A 64-bit data type may create compilation problems if you compile - * in strict ANSI mode. To avoid them, we disable other 64-bit data - * types if __STDC__ is defined. You can however ignore this rule - * by defining the FT_CONFIG_OPTION_FORCE_INT64 configuration macro. + * A 64-bit data type may create compilation problems if you compile in + * strict ANSI mode. To avoid them, we disable other 64-bit data types if + * __STDC__ is defined. You can however ignore this rule by defining the + * FT_CONFIG_OPTION_FORCE_INT64 configuration macro. */ #elif !defined( __STDC__ ) || defined( FT_CONFIG_OPTION_FORCE_INT64 ) diff --git a/include/freetype/config/ftheader.h b/include/freetype/config/ftheader.h index bb9683765..36e6b337d 100644 --- a/include/freetype/config/ftheader.h +++ b/include/freetype/config/ftheader.h @@ -73,23 +73,22 @@ * Macro definitions used to #include specific header files. * * @description: - * The following macros are defined to the name of specific - * FreeType~2 header files. They can be used directly in #include - * statements as in: + * The following macros are defined to the name of specific FreeType~2 + * header files. They can be used directly in #include statements as in: * - * { + * ``` * #include FT_FREETYPE_H * #include FT_MULTIPLE_MASTERS_H * #include FT_GLYPH_H - * } + * ``` * - * There are several reasons why we are now using macros to name - * public header files. The first one is that such macros are not - * limited to the infamous 8.3~naming rule required by DOS (and - * `FT_MULTIPLE_MASTERS_H' is a lot more meaningful than `ftmm.h'). + * There are several reasons why we are now using macros to name public + * header files. The first one is that such macros are not limited to + * the infamous 8.3~naming rule required by DOS (and + * `FT_MULTIPLE_MASTERS_H` is a lot more meaningful than `ftmm.h`). * - * The second reason is that it allows for more flexibility in the - * way FreeType~2 is installed on a given system. + * The second reason is that it allows for more flexibility in the way + * FreeType~2 is installed on a given system. * */ @@ -436,7 +435,7 @@ * * @description: * A macro used in #include statements to name the file containing the - * definitions of TrueType four-byte `tags' which identify blocks in + * definitions of TrueType four-byte 'tags' which identify blocks in * SFNT-based font formats (i.e., TrueType and OpenType). * */ @@ -450,8 +449,7 @@ * * @description: * A macro used in #include statements to name the file containing the - * definitions of an API which accesses BDF-specific strings from a - * face. + * definitions of an API which accesses BDF-specific strings from a face. * */ #define FT_BDF_H <freetype/ftbdf.h> @@ -464,8 +462,7 @@ * * @description: * A macro used in #include statements to name the file containing the - * definitions of an API which access CID font information from a - * face. + * definitions of an API which access CID font information from a face. * */ #define FT_CID_H <freetype/ftcid.h> @@ -582,8 +579,8 @@ * * @description: * A macro used in #include statements to name the file containing the - * Macintosh-specific FreeType~2 API. The latter is used to access - * fonts embedded in resource forks. + * Macintosh-specific FreeType~2 API. The latter is used to access fonts + * embedded in resource forks. * * This header file must be explicitly included by client applications * compiled on the Mac (note that the base API still works though). @@ -612,7 +609,7 @@ * * @description: * A macro used in #include statements to name the file containing the - * optional FreeType~2 API which accesses embedded `name' strings in + * optional FreeType~2 API which accesses embedded 'name' strings in * SFNT-based font formats (i.e., TrueType and OpenType). * */ @@ -801,8 +798,8 @@ /* - * Include internal headers definitions from <internal/...> - * only when building the library. + * Include internal headers definitions from <internal/...> only when + * building the library. */ #ifdef FT2_BUILD_LIBRARY #define FT_INTERNAL_INTERNAL_H <freetype/internal/internal.h> diff --git a/include/freetype/config/ftoption.h b/include/freetype/config/ftoption.h index 18c7d13eb..908e4e970 100644 --- a/include/freetype/config/ftoption.h +++ b/include/freetype/config/ftoption.h @@ -29,33 +29,33 @@ FT_BEGIN_HEADER * * USER-SELECTABLE CONFIGURATION MACROS * - * This file contains the default configuration macro definitions for - * a standard build of the FreeType library. There are three ways to - * use this file to build project-specific versions of the library: + * This file contains the default configuration macro definitions for a + * standard build of the FreeType library. There are three ways to use + * this file to build project-specific versions of the library: * * - You can modify this file by hand, but this is not recommended in - * cases where you would like to build several versions of the - * library from a single source directory. + * cases where you would like to build several versions of the library + * from a single source directory. * * - You can put a copy of this file in your build directory, more - * precisely in `$BUILD/freetype/config/ftoption.h', where `$BUILD' - * is the name of a directory that is included _before_ the FreeType - * include path during compilation. + * precisely in '$BUILD/freetype/config/ftoption.h', where '$BUILD' is + * the name of a directory that is included _before_ the FreeType include + * path during compilation. * - * The default FreeType Makefiles and Jamfiles use the build - * directory `builds/<system>' by default, but you can easily change - * that for your own projects. + * The default FreeType Makefiles and Jamfiles use the build directory + * 'builds/<system>' by default, but you can easily change that for your + * own projects. * - * - Copy the file <ft2build.h> to `$BUILD/ft2build.h' and modify it - * slightly to pre-define the macro FT_CONFIG_OPTIONS_H used to - * locate this file during the build. For example, + * - Copy the file <ft2build.h> to '$BUILD/ft2build.h' and modify it + * slightly to pre-define the macro FT_CONFIG_OPTIONS_H used to locate + * this file during the build. For example, * - * { + * ``` * #define FT_CONFIG_OPTIONS_H <myftoptions.h> * #include <freetype/config/ftheader.h> - * } + * ``` * - * will use `$BUILD/myftoptions.h' instead of this file for macro + * will use '$BUILD/myftoptions.h' instead of this file for macro * definitions. * * Note also that you can similarly pre-define the macro @@ -117,35 +117,34 @@ FT_BEGIN_HEADER * * Uncomment the line below if you want to activate LCD rendering * technology similar to ClearType in this build of the library. This - * technology triples the resolution in the direction color subpixels. - * To mitigate color fringes inherent to this technology, you also need - * to explicitly set up LCD filtering. + * technology triples the resolution in the direction color subpixels. To + * mitigate color fringes inherent to this technology, you also need to + * explicitly set up LCD filtering. * - * Note that this feature is covered by several Microsoft patents - * and should not be activated in any default build of the library. - * When this macro is not defined, FreeType offers alternative LCD - * rendering technology that produces excellent output without LCD - * filtering. + * Note that this feature is covered by several Microsoft patents and + * should not be activated in any default build of the library. When this + * macro is not defined, FreeType offers alternative LCD rendering + * technology that produces excellent output without LCD filtering. */ /* #define FT_CONFIG_OPTION_SUBPIXEL_RENDERING */ /************************************************************************** * - * Many compilers provide a non-ANSI 64-bit data type that can be used - * by FreeType to speed up some computations. However, this will create - * some problems when compiling the library in strict ANSI mode. + * Many compilers provide a non-ANSI 64-bit data type that can be used by + * FreeType to speed up some computations. However, this will create some + * problems when compiling the library in strict ANSI mode. * * For this reason, the use of 64-bit integers is normally disabled when - * the __STDC__ macro is defined. You can however disable this by - * defining the macro FT_CONFIG_OPTION_FORCE_INT64 here. + * the __STDC__ macro is defined. You can however disable this by defining + * the macro FT_CONFIG_OPTION_FORCE_INT64 here. * * For most compilers, this will only create compilation warnings when * building the library. * * ObNote: The compiler-specific 64-bit integers are detected in the - * file `ftconfig.h' either statically or through the - * `configure' script on supported platforms. + * file `ftconfig.h` either statically or through the 'configure' + * script on supported platforms. */ #undef FT_CONFIG_OPTION_FORCE_INT64 @@ -154,20 +153,20 @@ FT_BEGIN_HEADER * * If this macro is defined, do not try to use an assembler version of * performance-critical functions (e.g. FT_MulFix). You should only do - * that to verify that the assembler function works properly, or to - * execute benchmark tests of the various implementations. + * that to verify that the assembler function works properly, or to execute + * benchmark tests of the various implementations. */ /* #define FT_CONFIG_OPTION_NO_ASSEMBLER */ /************************************************************************** * - * If this macro is defined, try to use an inlined assembler version of - * the `FT_MulFix' function, which is a `hotspot' when loading and - * hinting glyphs, and which should be executed as fast as possible. + * If this macro is defined, try to use an inlined assembler version of the + * `FT_MulFix` function, which is a 'hotspot' when loading and hinting + * glyphs, and which should be executed as fast as possible. * - * Note that if your compiler or CPU is not supported, this will default - * to the standard and portable implementation found in `ftcalc.c'. + * Note that if your compiler or CPU is not supported, this will default to + * the standard and portable implementation found in `ftcalc.c`. */ #define FT_CONFIG_OPTION_INLINE_MULFIX @@ -177,12 +176,12 @@ FT_BEGIN_HEADER * LZW-compressed file support. * * FreeType now handles font files that have been compressed with the - * `compress' program. This is mostly used to parse many of the PCF + * 'compress' program. This is mostly used to parse many of the PCF * files that come with various X11 distributions. The implementation - * uses NetBSD's `zopen' to partially uncompress the file on the fly - * (see src/lzw/ftgzip.c). + * uses NetBSD's 'zopen' to partially uncompress the file on the fly (see + * src/lzw/ftgzip.c). * - * Define this macro if you want to enable this `feature'. + * Define this macro if you want to enable this 'feature'. */ #define FT_CONFIG_OPTION_USE_LZW @@ -192,12 +191,12 @@ FT_BEGIN_HEADER * Gzip-compressed file support. * * FreeType now handles font files that have been compressed with the - * `gzip' program. This is mostly used to parse many of the PCF files - * that come with XFree86. The implementation uses `zlib' to - * partially uncompress the file on the fly (see src/gzip/ftgzip.c). + * 'gzip' program. This is mostly used to parse many of the PCF files + * that come with XFree86. The implementation uses 'zlib' to partially + * uncompress the file on the fly (see src/gzip/ftgzip.c). * - * Define this macro if you want to enable this `feature'. See also - * the macro FT_CONFIG_OPTION_SYSTEM_ZLIB below. + * Define this macro if you want to enable this 'feature'. See also the + * macro FT_CONFIG_OPTION_SYSTEM_ZLIB below. */ #define FT_CONFIG_OPTION_USE_ZLIB @@ -206,23 +205,23 @@ FT_BEGIN_HEADER * * ZLib library selection * - * This macro is only used when FT_CONFIG_OPTION_USE_ZLIB is defined. - * It allows FreeType's `ftgzip' component to link to the system's - * installation of the ZLib library. This is useful on systems like - * Unix or VMS where it generally is already available. + * This macro is only used when FT_CONFIG_OPTION_USE_ZLIB is defined. It + * allows FreeType's 'ftgzip' component to link to the system's + * installation of the ZLib library. This is useful on systems like Unix + * or VMS where it generally is already available. * - * If you let it undefined, the component will use its own copy - * of the zlib sources instead. These have been modified to be - * included directly within the component and *not* export external - * function names. This allows you to link any program with FreeType - * _and_ ZLib without linking conflicts. + * If you let it undefined, the component will use its own copy of the + * zlib sources instead. These have been modified to be included + * directly within the component and **not** export external function + * names. This allows you to link any program with FreeType _and_ ZLib + * without linking conflicts. * - * Do not #undef this macro here since the build system might define - * it for certain configurations only. + * Do not #undef this macro here since the build system might define it + * for certain configurations only. * - * If you use a build system like cmake or the `configure' script, - * options set by those programs have precendence, overwriting the - * value here with the configured one. + * If you use a build system like cmake or the 'configure' script, + * options set by those programs have precendence, overwriting the value + * here with the configured one. */ /* #define FT_CONFIG_OPTION_SYSTEM_ZLIB */ @@ -232,17 +231,17 @@ FT_BEGIN_HEADER * Bzip2-compressed file support. * * FreeType now handles font files that have been compressed with the - * `bzip2' program. This is mostly used to parse many of the PCF - * files that come with XFree86. The implementation uses `libbz2' to - * partially uncompress the file on the fly (see src/bzip2/ftbzip2.c). - * Contrary to gzip, bzip2 currently is not included and need to use - * the system available bzip2 implementation. + * 'bzip2' program. This is mostly used to parse many of the PCF files + * that come with XFree86. The implementation uses 'libbz2' to partially + * uncompress the file on the fly (see src/bzip2/ftbzip2.c). Contrary to + * gzip, bzip2 currently is not included and need to use the system + * available bzip2 implementation. * - * Define this macro if you want to enable this `feature'. + * Define this macro if you want to enable this 'feature'. * - * If you use a build system like cmake or the `configure' script, - * options set by those programs have precendence, overwriting the - * value here with the configured one. + * If you use a build system like cmake or the 'configure' script, + * options set by those programs have precendence, overwriting the value + * here with the configured one. */ /* #define FT_CONFIG_OPTION_USE_BZIP2 */ @@ -251,9 +250,9 @@ FT_BEGIN_HEADER * * Define to disable the use of file stream functions and types, FILE, * fopen() etc. Enables the use of smaller system libraries on embedded - * systems that have multiple system libraries, some with or without - * file stream support, in the cases where file stream support is not - * necessary such as memory loading of font files. + * systems that have multiple system libraries, some with or without file + * stream support, in the cases where file stream support is not necessary + * such as memory loading of font files. */ /* #define FT_CONFIG_OPTION_DISABLE_STREAM_SUPPORT */ @@ -264,14 +263,14 @@ FT_BEGIN_HEADER * * FreeType now handles loading color bitmap glyphs in the PNG format. * This requires help from the external libpng library. Uncompressed - * color bitmaps do not need any external libraries and will be - * supported regardless of this configuration. + * color bitmaps do not need any external libraries and will be supported + * regardless of this configuration. * - * Define this macro if you want to enable this `feature'. + * Define this macro if you want to enable this 'feature'. * - * If you use a build system like cmake or the `configure' script, - * options set by those programs have precendence, overwriting the - * value here with the configured one. + * If you use a build system like cmake or the 'configure' script, + * options set by those programs have precendence, overwriting the value + * here with the configured one. */ /* #define FT_CONFIG_OPTION_USE_PNG */ @@ -280,15 +279,15 @@ FT_BEGIN_HEADER * * HarfBuzz support. * - * FreeType uses the HarfBuzz library to improve auto-hinting of - * OpenType fonts. If available, many glyphs not directly addressable - * by a font's character map will be hinted also. + * FreeType uses the HarfBuzz library to improve auto-hinting of OpenType + * fonts. If available, many glyphs not directly addressable by a font's + * character map will be hinted also. * - * Define this macro if you want to enable this `feature'. + * Define this macro if you want to enable this 'feature'. * - * If you use a build system like cmake or the `configure' script, - * options set by those programs have precendence, overwriting the - * value here with the configured one. + * If you use a build system like cmake or the 'configure' script, + * options set by those programs have precendence, overwriting the value + * here with the configured one. */ /* #define FT_CONFIG_OPTION_USE_HARFBUZZ */ @@ -297,23 +296,23 @@ FT_BEGIN_HEADER * * Glyph Postscript Names handling * - * By default, FreeType 2 is compiled with the `psnames' module. This - * module is in charge of converting a glyph name string into a - * Unicode value, or return a Macintosh standard glyph name for the - * use with the TrueType `post' table. + * By default, FreeType 2 is compiled with the 'psnames' module. This + * module is in charge of converting a glyph name string into a Unicode + * value, or return a Macintosh standard glyph name for the use with the + * TrueType 'post' table. * - * Undefine this macro if you do not want `psnames' compiled in your + * Undefine this macro if you do not want 'psnames' compiled in your * build of FreeType. This has the following effects: * * - The TrueType driver will provide its own set of glyph names, - * if you build it to support postscript names in the TrueType - * `post' table, but will not synthesize a missing Unicode charmap. + * if you build it to support postscript names in the TrueType 'post' + * table, but will not synthesize a missing Unicode charmap. * * - The Type 1 driver will not be able to synthesize a Unicode * charmap out of the glyphs found in the fonts. * - * You would normally undefine this configuration macro when building - * a version of FreeType that doesn't contain a Type 1 or CFF driver. + * You would normally undefine this configuration macro when building a + * version of FreeType that doesn't contain a Type 1 or CFF driver. */ #define FT_CONFIG_OPTION_POSTSCRIPT_NAMES @@ -322,16 +321,15 @@ FT_BEGIN_HEADER * * Postscript Names to Unicode Values support * - * By default, FreeType 2 is built with the `PSNames' module compiled - * in. Among other things, the module is used to convert a glyph name - * into a Unicode value. This is especially useful in order to - * synthesize on the fly a Unicode charmap from the CFF/Type 1 driver - * through a big table named the `Adobe Glyph List' (AGL). + * By default, FreeType 2 is built with the 'PSNames' module compiled in. + * Among other things, the module is used to convert a glyph name into a + * Unicode value. This is especially useful in order to synthesize on + * the fly a Unicode charmap from the CFF/Type 1 driver through a big + * table named the 'Adobe Glyph List' (AGL). * - * Undefine this macro if you do not want the Adobe Glyph List - * compiled in your `PSNames' module. The Type 1 driver will not be - * able to synthesize a Unicode charmap out of the glyphs found in the - * fonts. + * Undefine this macro if you do not want the Adobe Glyph List compiled + * in your 'PSNames' module. The Type 1 driver will not be able to + * synthesize a Unicode charmap out of the glyphs found in the fonts. */ #define FT_CONFIG_OPTION_ADOBE_GLYPH_LIST @@ -340,11 +338,11 @@ FT_BEGIN_HEADER * * Support for Mac fonts * - * Define this macro if you want support for outline fonts in Mac - * format (mac dfont, mac resource, macbinary containing a mac - * resource) on non-Mac platforms. + * Define this macro if you want support for outline fonts in Mac format + * (mac dfont, mac resource, macbinary containing a mac resource) on + * non-Mac platforms. * - * Note that the `FOND' resource isn't checked. + * Note that the 'FOND' resource isn't checked. */ #define FT_CONFIG_OPTION_MAC_FONTS @@ -358,10 +356,9 @@ FT_BEGIN_HEADER * Resource forks which include fonts data are stored sometimes in * locations which users or developers don't expected. In some cases, * resource forks start with some offset from the head of a file. In - * other cases, the actual resource fork is stored in file different - * from what the user specifies. If this option is activated, - * FreeType tries to guess whether such offsets or different file - * names must be used. + * other cases, the actual resource fork is stored in file different from + * what the user specifies. If this option is activated, FreeType tries + * to guess whether such offsets or different file names must be used. * * Note that normal, direct access of resource forks is controlled via * the FT_CONFIG_OPTION_MAC_FONTS option. @@ -373,19 +370,19 @@ FT_BEGIN_HEADER /************************************************************************** * - * Allow the use of FT_Incremental_Interface to load typefaces that - * contain no glyph data, but supply it via a callback function. - * This is required by clients supporting document formats which - * supply font data incrementally as the document is parsed, such - * as the Ghostscript interpreter for the PostScript language. + * Allow the use of FT_Incremental_Interface to load typefaces that contain + * no glyph data, but supply it via a callback function. This is required + * by clients supporting document formats which supply font data + * incrementally as the document is parsed, such as the Ghostscript + * interpreter for the PostScript language. */ #define FT_CONFIG_OPTION_INCREMENTAL /************************************************************************** * - * The size in bytes of the render pool used by the scan-line converter - * to do all of its work. + * The size in bytes of the render pool used by the scan-line converter to + * do all of its work. */ #define FT_RENDER_POOL_SIZE 16384L @@ -405,14 +402,13 @@ FT_BEGIN_HEADER * Debug level * * FreeType can be compiled in debug or trace mode. In debug mode, - * errors are reported through the `ftdebug' component. In trace - * mode, additional messages are sent to the standard output during - * execution. + * errors are reported through the 'ftdebug' component. In trace mode, + * additional messages are sent to the standard output during execution. * * Define FT_DEBUG_LEVEL_ERROR to build the library in debug mode. * Define FT_DEBUG_LEVEL_TRACE to build it in trace mode. * - * Don't define any of these macros to compile in `release' mode! + * Don't define any of these macros to compile in 'release' mode! * * Do not #undef these macros here since the build system might define * them for certain configurations only. @@ -427,33 +423,33 @@ FT_BEGIN_HEADER * * If FT_DEBUG_AUTOFIT is defined, FreeType provides some means to * control the autofitter behaviour for debugging purposes with global - * boolean variables (consequently, you should *never* enable this - * while compiling in `release' mode): + * boolean variables (consequently, you should **never** enable this + * while compiling in 'release' mode): * - * { + * ``` * _af_debug_disable_horz_hints * _af_debug_disable_vert_hints * _af_debug_disable_blue_hints - * } + * ``` * * Additionally, the following functions provide dumps of various - * internal autofit structures to stdout (using `printf'): + * internal autofit structures to stdout (using 'printf'): * - * { + * ``` * af_glyph_hints_dump_points * af_glyph_hints_dump_segments * af_glyph_hints_dump_edges * af_glyph_hints_get_num_segments * af_glyph_hints_get_segment_offset - * } + * ``` * * As an argument, they use another global variable: * - * { + * ``` * _af_debug_hints - * } + * ``` * - * Please have a look at the `ftgrid' demo program to see how those + * Please have a look at the 'ftgrid' demo program to see how those * variables and macros should be used. * * Do not #undef these macros here since the build system might define @@ -466,16 +462,16 @@ FT_BEGIN_HEADER * * Memory Debugging * - * FreeType now comes with an integrated memory debugger that is - * capable of detecting simple errors like memory leaks or double - * deletes. To compile it within your build of the library, you - * should define FT_DEBUG_MEMORY here. + * FreeType now comes with an integrated memory debugger that is capable + * of detecting simple errors like memory leaks or double deletes. To + * compile it within your build of the library, you should define + * FT_DEBUG_MEMORY here. * - * Note that the memory debugger is only activated at runtime when - * when the _environment_ variable `FT2_DEBUG_MEMORY' is defined also! + * Note that the memory debugger is only activated at runtime when when + * the _environment_ variable `FT2_DEBUG_MEMORY` is defined also! * - * Do not #undef this macro here since the build system might define - * it for certain configurations only. + * Do not #undef this macro here since the build system might define it + * for certain configurations only. */ /* #define FT_DEBUG_MEMORY */ @@ -484,13 +480,13 @@ FT_BEGIN_HEADER * * Module errors * - * If this macro is set (which is _not_ the default), the higher byte - * of an error code gives the module in which the error has occurred, - * while the lower byte is the real error code. + * If this macro is set (which is _not_ the default), the higher byte of + * an error code gives the module in which the error has occurred, while + * the lower byte is the real error code. * - * Setting this macro makes sense for debugging purposes only, since - * it would break source compatibility of certain programs that use - * FreeType 2. + * Setting this macro makes sense for debugging purposes only, since it + * would break source compatibility of certain programs that use FreeType + * 2. * * More details can be found in the files ftmoderr.h and fterrors.h. */ @@ -508,9 +504,9 @@ FT_BEGIN_HEADER /************************************************************************** * - * Define TT_CONFIG_OPTION_EMBEDDED_BITMAPS if you want to support - * embedded bitmaps in all formats using the SFNT module (namely - * TrueType & OpenType). + * Define TT_CONFIG_OPTION_EMBEDDED_BITMAPS if you want to support embedded + * bitmaps in all formats using the SFNT module (namely TrueType & + * OpenType). */ #define TT_CONFIG_OPTION_EMBEDDED_BITMAPS @@ -526,29 +522,28 @@ FT_BEGIN_HEADER /************************************************************************** * - * Define TT_CONFIG_OPTION_POSTSCRIPT_NAMES if you want to be able to - * load and enumerate the glyph Postscript names in a TrueType or - * OpenType file. + * Define TT_CONFIG_OPTION_POSTSCRIPT_NAMES if you want to be able to load + * and enumerate the glyph Postscript names in a TrueType or OpenType file. * - * Note that when you do not compile the `PSNames' module by undefining - * the above FT_CONFIG_OPTION_POSTSCRIPT_NAMES, the `sfnt' module will - * contain additional code used to read the PS Names table from a font. + * Note that when you do not compile the 'PSNames' module by undefining the + * above FT_CONFIG_OPTION_POSTSCRIPT_NAMES, the 'sfnt' module will contain + * additional code used to read the PS Names table from a font. * - * (By default, the module uses `PSNames' to extract glyph names.) + * (By default, the module uses 'PSNames' to extract glyph names.) */ #define TT_CONFIG_OPTION_POSTSCRIPT_NAMES /************************************************************************** * - * Define TT_CONFIG_OPTION_SFNT_NAMES if your applications need to - * access the internal name table in a SFNT-based format like TrueType - * or OpenType. The name table contains various strings used to - * describe the font, like family name, copyright, version, etc. It - * does not contain any glyph name though. + * Define TT_CONFIG_OPTION_SFNT_NAMES if your applications need to access + * the internal name table in a SFNT-based format like TrueType or + * OpenType. The name table contains various strings used to describe the + * font, like family name, copyright, version, etc. It does not contain + * any glyph name though. * * Accessing SFNT names is done through the functions declared in - * `ftsnames.h'. + * `ftsnames.h`. */ #define TT_CONFIG_OPTION_SFNT_NAMES @@ -581,54 +576,52 @@ FT_BEGIN_HEADER /************************************************************************** * - * Define TT_CONFIG_OPTION_BYTECODE_INTERPRETER if you want to compile - * a bytecode interpreter in the TrueType driver. + * Define TT_CONFIG_OPTION_BYTECODE_INTERPRETER if you want to compile a + * bytecode interpreter in the TrueType driver. * * By undefining this, you will only compile the code necessary to load * TrueType glyphs without hinting. * - * Do not #undef this macro here, since the build system might - * define it for certain configurations only. + * Do not #undef this macro here, since the build system might define it + * for certain configurations only. */ #define TT_CONFIG_OPTION_BYTECODE_INTERPRETER /************************************************************************** * - * Define TT_CONFIG_OPTION_SUBPIXEL_HINTING if you want to compile - * subpixel hinting support into the TrueType driver. This modifies the - * TrueType hinting mechanism when anything but FT_RENDER_MODE_MONO is - * requested. + * Define TT_CONFIG_OPTION_SUBPIXEL_HINTING if you want to compile subpixel + * hinting support into the TrueType driver. This modifies the TrueType + * hinting mechanism when anything but FT_RENDER_MODE_MONO is requested. * * In particular, it modifies the bytecode interpreter to interpret (or - * not) instructions in a certain way so that all TrueType fonts look - * like they do in a Windows ClearType (DirectWrite) environment. See - * [1] for a technical overview on what this means. See `ttinterp.h' - * for more details on the LEAN option. + * not) instructions in a certain way so that all TrueType fonts look like + * they do in a Windows ClearType (DirectWrite) environment. See [1] for a + * technical overview on what this means. See `ttinterp.h` for more + * details on the LEAN option. * * There are three possible values. * * Value 1: - * This value is associated with the `Infinality' moniker, - * contributed by an individual nicknamed Infinality with the goal of - * making TrueType fonts render better than on Windows. A high - * amount of configurability and flexibility, down to rules for - * single glyphs in fonts, but also very slow. Its experimental and - * slow nature and the original developer losing interest meant that - * this option was never enabled in default builds. + * This value is associated with the 'Infinality' moniker, contributed by + * an individual nicknamed Infinality with the goal of making TrueType + * fonts render better than on Windows. A high amount of configurability + * and flexibility, down to rules for single glyphs in fonts, but also + * very slow. Its experimental and slow nature and the original + * developer losing interest meant that this option was never enabled in + * default builds. * * The corresponding interpreter version is v38. * * Value 2: * The new default mode for the TrueType driver. The Infinality code - * base was stripped to the bare minimum and all configurability - * removed in the name of speed and simplicity. The configurability - * was mainly aimed at legacy fonts like Arial, Times New Roman, or - * Courier. Legacy fonts are fonts that modify vertical stems to - * achieve clean black-and-white bitmaps. The new mode focuses on - * applying a minimal set of rules to all fonts indiscriminately so - * that modern and web fonts render well while legacy fonts render - * okay. + * base was stripped to the bare minimum and all configurability removed + * in the name of speed and simplicity. The configurability was mainly + * aimed at legacy fonts like Arial, Times New Roman, or Courier. Legacy + * fonts are fonts that modify vertical stems to achieve clean + * black-and-white bitmaps. The new mode focuses on applying a minimal + * set of rules to all fonts indiscriminately so that modern and web + * fonts render well while legacy fonts render okay. * * The corresponding interpreter version is v40. * @@ -636,18 +629,18 @@ FT_BEGIN_HEADER * Compile both, making both v38 and v40 available (the latter is the * default). * - * By undefining these, you get rendering behavior like on Windows - * without ClearType, i.e., Windows XP without ClearType enabled and - * Win9x (interpreter version v35). Or not, depending on how much - * hinting blood and testing tears the font designer put into a given - * font. If you define one or both subpixel hinting options, you can - * switch between between v35 and the ones you define (using - * `FT_Property_Set'). + * By undefining these, you get rendering behavior like on Windows without + * ClearType, i.e., Windows XP without ClearType enabled and Win9x + * (interpreter version v35). Or not, depending on how much hinting blood + * and testing tears the font designer put into a given font. If you + * define one or both subpixel hinting options, you can switch between + * between v35 and the ones you define (using `FT_Property_Set`). * * This option requires TT_CONFIG_OPTION_BYTECODE_INTERPRETER to be * defined. * - * [1] https://www.microsoft.com/typography/cleartype/truetypecleartype.aspx + * [1] + * https://www.microsoft.com/typography/cleartype/truetypecleartype.aspx */ /* #define TT_CONFIG_OPTION_SUBPIXEL_HINTING 1 */ #define TT_CONFIG_OPTION_SUBPIXEL_HINTING 2 @@ -656,16 +649,16 @@ FT_BEGIN_HEADER /************************************************************************** * - * Define TT_CONFIG_OPTION_COMPONENT_OFFSET_SCALED to compile the - * TrueType glyph loader to use Apple's definition of how to handle - * component offsets in composite glyphs. + * Define TT_CONFIG_OPTION_COMPONENT_OFFSET_SCALED to compile the TrueType + * glyph loader to use Apple's definition of how to handle component + * offsets in composite glyphs. * - * Apple and MS disagree on the default behavior of component offsets - * in composites. Apple says that they should be scaled by the scaling - * factors in the transformation matrix (roughly, it's more complex) - * while MS says they should not. OpenType defines two bits in the - * composite flags array which can be used to disambiguate, but old - * fonts will not have them. + * Apple and MS disagree on the default behavior of component offsets in + * composites. Apple says that they should be scaled by the scaling + * factors in the transformation matrix (roughly, it's more complex) while + * MS says they should not. OpenType defines two bits in the composite + * flags array which can be used to disambiguate, but old fonts will not + * have them. * * https://www.microsoft.com/typography/otspec/glyf.htm * https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6glyf.html @@ -675,34 +668,33 @@ FT_BEGIN_HEADER /************************************************************************** * - * Define TT_CONFIG_OPTION_GX_VAR_SUPPORT if you want to include - * support for Apple's distortable font technology (fvar, gvar, cvar, - * and avar tables). This has many similarities to Type 1 Multiple - * Masters support. + * Define TT_CONFIG_OPTION_GX_VAR_SUPPORT if you want to include support + * for Apple's distortable font technology (fvar, gvar, cvar, and avar + * tables). This has many similarities to Type 1 Multiple Masters support. */ #define TT_CONFIG_OPTION_GX_VAR_SUPPORT /************************************************************************** * - * Define TT_CONFIG_OPTION_BDF if you want to include support for - * an embedded `BDF ' table within SFNT-based bitmap formats. + * Define TT_CONFIG_OPTION_BDF if you want to include support for an + * embedded 'BDF ' table within SFNT-based bitmap formats. */ #define TT_CONFIG_OPTION_BDF /************************************************************************** * - * Option TT_CONFIG_OPTION_MAX_RUNNABLE_OPCODES controls the maximum - * number of bytecode instructions executed for a single run of the - * bytecode interpreter, needed to prevent infinite loops. You don't - * want to change this except for very special situations (e.g., making - * a library fuzzer spend less time to handle broken fonts). + * Option TT_CONFIG_OPTION_MAX_RUNNABLE_OPCODES controls the maximum number + * of bytecode instructions executed for a single run of the bytecode + * interpreter, needed to prevent infinite loops. You don't want to change + * this except for very special situations (e.g., making a library fuzzer + * spend less time to handle broken fonts). * * It is not expected that this value is ever modified by a configuring - * script; instead, it gets surrounded with #ifndef ... #endif so that - * the value can be set as a preprocessor option on the compiler's - * command line. + * script; instead, it gets surrounded with #ifndef ... #endif so that the + * value can be set as a preprocessor option on the compiler's command + * line. */ #ifndef TT_CONFIG_OPTION_MAX_RUNNABLE_OPCODES #define TT_CONFIG_OPTION_MAX_RUNNABLE_OPCODES 1000000L @@ -720,9 +712,8 @@ FT_BEGIN_HEADER /************************************************************************** * - * T1_MAX_DICT_DEPTH is the maximum depth of nest dictionaries and - * arrays in the Type 1 stream (see t1load.c). A minimum of 4 is - * required. + * T1_MAX_DICT_DEPTH is the maximum depth of nest dictionaries and arrays + * in the Type 1 stream (see t1load.c). A minimum of 4 is required. */ #define T1_MAX_DICT_DEPTH 5 @@ -747,29 +738,28 @@ FT_BEGIN_HEADER /************************************************************************** * - * Define this configuration macro if you want to prevent the - * compilation of `t1afm', which is in charge of reading Type 1 AFM - * files into an existing face. Note that if set, the T1 driver will be - * unable to produce kerning distances. + * Define this configuration macro if you want to prevent the compilation + * of 't1afm', which is in charge of reading Type 1 AFM files into an + * existing face. Note that if set, the T1 driver will be unable to + * produce kerning distances. */ #undef T1_CONFIG_OPTION_NO_AFM /************************************************************************** * - * Define this configuration macro if you want to prevent the - * compilation of the Multiple Masters font support in the Type 1 - * driver. + * Define this configuration macro if you want to prevent the compilation + * of the Multiple Masters font support in the Type 1 driver. */ #undef T1_CONFIG_OPTION_NO_MM_SUPPORT /************************************************************************** * - * T1_CONFIG_OPTION_OLD_ENGINE controls whether the pre-Adobe Type 1 - * engine gets compiled into FreeType. If defined, it is possible to - * switch between the two engines using the `hinting-engine' property of - * the type1 driver module. + * T1_CONFIG_OPTION_OLD_ENGINE controls whether the pre-Adobe Type 1 engine + * gets compiled into FreeType. If defined, it is possible to switch + * between the two engines using the 'hinting-engine' property of the type1 + * driver module. */ /* #define T1_CONFIG_OPTION_OLD_ENGINE */ @@ -787,12 +777,11 @@ FT_BEGIN_HEADER * * Using CFF_CONFIG_OPTION_DARKENING_PARAMETER_{X,Y}{1,2,3,4} it is * possible to set up the default values of the four control points that - * define the stem darkening behaviour of the (new) CFF engine. For - * more details please read the documentation of the - * `darkening-parameters' property (file `ftdriver.h'), which allows the - * control at run-time. + * define the stem darkening behaviour of the (new) CFF engine. For more + * details please read the documentation of the 'darkening-parameters' + * property (file `ftdriver.h`), which allows the control at run-time. * - * Do *not* undefine these macros! + * Do **not** undefine these macros! */ #define CFF_CONFIG_OPTION_DARKENING_PARAMETER_X1 500 #define CFF_CONFIG_OPTION_DARKENING_PARAMETER_Y1 400 @@ -809,10 +798,10 @@ FT_BEGIN_HEADER /************************************************************************** * - * CFF_CONFIG_OPTION_OLD_ENGINE controls whether the pre-Adobe CFF - * engine gets compiled into FreeType. If defined, it is possible to - * switch between the two engines using the `hinting-engine' property of - * the cff driver module. + * CFF_CONFIG_OPTION_OLD_ENGINE controls whether the pre-Adobe CFF engine + * gets compiled into FreeType. If defined, it is possible to switch + * between the two engines using the 'hinting-engine' property of the cff + * driver module. */ /* #define CFF_CONFIG_OPTION_OLD_ENGINE */ @@ -828,18 +817,18 @@ FT_BEGIN_HEADER /************************************************************************** * - * There are many PCF fonts just called `Fixed' which look completely - * different, and which have nothing to do with each other. When - * selecting `Fixed' in KDE or Gnome one gets results that appear rather - * random, the style changes often if one changes the size and one - * cannot select some fonts at all. This option makes the PCF module - * prepend the foundry name (plus a space) to the family name. + * There are many PCF fonts just called 'Fixed' which look completely + * different, and which have nothing to do with each other. When selecting + * 'Fixed' in KDE or Gnome one gets results that appear rather random, the + * style changes often if one changes the size and one cannot select some + * fonts at all. This option makes the PCF module prepend the foundry name + * (plus a space) to the family name. * - * We also check whether we have `wide' characters; all put together, we - * get family names like `Sony Fixed' or `Misc Fixed Wide'. + * We also check whether we have 'wide' characters; all put together, we + * get family names like 'Sony Fixed' or 'Misc Fixed Wide'. * * If this option is activated, it can be controlled with the - * `no-long-family-names' property of the pcf driver module. + * 'no-long-family-names' property of the pcf driver module. */ /* #define PCF_CONFIG_OPTION_LONG_FAMILY_NAMES */ @@ -862,44 +851,44 @@ FT_BEGIN_HEADER /************************************************************************** * - * Compile autofit module with fallback Indic script support, covering - * some scripts that the `latin' submodule of the autofit module doesn't - * (yet) handle. + * Compile autofit module with fallback Indic script support, covering some + * scripts that the 'latin' submodule of the autofit module doesn't (yet) + * handle. */ #define AF_CONFIG_OPTION_INDIC /************************************************************************** * - * Compile autofit module with warp hinting. The idea of the warping - * code is to slightly scale and shift a glyph within a single dimension - * so that as much of its segments are aligned (more or less) on the - * grid. To find out the optimal scaling and shifting value, various - * parameter combinations are tried and scored. + * Compile autofit module with warp hinting. The idea of the warping code + * is to slightly scale and shift a glyph within a single dimension so that + * as much of its segments are aligned (more or less) on the grid. To find + * out the optimal scaling and shifting value, various parameter + * combinations are tried and scored. * * This experimental option is active only if the rendering mode is * FT_RENDER_MODE_LIGHT; you can switch warping on and off with the - * `warping' property of the auto-hinter (see file `ftdriver.h' for more + * 'warping' property of the auto-hinter (see file `ftdriver.h` for more * information; by default it is switched off). */ #define AF_CONFIG_OPTION_USE_WARPER /************************************************************************** * - * Use TrueType-like size metrics for `light' auto-hinting. + * Use TrueType-like size metrics for 'light' auto-hinting. * * It is strongly recommended to avoid this option, which exists only to - * help some legacy applications retain its appearance and behaviour - * with respect to auto-hinted TrueType fonts. + * help some legacy applications retain its appearance and behaviour with + * respect to auto-hinted TrueType fonts. * * The very reason this option exists at all are GNU/Linux distributions * like Fedora that did not un-patch the following change (which was * present in FreeType between versions 2.4.6 and 2.7.1, inclusive). * - * { + * ``` * 2011-07-16 Steven Chu <steven.f.chu@gmail.com> * * [truetype] Fix metrics on size request for scalable fonts. - * } + * ``` * * This problematic commit is now reverted (more or less). */ @@ -909,8 +898,8 @@ FT_BEGIN_HEADER /* - * This macro is obsolete. Support has been removed in FreeType - * version 2.5. + * This macro is obsolete. Support has been removed in FreeType version + * 2.5. */ /* #define FT_CONFIG_OPTION_OLD_INTERNALS */ diff --git a/include/freetype/config/ftstdlib.h b/include/freetype/config/ftstdlib.h index a744d0d05..a11db25f8 100644 --- a/include/freetype/config/ftstdlib.h +++ b/include/freetype/config/ftstdlib.h @@ -41,17 +41,17 @@ * * integer limits * - * UINT_MAX and ULONG_MAX are used to automatically compute the size - * of `int' and `long' in bytes at compile-time. So far, this works - * for all platforms the library has been tested on. + * UINT_MAX and ULONG_MAX are used to automatically compute the size of + * 'int' and 'long' in bytes at compile-time. So far, this works for all + * platforms the library has been tested on. * - * Note that on the extremely rare platforms that do not provide - * integer types that are _exactly_ 16 and 32 bits wide (e.g. some - * old Crays where `int' is 36 bits), we do not make any guarantee - * about the correct behaviour of FT2 with all fonts. + * Note that on the extremely rare platforms that do not provide integer + * types that are _exactly_ 16 and 32 bits wide (e.g. some old Crays where + * 'int' is 36 bits), we do not make any guarantee about the correct + * behaviour of FT2 with all fonts. * - * In these case, `ftconfig.h' will refuse to compile anyway with a - * message like `couldn't find 32-bit type' or something similar. + * In these case, `ftconfig.h` will refuse to compile anyway with a message + * like 'couldn't find 32-bit type' or something similar. * */ diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h index ace6e2b70..ca4d1cc67 100644 --- a/include/freetype/freetype.h +++ b/include/freetype/freetype.h @@ -51,21 +51,20 @@ FT_BEGIN_HEADER * How client applications should include FreeType header files. * * @description: - * To be as flexible as possible (and for historical reasons), - * FreeType uses a very special inclusion scheme to load header - * files, for example + * To be as flexible as possible (and for historical reasons), FreeType + * uses a very special inclusion scheme to load header files, for example * - * { + * ``` * #include <ft2build.h> * * #include FT_FREETYPE_H * #include FT_OUTLINE_H - * } + * ``` * - * A compiler and its preprocessor only needs an include path to find - * the file `ft2build.h'; the exact locations and names of the other - * FreeType header files are hidden by @header_file_macros, loaded by - * `ft2build.h'. The API documentation always gives the header macro + * A compiler and its preprocessor only needs an include path to find the + * file `ft2build.h`; the exact locations and names of the other FreeType + * header files are hidden by @header_file_macros, loaded by + * `ft2build.h`. The API documentation always gives the header macro * name needed for a particular function. * */ @@ -83,10 +82,10 @@ FT_BEGIN_HEADER * How client applications should allocate FreeType data structures. * * @description: - * FreeType assumes that structures allocated by the user and passed - * as arguments are zeroed out except for the actual data. In other - * words, it is recommended to use `calloc' (or variants of it) - * instead of `malloc' for allocation. + * FreeType assumes that structures allocated by the user and passed as + * arguments are zeroed out except for the actual data. In other words, + * it is recommended to use 'calloc' (or variants of it) instead of + * 'malloc' for allocation. * */ @@ -269,10 +268,10 @@ FT_BEGIN_HEADER * FT_Glyph_Metrics * * @description: - * A structure to model the metrics of a single glyph. The values - * are expressed in 26.6 fractional pixel format; if the flag - * @FT_LOAD_NO_SCALE has been used while loading the glyph, values - * are expressed in font units instead. + * A structure to model the metrics of a single glyph. The values are + * expressed in 26.6 fractional pixel format; if the flag + * @FT_LOAD_NO_SCALE has been used while loading the glyph, values are + * expressed in font units instead. * * @fields: * width :: @@ -294,25 +293,25 @@ FT_BEGIN_HEADER * Left side bearing for vertical layout. * * vertBearingY :: - * Top side bearing for vertical layout. Larger positive values - * mean further below the vertical glyph origin. + * Top side bearing for vertical layout. Larger positive values mean + * further below the vertical glyph origin. * * vertAdvance :: - * Advance height for vertical layout. Positive values mean the - * glyph has a positive advance downward. + * Advance height for vertical layout. Positive values mean the glyph + * has a positive advance downward. * * @note: * If not disabled with @FT_LOAD_NO_HINTING, the values represent * dimensions of the hinted glyph (in case hinting is applicable). * * Stroking a glyph with an outside border does not increase - * `horiAdvance' or `vertAdvance'; you have to manually adjust these + * `horiAdvance` or `vertAdvance`; you have to manually adjust these * values to account for the added width and height. * - * FreeType doesn't use the `VORG' table data for CFF fonts because - * it doesn't have an interface to quickly retrieve the glyph height. - * The y~coordinate of the vertical origin can be simply computed as - * `vertBearingY + height' after loading a glyph. + * FreeType doesn't use the 'VORG' table data for CFF fonts because it + * doesn't have an interface to quickly retrieve the glyph height. The + * y~coordinate of the vertical origin can be simply computed as + * `vertBearingY + height` after loading a glyph. */ typedef struct FT_Glyph_Metrics_ { @@ -336,42 +335,38 @@ FT_BEGIN_HEADER * FT_Bitmap_Size * * @description: - * This structure models the metrics of a bitmap strike (i.e., a set - * of glyphs for a given point size and resolution) in a bitmap font. - * It is used for the `available_sizes' field of @FT_Face. + * This structure models the metrics of a bitmap strike (i.e., a set of + * glyphs for a given point size and resolution) in a bitmap font. It is + * used for the `available_sizes` field of @FT_Face. * * @fields: * height :: - * The vertical distance, in pixels, between two - * consecutive baselines. It is always positive. + * The vertical distance, in pixels, between two consecutive baselines. + * It is always positive. * * width :: - * The average width, in pixels, of all glyphs in the - * strike. + * The average width, in pixels, of all glyphs in the strike. * * size :: - * The nominal size of the strike in 26.6 fractional - * points. This field is not very useful. + * The nominal size of the strike in 26.6 fractional points. This + * field is not very useful. * * x_ppem :: - * The horizontal ppem (nominal width) in 26.6 fractional - * pixels. + * The horizontal ppem (nominal width) in 26.6 fractional pixels. * * y_ppem :: - * The vertical ppem (nominal height) in 26.6 fractional - * pixels. + * The vertical ppem (nominal height) in 26.6 fractional pixels. * * @note: * Windows FNT: - * The nominal size given in a FNT font is not reliable. If the - * driver finds it incorrect, it sets `size' to some calculated - * values, and `x_ppem' and `y_ppem' to the pixel width and height - * given in the font, respectively. + * The nominal size given in a FNT font is not reliable. If the driver + * finds it incorrect, it sets 'size' to some calculated values, and + * `x_ppem` and `y_ppem` to the pixel width and height given in the + * font, respectively. * * TrueType embedded bitmaps: - * `size', `width', and `height' values are not contained in the - * bitmap strike itself. They are computed from the global font - * parameters. + * 'size', 'width', and 'height' values are not contained in the bitmap + * strike itself. They are computed from the global font parameters. */ typedef struct FT_Bitmap_Size_ { @@ -400,23 +395,22 @@ FT_BEGIN_HEADER * FT_Library * * @description: - * A handle to a FreeType library instance. Each `library' is - * completely independent from the others; it is the `root' of a set - * of objects like fonts, faces, sizes, etc. + * A handle to a FreeType library instance. Each 'library' is completely + * independent from the others; it is the 'root' of a set of objects like + * fonts, faces, sizes, etc. * * It also embeds a memory manager (see @FT_Memory), as well as a * scan-line converter object (see @FT_Raster). * * [Since 2.5.6] In multi-threaded applications it is easiest to use one - * `FT_Library' object per thread. In case this is too cumbersome, a - * single `FT_Library' object across threads is possible also, as long - * as a mutex lock is used around @FT_New_Face and @FT_Done_Face. + * `FT_Library` object per thread. In case this is too cumbersome, a + * single `FT_Library` object across threads is possible also, as long as + * a mutex lock is used around @FT_New_Face and @FT_Done_Face. * * @note: * Library objects are normally created by @FT_Init_FreeType, and * destroyed with @FT_Done_FreeType. If you need reference-counting - * (cf. @FT_Reference_Library), use @FT_New_Library and - * @FT_Done_Library. + * (cf. @FT_Reference_Library), use @FT_New_Library and @FT_Done_Library. */ typedef struct FT_LibraryRec_ *FT_Library; @@ -434,9 +428,9 @@ FT_BEGIN_HEADER * FT_Module * * @description: - * A handle to a given FreeType module object. A module can be a - * font driver, a renderer, or anything else that provides services - * to the former. + * A handle to a given FreeType module object. A module can be a font + * driver, a renderer, or anything else that provides services to the + * former. */ typedef struct FT_ModuleRec_* FT_Module; @@ -447,8 +441,8 @@ FT_BEGIN_HEADER * FT_Driver * * @description: - * A handle to a given FreeType font driver object. A font driver - * is a module capable of creating faces from font files. + * A handle to a given FreeType font driver object. A font driver is a + * module capable of creating faces from font files. */ typedef struct FT_DriverRec_* FT_Driver; @@ -460,9 +454,8 @@ FT_BEGIN_HEADER * * @description: * A handle to a given FreeType renderer. A renderer is a module in - * charge of converting a glyph's outline image to a bitmap. It - * supports a single glyph image format, and one or more target - * surface depths. + * charge of converting a glyph's outline image to a bitmap. It supports + * a single glyph image format, and one or more target surface depths. */ typedef struct FT_RendererRec_* FT_Renderer; @@ -480,25 +473,24 @@ FT_BEGIN_HEADER * FT_Face * * @description: - * A handle to a typographic face object. A face object models a - * given typeface, in a given style. + * A handle to a typographic face object. A face object models a given + * typeface, in a given style. * * @note: - * A face object also owns a single @FT_GlyphSlot object, as well - * as one or more @FT_Size objects. + * A face object also owns a single @FT_GlyphSlot object, as well as one + * or more @FT_Size objects. * - * Use @FT_New_Face or @FT_Open_Face to create a new face object from - * a given filepath or a custom input stream. + * Use @FT_New_Face or @FT_Open_Face to create a new face object from a + * given filepath or a custom input stream. * * Use @FT_Done_Face to destroy it (along with its slot and sizes). * - * An `FT_Face' object can only be safely used from one thread at a - * time. Similarly, creation and destruction of `FT_Face' with the - * same @FT_Library object can only be done from one thread at a - * time. On the other hand, functions like @FT_Load_Glyph and its - * siblings are thread-safe and do not need the lock to be held as - * long as the same `FT_Face' object is not used from multiple - * threads at the same time. + * An `FT_Face` object can only be safely used from one thread at a time. + * Similarly, creation and destruction of `FT_Face` with the same + * @FT_Library object can only be done from one thread at a time. On the + * other hand, functions like @FT_Load_Glyph and its siblings are + * thread-safe and do not need the lock to be held as long as the same + * `FT_Face` object is not used from multiple threads at the same time. * * @also: * See @FT_FaceRec for the publicly accessible fields of a given face @@ -513,23 +505,22 @@ FT_BEGIN_HEADER * FT_Size * * @description: - * A handle to an object that models a face scaled to a given - * character size. + * A handle to an object that models a face scaled to a given character + * size. * * @note: - * An @FT_Face has one _active_ @FT_Size object that is used by - * functions like @FT_Load_Glyph to determine the scaling - * transformation that in turn is used to load and hint glyphs and - * metrics. + * An @FT_Face has one _active_ @FT_Size object that is used by functions + * like @FT_Load_Glyph to determine the scaling transformation that in + * turn is used to load and hint glyphs and metrics. * - * You can use @FT_Set_Char_Size, @FT_Set_Pixel_Sizes, - * @FT_Request_Size or even @FT_Select_Size to change the content - * (i.e., the scaling values) of the active @FT_Size. + * You can use @FT_Set_Char_Size, @FT_Set_Pixel_Sizes, @FT_Request_Size + * or even @FT_Select_Size to change the content (i.e., the scaling + * values) of the active @FT_Size. * - * You can use @FT_New_Size to create additional size objects for a - * given @FT_Face, but they won't be used by other functions until - * you activate it through @FT_Activate_Size. Only one size can be - * activated at any given time per face. + * You can use @FT_New_Size to create additional size objects for a given + * @FT_Face, but they won't be used by other functions until you activate + * it through @FT_Activate_Size. Only one size can be activated at any + * given time per face. * * @also: * See @FT_SizeRec for the publicly accessible fields of a given size @@ -544,13 +535,12 @@ FT_BEGIN_HEADER * FT_GlyphSlot * * @description: - * A handle to a given `glyph slot'. A slot is a container that can - * hold any of the glyphs contained in its parent face. + * A handle to a given 'glyph slot'. A slot is a container that can hold + * any of the glyphs contained in its parent face. * - * In other words, each time you call @FT_Load_Glyph or - * @FT_Load_Char, the slot's content is erased by the new glyph data, - * i.e., the glyph's metrics, its image (bitmap or outline), and - * other control information. + * In other words, each time you call @FT_Load_Glyph or @FT_Load_Char, + * the slot's content is erased by the new glyph data, i.e., the glyph's + * metrics, its image (bitmap or outline), and other control information. * * @also: * See @FT_GlyphSlotRec for the publicly accessible glyph fields. @@ -564,26 +554,26 @@ FT_BEGIN_HEADER * FT_CharMap * * @description: - * A handle to a character map (usually abbreviated to `charmap'). A - * charmap is used to translate character codes in a given encoding - * into glyph indexes for its parent's face. Some font formats may - * provide several charmaps per font. + * A handle to a character map (usually abbreviated to 'charmap'). A + * charmap is used to translate character codes in a given encoding into + * glyph indexes for its parent's face. Some font formats may provide + * several charmaps per font. * - * Each face object owns zero or more charmaps, but only one of them - * can be `active', providing the data used by @FT_Get_Char_Index or + * Each face object owns zero or more charmaps, but only one of them can + * be 'active', providing the data used by @FT_Get_Char_Index or * @FT_Load_Char. * * The list of available charmaps in a face is available through the - * `face->num_charmaps' and `face->charmaps' fields of @FT_FaceRec. + * `face->num_charmaps` and `face->charmaps` fields of @FT_FaceRec. * - * The currently active charmap is available as `face->charmap'. - * You should call @FT_Set_Charmap to change it. + * The currently active charmap is available as `face->charmap`. You + * should call @FT_Set_Charmap to change it. * * @note: * When a new face is created (either through @FT_New_Face or - * @FT_Open_Face), the library looks for a Unicode charmap within - * the list and automatically activates it. If there is no Unicode - * charmap, FreeType doesn't set an `active' charmap. + * @FT_Open_Face), the library looks for a Unicode charmap within the + * list and automatically activates it. If there is no Unicode charmap, + * FreeType doesn't set an 'active' charmap. * * @also: * See @FT_CharMapRec for the publicly accessible fields of a given @@ -599,16 +589,15 @@ FT_BEGIN_HEADER * * @description: * This macro converts four-letter tags into an unsigned long. It is - * used to define `encoding' identifiers (see @FT_Encoding). + * used to define 'encoding' identifiers (see @FT_Encoding). * * @note: - * Since many 16-bit compilers don't like 32-bit enumerations, you - * should redefine this macro in case of problems to something like - * this: + * Since many 16-bit compilers don't like 32-bit enumerations, you should + * redefine this macro in case of problems to something like this: * - * { + * ``` * #define FT_ENC_TAG( value, a, b, c, d ) value - * } + * ``` * * to get a simple enumeration without assigning special numbers. */ @@ -629,8 +618,8 @@ FT_BEGIN_HEADER * FT_Encoding * * @description: - * An enumeration to specify character sets supported by charmaps. - * Used in the @FT_Select_Charmap API function. + * An enumeration to specify character sets supported by charmaps. Used + * in the @FT_Select_Charmap API function. * * @note: * Despite the name, this enumeration lists specific character @@ -645,43 +634,42 @@ FT_BEGIN_HEADER * and Windows FNT; see below for more information. * * FT_ENCODING_UNICODE :: - * The Unicode character set. This value covers all versions of - * the Unicode repertoire, including ASCII and Latin-1. Most fonts - * include a Unicode charmap, but not all of them. + * The Unicode character set. This value covers all versions of the + * Unicode repertoire, including ASCII and Latin-1. Most fonts include + * a Unicode charmap, but not all of them. * - * For example, if you want to access Unicode value U+1F028 (and - * the font contains it), use value 0x1F028 as the input value for + * For example, if you want to access Unicode value U+1F028 (and the + * font contains it), use value 0x1F028 as the input value for * @FT_Get_Char_Index. * * FT_ENCODING_MS_SYMBOL :: - * Microsoft Symbol encoding, used to encode mathematical symbols - * and wingdings. For more information, see - * `https://www.microsoft.com/typography/otspec/recom.htm', - * `http://www.kostis.net/charsets/symbol.htm', and - * `http://www.kostis.net/charsets/wingding.htm'. + * Microsoft Symbol encoding, used to encode mathematical symbols and + * wingdings. For more information, see + * 'https://www.microsoft.com/typography/otspec/recom.htm', + * 'http://www.kostis.net/charsets/symbol.htm', and + * 'http://www.kostis.net/charsets/wingding.htm'. * * This encoding uses character codes from the PUA (Private Unicode * Area) in the range U+F020-U+F0FF. * * FT_ENCODING_SJIS :: * Shift JIS encoding for Japanese. More info at - * `https://en.wikipedia.org/wiki/Shift_JIS'. See note on - * multi-byte encodings below. + * 'https://en.wikipedia.org/wiki/Shift_JIS'. See note on multi-byte + * encodings below. * * FT_ENCODING_PRC :: * Corresponds to encoding systems mainly for Simplified Chinese as - * used in People's Republic of China (PRC). The encoding layout - * is based on GB~2312 and its supersets GBK and GB~18030. + * used in People's Republic of China (PRC). The encoding layout is + * based on GB~2312 and its supersets GBK and GB~18030. * * FT_ENCODING_BIG5 :: - * Corresponds to an encoding system for Traditional Chinese as - * used in Taiwan and Hong Kong. + * Corresponds to an encoding system for Traditional Chinese as used in + * Taiwan and Hong Kong. * * FT_ENCODING_WANSUNG :: - * Corresponds to the Korean encoding system known as Extended - * Wansung (MS Windows code page 949). - * For more information see - * `https://www.unicode.org/Public/MAPPINGS/VENDORS/MICSFT/WindowsBestFit/bestfit949.txt'. + * Corresponds to the Korean encoding system known as Extended Wansung + * (MS Windows code page 949). For more information see + * 'https://www.unicode.org/Public/MAPPINGS/VENDORS/MICSFT/WindowsBestFit/bestfit949.txt'. * * FT_ENCODING_JOHAB :: * The Korean standard character set (KS~C 5601-1992), which @@ -689,12 +677,12 @@ FT_BEGIN_HEADER * includes all possible Hangul character combinations. * * FT_ENCODING_ADOBE_LATIN_1 :: - * Corresponds to a Latin-1 encoding as defined in a Type~1 - * PostScript font. It is limited to 256 character codes. + * Corresponds to a Latin-1 encoding as defined in a Type~1 PostScript + * font. It is limited to 256 character codes. * * FT_ENCODING_ADOBE_STANDARD :: - * Adobe Standard encoding, as found in Type~1, CFF, and - * OpenType/CFF fonts. It is limited to 256 character codes. + * Adobe Standard encoding, as found in Type~1, CFF, and OpenType/CFF + * fonts. It is limited to 256 character codes. * * FT_ENCODING_ADOBE_EXPERT :: * Adobe Expert encoding, as found in Type~1, CFF, and OpenType/CFF @@ -705,9 +693,9 @@ FT_BEGIN_HEADER * OpenType/CFF fonts. It is limited to 256 character codes. * * FT_ENCODING_APPLE_ROMAN :: - * Apple roman encoding. Many TrueType and OpenType fonts contain - * a charmap for this 8-bit encoding, since older versions of Mac - * OS are able to use it. + * Apple roman encoding. Many TrueType and OpenType fonts contain a + * charmap for this 8-bit encoding, since older versions of Mac OS are + * able to use it. * * FT_ENCODING_OLD_LATIN_2 :: * This value is deprecated and was neither used nor reported by @@ -731,42 +719,39 @@ FT_BEGIN_HEADER * @note: * By default, FreeType enables a Unicode charmap and tags it with * FT_ENCODING_UNICODE when it is either provided or can be generated - * from PostScript glyph name dictionaries in the font file. - * All other encodings are considered legacy and tagged only if - * explicitly defined in the font file. Otherwise, FT_ENCODING_NONE - * is used. - * - * FT_ENCODING_NONE is set by the BDF and PCF drivers if the charmap - * is neither Unicode nor ISO-8859-1 (otherwise it is set to - * FT_ENCODING_UNICODE). Use @FT_Get_BDF_Charset_ID to find out - * which encoding is really present. If, for example, the - * `cs_registry' field is `KOI8' and the `cs_encoding' field is `R', - * the font is encoded in KOI8-R. + * from PostScript glyph name dictionaries in the font file. All other + * encodings are considered legacy and tagged only if explicitly defined + * in the font file. Otherwise, FT_ENCODING_NONE is used. + * + * FT_ENCODING_NONE is set by the BDF and PCF drivers if the charmap is + * neither Unicode nor ISO-8859-1 (otherwise it is set to + * FT_ENCODING_UNICODE). Use @FT_Get_BDF_Charset_ID to find out which + * encoding is really present. If, for example, the `cs_registry` field + * is 'KOI8' and the `cs_encoding` field is 'R', the font is encoded in + * KOI8-R. * * FT_ENCODING_NONE is always set (with a single exception) by the - * winfonts driver. Use @FT_Get_WinFNT_Header and examine the - * `charset' field of the @FT_WinFNT_HeaderRec structure to find out - * which encoding is really present. For example, - * @FT_WinFNT_ID_CP1251 (204) means Windows code page 1251 (for - * Russian). - * - * FT_ENCODING_NONE is set if `platform_id' is @TT_PLATFORM_MACINTOSH - * and `encoding_id' is not `TT_MAC_ID_ROMAN' (otherwise it is set to + * winfonts driver. Use @FT_Get_WinFNT_Header and examine the 'charset' + * field of the @FT_WinFNT_HeaderRec structure to find out which encoding + * is really present. For example, @FT_WinFNT_ID_CP1251 (204) means + * Windows code page 1251 (for Russian). + * + * FT_ENCODING_NONE is set if `platform_id` is @TT_PLATFORM_MACINTOSH and + * `encoding_id` is not `TT_MAC_ID_ROMAN` (otherwise it is set to * FT_ENCODING_APPLE_ROMAN). * - * If `platform_id' is @TT_PLATFORM_MACINTOSH, use the function - * @FT_Get_CMap_Language_ID to query the Mac language ID that may - * be needed to be able to distinguish Apple encoding variants. See + * If `platform_id` is @TT_PLATFORM_MACINTOSH, use the function + * @FT_Get_CMap_Language_ID to query the Mac language ID that may be + * needed to be able to distinguish Apple encoding variants. See * * https://www.unicode.org/Public/MAPPINGS/VENDORS/APPLE/Readme.txt * - * to get an idea how to do that. Basically, if the language ID - * is~0, don't use it, otherwise subtract 1 from the language ID. - * Then examine `encoding_id'. If, for example, `encoding_id' is - * `TT_MAC_ID_ROMAN' and the language ID (minus~1) is - * `TT_MAC_LANGID_GREEK', it is the Greek encoding, not Roman. - * `TT_MAC_ID_ARABIC' with `TT_MAC_LANGID_FARSI' means the Farsi - * variant the Arabic encoding. + * to get an idea how to do that. Basically, if the language ID is~0, + * don't use it, otherwise subtract 1 from the language ID. Then examine + * `encoding_id`. If, for example, `encoding_id` is `TT_MAC_ID_ROMAN` + * and the language ID (minus~1) is `TT_MAC_LANGID_GREEK`, it is the + * Greek encoding, not Roman. `TT_MAC_ID_ARABIC` with + * `TT_MAC_LANGID_FARSI` means the Farsi variant the Arabic encoding. */ typedef enum FT_Encoding_ { @@ -833,14 +818,13 @@ FT_BEGIN_HEADER * A handle to the parent face object. * * encoding :: - * An @FT_Encoding tag identifying the charmap. Use - * this with @FT_Select_Charmap. + * An @FT_Encoding tag identifying the charmap. Use this with + * @FT_Select_Charmap. * * platform_id :: - * An ID number describing the platform for the - * following encoding ID. This comes directly from - * the TrueType specification and gets emulated for - * other formats. + * An ID number describing the platform for the following encoding ID. + * This comes directly from the TrueType specification and gets + * emulated for other formats. * * encoding_id :: * A platform-specific encoding number. This also comes from the @@ -871,11 +855,11 @@ FT_BEGIN_HEADER * FT_Face_Internal * * @description: - * An opaque handle to an `FT_Face_InternalRec' structure that models - * the private data of a given @FT_Face object. + * An opaque handle to an `FT_Face_InternalRec` structure that models the + * private data of a given @FT_Face object. * - * This structure might change between releases of FreeType~2 and is - * not generally available to client applications. + * This structure might change between releases of FreeType~2 and is not + * generally available to client applications. */ typedef struct FT_Face_InternalRec_* FT_Face_Internal; @@ -886,107 +870,89 @@ FT_BEGIN_HEADER * FT_FaceRec * * @description: - * FreeType root face class structure. A face object models a - * typeface in a font file. + * FreeType root face class structure. A face object models a typeface + * in a font file. * * @fields: * num_faces :: - * The number of faces in the font file. Some - * font formats can have multiple faces in - * a single font file. + * The number of faces in the font file. Some font formats can have + * multiple faces in a single font file. * * face_index :: - * This field holds two different values. - * Bits 0-15 are the index of the face in the - * font file (starting with value~0). They - * are set to~0 if there is only one face in - * the font file. - * - * [Since 2.6.1] Bits 16-30 are relevant to GX - * and OpenType variation fonts only, holding - * the named instance index for the current - * face index (starting with value~1; value~0 - * indicates font access without a named - * instance). For non-variation fonts, bits - * 16-30 are ignored. If we have the third - * named instance of face~4, say, `face_index' - * is set to 0x00030004. - * - * Bit 31 is always zero (this is, - * `face_index' is always a positive value). - * - * [Since 2.9] Changing the design coordinates - * with @FT_Set_Var_Design_Coordinates or - * @FT_Set_Var_Blend_Coordinates does not - * influence the named instance index value - * (only @FT_Set_Named_Instance does that). + * This field holds two different values. Bits 0-15 are the index of + * the face in the font file (starting with value~0). They are set + * to~0 if there is only one face in the font file. + * + * [Since 2.6.1] Bits 16-30 are relevant to GX and OpenType variation + * fonts only, holding the named instance index for the current face + * index (starting with value~1; value~0 indicates font access without + * a named instance). For non-variation fonts, bits 16-30 are ignored. + * If we have the third named instance of face~4, say, `face_index` is + * set to 0x00030004. + * + * Bit 31 is always zero (this is, `face_index` is always a positive + * value). + * + * [Since 2.9] Changing the design coordinates with + * @FT_Set_Var_Design_Coordinates or @FT_Set_Var_Blend_Coordinates does + * not influence the named instance index value (only + * @FT_Set_Named_Instance does that). * * face_flags :: - * A set of bit flags that give important - * information about the face; see - * @FT_FACE_FLAG_XXX for the details. + * A set of bit flags that give important information about the face; + * see @FT_FACE_FLAG_XXX for the details. * * style_flags :: - * The lower 16~bits contain a set of bit - * flags indicating the style of the face; see - * @FT_STYLE_FLAG_XXX for the details. - * - * [Since 2.6.1] Bits 16-30 hold the number - * of named instances available for the - * current face if we have a GX or OpenType - * variation (sub)font. Bit 31 is always zero - * (this is, `style_flags' is always a - * positive value). Note that a variation - * font has always at least one named - * instance, namely the default instance. + * The lower 16~bits contain a set of bit flags indicating the style of + * the face; see @FT_STYLE_FLAG_XXX for the details. + * + * [Since 2.6.1] Bits 16-30 hold the number of named instances + * available for the current face if we have a GX or OpenType variation + * (sub)font. Bit 31 is always zero (this is, `style_flags` is always + * a positive value). Note that a variation font has always at least + * one named instance, namely the default instance. * * num_glyphs :: - * The number of glyphs in the face. If the - * face is scalable and has sbits (see - * `num_fixed_sizes'), it is set to the number - * of outline glyphs. + * The number of glyphs in the face. If the face is scalable and has + * sbits (see `num_fixed_sizes`), it is set to the number of outline + * glyphs. * - * For CID-keyed fonts (not in an SFNT - * wrapper) this value gives the highest CID - * used in the font. + * For CID-keyed fonts (not in an SFNT wrapper) this value gives the + * highest CID used in the font. * * family_name :: * The face's family name. This is an ASCII string, usually in - * English, that describes the typeface's family (like `Times New - * Roman', `Bodoni', `Garamond', etc). This is a least common + * English, that describes the typeface's family (like 'Times New + * Roman', 'Bodoni', 'Garamond', etc). This is a least common * denominator used to list fonts. Some formats (TrueType & OpenType) - * provide localized and Unicode versions of this string. - * Applications should use the format-specific interface to access - * them. Can be NULL (e.g., in fonts embedded in a PDF file). + * provide localized and Unicode versions of this string. Applications + * should use the format-specific interface to access them. Can be + * NULL (e.g., in fonts embedded in a PDF file). * - * In case the font doesn't provide a specific - * family name entry, FreeType tries to - * synthesize one, deriving it from other name + * In case the font doesn't provide a specific family name entry, + * FreeType tries to synthesize one, deriving it from other name * entries. * * style_name :: - * The face's style name. This is an ASCII string, usually in - * English, that describes the typeface's style (like `Italic', - * `Bold', `Condensed', etc). Not all font formats provide a style - * name, so this field is optional, and can be set to NULL. As for - * `family_name', some formats provide localized and Unicode versions + * The face's style name. This is an ASCII string, usually in English, + * that describes the typeface's style (like 'Italic', 'Bold', + * 'Condensed', etc). Not all font formats provide a style name, so + * this field is optional, and can be set to NULL. As for + * `family_name`, some formats provide localized and Unicode versions * of this string. Applications should use the format-specific * interface to access them. * * num_fixed_sizes :: - * The number of bitmap strikes in the face. - * Even if the face is scalable, there might - * still be bitmap strikes, which are called - * `sbits' in that case. + * The number of bitmap strikes in the face. Even if the face is + * scalable, there might still be bitmap strikes, which are called + * 'sbits' in that case. * * available_sizes :: - * An array of @FT_Bitmap_Size for all bitmap - * strikes in the face. It is set to NULL if - * there is no bitmap strike. + * An array of @FT_Bitmap_Size for all bitmap strikes in the face. It + * is set to NULL if there is no bitmap strike. * - * Note that FreeType tries to sanitize the - * strike data since they are sometimes sloppy - * or incorrect, but this can easily fail. + * Note that FreeType tries to sanitize the strike data since they are + * sometimes sloppy or incorrect, but this can easily fail. * * num_charmaps :: * The number of charmaps in the face. @@ -995,79 +961,61 @@ FT_BEGIN_HEADER * An array of the charmaps of the face. * * generic :: - * A field reserved for client uses. See the - * @FT_Generic type description. + * A field reserved for client uses. See the @FT_Generic type + * description. * * bbox :: - * The font bounding box. Coordinates are - * expressed in font units (see - * `units_per_EM'). The box is large enough - * to contain any glyph from the font. Thus, - * `bbox.yMax' can be seen as the `maximum - * ascender', and `bbox.yMin' as the `minimum - * descender'. Only relevant for scalable - * formats. - * - * Note that the bounding box might be off by - * (at least) one pixel for hinted fonts. See - * @FT_Size_Metrics for further discussion. + * The font bounding box. Coordinates are expressed in font units (see + * `units_per_EM`). The box is large enough to contain any glyph from + * the font. Thus, `bbox.yMax` can be seen as the 'maximum ascender', + * and `bbox.yMin` as the 'minimum descender'. Only relevant for + * scalable formats. + * + * Note that the bounding box might be off by (at least) one pixel for + * hinted fonts. See @FT_Size_Metrics for further discussion. * * units_per_EM :: - * The number of font units per EM square for - * this face. This is typically 2048 for - * TrueType fonts, and 1000 for Type~1 fonts. - * Only relevant for scalable formats. + * The number of font units per EM square for this face. This is + * typically 2048 for TrueType fonts, and 1000 for Type~1 fonts. Only + * relevant for scalable formats. * * ascender :: - * The typographic ascender of the face, - * expressed in font units. For font formats - * not having this information, it is set to - * `bbox.yMax'. Only relevant for scalable - * formats. + * The typographic ascender of the face, expressed in font units. For + * font formats not having this information, it is set to `bbox.yMax`. + * Only relevant for scalable formats. * * descender :: - * The typographic descender of the face, - * expressed in font units. For font formats - * not having this information, it is set to - * `bbox.yMin'. Note that this field is - * negative for values below the baseline. + * The typographic descender of the face, expressed in font units. For + * font formats not having this information, it is set to `bbox.yMin`. + * Note that this field is negative for values below the baseline. * Only relevant for scalable formats. * * height :: - * This value is the vertical distance - * between two consecutive baselines, - * expressed in font units. It is always - * positive. Only relevant for scalable - * formats. + * This value is the vertical distance between two consecutive + * baselines, expressed in font units. It is always positive. Only + * relevant for scalable formats. * - * If you want the global glyph height, use - * `ascender - descender'. + * If you want the global glyph height, use 'ascender - descender'. * * max_advance_width :: - * The maximum advance width, in font units, - * for all glyphs in this face. This can be - * used to make word wrapping computations - * faster. Only relevant for scalable - * formats. + * The maximum advance width, in font units, for all glyphs in this + * face. This can be used to make word wrapping computations faster. + * Only relevant for scalable formats. * * max_advance_height :: - * The maximum advance height, in font units, - * for all glyphs in this face. This is only - * relevant for vertical layouts, and is set - * to `height' for fonts that do not provide - * vertical metrics. Only relevant for - * scalable formats. + * The maximum advance height, in font units, for all glyphs in this + * face. This is only relevant for vertical layouts, and is set to + * 'height' for fonts that do not provide vertical metrics. Only + * relevant for scalable formats. * * underline_position :: - * The position, in font units, of the - * underline line for this face. It is the - * center of the underlining stem. Only - * relevant for scalable formats. + * The position, in font units, of the underline line for this face. + * It is the center of the underlining stem. Only relevant for + * scalable formats. * * underline_thickness :: - * The thickness, in font units, of the - * underline for this face. Only relevant for - * scalable formats. + * The thickness, in font units, of the underline for this face. Only + * relevant for scalable formats. * * glyph :: * The face's associated glyph slot(s). @@ -1082,11 +1030,10 @@ FT_BEGIN_HEADER * Fields may be changed after a call to @FT_Attach_File or * @FT_Attach_Stream. * - * For an OpenType variation font, the values of the following fields - * can change after a call to @FT_Set_Var_Design_Coordinates (and - * friends) if the font contains an `MVAR' table: `ascender', - * `descender', `height', `underline_position', and - * `underline_thickness'. + * For an OpenType variation font, the values of the following fields can + * change after a call to @FT_Set_Var_Design_Coordinates (and friends) if + * the font contains an 'MVAR' table: 'ascender', 'descender', 'height', + * `underline_position`, and `underline_thickness`. * * Especially for TrueType fonts see also the documentation for * @FT_Size_Metrics. @@ -1156,9 +1103,9 @@ FT_BEGIN_HEADER * FT_FACE_FLAG_XXX * * @description: - * A list of bit flags used in the `face_flags' field of the - * @FT_FaceRec structure. They inform client applications of - * properties of the corresponding face. + * A list of bit flags used in the `face_flags` field of the @FT_FaceRec + * structure. They inform client applications of properties of the + * corresponding face. * * @values: * FT_FACE_FLAG_SCALABLE :: @@ -1167,99 +1114,98 @@ FT_BEGIN_HEADER * @FT_FACE_FLAG_FIXED_SIZES set. * * FT_FACE_FLAG_FIXED_SIZES :: - * The face contains bitmap strikes. See also the - * `num_fixed_sizes' and `available_sizes' fields of @FT_FaceRec. + * The face contains bitmap strikes. See also the `num_fixed_sizes` + * and `available_sizes` fields of @FT_FaceRec. * * FT_FACE_FLAG_FIXED_WIDTH :: * The face contains fixed-width characters (like Courier, Lucida, * MonoType, etc.). * * FT_FACE_FLAG_SFNT :: - * The face uses the SFNT storage scheme. For now, this means - * TrueType and OpenType. + * The face uses the SFNT storage scheme. For now, this means TrueType + * and OpenType. * * FT_FACE_FLAG_HORIZONTAL :: - * The face contains horizontal glyph metrics. This should be set - * for all common formats. + * The face contains horizontal glyph metrics. This should be set for + * all common formats. * * FT_FACE_FLAG_VERTICAL :: - * The face contains vertical glyph metrics. This is only - * available in some formats, not all of them. + * The face contains vertical glyph metrics. This is only available in + * some formats, not all of them. * * FT_FACE_FLAG_KERNING :: - * The face contains kerning information. If set, the kerning - * distance can be retrieved using the function @FT_Get_Kerning. - * Otherwise the function always return the vector (0,0). Note - * that FreeType doesn't handle kerning data from the SFNT `GPOS' - * table (as present in many OpenType fonts). + * The face contains kerning information. If set, the kerning distance + * can be retrieved using the function @FT_Get_Kerning. Otherwise the + * function always return the vector (0,0). Note that FreeType doesn't + * handle kerning data from the SFNT 'GPOS' table (as present in many + * OpenType fonts). * * FT_FACE_FLAG_FAST_GLYPHS :: * THIS FLAG IS DEPRECATED. DO NOT USE OR TEST IT. * * FT_FACE_FLAG_MULTIPLE_MASTERS :: - * The face contains multiple masters and is capable of - * interpolating between them. Supported formats are Adobe MM, - * TrueType GX, and OpenType variation fonts. + * The face contains multiple masters and is capable of interpolating + * between them. Supported formats are Adobe MM, TrueType GX, and + * OpenType variation fonts. * * See section @multiple_masters for API details. * * FT_FACE_FLAG_GLYPH_NAMES :: * The face contains glyph names, which can be retrieved using - * @FT_Get_Glyph_Name. Note that some TrueType fonts contain - * broken glyph name tables. Use the function - * @FT_Has_PS_Glyph_Names when needed. + * @FT_Get_Glyph_Name. Note that some TrueType fonts contain broken + * glyph name tables. Use the function @FT_Has_PS_Glyph_Names when + * needed. * * FT_FACE_FLAG_EXTERNAL_STREAM :: * Used internally by FreeType to indicate that a face's stream was - * provided by the client application and should not be destroyed - * when @FT_Done_Face is called. Don't read or test this flag. + * provided by the client application and should not be destroyed when + * @FT_Done_Face is called. Don't read or test this flag. * * FT_FACE_FLAG_HINTER :: - * The font driver has a hinting machine of its own. For example, - * with TrueType fonts, it makes sense to use data from the SFNT - * `gasp' table only if the native TrueType hinting engine (with - * the bytecode interpreter) is available and active. + * The font driver has a hinting machine of its own. For example, with + * TrueType fonts, it makes sense to use data from the SFNT 'gasp' + * table only if the native TrueType hinting engine (with the bytecode + * interpreter) is available and active. * * FT_FACE_FLAG_CID_KEYED :: - * The face is CID-keyed. In that case, the face is not accessed - * by glyph indices but by CID values. For subsetted CID-keyed - * fonts this has the consequence that not all index values are a - * valid argument to @FT_Load_Glyph. Only the CID values for which - * corresponding glyphs in the subsetted font exist make - * `FT_Load_Glyph' return successfully; in all other cases you get - * an `FT_Err_Invalid_Argument' error. - * - * Note that CID-keyed fonts that are in an SFNT wrapper (this is, - * all OpenType/CFF fonts) don't have this flag set since the - * glyphs are accessed in the normal way (using contiguous - * indices); the `CID-ness' isn't visible to the application. + * The face is CID-keyed. In that case, the face is not accessed by + * glyph indices but by CID values. For subsetted CID-keyed fonts this + * has the consequence that not all index values are a valid argument + * to @FT_Load_Glyph. Only the CID values for which corresponding + * glyphs in the subsetted font exist make `FT_Load_Glyph` return + * successfully; in all other cases you get an + * `FT_Err_Invalid_Argument` error. + * + * Note that CID-keyed fonts that are in an SFNT wrapper (this is, all + * OpenType/CFF fonts) don't have this flag set since the glyphs are + * accessed in the normal way (using contiguous indices); the + * 'CID-ness' isn't visible to the application. * * FT_FACE_FLAG_TRICKY :: - * The face is `tricky', this is, it always needs the font format's - * native hinting engine to get a reasonable result. A typical - * example is the old Chinese font `mingli.ttf' (but not - * `mingliu.ttc') that uses TrueType bytecode instructions to move - * and scale all of its subglyphs. + * The face is 'tricky', this is, it always needs the font format's + * native hinting engine to get a reasonable result. A typical example + * is the old Chinese font `mingli.ttf` (but not `mingliu.ttc`) that + * uses TrueType bytecode instructions to move and scale all of its + * subglyphs. * * It is not possible to auto-hint such fonts using - * @FT_LOAD_FORCE_AUTOHINT; it will also ignore - * @FT_LOAD_NO_HINTING. You have to set both @FT_LOAD_NO_HINTING - * and @FT_LOAD_NO_AUTOHINT to really disable hinting; however, you - * probably never want this except for demonstration purposes. + * @FT_LOAD_FORCE_AUTOHINT; it will also ignore @FT_LOAD_NO_HINTING. + * You have to set both @FT_LOAD_NO_HINTING and @FT_LOAD_NO_AUTOHINT to + * really disable hinting; however, you probably never want this except + * for demonstration purposes. * * Currently, there are about a dozen TrueType fonts in the list of - * tricky fonts; they are hard-coded in file `ttobjs.c'. + * tricky fonts; they are hard-coded in file `ttobjs.c`. * * FT_FACE_FLAG_COLOR :: - * [Since 2.5.1] The face has color glyph tables. See - * @FT_LOAD_COLOR for more information. + * [Since 2.5.1] The face has color glyph tables. See @FT_LOAD_COLOR + * for more information. * * FT_FACE_FLAG_VARIATION :: * [Since 2.9] Set if the current face (or named instance) has been * altered with @FT_Set_MM_Design_Coordinates, - * @FT_Set_Var_Design_Coordinates, or - * @FT_Set_Var_Blend_Coordinates. This flag is unset by a call to - * @FT_Set_Named_Instance. + * @FT_Set_Var_Design_Coordinates, or @FT_Set_Var_Blend_Coordinates. + * This flag is unset by a call to @FT_Set_Named_Instance. */ #define FT_FACE_FLAG_SCALABLE ( 1L << 0 ) #define FT_FACE_FLAG_FIXED_SIZES ( 1L << 1 ) @@ -1285,8 +1231,8 @@ FT_BEGIN_HEADER * FT_HAS_HORIZONTAL * * @description: - * A macro that returns true whenever a face object contains - * horizontal metrics (this is true for all font formats though). + * A macro that returns true whenever a face object contains horizontal + * metrics (this is true for all font formats though). * * @also: * @FT_HAS_VERTICAL can be used to check for vertical metrics. @@ -1316,8 +1262,8 @@ FT_BEGIN_HEADER * FT_HAS_KERNING * * @description: - * A macro that returns true whenever a face object contains kerning - * data that can be accessed with @FT_Get_Kerning. + * A macro that returns true whenever a face object contains kerning data + * that can be accessed with @FT_Get_Kerning. * */ #define FT_HAS_KERNING( face ) \ @@ -1331,8 +1277,8 @@ FT_BEGIN_HEADER * * @description: * A macro that returns true whenever a face object contains a scalable - * font face (true for TrueType, Type~1, Type~42, CID, OpenType/CFF, - * and PFR font formats). + * font face (true for TrueType, Type~1, Type~42, CID, OpenType/CFF, and + * PFR font formats). * */ #define FT_IS_SCALABLE( face ) \ @@ -1345,10 +1291,10 @@ FT_BEGIN_HEADER * FT_IS_SFNT * * @description: - * A macro that returns true whenever a face object contains a font - * whose format is based on the SFNT storage scheme. This usually - * means: TrueType fonts, OpenType fonts, as well as SFNT-based embedded - * bitmap fonts. + * A macro that returns true whenever a face object contains a font whose + * format is based on the SFNT storage scheme. This usually means: + * TrueType fonts, OpenType fonts, as well as SFNT-based embedded bitmap + * fonts. * * If this macro is true, all functions defined in @FT_SFNT_NAMES_H and * @FT_TRUETYPE_TABLES_H are available. @@ -1365,7 +1311,7 @@ FT_BEGIN_HEADER * * @description: * A macro that returns true whenever a face object contains a font face - * that contains fixed-width (or `monospace', `fixed-pitch', etc.) + * that contains fixed-width (or 'monospace', 'fixed-pitch', etc.) * glyphs. * */ @@ -1380,8 +1326,8 @@ FT_BEGIN_HEADER * * @description: * A macro that returns true whenever a face object contains some - * embedded bitmaps. See the `available_sizes' field of the - * @FT_FaceRec structure. + * embedded bitmaps. See the `available_sizes` field of the @FT_FaceRec + * structure. * */ #define FT_HAS_FIXED_SIZES( face ) \ @@ -1457,8 +1403,8 @@ FT_BEGIN_HEADER * FT_IS_VARIATION * * @description: - * A macro that returns true whenever a face object has been altered - * by @FT_Set_MM_Design_Coordinates, @FT_Set_Var_Design_Coordinates, or + * A macro that returns true whenever a face object has been altered by + * @FT_Set_MM_Design_Coordinates, @FT_Set_Var_Design_Coordinates, or * @FT_Set_Var_Blend_Coordinates. * * @since: @@ -1476,8 +1422,7 @@ FT_BEGIN_HEADER * * @description: * A macro that returns true whenever a face object contains a CID-keyed - * font. See the discussion of @FT_FACE_FLAG_CID_KEYED for more - * details. + * font. See the discussion of @FT_FACE_FLAG_CID_KEYED for more details. * * If this macro is true, all functions defined in @FT_CID_H are * available. @@ -1493,7 +1438,7 @@ FT_BEGIN_HEADER * FT_IS_TRICKY * * @description: - * A macro that returns true whenever a face represents a `tricky' font. + * A macro that returns true whenever a face represents a 'tricky' font. * See the discussion of @FT_FACE_FLAG_TRICKY for more details. * */ @@ -1507,8 +1452,8 @@ FT_BEGIN_HEADER * FT_HAS_COLOR * * @description: - * A macro that returns true whenever a face object contains - * tables for color glyphs. + * A macro that returns true whenever a face object contains tables for + * color glyphs. * * @since: * 2.5.1 @@ -1524,8 +1469,8 @@ FT_BEGIN_HEADER * FT_STYLE_FLAG_XXX * * @description: - * A list of bit flags to indicate the style of a given face. These - * are used in the `style_flags' field of @FT_FaceRec. + * A list of bit flags to indicate the style of a given face. These are + * used in the `style_flags` field of @FT_FaceRec. * * @values: * FT_STYLE_FLAG_ITALIC :: @@ -1536,9 +1481,9 @@ FT_BEGIN_HEADER * * @note: * The style information as provided by FreeType is very basic. More - * details are beyond the scope and should be done on a higher level - * (for example, by analyzing various fields of the `OS/2' table in - * SFNT based fonts). + * details are beyond the scope and should be done on a higher level (for + * example, by analyzing various fields of the 'OS/2' table in SFNT based + * fonts). */ #define FT_STYLE_FLAG_ITALIC ( 1 << 0 ) #define FT_STYLE_FLAG_BOLD ( 1 << 1 ) @@ -1550,8 +1495,8 @@ FT_BEGIN_HEADER * FT_Size_Internal * * @description: - * An opaque handle to an `FT_Size_InternalRec' structure, used to - * model private data of a given @FT_Size object. + * An opaque handle to an `FT_Size_InternalRec` structure, used to model + * private data of a given @FT_Size object. */ typedef struct FT_Size_InternalRec_* FT_Size_Internal; @@ -1566,89 +1511,80 @@ FT_BEGIN_HEADER * * @fields: * x_ppem :: - * The width of the scaled EM square in pixels, hence - * the term `ppem' (pixels per EM). It is also - * referred to as `nominal width'. + * The width of the scaled EM square in pixels, hence the term 'ppem' + * (pixels per EM). It is also referred to as 'nominal width'. * * y_ppem :: - * The height of the scaled EM square in pixels, - * hence the term `ppem' (pixels per EM). It is also - * referred to as `nominal height'. + * The height of the scaled EM square in pixels, hence the term 'ppem' + * (pixels per EM). It is also referred to as 'nominal height'. * * x_scale :: - * A 16.16 fractional scaling value to convert - * horizontal metrics from font units to 26.6 - * fractional pixels. Only relevant for scalable + * A 16.16 fractional scaling value to convert horizontal metrics from + * font units to 26.6 fractional pixels. Only relevant for scalable * font formats. * * y_scale :: - * A 16.16 fractional scaling value to convert - * vertical metrics from font units to 26.6 - * fractional pixels. Only relevant for scalable + * A 16.16 fractional scaling value to convert vertical metrics from + * font units to 26.6 fractional pixels. Only relevant for scalable * font formats. * * ascender :: - * The ascender in 26.6 fractional pixels, rounded up - * to an integer value. See @FT_FaceRec for the - * details. + * The ascender in 26.6 fractional pixels, rounded up to an integer + * value. See @FT_FaceRec for the details. * * descender :: - * The descender in 26.6 fractional pixels, rounded - * down to an integer value. See @FT_FaceRec for the - * details. + * The descender in 26.6 fractional pixels, rounded down to an integer + * value. See @FT_FaceRec for the details. * * height :: - * The height in 26.6 fractional pixels, rounded to - * an integer value. See @FT_FaceRec for the - * details. + * The height in 26.6 fractional pixels, rounded to an integer value. + * See @FT_FaceRec for the details. * * max_advance :: - * The maximum advance width in 26.6 fractional - * pixels, rounded to an integer value. See - * @FT_FaceRec for the details. + * The maximum advance width in 26.6 fractional pixels, rounded to an + * integer value. See @FT_FaceRec for the details. * * @note: - * The scaling values, if relevant, are determined first during a - * size changing operation. The remaining fields are then set by the - * driver. For scalable formats, they are usually set to scaled - * values of the corresponding fields in @FT_FaceRec. Some values - * like ascender or descender are rounded for historical reasons; - * more precise values (for outline fonts) can be derived by scaling - * the corresponding @FT_FaceRec values manually, with code similar - * to the following. - * - * { + * The scaling values, if relevant, are determined first during a size + * changing operation. The remaining fields are then set by the driver. + * For scalable formats, they are usually set to scaled values of the + * corresponding fields in @FT_FaceRec. Some values like ascender or + * descender are rounded for historical reasons; more precise values (for + * outline fonts) can be derived by scaling the corresponding @FT_FaceRec + * values manually, with code similar to the following. + * + * ``` * scaled_ascender = FT_MulFix( face->ascender, * size_metrics->y_scale ); - * } + * ``` * - * Note that due to glyph hinting and the selected rendering mode - * these values are usually not exact; consequently, they must be - * treated as unreliable with an error margin of at least one pixel! + * Note that due to glyph hinting and the selected rendering mode these + * values are usually not exact; consequently, they must be treated as + * unreliable with an error margin of at least one pixel! * * Indeed, the only way to get the exact metrics is to render _all_ * glyphs. As this would be a definite performance hit, it is up to * client applications to perform such computations. * - * The `FT_Size_Metrics' structure is valid for bitmap fonts also. + * The `FT_Size_Metrics` structure is valid for bitmap fonts also. * * - * *TrueType* *fonts* *with* *native* *bytecode* *hinting* + * **TrueType fonts with native bytecode hinting** * - * All applications that handle TrueType fonts with native hinting - * must be aware that TTFs expect different rounding of vertical font - * dimensions. The application has to cater for this, especially if - * it wants to rely on a TTF's vertical data (for example, to - * properly align box characters vertically). + * All applications that handle TrueType fonts with native hinting must + * be aware that TTFs expect different rounding of vertical font + * dimensions. The application has to cater for this, especially if it + * wants to rely on a TTF's vertical data (for example, to properly align + * box characters vertically). * - * Only the application knows _in_ _advance_ that it is going to use - * native hinting for TTFs! FreeType, on the other hand, selects the - * hinting mode not at the time of creating an @FT_Size object but - * much later, namely while calling @FT_Load_Glyph. + * Only the application knows _in advance_ that it is going to use native + * hinting for TTFs! FreeType, on the other hand, selects the hinting + * mode not at the time of creating an @FT_Size object but much later, + * namely while calling @FT_Load_Glyph. * * Here is some pseudo code that illustrates a possible solution. * - * { + * ``` * font_format = FT_Get_Font_Format( face ); * * if ( !strcmp( font_format, "TrueType" ) && @@ -1667,7 +1603,7 @@ FT_BEGIN_HEADER * * height = size_metrics->height; * max_advance = size_metrics->max_advance; - * } + * ``` */ typedef struct FT_Size_Metrics_ { @@ -1699,10 +1635,9 @@ FT_BEGIN_HEADER * Handle to the parent face object. * * generic :: - * A typeless pointer, unused by the FreeType library or - * any of its drivers. It can be used by client - * applications to link their own data to each size - * object. + * A typeless pointer, unused by the FreeType library or any of its + * drivers. It can be used by client applications to link their own + * data to each size object. * * metrics :: * Metrics for this size object. This field is read-only. @@ -1727,8 +1662,8 @@ FT_BEGIN_HEADER * subglyphs (for example, in the case of composites). * * @note: - * The subglyph implementation is not part of the high-level API, - * hence the forward structure declaration. + * The subglyph implementation is not part of the high-level API, hence + * the forward structure declaration. * * You can however retrieve subglyph information with * @FT_Get_SubGlyph_Info. @@ -1742,8 +1677,8 @@ FT_BEGIN_HEADER * FT_Slot_Internal * * @description: - * An opaque handle to an `FT_Slot_InternalRec' structure, used to - * model private data of a given @FT_GlyphSlot object. + * An opaque handle to an `FT_Slot_InternalRec` structure, used to model + * private data of a given @FT_GlyphSlot object. */ typedef struct FT_Slot_InternalRec_* FT_Slot_Internal; @@ -1754,164 +1689,138 @@ FT_BEGIN_HEADER * FT_GlyphSlotRec * * @description: - * FreeType root glyph slot class structure. A glyph slot is a - * container where individual glyphs can be loaded, be they in - * outline or bitmap format. + * FreeType root glyph slot class structure. A glyph slot is a container + * where individual glyphs can be loaded, be they in outline or bitmap + * format. * * @fields: * library :: - * A handle to the FreeType library instance - * this slot belongs to. + * A handle to the FreeType library instance this slot belongs to. * * face :: * A handle to the parent face object. * * next :: - * In some cases (like some font tools), several - * glyph slots per face object can be a good - * thing. As this is rare, the glyph slots are - * listed through a direct, single-linked list - * using its `next' field. + * In some cases (like some font tools), several glyph slots per face + * object can be a good thing. As this is rare, the glyph slots are + * listed through a direct, single-linked list using its 'next' field. * * glyph_index :: - * [Since 2.10] The glyph index passed as an argument to - * @FT_Load_Glyph while initializing the glyph slot. + * [Since 2.10] The glyph index passed as an argument to @FT_Load_Glyph + * while initializing the glyph slot. * * generic :: - * A typeless pointer unused by the FreeType - * library or any of its drivers. It can be - * used by client applications to link their own + * A typeless pointer unused by the FreeType library or any of its + * drivers. It can be used by client applications to link their own * data to each glyph slot object. * * metrics :: - * The metrics of the last loaded glyph in the - * slot. The returned values depend on the last - * load flags (see the @FT_Load_Glyph API - * function) and can be expressed either in 26.6 - * fractional pixels or font units. + * The metrics of the last loaded glyph in the slot. The returned + * values depend on the last load flags (see the @FT_Load_Glyph API + * function) and can be expressed either in 26.6 fractional pixels or + * font units. * - * Note that even when the glyph image is - * transformed, the metrics are not. + * Note that even when the glyph image is transformed, the metrics are + * not. * * linearHoriAdvance :: - * The advance width of the unhinted glyph. - * Its value is expressed in 16.16 fractional - * pixels, unless @FT_LOAD_LINEAR_DESIGN is set - * when loading the glyph. This field can be - * important to perform correct WYSIWYG layout. - * Only relevant for outline glyphs. + * The advance width of the unhinted glyph. Its value is expressed in + * 16.16 fractional pixels, unless @FT_LOAD_LINEAR_DESIGN is set when + * loading the glyph. This field can be important to perform correct + * WYSIWYG layout. Only relevant for outline glyphs. * * linearVertAdvance :: - * The advance height of the unhinted glyph. - * Its value is expressed in 16.16 fractional - * pixels, unless @FT_LOAD_LINEAR_DESIGN is set - * when loading the glyph. This field can be - * important to perform correct WYSIWYG layout. - * Only relevant for outline glyphs. + * The advance height of the unhinted glyph. Its value is expressed in + * 16.16 fractional pixels, unless @FT_LOAD_LINEAR_DESIGN is set when + * loading the glyph. This field can be important to perform correct + * WYSIWYG layout. Only relevant for outline glyphs. * * advance :: - * This shorthand is, depending on - * @FT_LOAD_IGNORE_TRANSFORM, the transformed - * (hinted) advance width for the glyph, in 26.6 - * fractional pixel format. As specified with - * @FT_LOAD_VERTICAL_LAYOUT, it uses either the - * `horiAdvance' or the `vertAdvance' value of - * `metrics' field. + * This shorthand is, depending on @FT_LOAD_IGNORE_TRANSFORM, the + * transformed (hinted) advance width for the glyph, in 26.6 fractional + * pixel format. As specified with @FT_LOAD_VERTICAL_LAYOUT, it uses + * either the `horiAdvance` or the `vertAdvance` value of 'metrics' + * field. * * format :: - * This field indicates the format of the image - * contained in the glyph slot. Typically - * @FT_GLYPH_FORMAT_BITMAP, - * @FT_GLYPH_FORMAT_OUTLINE, or - * @FT_GLYPH_FORMAT_COMPOSITE, but other values - * are possible. + * This field indicates the format of the image contained in the glyph + * slot. Typically @FT_GLYPH_FORMAT_BITMAP, @FT_GLYPH_FORMAT_OUTLINE, + * or @FT_GLYPH_FORMAT_COMPOSITE, but other values are possible. * * bitmap :: - * This field is used as a bitmap descriptor. - * Note that the address and content of the - * bitmap buffer can change between calls of + * This field is used as a bitmap descriptor. Note that the address + * and content of the bitmap buffer can change between calls of * @FT_Load_Glyph and a few other functions. * * bitmap_left :: - * The bitmap's left bearing expressed in - * integer pixels. + * The bitmap's left bearing expressed in integer pixels. * * bitmap_top :: - * The bitmap's top bearing expressed in integer - * pixels. This is the distance from the - * baseline to the top-most glyph scanline, - * upwards y~coordinates being *positive*. + * The bitmap's top bearing expressed in integer pixels. This is the + * distance from the baseline to the top-most glyph scanline, upwards + * y~coordinates being **positive**. * * outline :: - * The outline descriptor for the current glyph - * image if its format is - * @FT_GLYPH_FORMAT_OUTLINE. Once a glyph is - * loaded, `outline' can be transformed, - * distorted, emboldened, etc. However, it must - * not be freed. + * The outline descriptor for the current glyph image if its format is + * @FT_GLYPH_FORMAT_OUTLINE. Once a glyph is loaded, 'outline' can be + * transformed, distorted, emboldened, etc. However, it must not be + * freed. * * num_subglyphs :: - * The number of subglyphs in a composite glyph. - * This field is only valid for the composite - * glyph format that should normally only be + * The number of subglyphs in a composite glyph. This field is only + * valid for the composite glyph format that should normally only be * loaded with the @FT_LOAD_NO_RECURSE flag. * * subglyphs :: - * An array of subglyph descriptors for - * composite glyphs. There are `num_subglyphs' - * elements in there. Currently internal to - * FreeType. + * An array of subglyph descriptors for composite glyphs. There are + * `num_subglyphs` elements in there. Currently internal to FreeType. * * control_data :: - * Certain font drivers can also return the - * control data for a given glyph image (e.g. - * TrueType bytecode, Type~1 charstrings, etc.). - * This field is a pointer to such data; it is - * currently internal to FreeType. + * Certain font drivers can also return the control data for a given + * glyph image (e.g. TrueType bytecode, Type~1 charstrings, etc.). + * This field is a pointer to such data; it is currently internal to + * FreeType. * * control_len :: - * This is the length in bytes of the control - * data. Currently internal to FreeType. + * This is the length in bytes of the control data. Currently internal + * to FreeType. * * other :: * Reserved. * * lsb_delta :: - * The difference between hinted and unhinted - * left side bearing while auto-hinting is - * active. Zero otherwise. + * The difference between hinted and unhinted left side bearing while + * auto-hinting is active. Zero otherwise. * * rsb_delta :: - * The difference between hinted and unhinted - * right side bearing while auto-hinting is - * active. Zero otherwise. + * The difference between hinted and unhinted right side bearing while + * auto-hinting is active. Zero otherwise. * * @note: - * If @FT_Load_Glyph is called with default flags (see - * @FT_LOAD_DEFAULT) the glyph image is loaded in the glyph slot in - * its native format (e.g., an outline glyph for TrueType and Type~1 - * formats). [Since 2.9] The prospective bitmap metrics are - * calculated according to @FT_LOAD_TARGET_XXX and other flags even - * for the outline glyph, even if @FT_LOAD_RENDER is not set. + * If @FT_Load_Glyph is called with default flags (see @FT_LOAD_DEFAULT) + * the glyph image is loaded in the glyph slot in its native format + * (e.g., an outline glyph for TrueType and Type~1 formats). [Since 2.9] + * The prospective bitmap metrics are calculated according to + * @FT_LOAD_TARGET_XXX and other flags even for the outline glyph, even + * if @FT_LOAD_RENDER is not set. * * This image can later be converted into a bitmap by calling - * @FT_Render_Glyph. This function searches the current renderer for - * the native image's format, then invokes it. + * @FT_Render_Glyph. This function searches the current renderer for the + * native image's format, then invokes it. * - * The renderer is in charge of transforming the native image through - * the slot's face transformation fields, then converting it into a - * bitmap that is returned in `slot->bitmap'. + * The renderer is in charge of transforming the native image through the + * slot's face transformation fields, then converting it into a bitmap + * that is returned in `slot->bitmap`. * - * Note that `slot->bitmap_left' and `slot->bitmap_top' are also used - * to specify the position of the bitmap relative to the current pen + * Note that `slot->bitmap_left` and `slot->bitmap_top` are also used to + * specify the position of the bitmap relative to the current pen * position (e.g., coordinates (0,0) on the baseline). Of course, - * `slot->format' is also changed to @FT_GLYPH_FORMAT_BITMAP. + * `slot->format` is also changed to @FT_GLYPH_FORMAT_BITMAP. * - * Here is a small pseudo code fragment that shows how to use - * `lsb_delta' and `rsb_delta' to do fractional positioning of - * glyphs: + * Here is a small pseudo code fragment that shows how to use `lsb_delta` + * and `rsb_delta` to do fractional positioning of glyphs: * - * { + * ``` * FT_GlyphSlot slot = face->glyph; * FT_Pos origin_x = 0; * @@ -1929,13 +1838,12 @@ FT_BEGIN_HEADER * origin_x += slot->advance.x; * origin_x += slot->rsb_delta - slot->lsb_delta; * endfor - * } + * ``` * * Here is another small pseudo code fragment that shows how to use - * `lsb_delta' and `rsb_delta' to improve integer positioning of - * glyphs: + * `lsb_delta` and `rsb_delta` to improve integer positioning of glyphs: * - * { + * ``` * FT_GlyphSlot slot = face->glyph; * FT_Pos origin_x = 0; * FT_Pos prev_rsb_delta = 0; @@ -1958,13 +1866,13 @@ FT_BEGIN_HEADER * * origin_x += slot->advance.x; * endfor - * } + * ``` * - * If you use strong auto-hinting, you *must* apply these delta - * values! Otherwise you will experience far too large inter-glyph - * spacing at small rendering sizes in most cases. Note that it - * doesn't harm to use the above code for other hinting modes also, - * since the delta values are zero then. + * If you use strong auto-hinting, you **must** apply these delta values! + * Otherwise you will experience far too large inter-glyph spacing at + * small rendering sizes in most cases. Note that it doesn't harm to use + * the above code for other hinting modes also, since the delta values + * are zero then. */ typedef struct FT_GlyphSlotRec_ { @@ -2018,8 +1926,8 @@ FT_BEGIN_HEADER * FT_Init_FreeType * * @description: - * Initialize a new FreeType library object. The set of modules - * that are registered by this function is determined at build time. + * Initialize a new FreeType library object. The set of modules that are + * registered by this function is determined at build time. * * @output: * alibrary :: @@ -2029,21 +1937,20 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * In case you want to provide your own memory allocating routines, - * use @FT_New_Library instead, followed by a call to - * @FT_Add_Default_Modules (or a series of calls to @FT_Add_Module) - * and @FT_Set_Default_Properties. + * In case you want to provide your own memory allocating routines, use + * @FT_New_Library instead, followed by a call to @FT_Add_Default_Modules + * (or a series of calls to @FT_Add_Module) and + * @FT_Set_Default_Properties. * - * See the documentation of @FT_Library and @FT_Face for - * multi-threading issues. + * See the documentation of @FT_Library and @FT_Face for multi-threading + * issues. * * If you need reference-counting (cf. @FT_Reference_Library), use * @FT_New_Library and @FT_Done_Library. * - * If compilation option FT_CONFIG_OPTION_ENVIRONMENT_PROPERTIES is - * set, this function reads the `FREETYPE_PROPERTIES' environment - * variable to control driver properties. See section @properties - * for more. + * If compilation option FT_CONFIG_OPTION_ENVIRONMENT_PROPERTIES is set, + * this function reads the `FREETYPE_PROPERTIES` environment variable to + * control driver properties. See section @properties for more. */ FT_EXPORT( FT_Error ) FT_Init_FreeType( FT_Library *alibrary ); @@ -2075,7 +1982,7 @@ FT_BEGIN_HEADER * FT_OPEN_XXX * * @description: - * A list of bit field constants used within the `flags' field of the + * A list of bit field constants used within the 'flags' field of the * @FT_Open_Args structure. * * @values: @@ -2083,21 +1990,20 @@ FT_BEGIN_HEADER * This is a memory-based stream. * * FT_OPEN_STREAM :: - * Copy the stream from the `stream' field. + * Copy the stream from the 'stream' field. * * FT_OPEN_PATHNAME :: - * Create a new input stream from a C~path - * name. + * Create a new input stream from a C~path name. * * FT_OPEN_DRIVER :: - * Use the `driver' field. + * Use the 'driver' field. * * FT_OPEN_PARAMS :: - * Use the `num_params' and `params' fields. + * Use the `num_params` and 'params' fields. * * @note: - * The `FT_OPEN_MEMORY', `FT_OPEN_STREAM', and `FT_OPEN_PATHNAME' - * flags are mutually exclusive. + * The `FT_OPEN_MEMORY`, `FT_OPEN_STREAM`, and `FT_OPEN_PATHNAME` flags + * are mutually exclusive. */ #define FT_OPEN_MEMORY 0x1 #define FT_OPEN_STREAM 0x2 @@ -2132,8 +2038,8 @@ FT_BEGIN_HEADER * A pointer to the parameter data. * * @note: - * The ID and function of parameters are driver-specific. See - * section @parameter_tags for more information. + * The ID and function of parameters are driver-specific. See section + * @parameter_tags for more information. */ typedef struct FT_Parameter_ { @@ -2155,8 +2061,7 @@ FT_BEGIN_HEADER * * @fields: * flags :: - * A set of bit flags indicating how to use the - * structure. + * A set of bit flags indicating how to use the structure. * * memory_base :: * The first byte of the file in memory. @@ -2171,44 +2076,41 @@ FT_BEGIN_HEADER * A handle to a source stream object. * * driver :: - * This field is exclusively used by @FT_Open_Face; - * it simply specifies the font driver to use for - * opening the face. If set to NULL, FreeType tries - * to load the face with each one of the drivers in - * its list. + * This field is exclusively used by @FT_Open_Face; it simply specifies + * the font driver to use for opening the face. If set to NULL, + * FreeType tries to load the face with each one of the drivers in its + * list. * * num_params :: * The number of extra parameters. * * params :: - * Extra parameters passed to the font driver when - * opening a new face. + * Extra parameters passed to the font driver when opening a new face. * * @note: - * The stream type is determined by the contents of `flags' that + * The stream type is determined by the contents of 'flags' that * are tested in the following order by @FT_Open_Face: * - * If the @FT_OPEN_MEMORY bit is set, assume that this is a - * memory file of `memory_size' bytes, located at `memory_address'. - * The data are not copied, and the client is responsible for - * releasing and destroying them _after_ the corresponding call to - * @FT_Done_Face. + * If the @FT_OPEN_MEMORY bit is set, assume that this is a memory file + * of `memory_size` bytes, located at `memory_address`. The data are not + * copied, and the client is responsible for releasing and destroying + * them _after_ the corresponding call to @FT_Done_Face. * - * Otherwise, if the @FT_OPEN_STREAM bit is set, assume that a - * custom input stream `stream' is used. + * Otherwise, if the @FT_OPEN_STREAM bit is set, assume that a custom + * input stream 'stream' is used. * - * Otherwise, if the @FT_OPEN_PATHNAME bit is set, assume that this - * is a normal file and use `pathname' to open it. + * Otherwise, if the @FT_OPEN_PATHNAME bit is set, assume that this is a + * normal file and use 'pathname' to open it. * - * If the @FT_OPEN_DRIVER bit is set, @FT_Open_Face only tries to - * open the file with the driver whose handler is in `driver'. + * If the @FT_OPEN_DRIVER bit is set, @FT_Open_Face only tries to open + * the file with the driver whose handler is in 'driver'. * * If the @FT_OPEN_PARAMS bit is set, the parameters given by - * `num_params' and `params' is used. They are ignored otherwise. + * `num_params` and 'params' is used. They are ignored otherwise. * - * Ideally, both the `pathname' and `params' fields should be tagged - * as `const'; this is missing for API backward compatibility. In - * other words, applications should treat them as read-only. + * Ideally, both the 'pathname' and 'params' fields should be tagged as + * 'const'; this is missing for API backward compatibility. In other + * words, applications should treat them as read-only. */ typedef struct FT_Open_Args_ { @@ -2241,20 +2143,19 @@ FT_BEGIN_HEADER * A path to the font file. * * face_index :: - * See @FT_Open_Face for a detailed description of this - * parameter. + * See @FT_Open_Face for a detailed description of this parameter. * * @output: * aface :: - * A handle to a new face object. If `face_index' is - * greater than or equal to zero, it must be non-NULL. + * A handle to a new face object. If `face_index` is greater than or + * equal to zero, it must be non-NULL. * * @return: * FreeType error code. 0~means success. * * @note: - * Use @FT_Done_Face to destroy the created @FT_Face object (along - * with its slot and sizes). + * Use @FT_Done_Face to destroy the created @FT_Face object (along with + * its slot and sizes). */ FT_EXPORT( FT_Error ) FT_New_Face( FT_Library library, @@ -2269,8 +2170,7 @@ FT_BEGIN_HEADER * FT_New_Memory_Face * * @description: - * Call @FT_Open_Face to open a font that has been loaded into - * memory. + * Call @FT_Open_Face to open a font that has been loaded into memory. * * @inout: * library :: @@ -2284,13 +2184,12 @@ FT_BEGIN_HEADER * The size of the memory chunk used by the font data. * * face_index :: - * See @FT_Open_Face for a detailed description of this - * parameter. + * See @FT_Open_Face for a detailed description of this parameter. * * @output: * aface :: - * A handle to a new face object. If `face_index' is - * greater than or equal to zero, it must be non-NULL. + * A handle to a new face object. If `face_index` is greater than or + * equal to zero, it must be non-NULL. * * @return: * FreeType error code. 0~means success. @@ -2312,8 +2211,7 @@ FT_BEGIN_HEADER * FT_Open_Face * * @description: - * Create a face object from a given resource described by - * @FT_Open_Args. + * Create a face object from a given resource described by @FT_Open_Args. * * @inout: * library :: @@ -2321,64 +2219,57 @@ FT_BEGIN_HEADER * * @input: * args :: - * A pointer to an `FT_Open_Args' structure that must - * be filled by the caller. + * A pointer to an `FT_Open_Args` structure that must be filled by the + * caller. * * face_index :: - * This field holds two different values. Bits 0-15 - * are the index of the face in the font file (starting - * with value~0). Set it to~0 if there is only one - * face in the font file. - * - * [Since 2.6.1] Bits 16-30 are relevant to GX and - * OpenType variation fonts only, specifying the named - * instance index for the current face index (starting - * with value~1; value~0 makes FreeType ignore named - * instances). For non-variation fonts, bits 16-30 are - * ignored. Assuming that you want to access the third - * named instance in face~4, `face_index' should be set - * to 0x00030004. If you want to access face~4 without - * variation handling, simply set `face_index' to + * This field holds two different values. Bits 0-15 are the index of + * the face in the font file (starting with value~0). Set it to~0 if + * there is only one face in the font file. + * + * [Since 2.6.1] Bits 16-30 are relevant to GX and OpenType variation + * fonts only, specifying the named instance index for the current face + * index (starting with value~1; value~0 makes FreeType ignore named + * instances). For non-variation fonts, bits 16-30 are ignored. + * Assuming that you want to access the third named instance in face~4, + * `face_index` should be set to 0x00030004. If you want to access + * face~4 without variation handling, simply set `face_index` to * value~4. * - * `FT_Open_Face' and its siblings can be used to - * quickly check whether the font format of a given - * font resource is supported by FreeType. In general, - * if the `face_index' argument is negative, the - * function's return value is~0 if the font format is - * recognized, or non-zero otherwise. The function - * allocates a more or less empty face handle in - * `*aface' (if `aface' isn't NULL); the only two - * useful fields in this special case are - * `face->num_faces' and `face->style_flags'. For any - * negative value of `face_index', `face->num_faces' - * gives the number of faces within the font file. For - * the negative value `-(N+1)' (with `N' a non-negative - * 16-bit value), bits 16-30 in `face->style_flags' - * give the number of named instances in face `N' if we - * have a variation font (or zero otherwise). After - * examination, the returned @FT_Face structure should - * be deallocated with a call to @FT_Done_Face. + * `FT_Open_Face` and its siblings can be used to quickly check whether + * the font format of a given font resource is supported by FreeType. + * In general, if the `face_index` argument is negative, the function's + * return value is~0 if the font format is recognized, or non-zero + * otherwise. The function allocates a more or less empty face handle + * in '*aface' (if 'aface' isn't NULL); the only two useful fields in + * this special case are `face->num_faces` and `face->style_flags`. + * For any negative value of `face_index`, `face->num_faces` gives the + * number of faces within the font file. For the negative value + * '-(N+1)' (with 'N' a non-negative 16-bit value), bits 16-30 in + * `face->style_flags` give the number of named instances in face 'N' + * if we have a variation font (or zero otherwise). After examination, + * the returned @FT_Face structure should be deallocated with a call to + * @FT_Done_Face. * * @output: * aface :: - * A handle to a new face object. If `face_index' is - * greater than or equal to zero, it must be non-NULL. + * A handle to a new face object. If `face_index` is greater than or + * equal to zero, it must be non-NULL. * * @return: * FreeType error code. 0~means success. * * @note: - * Unlike FreeType 1.x, this function automatically creates a glyph - * slot for the face object that can be accessed directly through - * `face->glyph'. + * Unlike FreeType 1.x, this function automatically creates a glyph slot + * for the face object that can be accessed directly through + * `face->glyph`. * - * Each new face object created with this function also owns a - * default @FT_Size object, accessible as `face->size'. + * Each new face object created with this function also owns a default + * @FT_Size object, accessible as `face->size`. * * One @FT_Library instance can have multiple face objects, this is, - * @FT_Open_Face and its siblings can be called multiple times using - * the same `library' argument. + * @FT_Open_Face and its siblings can be called multiple times using the + * same 'library' argument. * * See the discussion of reference counters in the description of * @FT_Reference_Face. @@ -2387,7 +2278,7 @@ FT_BEGIN_HEADER * To loop over all faces, use code similar to the following snippet * (omitting the error handling). * - * { + * ``` * ... * FT_Face face; * FT_Long i, num_faces; @@ -2407,15 +2298,14 @@ FT_BEGIN_HEADER * FT_Done_Face( face ); * ... * } - * } + * ``` * - * To loop over all valid values for `face_index', use something - * similar to the following snippet, again without error handling. - * The code accesses all faces immediately (thus only a single call - * of `FT_Open_Face' within the do-loop), with and without named - * instances. + * To loop over all valid values for `face_index`, use something similar + * to the following snippet, again without error handling. The code + * accesses all faces immediately (thus only a single call of + * `FT_Open_Face` within the do-loop), with and without named instances. * - * { + * ``` * ... * FT_Face face; * @@ -2450,7 +2340,7 @@ FT_BEGIN_HEADER * } * * } while ( face_idx < num_faces ) - * } + * ``` */ FT_EXPORT( FT_Error ) FT_Open_Face( FT_Library library, @@ -2489,10 +2379,10 @@ FT_BEGIN_HEADER * FT_Attach_Stream * * @description: - * `Attach' data to a face object. Normally, this is used to read + * 'Attach' data to a face object. Normally, this is used to read * additional information for the face object. For example, you can - * attach an AFM file that comes with a Type~1 font to get the - * kerning values and other metrics. + * attach an AFM file that comes with a Type~1 font to get the kerning + * values and other metrics. * * @inout: * face :: @@ -2500,20 +2390,19 @@ FT_BEGIN_HEADER * * @input: * parameters :: - * A pointer to @FT_Open_Args that must be filled by - * the caller. + * A pointer to @FT_Open_Args that must be filled by the caller. * * @return: * FreeType error code. 0~means success. * * @note: - * The meaning of the `attach' (i.e., what really happens when the - * new file is read) is not fixed by FreeType itself. It really - * depends on the font format (and thus the font driver). + * The meaning of the 'attach' (i.e., what really happens when the new + * file is read) is not fixed by FreeType itself. It really depends on + * the font format (and thus the font driver). * - * Client applications are expected to know what they are doing - * when invoking this function. Most drivers simply do not implement - * file or stream attachments. + * Client applications are expected to know what they are doing when + * invoking this function. Most drivers simply do not implement file or + * stream attachments. */ FT_EXPORT( FT_Error ) FT_Attach_Stream( FT_Face face, @@ -2526,9 +2415,9 @@ FT_BEGIN_HEADER * FT_Reference_Face * * @description: - * A counter gets initialized to~1 at the time an @FT_Face structure - * is created. This function increments the counter. @FT_Done_Face - * then only destroys a face if the counter is~1, otherwise it simply + * A counter gets initialized to~1 at the time an @FT_Face structure is + * created. This function increments the counter. @FT_Done_Face then + * only destroys a face if the counter is~1, otherwise it simply * decrements the counter. * * This function helps in managing life-cycles of structures that @@ -2578,10 +2467,10 @@ FT_BEGIN_HEADER * FT_Select_Size * * @description: - * Select a bitmap strike. To be more precise, this function sets - * the scaling factors of the active @FT_Size object in a face so - * that bitmaps from this particular strike are taken by - * @FT_Load_Glyph and friends. + * Select a bitmap strike. To be more precise, this function sets the + * scaling factors of the active @FT_Size object in a face so that + * bitmaps from this particular strike are taken by @FT_Load_Glyph and + * friends. * * @inout: * face :: @@ -2589,23 +2478,22 @@ FT_BEGIN_HEADER * * @input: * strike_index :: - * The index of the bitmap strike in the - * `available_sizes' field of @FT_FaceRec structure. + * The index of the bitmap strike in the `available_sizes` field of + * @FT_FaceRec structure. * * @return: * FreeType error code. 0~means success. * * @note: - * For bitmaps embedded in outline fonts it is common that only a - * subset of the available glyphs at a given ppem value is available. - * FreeType silently uses outlines if there is no bitmap for a given - * glyph index. + * For bitmaps embedded in outline fonts it is common that only a subset + * of the available glyphs at a given ppem value is available. FreeType + * silently uses outlines if there is no bitmap for a given glyph index. * - * For GX and OpenType variation fonts, a bitmap strike makes sense - * only if the default instance is active (this is, no glyph - * variation takes place); otherwise, FreeType simply ignores bitmap - * strikes. The same is true for all named instances that are - * different from the default instance. + * For GX and OpenType variation fonts, a bitmap strike makes sense only + * if the default instance is active (this is, no glyph variation takes + * place); otherwise, FreeType simply ignores bitmap strikes. The same + * is true for all named instances that are different from the default + * instance. * * Don't use this function if you are using the FreeType cache API. */ @@ -2620,40 +2508,38 @@ FT_BEGIN_HEADER * FT_Size_Request_Type * * @description: - * An enumeration type that lists the supported size request types, - * i.e., what input size (in font units) maps to the requested output - * size (in pixels, as computed from the arguments of - * @FT_Size_Request). + * An enumeration type that lists the supported size request types, i.e., + * what input size (in font units) maps to the requested output size (in + * pixels, as computed from the arguments of @FT_Size_Request). * * @values: * FT_SIZE_REQUEST_TYPE_NOMINAL :: - * The nominal size. The `units_per_EM' field of @FT_FaceRec is - * used to determine both scaling values. + * The nominal size. The `units_per_EM` field of @FT_FaceRec is used + * to determine both scaling values. * * This is the standard scaling found in most applications. In - * particular, use this size request type for TrueType fonts if - * they provide optical scaling or something similar. Note, - * however, that `units_per_EM' is a rather abstract value which - * bears no relation to the actual size of the glyphs in a font. + * particular, use this size request type for TrueType fonts if they + * provide optical scaling or something similar. Note, however, that + * `units_per_EM` is a rather abstract value which bears no relation to + * the actual size of the glyphs in a font. * * FT_SIZE_REQUEST_TYPE_REAL_DIM :: - * The real dimension. The sum of the `ascender' and (minus of) - * the `descender' fields of @FT_FaceRec is used to determine both - * scaling values. + * The real dimension. The sum of the 'ascender' and (minus of) the + * 'descender' fields of @FT_FaceRec is used to determine both scaling + * values. * * FT_SIZE_REQUEST_TYPE_BBOX :: - * The font bounding box. The width and height of the `bbox' field - * of @FT_FaceRec are used to determine the horizontal and vertical + * The font bounding box. The width and height of the 'bbox' field of + * @FT_FaceRec are used to determine the horizontal and vertical * scaling value, respectively. * * FT_SIZE_REQUEST_TYPE_CELL :: - * The `max_advance_width' field of @FT_FaceRec is used to - * determine the horizontal scaling value; the vertical scaling - * value is determined the same way as - * @FT_SIZE_REQUEST_TYPE_REAL_DIM does. Finally, both scaling - * values are set to the smaller one. This type is useful if you - * want to specify the font size for, say, a window of a given - * dimension and 80x24 cells. + * The `max_advance_width` field of @FT_FaceRec is used to determine + * the horizontal scaling value; the vertical scaling value is + * determined the same way as @FT_SIZE_REQUEST_TYPE_REAL_DIM does. + * Finally, both scaling values are set to the smaller one. This type + * is useful if you want to specify the font size for, say, a window of + * a given dimension and 80x24 cells. * * FT_SIZE_REQUEST_TYPE_SCALES :: * Specify the scaling values directly. @@ -2691,33 +2577,31 @@ FT_BEGIN_HEADER * See @FT_Size_Request_Type. * * width :: - * The desired width, given as a 26.6 fractional - * point value (with 72pt = 1in). + * The desired width, given as a 26.6 fractional point value (with 72pt + * = 1in). * * height :: - * The desired height, given as a 26.6 fractional - * point value (with 72pt = 1in). + * The desired height, given as a 26.6 fractional point value (with + * 72pt = 1in). * * horiResolution :: - * The horizontal resolution (dpi, i.e., pixels per - * inch). If set to zero, `width' is treated as a - * 26.6 fractional *pixel* value, which gets - * internally rounded to an integer. + * The horizontal resolution (dpi, i.e., pixels per inch). If set to + * zero, 'width' is treated as a 26.6 fractional **pixel** value, which + * gets internally rounded to an integer. * * vertResolution :: - * The vertical resolution (dpi, i.e., pixels per - * inch). If set to zero, `height' is treated as a - * 26.6 fractional *pixel* value, which gets - * internally rounded to an integer. + * The vertical resolution (dpi, i.e., pixels per inch). If set to + * zero, 'height' is treated as a 26.6 fractional **pixel** value, + * which gets internally rounded to an integer. * * @note: - * If `width' is zero, the horizontal scaling value is set equal - * to the vertical scaling value, and vice versa. + * If 'width' is zero, the horizontal scaling value is set equal to the + * vertical scaling value, and vice versa. * - * If `type' is FT_SIZE_REQUEST_TYPE_SCALES, `width' and `height' are - * interpreted directly as 16.16 fractional scaling values, without - * any further modification, and both `horiResolution' and - * `vertResolution' are ignored. + * If 'type' is FT_SIZE_REQUEST_TYPE_SCALES, 'width' and 'height' are + * interpreted directly as 16.16 fractional scaling values, without any + * further modification, and both `horiResolution` and `vertResolution` + * are ignored. */ typedef struct FT_Size_RequestRec_ { @@ -2761,20 +2645,19 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * Although drivers may select the bitmap strike matching the - * request, you should not rely on this if you intend to select a - * particular bitmap strike. Use @FT_Select_Size instead in that - * case. + * Although drivers may select the bitmap strike matching the request, + * you should not rely on this if you intend to select a particular + * bitmap strike. Use @FT_Select_Size instead in that case. * - * The relation between the requested size and the resulting glyph - * size is dependent entirely on how the size is defined in the - * source face. The font designer chooses the final size of each - * glyph relative to this size. For more information refer to - * `https://www.freetype.org/freetype2/docs/glyphs/glyphs-2.html'. + * The relation between the requested size and the resulting glyph size + * is dependent entirely on how the size is defined in the source face. + * The font designer chooses the final size of each glyph relative to + * this size. For more information refer to + * 'https://www.freetype.org/freetype2/docs/glyphs/glyphs-2.html'. * - * Contrary to @FT_Set_Char_Size, this function doesn't have special - * code to normalize zero-valued widths, heights, or resolutions - * (which lead to errors in most cases). + * Contrary to @FT_Set_Char_Size, this function doesn't have special code + * to normalize zero-valued widths, heights, or resolutions (which lead + * to errors in most cases). * * Don't use this function if you are using the FreeType cache API. */ @@ -2813,17 +2696,17 @@ FT_BEGIN_HEADER * * @note: * While this function allows fractional points as input values, the - * resulting ppem value for the given resolution is always rounded to - * the nearest integer. + * resulting ppem value for the given resolution is always rounded to the + * nearest integer. * - * If either the character width or height is zero, it is set equal - * to the other value. + * If either the character width or height is zero, it is set equal to + * the other value. * * If either the horizontal or vertical resolution is zero, it is set * equal to the other value. * - * A character width or height smaller than 1pt is set to 1pt; if - * both resolution values are zero, they are set to 72dpi. + * A character width or height smaller than 1pt is set to 1pt; if both + * resolution values are zero, they are set to 72dpi. * * Don't use this function if you are using the FreeType cache API. */ @@ -2880,37 +2763,35 @@ FT_BEGIN_HEADER * * @inout: * face :: - * A handle to the target face object where the glyph - * is loaded. + * A handle to the target face object where the glyph is loaded. * * @input: * glyph_index :: - * The index of the glyph in the font file. For - * CID-keyed fonts (either in PS or in CFF format) - * this argument specifies the CID value. + * The index of the glyph in the font file. For CID-keyed fonts + * (either in PS or in CFF format) this argument specifies the CID + * value. * * load_flags :: - * A flag indicating what to load for this glyph. The - * @FT_LOAD_XXX constants can be used to control the - * glyph loading process (e.g., whether the outline - * should be scaled, whether to load bitmaps or not, - * whether to hint the outline, etc). + * A flag indicating what to load for this glyph. The @FT_LOAD_XXX + * constants can be used to control the glyph loading process (e.g., + * whether the outline should be scaled, whether to load bitmaps or + * not, whether to hint the outline, etc). * * @return: * FreeType error code. 0~means success. * * @note: - * The loaded glyph may be transformed. See @FT_Set_Transform for - * the details. + * The loaded glyph may be transformed. See @FT_Set_Transform for the + * details. * - * For subsetted CID-keyed fonts, `FT_Err_Invalid_Argument' is - * returned for invalid CID values (this is, for CID values that - * don't have a corresponding glyph in the font). See the discussion - * of the @FT_FACE_FLAG_CID_KEYED flag for more details. + * For subsetted CID-keyed fonts, `FT_Err_Invalid_Argument` is returned + * for invalid CID values (this is, for CID values that don't have a + * corresponding glyph in the font). See the discussion of the + * @FT_FACE_FLAG_CID_KEYED flag for more details. * - * If you receive `FT_Err_Glyph_Too_Big', try getting the glyph - * outline at EM size, then scale it manually and fill it as a - * graphics operation. + * If you receive `FT_Err_Glyph_Too_Big`, try getting the glyph outline + * at EM size, then scale it manually and fill it as a graphics + * operation. */ FT_EXPORT( FT_Error ) FT_Load_Glyph( FT_Face face, @@ -2929,20 +2810,18 @@ FT_BEGIN_HEADER * * @inout: * face :: - * A handle to a target face object where the glyph - * is loaded. + * A handle to a target face object where the glyph is loaded. * * @input: * char_code :: - * The glyph's character code, according to the - * current charmap used in the face. + * The glyph's character code, according to the current charmap used in + * the face. * * load_flags :: - * A flag indicating what to load for this glyph. The - * @FT_LOAD_XXX constants can be used to control the - * glyph loading process (e.g., whether the outline - * should be scaled, whether to load bitmaps or not, - * whether to hint the outline, etc). + * A flag indicating what to load for this glyph. The @FT_LOAD_XXX + * constants can be used to control the glyph loading process (e.g., + * whether the outline should be scaled, whether to load bitmaps or + * not, whether to hint the outline, etc). * * @return: * FreeType error code. 0~means success. @@ -2950,13 +2829,12 @@ FT_BEGIN_HEADER * @note: * This function simply calls @FT_Get_Char_Index and @FT_Load_Glyph. * - * Many fonts contain glyphs that can't be loaded by this function - * since its glyph indices are not listed in any of the font's - * charmaps. + * Many fonts contain glyphs that can't be loaded by this function since + * its glyph indices are not listed in any of the font's charmaps. * - * If no active cmap is set up (i.e., `face->charmap' is zero), the - * call to @FT_Get_Char_Index is omitted, and the function behaves - * identically to @FT_Load_Glyph. + * If no active cmap is set up (i.e., `face->charmap` is zero), the call + * to @FT_Get_Char_Index is omitted, and the function behaves identically + * to @FT_Load_Glyph. */ FT_EXPORT( FT_Error ) FT_Load_Char( FT_Face face, @@ -2970,8 +2848,8 @@ FT_BEGIN_HEADER * FT_LOAD_XXX * * @description: - * A list of bit field constants for @FT_Load_Glyph to indicate what - * kind of operations to perform during glyph loading. + * A list of bit field constants for @FT_Load_Glyph to indicate what kind + * of operations to perform during glyph loading. * * @values: * FT_LOAD_DEFAULT :: @@ -2979,15 +2857,14 @@ FT_BEGIN_HEADER * operation. In this case, the following happens: * * 1. FreeType looks for a bitmap for the glyph corresponding to the - * face's current size. If one is found, the function returns. - * The bitmap data can be accessed from the glyph slot (see note - * below). + * face's current size. If one is found, the function returns. The + * bitmap data can be accessed from the glyph slot (see note below). * * 2. If no embedded bitmap is searched for or found, FreeType looks - * for a scalable outline. If one is found, it is loaded from - * the font file, scaled to device pixels, then `hinted' to the - * pixel grid in order to optimize it. The outline data can be - * accessed from the glyph slot (see note below). + * for a scalable outline. If one is found, it is loaded from the font + * file, scaled to device pixels, then 'hinted' to the pixel grid in + * order to optimize it. The outline data can be accessed from the + * glyph slot (see note below). * * Note that by default the glyph loader doesn't render outlines into * bitmaps. The following flags are used to modify this default @@ -2999,14 +2876,14 @@ FT_BEGIN_HEADER * This flag implies @FT_LOAD_NO_HINTING and @FT_LOAD_NO_BITMAP, and * unsets @FT_LOAD_RENDER. * - * If the font is `tricky' (see @FT_FACE_FLAG_TRICKY for more), using + * If the font is 'tricky' (see @FT_FACE_FLAG_TRICKY for more), using * FT_LOAD_NO_SCALE usually yields meaningless outlines because the * subglyphs must be scaled and positioned with hinting instructions. * This can be solved by loading the font without FT_LOAD_NO_SCALE and - * setting the character size to `font->units_per_EM'. + * setting the character size to `font->units_per_EM`. * * FT_LOAD_NO_HINTING :: - * Disable hinting. This generally generates `blurrier' bitmap glyphs + * Disable hinting. This generally generates 'blurrier' bitmap glyphs * when the glyph are rendered in any of the anti-aliased modes. See * also the note below. * @@ -3027,34 +2904,34 @@ FT_BEGIN_HEADER * * FT_LOAD_VERTICAL_LAYOUT :: * Load the glyph for vertical text layout. In particular, the - * `advance' value in the @FT_GlyphSlotRec structure is set to the - * `vertAdvance' value of the `metrics' field. + * 'advance' value in the @FT_GlyphSlotRec structure is set to the + * `vertAdvance` value of the 'metrics' field. * - * In case @FT_HAS_VERTICAL doesn't return true, you shouldn't use - * this flag currently. Reason is that in this case vertical metrics - * get synthesized, and those values are not always consistent across + * In case @FT_HAS_VERTICAL doesn't return true, you shouldn't use this + * flag currently. Reason is that in this case vertical metrics get + * synthesized, and those values are not always consistent across * various font formats. * * FT_LOAD_FORCE_AUTOHINT :: - * Prefer the auto-hinter over the font's native hinter. See also - * the note below. + * Prefer the auto-hinter over the font's native hinter. See also the + * note below. * * FT_LOAD_PEDANTIC :: * Make the font driver perform pedantic verifications during glyph - * loading. This is mostly used to detect broken glyphs in fonts. - * By default, FreeType tries to handle broken fonts also. + * loading. This is mostly used to detect broken glyphs in fonts. By + * default, FreeType tries to handle broken fonts also. * * In particular, errors from the TrueType bytecode engine are not - * passed to the application if this flag is not set; this might - * result in partially hinted or distorted glyphs in case a glyph's - * bytecode is buggy. + * passed to the application if this flag is not set; this might result + * in partially hinted or distorted glyphs in case a glyph's bytecode + * is buggy. * * FT_LOAD_NO_RECURSE :: - * Don't load composite glyphs recursively. Instead, the font - * driver should set the `num_subglyph' and `subglyphs' values of - * the glyph slot accordingly, and set `glyph->format' to - * @FT_GLYPH_FORMAT_COMPOSITE. The description of subglyphs can - * then be accessed with @FT_Get_SubGlyph_Info. + * Don't load composite glyphs recursively. Instead, the font driver + * should set the `num_subglyph` and 'subglyphs' values of the glyph + * slot accordingly, and set `glyph->format` to + * @FT_GLYPH_FORMAT_COMPOSITE. The description of subglyphs can then + * be accessed with @FT_Get_SubGlyph_Info. * * This flag implies @FT_LOAD_NO_SCALE and @FT_LOAD_IGNORE_TRANSFORM. * @@ -3071,9 +2948,8 @@ FT_BEGIN_HEADER * monochrome-optimized hinting algorithm is used. * * FT_LOAD_LINEAR_DESIGN :: - * Keep `linearHoriAdvance' and `linearVertAdvance' fields of - * @FT_GlyphSlotRec in font units. See @FT_GlyphSlotRec for - * details. + * Keep `linearHoriAdvance` and `linearVertAdvance` fields of + * @FT_GlyphSlotRec in font units. See @FT_GlyphSlotRec for details. * * FT_LOAD_NO_AUTOHINT :: * Disable the auto-hinter. See also the note below. @@ -3089,18 +2965,18 @@ FT_BEGIN_HEADER * bitmaps, using the @FT_PIXEL_MODE_GRAY format. * * [Since 2.10] If the glyph index contains an entry in the face's - * `COLR' table with a `CPAL' palette table (as defined in the - * OpenType specification), make @FT_Render_Glyph provide a default - * blending of the color glyph layers associated with the glyph index, - * using the same bitmap format as embedded color bitmap images. This - * is mainly for convenience; for full control of color layers use + * 'COLR' table with a 'CPAL' palette table (as defined in the OpenType + * specification), make @FT_Render_Glyph provide a default blending of + * the color glyph layers associated with the glyph index, using the + * same bitmap format as embedded color bitmap images. This is mainly + * for convenience; for full control of color layers use * @FT_Get_Color_Glyph_Layer and FreeType's color functions like - * @FT_Palette_Select instead of setting FT_LOAD_COLOR for rendering - * so that the client application can handle blending by itself. + * @FT_Palette_Select instead of setting FT_LOAD_COLOR for rendering so + * that the client application can handle blending by itself. * * FT_LOAD_COMPUTE_METRICS :: - * [Since 2.6.1] Compute glyph metrics from the glyph data, without - * the use of bundled metrics tables (for example, the `hdmx' table in + * [Since 2.6.1] Compute glyph metrics from the glyph data, without the + * use of bundled metrics tables (for example, the 'hdmx' table in * TrueType fonts). This flag is mainly used by font validating or * font editing applications, which need to ignore, verify, or edit * those tables. @@ -3109,9 +2985,9 @@ FT_BEGIN_HEADER * * FT_LOAD_BITMAP_METRICS_ONLY :: * [Since 2.7.1] Request loading of the metrics and bitmap image - * information of a (possibly embedded) bitmap glyph without - * allocating or copying the bitmap image data itself. No effect if - * the target glyph is not a bitmap image. + * information of a (possibly embedded) bitmap glyph without allocating + * or copying the bitmap image data itself. No effect if the target + * glyph is not a bitmap image. * * This flag unsets @FT_LOAD_RENDER. * @@ -3126,8 +3002,8 @@ FT_BEGIN_HEADER * @FT_FACE_FLAG_HINTER) is preferred over the auto-hinter. You can * disable hinting by setting @FT_LOAD_NO_HINTING or change the * precedence by setting @FT_LOAD_FORCE_AUTOHINT. You can also set - * @FT_LOAD_NO_AUTOHINT in case you don't want the auto-hinter to be - * used at all. + * @FT_LOAD_NO_AUTOHINT in case you don't want the auto-hinter to be used + * at all. * * See the description of @FT_FACE_FLAG_TRICKY for a special exception * (affecting only a handful of Asian fonts). @@ -3177,19 +3053,17 @@ FT_BEGIN_HEADER * * @description: * A list of values to select a specific hinting algorithm for the - * hinter. You should OR one of these values to your `load_flags' - * when calling @FT_Load_Glyph. + * hinter. You should OR one of these values to your `load_flags` when + * calling @FT_Load_Glyph. * - * Note that a font's native hinters may ignore the hinting algorithm - * you have specified (e.g., the TrueType bytecode interpreter). You - * can set @FT_LOAD_FORCE_AUTOHINT to ensure that the auto-hinter is - * used. + * Note that a font's native hinters may ignore the hinting algorithm you + * have specified (e.g., the TrueType bytecode interpreter). You can set + * @FT_LOAD_FORCE_AUTOHINT to ensure that the auto-hinter is used. * * @values: * FT_LOAD_TARGET_NORMAL :: * The default hinting algorithm, optimized for standard gray-level - * rendering. For monochrome output, use @FT_LOAD_TARGET_MONO - * instead. + * rendering. For monochrome output, use @FT_LOAD_TARGET_MONO instead. * * FT_LOAD_TARGET_LIGHT :: * A lighter hinting algorithm for gray-level modes. Many generated @@ -3202,14 +3076,13 @@ FT_BEGIN_HEADER * auto-hinter. * * Advance widths are rounded to integer values; however, using the - * `lsb_delta' and `rsb_delta' fields of @FT_GlyphSlotRec, it is + * `lsb_delta` and `rsb_delta` fields of @FT_GlyphSlotRec, it is * possible to get fractional advance widths for subpixel positioning * (which is recommended to use). * * If configuration option AF_CONFIG_OPTION_TT_SIZE_METRICS is active, - * TrueType-like metrics are used to make this mode behave similarly - * as in unpatched FreeType versions between 2.4.6 and 2.7.1 - * (inclusive). + * TrueType-like metrics are used to make this mode behave similarly as + * in unpatched FreeType versions between 2.4.6 and 2.7.1 (inclusive). * * FT_LOAD_TARGET_MONO :: * Strong hinting algorithm that should only be used for monochrome @@ -3226,7 +3099,7 @@ FT_BEGIN_HEADER * * @note: * You should use only _one_ of the FT_LOAD_TARGET_XXX values in your - * `load_flags'. They can't be ORed. + * `load_flags`. They can't be ORed. * * If @FT_LOAD_RENDER is also set, the glyph is rendered in the * corresponding mode (i.e., the mode that matches the used algorithm @@ -3234,16 +3107,16 @@ FT_BEGIN_HEADER * @FT_LOAD_MONOCHROME. * * You can use a hinting algorithm that doesn't correspond to the same - * rendering mode. As an example, it is possible to use the `light' + * rendering mode. As an example, it is possible to use the 'light' * hinting algorithm and have the results rendered in horizontal LCD * pixel mode, with code like * - * { + * ``` * FT_Load_Glyph( face, glyph_index, * load_flags | FT_LOAD_TARGET_LIGHT ); * * FT_Render_Glyph( face->glyph, FT_RENDER_MODE_LCD ); - * } + * ``` * * In general, you should stick with one rendering mode. For example, * switching between @FT_LOAD_TARGET_NORMAL and @FT_LOAD_TARGET_MONO @@ -3281,8 +3154,8 @@ FT_BEGIN_HEADER * FT_Set_Transform * * @description: - * Set the transformation that is applied to glyph images when they - * are loaded into a glyph slot through @FT_Load_Glyph. + * Set the transformation that is applied to glyph images when they are + * loaded into a glyph slot through @FT_Load_Glyph. * * @inout: * face :: @@ -3290,20 +3163,19 @@ FT_BEGIN_HEADER * * @input: * matrix :: - * A pointer to the transformation's 2x2 matrix. Use NULL - * for the identity matrix. + * A pointer to the transformation's 2x2 matrix. Use NULL for the + * identity matrix. * delta :: - * A pointer to the translation vector. Use NULL for the - * null vector. + * A pointer to the translation vector. Use NULL for the null vector. * * @note: - * The transformation is only applied to scalable image formats after - * the glyph has been loaded. It means that hinting is unaltered by - * the transformation and is performed on the character size given in - * the last call to @FT_Set_Char_Size or @FT_Set_Pixel_Sizes. + * The transformation is only applied to scalable image formats after the + * glyph has been loaded. It means that hinting is unaltered by the + * transformation and is performed on the character size given in the + * last call to @FT_Set_Char_Size or @FT_Set_Pixel_Sizes. * - * Note that this also transforms the `face.glyph.advance' field, but - * *not* the values in `face.glyph.metrics'. + * Note that this also transforms the `face.glyph.advance` field, but + * **not** the values in `face.glyph.metrics`. */ FT_EXPORT( void ) FT_Set_Transform( FT_Face face, @@ -3320,9 +3192,9 @@ FT_BEGIN_HEADER * Render modes supported by FreeType~2. Each mode corresponds to a * specific type of scanline conversion performed on the outline. * - * For bitmap fonts and embedded bitmaps the `bitmap->pixel_mode' - * field in the @FT_GlyphSlotRec structure gives the format of the - * returned bitmap. + * For bitmap fonts and embedded bitmaps the `bitmap->pixel_mode` field + * in the @FT_GlyphSlotRec structure gives the format of the returned + * bitmap. * * All modes except @FT_RENDER_MODE_MONO use 256 levels of opacity, * indicating pixel coverage. Use linear alpha blending and gamma @@ -3331,44 +3203,42 @@ FT_BEGIN_HEADER * * @values: * FT_RENDER_MODE_NORMAL :: - * Default render mode; it corresponds to 8-bit anti-aliased - * bitmaps. + * Default render mode; it corresponds to 8-bit anti-aliased bitmaps. * * FT_RENDER_MODE_LIGHT :: - * This is equivalent to @FT_RENDER_MODE_NORMAL. It is only - * defined as a separate value because render modes are also used - * indirectly to define hinting algorithm selectors. See - * @FT_LOAD_TARGET_XXX for details. + * This is equivalent to @FT_RENDER_MODE_NORMAL. It is only defined as + * a separate value because render modes are also used indirectly to + * define hinting algorithm selectors. See @FT_LOAD_TARGET_XXX for + * details. * * FT_RENDER_MODE_MONO :: - * This mode corresponds to 1-bit bitmaps (with 2~levels of - * opacity). + * This mode corresponds to 1-bit bitmaps (with 2~levels of opacity). * * FT_RENDER_MODE_LCD :: - * This mode corresponds to horizontal RGB and BGR subpixel - * displays like LCD screens. It produces 8-bit bitmaps that are - * 3~times the width of the original glyph outline in pixels, and - * which use the @FT_PIXEL_MODE_LCD mode. + * This mode corresponds to horizontal RGB and BGR subpixel displays + * like LCD screens. It produces 8-bit bitmaps that are 3~times the + * width of the original glyph outline in pixels, and which use the + * @FT_PIXEL_MODE_LCD mode. * * FT_RENDER_MODE_LCD_V :: * This mode corresponds to vertical RGB and BGR subpixel displays - * (like PDA screens, rotated LCD displays, etc.). It produces - * 8-bit bitmaps that are 3~times the height of the original - * glyph outline in pixels and use the @FT_PIXEL_MODE_LCD_V mode. + * (like PDA screens, rotated LCD displays, etc.). It produces 8-bit + * bitmaps that are 3~times the height of the original glyph outline in + * pixels and use the @FT_PIXEL_MODE_LCD_V mode. * * @note: * Should you define FT_CONFIG_OPTION_SUBPIXEL_RENDERING in your - * `ftoption.h', which enables patented ClearType-style rendering, - * the LCD-optimized glyph bitmaps should be filtered to reduce color - * fringes inherent to this technology. You can either set up LCD - * filtering with @FT_Library_SetLcdFilter or @FT_Face_Properties, - * or do the filtering yourself. The default FreeType LCD rendering - * technology does not require filtering. + * `ftoption.h`, which enables patented ClearType-style rendering, the + * LCD-optimized glyph bitmaps should be filtered to reduce color fringes + * inherent to this technology. You can either set up LCD filtering with + * @FT_Library_SetLcdFilter or @FT_Face_Properties, or do the filtering + * yourself. The default FreeType LCD rendering technology does not + * require filtering. * * The selected render mode only affects vector glyphs of a font. * Embedded bitmaps often have a different pixel mode like - * @FT_PIXEL_MODE_MONO. You can use @FT_Bitmap_Convert to transform - * them into 8-bit pixmaps. + * @FT_PIXEL_MODE_MONO. You can use @FT_Bitmap_Convert to transform them + * into 8-bit pixmaps. */ typedef enum FT_Render_Mode_ { @@ -3395,112 +3265,103 @@ FT_BEGIN_HEADER * FT_Render_Glyph * * @description: - * Convert a given glyph image to a bitmap. It does so by inspecting - * the glyph image format, finding the relevant renderer, and - * invoking it. + * Convert a given glyph image to a bitmap. It does so by inspecting the + * glyph image format, finding the relevant renderer, and invoking it. * * @inout: * slot :: - * A handle to the glyph slot containing the image to - * convert. + * A handle to the glyph slot containing the image to convert. * * @input: * render_mode :: - * The render mode used to render the glyph image into - * a bitmap. See @FT_Render_Mode for a list of - * possible values. - * - * If @FT_RENDER_MODE_NORMAL is used, the flag - * @FT_LOAD_COLOR can be additionally set to make the - * function provide a default blending of colored - * glyph layers associated with the current glyph slot - * (provided the font contains such layers) instead of - * rendering the glyph slot's outline. See - * @FT_LOAD_COLOR for more information. + * The render mode used to render the glyph image into a bitmap. See + * @FT_Render_Mode for a list of possible values. + * + * If @FT_RENDER_MODE_NORMAL is used, the flag @FT_LOAD_COLOR can be + * additionally set to make the function provide a default blending of + * colored glyph layers associated with the current glyph slot + * (provided the font contains such layers) instead of rendering the + * glyph slot's outline. See @FT_LOAD_COLOR for more information. * * @return: * FreeType error code. 0~means success. * * @note: * To get meaningful results, font scaling values must be set with - * functions like @FT_Set_Char_Size before calling `FT_Render_Glyph'. - * - * When FreeType outputs a bitmap of a glyph, it really outputs an - * alpha coverage map. If a pixel is completely covered by a - * filled-in outline, the bitmap contains 0xFF at that pixel, meaning - * that 0xFF/0xFF fraction of that pixel is covered, meaning the - * pixel is 100% black (or 0% bright). If a pixel is only 50% - * covered (value 0x80), the pixel is made 50% black (50% bright or a - * middle shade of grey). 0% covered means 0% black (100% bright or - * white). - * - * On high-DPI screens like on smartphones and tablets, the pixels - * are so small that their chance of being completely covered and - * therefore completely black are fairly good. On the low-DPI - * screens, however, the situation is different. The pixels are too - * large for most of the details of a glyph and shades of gray are - * the norm rather than the exception. - * - * This is relevant because all our screens have a second problem: - * they are not linear. 1~+~1 is not~2. Twice the value does not - * result in twice the brightness. When a pixel is only 50% covered, - * the coverage map says 50% black, and this translates to a pixel - * value of 128 when you use 8~bits per channel (0-255). However, - * this does not translate to 50% brightness for that pixel on our - * sRGB and gamma~2.2 screens. Due to their non-linearity, they - * dwell longer in the darks and only a pixel value of about 186 - * results in 50% brightness -- 128 ends up too dark on both bright - * and dark backgrounds. The net result is that dark text looks - * burnt-out, pixely and blotchy on bright background, bright text - * too frail on dark backgrounds, and colored text on colored + * functions like @FT_Set_Char_Size before calling `FT_Render_Glyph`. + * + * When FreeType outputs a bitmap of a glyph, it really outputs an alpha + * coverage map. If a pixel is completely covered by a filled-in + * outline, the bitmap contains 0xFF at that pixel, meaning that + * 0xFF/0xFF fraction of that pixel is covered, meaning the pixel is 100% + * black (or 0% bright). If a pixel is only 50% covered (value 0x80), + * the pixel is made 50% black (50% bright or a middle shade of grey). + * 0% covered means 0% black (100% bright or white). + * + * On high-DPI screens like on smartphones and tablets, the pixels are so + * small that their chance of being completely covered and therefore + * completely black are fairly good. On the low-DPI screens, however, + * the situation is different. The pixels are too large for most of the + * details of a glyph and shades of gray are the norm rather than the + * exception. + * + * This is relevant because all our screens have a second problem: they + * are not linear. 1~+~1 is not~2. Twice the value does not result in + * twice the brightness. When a pixel is only 50% covered, the coverage + * map says 50% black, and this translates to a pixel value of 128 when + * you use 8~bits per channel (0-255). However, this does not translate + * to 50% brightness for that pixel on our sRGB and gamma~2.2 screens. + * Due to their non-linearity, they dwell longer in the darks and only a + * pixel value of about 186 results in 50% brightness -- 128 ends up too + * dark on both bright and dark backgrounds. The net result is that dark + * text looks burnt-out, pixely and blotchy on bright background, bright + * text too frail on dark backgrounds, and colored text on colored * background (for example, red on green) seems to have dark halos or - * `dirt' around it. The situation is especially ugly for diagonal - * stems like in `w' glyph shapes where the quality of FreeType's - * anti-aliasing depends on the correct display of grays. On - * high-DPI screens where smaller, fully black pixels reign supreme, - * this doesn't matter, but on our low-DPI screens with all the gray - * shades, it does. 0% and 100% brightness are the same things in - * linear and non-linear space, just all the shades in-between - * aren't. + * 'dirt' around it. The situation is especially ugly for diagonal stems + * like in 'w' glyph shapes where the quality of FreeType's anti-aliasing + * depends on the correct display of grays. On high-DPI screens where + * smaller, fully black pixels reign supreme, this doesn't matter, but on + * our low-DPI screens with all the gray shades, it does. 0% and 100% + * brightness are the same things in linear and non-linear space, just + * all the shades in-between aren't. * * The blending function for placing text over a background is * - * { + * ``` * dst = alpha * src + (1 - alpha) * dst , - * } + * ``` * * which is known as the OVER operator. * - * To correctly composite an antialiased pixel of a glyph onto a - * surface, + * To correctly composite an antialiased pixel of a glyph onto a surface, * * 1. take the foreground and background colors (e.g., in sRGB space) * and apply gamma to get them in a linear space, * * 2. use OVER to blend the two linear colors using the glyph pixel - * as the alpha value (remember, the glyph bitmap is an alpha - * coverage bitmap), and + * as the alpha value (remember, the glyph bitmap is an alpha coverage + * bitmap), and * * 3. apply inverse gamma to the blended pixel and write it back to * the image. * - * Internal testing at Adobe found that a target inverse gamma of~1.8 - * for step~3 gives good results across a wide range of displays with - * an sRGB gamma curve or a similar one. + * Internal testing at Adobe found that a target inverse gamma of~1.8 for + * step~3 gives good results across a wide range of displays with an sRGB + * gamma curve or a similar one. * * This process can cost performance. There is an approximation that * does not need to know about the background color; see * https://bel.fi/alankila/lcd/ and * https://bel.fi/alankila/lcd/alpcor.html for details. * - * *ATTENTION*: Linear blending is even more important when dealing + * **ATTENTION**: Linear blending is even more important when dealing * with subpixel-rendered glyphs to prevent color-fringing! A * subpixel-rendered glyph must first be filtered with a filter that - * gives equal weight to the three color primaries and does not - * exceed a sum of 0x100, see section @lcd_rendering. Then the - * only difference to gray linear blending is that subpixel-rendered - * linear blending is done 3~times per pixel: red foreground subpixel - * to red background subpixel and so on for green and blue. + * gives equal weight to the three color primaries and does not exceed a + * sum of 0x100, see section @lcd_rendering. Then the only difference to + * gray linear blending is that subpixel-rendered linear blending is done + * 3~times per pixel: red foreground subpixel to red background subpixel + * and so on for green and blue. */ FT_EXPORT( FT_Error ) FT_Render_Glyph( FT_GlyphSlot slot, @@ -3518,21 +3379,18 @@ FT_BEGIN_HEADER * * @values: * FT_KERNING_DEFAULT :: - * Return grid-fitted kerning distances in - * 26.6 fractional pixels. + * Return grid-fitted kerning distances in 26.6 fractional pixels. * * FT_KERNING_UNFITTED :: - * Return un-grid-fitted kerning distances in - * 26.6 fractional pixels. + * Return un-grid-fitted kerning distances in 26.6 fractional pixels. * * FT_KERNING_UNSCALED :: - * Return the kerning vector in original font - * units. + * Return the kerning vector in original font units. * * @note: - * FT_KERNING_DEFAULT returns full pixel values; it also makes - * FreeType heuristically scale down kerning distances at small ppem - * values so that they don't become too big. + * FT_KERNING_DEFAULT returns full pixel values; it also makes FreeType + * heuristically scale down kerning distances at small ppem values so + * that they don't become too big. * * Both FT_KERNING_DEFAULT and FT_KERNING_UNFITTED use the current * horizontal scaling factor (as set e.g. with @FT_Set_Char_Size) to @@ -3573,29 +3431,27 @@ FT_BEGIN_HEADER * The index of the right glyph in the kern pair. * * kern_mode :: - * See @FT_Kerning_Mode for more information. - * Determines the scale and dimension of the returned - * kerning vector. + * See @FT_Kerning_Mode for more information. Determines the scale and + * dimension of the returned kerning vector. * * @output: * akerning :: - * The kerning vector. This is either in font units, - * fractional pixels (26.6 format), or pixels for - * scalable formats, and in pixels for fixed-sizes - * formats. + * The kerning vector. This is either in font units, fractional pixels + * (26.6 format), or pixels for scalable formats, and in pixels for + * fixed-sizes formats. * * @return: * FreeType error code. 0~means success. * * @note: - * Only horizontal layouts (left-to-right & right-to-left) are - * supported by this method. Other layouts, or more sophisticated - * kernings, are out of the scope of this API function -- they can be - * implemented through format-specific interfaces. + * Only horizontal layouts (left-to-right & right-to-left) are supported + * by this method. Other layouts, or more sophisticated kernings, are + * out of the scope of this API function -- they can be implemented + * through format-specific interfaces. * - * Kerning for OpenType fonts implemented in a `GPOS' table is not + * Kerning for OpenType fonts implemented in a 'GPOS' table is not * supported; use @FT_HAS_KERNING to find out whether a font has data - * that can be extracted with `FT_Get_Kerning'. + * that can be extracted with `FT_Get_Kerning`. */ FT_EXPORT( FT_Error ) FT_Get_Kerning( FT_Face face, @@ -3621,26 +3477,25 @@ FT_BEGIN_HEADER * The point size in 16.16 fractional points. * * degree :: - * The degree of tightness. Increasingly negative - * values represent tighter track kerning, while - * increasingly positive values represent looser track - * kerning. Value zero means no track kerning. + * The degree of tightness. Increasingly negative values represent + * tighter track kerning, while increasingly positive values represent + * looser track kerning. Value zero means no track kerning. * * @output: * akerning :: - * The kerning in 16.16 fractional points, to be - * uniformly applied between all glyphs. + * The kerning in 16.16 fractional points, to be uniformly applied + * between all glyphs. * * @return: * FreeType error code. 0~means success. * * @note: - * Currently, only the Type~1 font driver supports track kerning, - * using data from AFM files (if attached with @FT_Attach_File or + * Currently, only the Type~1 font driver supports track kerning, using + * data from AFM files (if attached with @FT_Attach_File or * @FT_Attach_Stream). * - * Only very few AFM files come with track kerning data; please refer - * to Adobe's AFM specification for more details. + * Only very few AFM files come with track kerning data; please refer to + * Adobe's AFM specification for more details. */ FT_EXPORT( FT_Error ) FT_Get_Track_Kerning( FT_Face face, @@ -3655,8 +3510,8 @@ FT_BEGIN_HEADER * FT_Get_Glyph_Name * * @description: - * Retrieve the ASCII name of a given glyph in a face. This only - * works for those faces where @FT_HAS_GLYPH_NAMES(face) returns~1. + * Retrieve the ASCII name of a given glyph in a face. This only works + * for those faces where @FT_HAS_GLYPH_NAMES(face) returns~1. * * @input: * face :: @@ -3666,31 +3521,28 @@ FT_BEGIN_HEADER * The glyph index. * * buffer_max :: - * The maximum number of bytes available in the - * buffer. + * The maximum number of bytes available in the buffer. * * @output: * buffer :: - * A pointer to a target buffer where the name is - * copied to. + * A pointer to a target buffer where the name is copied to. * * @return: * FreeType error code. 0~means success. * * @note: - * An error is returned if the face doesn't provide glyph names or if - * the glyph index is invalid. In all cases of failure, the first - * byte of `buffer' is set to~0 to indicate an empty name. + * An error is returned if the face doesn't provide glyph names or if the + * glyph index is invalid. In all cases of failure, the first byte of + * 'buffer' is set to~0 to indicate an empty name. * * The glyph name is truncated to fit within the buffer if it is too * long. The returned string is always zero-terminated. * - * Be aware that FreeType reorders glyph indices internally so that - * glyph index~0 always corresponds to the `missing glyph' (called - * `.notdef'). + * Be aware that FreeType reorders glyph indices internally so that glyph + * index~0 always corresponds to the 'missing glyph' (called '.notdef'). * * This function always returns an error if the config macro - * `FT_CONFIG_OPTION_NO_GLYPH_NAMES' is not defined in `ftoption.h'. + * `FT_CONFIG_OPTION_NO_GLYPH_NAMES` is not defined in `ftoption.h`. */ FT_EXPORT( FT_Error ) FT_Get_Glyph_Name( FT_Face face, @@ -3716,22 +3568,20 @@ FT_BEGIN_HEADER * A pointer to the face's PostScript name. NULL if unavailable. * * @note: - * The returned pointer is owned by the face and is destroyed with - * it. + * The returned pointer is owned by the face and is destroyed with it. * * For variation fonts, this string changes if you select a different - * instance, and you have to call `FT_Get_PostScript_Name' again to - * retrieve it. FreeType follows Adobe TechNote #5902, `Generating + * instance, and you have to call `FT_Get_PostScript_Name` again to + * retrieve it. FreeType follows Adobe TechNote #5902, 'Generating * PostScript Names for Fonts Using OpenType Font Variations'. * * https://download.macromedia.com/pub/developer/opentype/tech-notes/5902.AdobePSNameGeneration.html * * [Since 2.9] Special PostScript names for named instances are only - * returned if the named instance is set with @FT_Set_Named_Instance - * (and the font has corresponding entries in its `fvar' table). If - * @FT_IS_VARIATION returns true, the algorithmically derived - * PostScript name is provided, not looking up special entries for - * named instances. + * returned if the named instance is set with @FT_Set_Named_Instance (and + * the font has corresponding entries in its 'fvar' table). If + * @FT_IS_VARIATION returns true, the algorithmically derived PostScript + * name is provided, not looking up special entries for named instances. */ FT_EXPORT( const char* ) FT_Get_Postscript_Name( FT_Face face ); @@ -3744,7 +3594,7 @@ FT_BEGIN_HEADER * * @description: * Select a given charmap by its encoding tag (as listed in - * `freetype.h'). + * `freetype.h`). * * @inout: * face :: @@ -3758,14 +3608,14 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * This function returns an error if no charmap in the face - * corresponds to the encoding queried here. + * This function returns an error if no charmap in the face corresponds + * to the encoding queried here. * * Because many fonts contain more than a single cmap for Unicode - * encoding, this function has some special code to select the one - * that covers Unicode best (`best' in the sense that a UCS-4 cmap is - * preferred to a UCS-2 cmap). It is thus preferable to - * @FT_Set_Charmap in this case. + * encoding, this function has some special code to select the one that + * covers Unicode best ('best' in the sense that a UCS-4 cmap is + * preferred to a UCS-2 cmap). It is thus preferable to @FT_Set_Charmap + * in this case. */ FT_EXPORT( FT_Error ) FT_Select_Charmap( FT_Face face, @@ -3792,9 +3642,8 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * This function returns an error if the charmap is not part of - * the face (i.e., if it is not listed in the `face->charmaps' - * table). + * This function returns an error if the charmap is not part of the face + * (i.e., if it is not listed in the `face->charmaps` table). * * It also fails if an OpenType type~14 charmap is selected (which * doesn't map character codes to glyph indices at all). @@ -3818,7 +3667,7 @@ FT_BEGIN_HEADER * * @return: * The index into the array of character maps within the face to which - * `charmap' belongs. If an error occurs, -1 is returned. + * 'charmap' belongs. If an error occurs, -1 is returned. * */ FT_EXPORT( FT_Int ) @@ -3831,8 +3680,8 @@ FT_BEGIN_HEADER * FT_Get_Char_Index * * @description: - * Return the glyph index of a given character code. This function - * uses the currently selected charmap to do the mapping. + * Return the glyph index of a given character code. This function uses + * the currently selected charmap to do the mapping. * * @input: * face :: @@ -3842,20 +3691,19 @@ FT_BEGIN_HEADER * The character code. * * @return: - * The glyph index. 0~means `undefined character code'. + * The glyph index. 0~means 'undefined character code'. * * @note: - * If you use FreeType to manipulate the contents of font files - * directly, be aware that the glyph index returned by this function - * doesn't always correspond to the internal indices used within the - * file. This is done to ensure that value~0 always corresponds to - * the `missing glyph'. If the first glyph is not named `.notdef', - * then for Type~1 and Type~42 fonts, `.notdef' will be moved into - * the glyph ID~0 position, and whatever was there will be moved to - * the position `.notdef' had. For Type~1 fonts, if there is no - * `.notdef' glyph at all, then one will be created at index~0 and - * whatever was there will be moved to the last index -- Type~42 - * fonts are considered invalid under this condition. + * If you use FreeType to manipulate the contents of font files directly, + * be aware that the glyph index returned by this function doesn't always + * correspond to the internal indices used within the file. This is done + * to ensure that value~0 always corresponds to the 'missing glyph'. If + * the first glyph is not named '.notdef', then for Type~1 and Type~42 + * fonts, '.notdef' will be moved into the glyph ID~0 position, and + * whatever was there will be moved to the position '.notdef' had. For + * Type~1 fonts, if there is no '.notdef' glyph at all, then one will be + * created at index~0 and whatever was there will be moved to the last + * index -- Type~42 fonts are considered invalid under this condition. */ FT_EXPORT( FT_UInt ) FT_Get_Char_Index( FT_Face face, @@ -3877,18 +3725,17 @@ FT_BEGIN_HEADER * * @output: * agindex :: - * Glyph index of first character code. 0~if charmap is - * empty. + * Glyph index of first character code. 0~if charmap is empty. * * @return: * The charmap's first character code. * * @note: - * You should use this function together with @FT_Get_Next_Char to - * parse all character codes available in a given charmap. The code - * should look like this: + * You should use this function together with @FT_Get_Next_Char to parse + * all character codes available in a given charmap. The code should + * look like this: * - * { + * ``` * FT_ULong charcode; * FT_UInt gindex; * @@ -3900,18 +3747,18 @@ FT_BEGIN_HEADER * * charcode = FT_Get_Next_Char( face, charcode, &gindex ); * } - * } - * - * Be aware that character codes can have values up to 0xFFFFFFFF; - * this might happen for non-Unicode or malformed cmaps. However, - * even with regular Unicode encoding, so-called `last resort fonts' - * (using SFNT cmap format 13, see function @FT_Get_CMap_Format) - * normally have entries for all Unicode characters up to 0x1FFFFF, - * which can cause *a lot* of iterations. - * - * Note that `*agindex' is set to~0 if the charmap is empty. The - * result itself can be~0 in two cases: if the charmap is empty or - * if the value~0 is the first valid character code. + * ``` + * + * Be aware that character codes can have values up to 0xFFFFFFFF; this + * might happen for non-Unicode or malformed cmaps. However, even with + * regular Unicode encoding, so-called 'last resort fonts' (using SFNT + * cmap format 13, see function @FT_Get_CMap_Format) normally have + * entries for all Unicode characters up to 0x1FFFFF, which can cause *a + * lot* of iterations. + * + * Note that '*agindex' is set to~0 if the charmap is empty. The result + * itself can be~0 in two cases: if the charmap is empty or if the + * value~0 is the first valid character code. */ FT_EXPORT( FT_ULong ) FT_Get_First_Char( FT_Face face, @@ -3924,9 +3771,9 @@ FT_BEGIN_HEADER * FT_Get_Next_Char * * @description: - * Return the next character code in the current charmap of a given - * face following the value `char_code', as well as the corresponding - * glyph index. + * Return the next character code in the current charmap of a given face + * following the value `char_code`, as well as the corresponding glyph + * index. * * @input: * face :: @@ -3937,19 +3784,18 @@ FT_BEGIN_HEADER * * @output: * agindex :: - * Glyph index of next character code. 0~if charmap - * is empty. + * Glyph index of next character code. 0~if charmap is empty. * * @return: * The charmap's next character code. * * @note: - * You should use this function with @FT_Get_First_Char to walk - * over all character codes available in a given charmap. See the - * note for that function for a simple code example. + * You should use this function with @FT_Get_First_Char to walk over all + * character codes available in a given charmap. See the note for that + * function for a simple code example. * - * Note that `*agindex' is set to~0 when there are no more codes in - * the charmap. + * Note that '*agindex' is set to~0 when there are no more codes in the + * charmap. */ FT_EXPORT( FT_ULong ) FT_Get_Next_Char( FT_Face face, @@ -3965,27 +3811,26 @@ FT_BEGIN_HEADER * @description: * Set or override certain (library or module-wide) properties on a * face-by-face basis. Useful for finer-grained control and avoiding - * locks on shared structures (threads can modify their own faces as - * they see fit). + * locks on shared structures (threads can modify their own faces as they + * see fit). * - * Contrary to @FT_Property_Set, this function uses @FT_Parameter so - * that you can pass multiple properties to the target face in one call. - * Note that only a subset of the available properties can be - * controlled. + * Contrary to @FT_Property_Set, this function uses @FT_Parameter so that + * you can pass multiple properties to the target face in one call. Note + * that only a subset of the available properties can be controlled. * * * @FT_PARAM_TAG_STEM_DARKENING (stem darkening, corresponding to the - * property `no-stem-darkening' provided by the `autofit', `cff', - * `type1', and `t1cid' modules; see @no-stem-darkening). + * property 'no-stem-darkening' provided by the 'autofit', 'cff', + * 'type1', and 't1cid' modules; see @no-stem-darkening). * * * @FT_PARAM_TAG_LCD_FILTER_WEIGHTS (LCD filter weights, corresponding * to function @FT_Library_SetLcdFilterWeights). * * * @FT_PARAM_TAG_RANDOM_SEED (seed value for the CFF, Type~1, and CID - * `random' operator, corresponding to the `random-seed' property - * provided by the `cff', `type1', and `t1cid' modules; see + * 'random' operator, corresponding to the 'random-seed' property + * provided by the 'cff', 'type1', and 't1cid' modules; see * @random-seed). * - * Pass NULL as `data' in @FT_Parameter for a given tag to reset the + * Pass NULL as 'data' in @FT_Parameter for a given tag to reset the * option and use the library or module default again. * * @input: @@ -3996,7 +3841,7 @@ FT_BEGIN_HEADER * The number of properties that follow. * * properties :: - * A handle to an @FT_Parameter array with `num_properties' elements. + * A handle to an @FT_Parameter array with `num_properties` elements. * * @return: * FreeType error code. 0~means success. @@ -4006,7 +3851,7 @@ FT_BEGIN_HEADER * FT_CONFIG_OPTION_SUBPIXEL_RENDERING to make the LCD filter examples * work. * - * { + * ``` * FT_Parameter property1; * FT_Bool darken_stems = 1; * @@ -4032,11 +3877,11 @@ FT_BEGIN_HEADER * property3.data = &random_seed; * * FT_Face_Properties( face, 3, properties ); - * } + * ``` * * The next example resets a single property to its default value. * - * { + * ``` * FT_Parameter property; * * @@ -4044,7 +3889,7 @@ FT_BEGIN_HEADER * property.data = NULL; * * FT_Face_Properties( face, 1, &property ); - * } + * ``` * * @since: * 2.8 @@ -4072,7 +3917,7 @@ FT_BEGIN_HEADER * The glyph name. * * @return: - * The glyph index. 0~means `undefined character code'. + * The glyph index. 0~means 'undefined character code'. */ FT_EXPORT( FT_UInt ) FT_Get_Name_Index( FT_Face face, @@ -4085,10 +3930,9 @@ FT_BEGIN_HEADER * FT_SUBGLYPH_FLAG_XXX * * @description: - * A list of constants describing subglyphs. Please refer to the - * `glyf' table description in the OpenType specification for the - * meaning of the various flags (which get synthesized for - * non-OpenType subglyphs). + * A list of constants describing subglyphs. Please refer to the 'glyf' + * table description in the OpenType specification for the meaning of the + * various flags (which get synthesized for non-OpenType subglyphs). * * https://docs.microsoft.com/en-us/typography/opentype/spec/glyf#composite-glyph-description * @@ -4118,8 +3962,8 @@ FT_BEGIN_HEADER * * @description: * Retrieve a description of a given subglyph. Only use it if - * `glyph->format' is @FT_GLYPH_FORMAT_COMPOSITE; an error is - * returned otherwise. + * `glyph->format` is @FT_GLYPH_FORMAT_COMPOSITE; an error is returned + * otherwise. * * @input: * glyph :: @@ -4127,7 +3971,7 @@ FT_BEGIN_HEADER * * sub_index :: * The index of the subglyph. Must be less than - * `glyph->num_subglyphs'. + * `glyph->num_subglyphs`. * * @output: * p_index :: @@ -4149,8 +3993,8 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * The values of `*p_arg1', `*p_arg2', and `*p_transform' must be - * interpreted depending on the flags returned in `*p_flags'. See the + * The values of `*p_arg1`, `*p_arg2`, and `*p_transform` must be + * interpreted depending on the flags returned in `*p_flags`. See the * OpenType specification for details. * */ @@ -4173,11 +4017,11 @@ FT_BEGIN_HEADER * Glyph Layer Management * * @abstract: - * Retrieving and manipulating OpenType's `COLR' table data. + * Retrieving and manipulating OpenType's 'COLR' table data. * * @description: * The functions described here allow access of colored glyph layer data - * in OpenType's `COLR' tables. + * in OpenType's 'COLR' tables. */ @@ -4198,7 +4042,7 @@ FT_BEGIN_HEADER * The current layer. Will be set by @FT_Get_Color_Glyph_Layer. * * p :: - * An opaque pointer into `COLR' table data. The caller must set this + * An opaque pointer into 'COLR' table data. The caller must set this * to NULL before the first call of @FT_Get_Color_Glyph_Layer. */ typedef struct FT_LayerIterator_ @@ -4216,7 +4060,7 @@ FT_BEGIN_HEADER * FT_Get_Color_Glyph_Layer * * @description: - * This is an interface to the `COLR' table in OpenType fonts to + * This is an interface to the 'COLR' table in OpenType fonts to * iteratively retrieve the colored glyph layers associated with the * current glyph slot. * @@ -4229,7 +4073,7 @@ FT_BEGIN_HEADER * layer. * * The returned elements are ordered in the z~direction from bottom to - * top; the `n'th element should be rendered with the associated palette + * top; the 'n'th element should be rendered with the associated palette * color and blended on top of the already rendered layers (elements 0, * 1, ..., n-1). * @@ -4243,8 +4087,8 @@ FT_BEGIN_HEADER * @inout: * iterator :: * An @FT_LayerIterator object. For the first call you should set - * `iterator->p' to NULL. For all following calls, simply use the - * same object again. + * `iterator->p` to NULL. For all following calls, simply use the same + * object again. * * @output: * aglyph_index :: @@ -4259,9 +4103,9 @@ FT_BEGIN_HEADER * The color palette can be retrieved with @FT_Palette_Select. * * @return: - * Value~1 if everything is OK. If there are no more layers (or if - * there are no layers at all), value~0 gets returned. In case of an - * error, value~0 is returned also. + * Value~1 if everything is OK. If there are no more layers (or if there + * are no layers at all), value~0 gets returned. In case of an error, + * value~0 is returned also. * * @note: * This function is necessary if you want to handle glyph layers by @@ -4269,11 +4113,11 @@ FT_BEGIN_HEADER * objects (like @FT_Get_Glyph or @FT_Glyph_To_Bitmap) don't have access * to this information. * - * @FT_Render_Glyph, however, handles colored glyph layers - * automatically if the @FT_LOAD_COLOR flag is passed to it. + * @FT_Render_Glyph, however, handles colored glyph layers automatically + * if the @FT_LOAD_COLOR flag is passed to it. * * @example: - * { + * ``` * FT_Color* palette; * FT_LayerIterator iterator; * @@ -4315,7 +4159,7 @@ FT_BEGIN_HEADER * &layer_color_index, * &iterator ) ); * } - * } + * ``` */ FT_EXPORT( FT_Bool ) FT_Get_Color_Glyph_Layer( FT_Face face, @@ -4338,11 +4182,11 @@ FT_BEGIN_HEADER * FT_FSTYPE_XXX * * @description: - * A list of bit flags used in the `fsType' field of the OS/2 table - * in a TrueType or OpenType font and the `FSType' entry in a - * PostScript font. These bit flags are returned by - * @FT_Get_FSType_Flags; they inform client applications of embedding - * and subsetting restrictions associated with a font. + * A list of bit flags used in the `fsType` field of the OS/2 table in a + * TrueType or OpenType font and the 'FSType' entry in a PostScript font. + * These bit flags are returned by @FT_Get_FSType_Flags; they inform + * client applications of embedding and subsetting restrictions + * associated with a font. * * See * https://www.adobe.com/content/dam/Adobe/en/devnet/acrobat/pdfs/FontPolicies.pdf @@ -4354,36 +4198,36 @@ FT_BEGIN_HEADER * installed on the remote system by an application. * * FT_FSTYPE_RESTRICTED_LICENSE_EMBEDDING :: - * Fonts that have only this bit set must not be modified, embedded - * or exchanged in any manner without first obtaining permission of - * the font software copyright owner. + * Fonts that have only this bit set must not be modified, embedded or + * exchanged in any manner without first obtaining permission of the + * font software copyright owner. * * FT_FSTYPE_PREVIEW_AND_PRINT_EMBEDDING :: * The font may be embedded and temporarily loaded on the remote - * system. Documents containing Preview & Print fonts must be - * opened `read-only'; no edits can be applied to the document. + * system. Documents containing Preview & Print fonts must be opened + * 'read-only'; no edits can be applied to the document. * * FT_FSTYPE_EDITABLE_EMBEDDING :: - * The font may be embedded but must only be installed temporarily - * on other systems. In contrast to Preview & Print fonts, - * documents containing editable fonts may be opened for reading, - * editing is permitted, and changes may be saved. + * The font may be embedded but must only be installed temporarily on + * other systems. In contrast to Preview & Print fonts, documents + * containing editable fonts may be opened for reading, editing is + * permitted, and changes may be saved. * * FT_FSTYPE_NO_SUBSETTING :: * The font may not be subsetted prior to embedding. * * FT_FSTYPE_BITMAP_EMBEDDING_ONLY :: - * Only bitmaps contained in the font may be embedded; no outline - * data may be embedded. If there are no bitmaps available in the - * font, then the font is unembeddable. + * Only bitmaps contained in the font may be embedded; no outline data + * may be embedded. If there are no bitmaps available in the font, + * then the font is unembeddable. * * @note: * The flags are ORed together, thus more than a single value can be * returned. * - * While the `fsType' flags can indicate that a font may be embedded, - * a license with the font vendor may be separately required to use - * the font in this way. + * While the `fsType` flags can indicate that a font may be embedded, a + * license with the font vendor may be separately required to use the + * font in this way. */ #define FT_FSTYPE_INSTALLABLE_EMBEDDING 0x0000 #define FT_FSTYPE_RESTRICTED_LICENSE_EMBEDDING 0x0002 @@ -4399,19 +4243,19 @@ FT_BEGIN_HEADER * FT_Get_FSType_Flags * * @description: - * Return the `fsType' flags for a font. + * Return the `fsType` flags for a font. * * @input: * face :: * A handle to the source face object. * * @return: - * The `fsType' flags, see @FT_FSTYPE_XXX. + * The `fsType` flags, see @FT_FSTYPE_XXX. * * @note: - * Use this function rather than directly reading the `fs_type' field - * in the @PS_FontInfoRec structure, which is only guaranteed to - * return the correct results for Type~1 fonts. + * Use this function rather than directly reading the `fs_type` field in + * the @PS_FontInfoRec structure, which is only guaranteed to return the + * correct results for Type~1 fonts. * * @since: * 2.3.8 @@ -4429,48 +4273,45 @@ FT_BEGIN_HEADER * Unicode Variation Sequences * * @abstract: - * The FreeType~2 interface to Unicode Variation Sequences (UVS), - * using the SFNT cmap format~14. + * The FreeType~2 interface to Unicode Variation Sequences (UVS), using + * the SFNT cmap format~14. * * @description: - * Many characters, especially for CJK scripts, have variant forms. - * They are a sort of grey area somewhere between being totally - * irrelevant and semantically distinct; for this reason, the Unicode - * consortium decided to introduce Variation Sequences (VS), - * consisting of a Unicode base character and a variation selector - * instead of further extending the already huge number of - * characters. - * - * Unicode maintains two different sets, namely `Standardized - * Variation Sequences' and registered `Ideographic Variation - * Sequences' (IVS), collected in the `Ideographic Variation - * Database' (IVD). + * Many characters, especially for CJK scripts, have variant forms. They + * are a sort of grey area somewhere between being totally irrelevant and + * semantically distinct; for this reason, the Unicode consortium decided + * to introduce Variation Sequences (VS), consisting of a Unicode base + * character and a variation selector instead of further extending the + * already huge number of characters. + * + * Unicode maintains two different sets, namely 'Standardized Variation + * Sequences' and registered 'Ideographic Variation Sequences' (IVS), + * collected in the 'Ideographic Variation Database' (IVD). * * https://unicode.org/Public/UCD/latest/ucd/StandardizedVariants.txt - * https://unicode.org/reports/tr37/ - * https://unicode.org/ivd/ + * https://unicode.org/reports/tr37/ https://unicode.org/ivd/ * * To date (January 2017), the character with the most ideographic * variations is U+9089, having 32 such IVS. * - * Three Mongolian Variation Selectors have the values U+180B-U+180D; - * 256 generic Variation Selectors are encoded in the ranges - * U+FE00-U+FE0F and U+E0100-U+E01EF. IVS currently use Variation - * Selectors from the range U+E0100-U+E01EF only. + * Three Mongolian Variation Selectors have the values U+180B-U+180D; 256 + * generic Variation Selectors are encoded in the ranges U+FE00-U+FE0F + * and U+E0100-U+E01EF. IVS currently use Variation Selectors from the + * range U+E0100-U+E01EF only. * * A VS consists of the base character value followed by a single * Variation Selector. For example, to get the first variation of - * U+9089, you have to write the character sequence `U+9089 U+E0100'. + * U+9089, you have to write the character sequence `U+9089 U+E0100`. * - * Adobe and MS decided to support both standardized and ideographic - * VS with a new cmap subtable (format~14). It is an odd subtable - * because it is not a mapping of input code points to glyphs, but - * contains lists of all variations supported by the font. + * Adobe and MS decided to support both standardized and ideographic VS + * with a new cmap subtable (format~14). It is an odd subtable because + * it is not a mapping of input code points to glyphs, but contains lists + * of all variations supported by the font. * - * A variation may be either `default' or `non-default' for a given - * font. A default variation is the one you will get for that code - * point if you look it up in the standard Unicode cmap. A - * non-default variation is a different glyph. + * A variation may be either 'default' or 'non-default' for a given font. + * A default variation is the one you will get for that code point if you + * look it up in the standard Unicode cmap. A non-default variation is a + * different glyph. * */ @@ -4481,8 +4322,8 @@ FT_BEGIN_HEADER * FT_Face_GetCharVariantIndex * * @description: - * Return the glyph index of a given character code as modified by - * the variation selector. + * Return the glyph index of a given character code as modified by the + * variation selector. * * @input: * face :: @@ -4495,20 +4336,18 @@ FT_BEGIN_HEADER * The Unicode code point of the variation selector. * * @return: - * The glyph index. 0~means either `undefined character code', or - * `undefined selector code', or `no variation selector cmap - * subtable', or `current CharMap is not Unicode'. + * The glyph index. 0~means either 'undefined character code', or + * 'undefined selector code', or 'no variation selector cmap subtable', + * or 'current CharMap is not Unicode'. * * @note: - * If you use FreeType to manipulate the contents of font files - * directly, be aware that the glyph index returned by this function - * doesn't always correspond to the internal indices used within - * the file. This is done to ensure that value~0 always corresponds - * to the `missing glyph'. + * If you use FreeType to manipulate the contents of font files directly, + * be aware that the glyph index returned by this function doesn't always + * correspond to the internal indices used within the file. This is done + * to ensure that value~0 always corresponds to the 'missing glyph'. * * This function is only meaningful if - * a) the font has a variation selector cmap sub table, - * and + * a) the font has a variation selector cmap sub table, and * b) the current charmap has a Unicode encoding. * * @since: @@ -4526,8 +4365,8 @@ FT_BEGIN_HEADER * FT_Face_GetCharVariantIsDefault * * @description: - * Check whether this variation of this Unicode character is the one - * to be found in the `cmap'. + * Check whether this variation of this Unicode character is the one to + * be found in the 'cmap'. * * @input: * face :: @@ -4540,12 +4379,12 @@ FT_BEGIN_HEADER * The Unicode codepoint of the variation selector. * * @return: - * 1~if found in the standard (Unicode) cmap, 0~if found in the - * variation selector cmap, or -1 if it is not a variation. + * 1~if found in the standard (Unicode) cmap, 0~if found in the variation + * selector cmap, or -1 if it is not a variation. * * @note: - * This function is only meaningful if the font has a variation - * selector cmap subtable. + * This function is only meaningful if the font has a variation selector + * cmap subtable. * * @since: * 2.3.6 @@ -4562,21 +4401,21 @@ FT_BEGIN_HEADER * FT_Face_GetVariantSelectors * * @description: - * Return a zero-terminated list of Unicode variation selectors found - * in the font. + * Return a zero-terminated list of Unicode variation selectors found in + * the font. * * @input: * face :: * A handle to the source face object. * * @return: - * A pointer to an array of selector code points, or NULL if there is - * no valid variation selector cmap subtable. + * A pointer to an array of selector code points, or NULL if there is no + * valid variation selector cmap subtable. * * @note: - * The last item in the array is~0; the array is owned by the - * @FT_Face object but can be overwritten or released on the next - * call to a FreeType function. + * The last item in the array is~0; the array is owned by the @FT_Face + * object but can be overwritten or released on the next call to a + * FreeType function. * * @since: * 2.3.6 @@ -4591,8 +4430,8 @@ FT_BEGIN_HEADER * FT_Face_GetVariantsOfChar * * @description: - * Return a zero-terminated list of Unicode variation selectors found - * for the specified character code. + * Return a zero-terminated list of Unicode variation selectors found for + * the specified character code. * * @input: * face :: @@ -4603,13 +4442,13 @@ FT_BEGIN_HEADER * * @return: * A pointer to an array of variation selector code points that are - * active for the given character, or NULL if the corresponding list - * is empty. + * active for the given character, or NULL if the corresponding list is + * empty. * * @note: - * The last item in the array is~0; the array is owned by the - * @FT_Face object but can be overwritten or released on the next - * call to a FreeType function. + * The last item in the array is~0; the array is owned by the @FT_Face + * object but can be overwritten or released on the next call to a + * FreeType function. * * @since: * 2.3.6 @@ -4625,8 +4464,8 @@ FT_BEGIN_HEADER * FT_Face_GetCharsOfVariant * * @description: - * Return a zero-terminated list of Unicode character codes found for - * the specified variation selector. + * Return a zero-terminated list of Unicode character codes found for the + * specified variation selector. * * @input: * face :: @@ -4637,13 +4476,13 @@ FT_BEGIN_HEADER * * @return: * A list of all the code points that are specified by this selector - * (both default and non-default codes are returned) or NULL if there - * is no valid cmap or the variation selector is invalid. + * (both default and non-default codes are returned) or NULL if there is + * no valid cmap or the variation selector is invalid. * * @note: - * The last item in the array is~0; the array is owned by the - * @FT_Face object but can be overwritten or released on the next - * call to a FreeType function. + * The last item in the array is~0; the array is owned by the @FT_Face + * object but can be overwritten or released on the next call to a + * FreeType function. * * @since: * 2.3.6 @@ -4665,13 +4504,13 @@ FT_BEGIN_HEADER * Crunching fixed numbers and vectors. * * @description: - * This section contains various functions used to perform - * computations on 16.16 fixed-float numbers or 2d vectors. + * This section contains various functions used to perform computations + * on 16.16 fixed-float numbers or 2d vectors. * - * *Attention*: Most arithmetic functions take `FT_Long' as arguments. + * **Attention**: Most arithmetic functions take `FT_Long` as arguments. * For historical reasons, FreeType was designed under the assumption - * that `FT_Long' is a 32-bit integer; results can thus be undefined - * if the arguments don't fit into 32 bits. + * that `FT_Long` is a 32-bit integer; results can thus be undefined if + * the arguments don't fit into 32 bits. * * @order: * FT_MulDiv @@ -4693,8 +4532,8 @@ FT_BEGIN_HEADER * FT_MulDiv * * @description: - * Compute `(a*b)/c' with maximum accuracy, using a 64-bit - * intermediate integer whenever necessary. + * Compute '(a*b)/c' with maximum accuracy, using a 64-bit intermediate + * integer whenever necessary. * * This function isn't necessarily as fast as some processor-specific * operations, but is at least completely portable. @@ -4710,9 +4549,9 @@ FT_BEGIN_HEADER * The divisor. * * @return: - * The result of `(a*b)/c'. This function never traps when trying to - * divide by zero; it simply returns `MaxInt' or `MinInt' depending - * on the signs of `a' and `b'. + * The result of '(a*b)/c'. This function never traps when trying to + * divide by zero; it simply returns 'MaxInt' or 'MinInt' depending on + * the signs of 'a' and 'b'. */ FT_EXPORT( FT_Long ) FT_MulDiv( FT_Long a, @@ -4726,7 +4565,7 @@ FT_BEGIN_HEADER * FT_MulFix * * @description: - * Compute `(a*b)/0x10000' with maximum accuracy. Its main use is to + * Compute '(a*b)/0x10000' with maximum accuracy. Its main use is to * multiply a given value by a 16.16 fixed-point factor. * * @input: @@ -4734,22 +4573,21 @@ FT_BEGIN_HEADER * The first multiplier. * * b :: - * The second multiplier. Use a 16.16 factor here whenever - * possible (see note below). + * The second multiplier. Use a 16.16 factor here whenever possible + * (see note below). * * @return: - * The result of `(a*b)/0x10000'. + * The result of '(a*b)/0x10000'. * * @note: - * This function has been optimized for the case where the absolute - * value of `a' is less than 2048, and `b' is a 16.16 scaling factor. - * As this happens mainly when scaling from notional units to - * fractional pixels in FreeType, it resulted in noticeable speed - * improvements between versions 2.x and 1.x. - * - * As a conclusion, always try to place a 16.16 factor as the - * _second_ argument of this function; this can make a great - * difference. + * This function has been optimized for the case where the absolute value + * of 'a' is less than 2048, and 'b' is a 16.16 scaling factor. As this + * happens mainly when scaling from notional units to fractional pixels + * in FreeType, it resulted in noticeable speed improvements between + * versions 2.x and 1.x. + * + * As a conclusion, always try to place a 16.16 factor as the _second_ + * argument of this function; this can make a great difference. */ FT_EXPORT( FT_Long ) FT_MulFix( FT_Long a, @@ -4762,7 +4600,7 @@ FT_BEGIN_HEADER * FT_DivFix * * @description: - * Compute `(a*0x10000)/b' with maximum accuracy. Its main use is to + * Compute '(a*0x10000)/b' with maximum accuracy. Its main use is to * divide a given value by a 16.16 fixed-point factor. * * @input: @@ -4773,7 +4611,7 @@ FT_BEGIN_HEADER * The denominator. Use a 16.16 factor here. * * @return: - * The result of `(a*0x10000)/b'. + * The result of '(a*0x10000)/b'. */ FT_EXPORT( FT_Long ) FT_DivFix( FT_Long a, @@ -4793,7 +4631,7 @@ FT_BEGIN_HEADER * The number to be rounded. * * @return: - * `a' rounded to the nearest 16.16 fixed integer, halfway cases away + * 'a' rounded to the nearest 16.16 fixed integer, halfway cases away * from zero. * * @note: @@ -4816,7 +4654,7 @@ FT_BEGIN_HEADER * The number for which the ceiling function is to be computed. * * @return: - * `a' rounded towards plus infinity. + * 'a' rounded towards plus infinity. * * @note: * The function uses wrap-around arithmetic. @@ -4838,7 +4676,7 @@ FT_BEGIN_HEADER * The number for which the floor function is to be computed. * * @return: - * `a' rounded towards minus infinity. + * 'a' rounded towards minus infinity. */ FT_EXPORT( FT_Fixed ) FT_FloorFix( FT_Fixed a ); @@ -4861,7 +4699,7 @@ FT_BEGIN_HEADER * A pointer to the source 2x2 matrix. * * @note: - * The result is undefined if either `vector' or `matrix' is invalid. + * The result is undefined if either 'vector' or 'matrix' is invalid. */ FT_EXPORT( void ) FT_Vector_Transform( FT_Vector* vec, @@ -4880,9 +4718,9 @@ FT_BEGIN_HEADER * 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. + * 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. * * @order: * FT_Library_Version @@ -4903,8 +4741,8 @@ FT_BEGIN_HEADER * FREETYPE_XXX * * @description: - * These three macros identify the FreeType source code version. - * Use @FT_Library_Version to access them at runtime. + * These three macros identify the FreeType source code version. Use + * @FT_Library_Version to access them at runtime. * * @values: * FREETYPE_MAJOR :: @@ -4915,9 +4753,8 @@ FT_BEGIN_HEADER * 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. + * 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 @@ -4931,10 +4768,9 @@ FT_BEGIN_HEADER * 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. + * 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 :: @@ -4951,12 +4787,12 @@ FT_BEGIN_HEADER * 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. + * 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. + * 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, diff --git a/include/freetype/ftadvanc.h b/include/freetype/ftadvanc.h index 9c3f54596..13c53a9ec 100644 --- a/include/freetype/ftadvanc.h +++ b/include/freetype/ftadvanc.h @@ -62,20 +62,18 @@ FT_BEGIN_HEADER * FT_ADVANCE_FLAG_FAST_ONLY * * @description: - * A bit-flag to be OR-ed with the `flags' parameter of the + * A bit-flag to be OR-ed with the 'flags' parameter of the * @FT_Get_Advance and @FT_Get_Advances functions. * * If set, it indicates that you want these functions to fail if the - * corresponding hinting mode or font driver doesn't allow for very - * quick advance computation. + * corresponding hinting mode or font driver doesn't allow for very quick + * advance computation. * - * Typically, glyphs that are either unscaled, unhinted, bitmapped, - * or light-hinted can have their advance width computed very - * quickly. + * Typically, glyphs that are either unscaled, unhinted, bitmapped, or + * light-hinted can have their advance width computed very quickly. * - * Normal and bytecode hinted modes that require loading, scaling, - * and hinting of the glyph outline, are extremely slow by - * comparison. + * Normal and bytecode hinted modes that require loading, scaling, and + * hinting of the glyph outline, are extremely slow by comparison. */ #define FT_ADVANCE_FLAG_FAST_ONLY 0x20000000L @@ -86,8 +84,7 @@ FT_BEGIN_HEADER * FT_Get_Advance * * @description: - * Retrieve the advance value of a given glyph outline in an - * @FT_Face. + * Retrieve the advance value of a given glyph outline in an @FT_Face. * * @input: * face :: @@ -97,30 +94,28 @@ FT_BEGIN_HEADER * The glyph index. * * load_flags :: - * A set of bit flags similar to those used when - * calling @FT_Load_Glyph, used to determine what kind - * of advances you need. + * A set of bit flags similar to those used when calling + * @FT_Load_Glyph, used to determine what kind of advances you need. * @output: * padvance :: - * The advance value. If scaling is performed (based on - * the value of `load_flags'), the advance value is in - * 16.16 format. Otherwise, it is in font units. + * The advance value. If scaling is performed (based on the value of + * `load_flags`), the advance value is in 16.16 format. Otherwise, it + * is in font units. * - * If @FT_LOAD_VERTICAL_LAYOUT is set, this is the - * vertical advance corresponding to a vertical layout. - * Otherwise, it is the horizontal advance in a - * horizontal layout. + * If @FT_LOAD_VERTICAL_LAYOUT is set, this is the vertical advance + * corresponding to a vertical layout. Otherwise, it is the horizontal + * advance in a horizontal layout. * * @return: * FreeType error code. 0 means success. * * @note: - * This function may fail if you use @FT_ADVANCE_FLAG_FAST_ONLY and - * if the corresponding font backend doesn't have a quick way to - * retrieve the advances. + * This function may fail if you use @FT_ADVANCE_FLAG_FAST_ONLY and if + * the corresponding font backend doesn't have a quick way to retrieve + * the advances. * - * A scaled advance is returned in 16.16 format but isn't transformed - * by the affine transformation specified by @FT_Set_Transform. + * A scaled advance is returned in 16.16 format but isn't transformed by + * the affine transformation specified by @FT_Set_Transform. */ FT_EXPORT( FT_Error ) FT_Get_Advance( FT_Face face, @@ -135,8 +130,7 @@ FT_BEGIN_HEADER * FT_Get_Advances * * @description: - * Retrieve the advance values of several glyph outlines in an - * @FT_Face. + * Retrieve the advance values of several glyph outlines in an @FT_Face. * * @input: * face :: @@ -149,34 +143,32 @@ FT_BEGIN_HEADER * The number of advance values you want to retrieve. * * load_flags :: - * A set of bit flags similar to those used when - * calling @FT_Load_Glyph. + * A set of bit flags similar to those used when calling + * @FT_Load_Glyph. * * @output: * padvance :: - * The advance values. This array, to be provided by the - * caller, must contain at least `count' elements. + * The advance values. This array, to be provided by the caller, must + * contain at least 'count' elements. * - * If scaling is performed (based on the value of - * `load_flags'), the advance values are in 16.16 format. - * Otherwise, they are in font units. + * If scaling is performed (based on the value of `load_flags`), the + * advance values are in 16.16 format. Otherwise, they are in font + * units. * - * If @FT_LOAD_VERTICAL_LAYOUT is set, these are the - * vertical advances corresponding to a vertical layout. - * Otherwise, they are the horizontal advances in a - * horizontal layout. + * If @FT_LOAD_VERTICAL_LAYOUT is set, these are the vertical advances + * corresponding to a vertical layout. Otherwise, they are the + * horizontal advances in a horizontal layout. * * @return: * FreeType error code. 0 means success. * * @note: - * This function may fail if you use @FT_ADVANCE_FLAG_FAST_ONLY and - * if the corresponding font backend doesn't have a quick way to - * retrieve the advances. + * This function may fail if you use @FT_ADVANCE_FLAG_FAST_ONLY and if + * the corresponding font backend doesn't have a quick way to retrieve + * the advances. * - * Scaled advances are returned in 16.16 format but aren't - * transformed by the affine transformation specified by - * @FT_Set_Transform. + * Scaled advances are returned in 16.16 format but aren't transformed by + * the affine transformation specified by @FT_Set_Transform. */ FT_EXPORT( FT_Error ) FT_Get_Advances( FT_Face face, diff --git a/include/freetype/ftbbox.h b/include/freetype/ftbbox.h index 9a0dcfc76..7f8d85af1 100644 --- a/include/freetype/ftbbox.h +++ b/include/freetype/ftbbox.h @@ -22,7 +22,7 @@ * boxes. * * It is separated from the rest of the engine for various technical - * reasons. It may well be integrated in `ftoutln' later. + * reasons. It may well be integrated in 'ftoutln' later. * */ @@ -58,11 +58,10 @@ FT_BEGIN_HEADER * FT_Outline_Get_BBox * * @description: - * Compute the exact bounding box of an outline. This is slower - * than computing the control box. However, it uses an advanced - * algorithm that returns _very_ quickly when the two boxes - * coincide. Otherwise, the outline Bezier arcs are traversed to - * extract their extrema. + * Compute the exact bounding box of an outline. This is slower than + * computing the control box. However, it uses an advanced algorithm + * that returns _very_ quickly when the two boxes coincide. Otherwise, + * the outline Bezier arcs are traversed to extract their extrema. * * @input: * outline :: @@ -78,10 +77,10 @@ FT_BEGIN_HEADER * @note: * If the font is tricky and the glyph has been loaded with * @FT_LOAD_NO_SCALE, the resulting BBox is meaningless. To get - * reasonable values for the BBox it is necessary to load the glyph - * at a large ppem value (so that the hinting instructions can - * properly shift and scale the subglyphs), then extracting the BBox, - * which can be eventually converted back to font units. + * reasonable values for the BBox it is necessary to load the glyph at a + * large ppem value (so that the hinting instructions can properly shift + * and scale the subglyphs), then extracting the BBox, which can be + * eventually converted back to font units. */ FT_EXPORT( FT_Error ) FT_Outline_Get_BBox( FT_Outline* outline, diff --git a/include/freetype/ftbdf.h b/include/freetype/ftbdf.h index 69dbb4dab..6df45d3a4 100644 --- a/include/freetype/ftbdf.h +++ b/include/freetype/ftbdf.h @@ -44,8 +44,8 @@ FT_BEGIN_HEADER * BDF and PCF specific API. * * @description: - * This section contains the declaration of functions specific to BDF - * and PCF fonts. + * This section contains the declaration of functions specific to BDF and + * PCF fonts. * */ @@ -87,8 +87,8 @@ FT_BEGIN_HEADER * BDF_Property * * @description: - * A handle to a @BDF_PropertyRec structure to model a given - * BDF/PCF property. + * A handle to a @BDF_PropertyRec structure to model a given BDF/PCF + * property. */ typedef struct BDF_PropertyRec_* BDF_Property; @@ -106,8 +106,8 @@ FT_BEGIN_HEADER * The property type. * * u.atom :: - * The atom string, if type is @BDF_PROPERTY_TYPE_ATOM. May be - * NULL, indicating an empty string. + * The atom string, if type is @BDF_PROPERTY_TYPE_ATOM. May be NULL, + * indicating an empty string. * * u.integer :: * A signed integer, if type is @BDF_PROPERTY_TYPE_INTEGER. @@ -134,8 +134,8 @@ FT_BEGIN_HEADER * FT_Get_BDF_Charset_ID * * @description: - * Retrieve a BDF font character set identity, according to - * the BDF specification. + * Retrieve a BDF font character set identity, according to the BDF + * specification. * * @input: * face :: @@ -187,15 +187,15 @@ FT_BEGIN_HEADER * otherwise. It also returns an error if the property is not in the * font. * - * A `property' is a either key-value pair within the STARTPROPERTIES + * A 'property' is a either key-value pair within the STARTPROPERTIES * ... ENDPROPERTIES block of a BDF font or a key-value pair from the - * `info->props' array within a `FontRec' structure of a PCF font. + * `info->props` array within a 'FontRec' structure of a PCF font. * - * Integer properties are always stored as `signed' within PCF fonts; + * Integer properties are always stored as 'signed' within PCF fonts; * consequently, @BDF_PROPERTY_TYPE_CARDINAL is a possible return value * for BDF fonts only. * - * In case of error, `aproperty->type' is always set to + * In case of error, `aproperty->type` is always set to * @BDF_PROPERTY_TYPE_NONE. */ FT_EXPORT( FT_Error ) diff --git a/include/freetype/ftbitmap.h b/include/freetype/ftbitmap.h index 3d195cd56..900c0ae52 100644 --- a/include/freetype/ftbitmap.h +++ b/include/freetype/ftbitmap.h @@ -49,11 +49,11 @@ FT_BEGIN_HEADER * This section contains functions for handling @FT_Bitmap objects, * automatically adjusting the target's bitmap buffer size as needed. * - * Note that none of the functions changes the bitmap's `flow' (as - * indicated by the sign of the `pitch' field in @FT_Bitmap). + * Note that none of the functions changes the bitmap's 'flow' (as + * indicated by the sign of the 'pitch' field in @FT_Bitmap). * * To set the flow, assign an appropriate positive or negative value to - * the `pitch' field of the target @FT_Bitmap object after calling + * the 'pitch' field of the target @FT_Bitmap object after calling * @FT_Bitmap_Init but before calling any of the other functions * described here. */ @@ -72,7 +72,7 @@ FT_BEGIN_HEADER * A pointer to the bitmap structure. * * @note: - * A deprecated name for the same function is `FT_Bitmap_New'. + * A deprecated name for the same function is `FT_Bitmap_New`. */ FT_EXPORT( void ) FT_Bitmap_Init( FT_Bitmap *abitmap ); @@ -106,7 +106,7 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * `source->buffer' and `target->buffer' must neither be equal nor + * `source->buffer` and `target->buffer` must neither be equal nor * overlap. */ FT_EXPORT( FT_Error ) @@ -121,21 +121,21 @@ FT_BEGIN_HEADER * FT_Bitmap_Embolden * * @description: - * Embolden a bitmap. The new bitmap will be about `xStrength' - * pixels wider and `yStrength' pixels higher. The left and bottom - * borders are kept unchanged. + * Embolden a bitmap. The new bitmap will be about `xStrength` pixels + * wider and `yStrength` pixels higher. The left and bottom borders are + * kept unchanged. * * @input: * library :: * A handle to a library object. * * xStrength :: - * How strong the glyph is emboldened horizontally. - * Expressed in 26.6 pixel format. + * How strong the glyph is emboldened horizontally. Expressed in 26.6 + * pixel format. * * yStrength :: - * How strong the glyph is emboldened vertically. - * Expressed in 26.6 pixel format. + * How strong the glyph is emboldened vertically. Expressed in 26.6 + * pixel format. * * @inout: * bitmap :: @@ -145,14 +145,14 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * The current implementation restricts `xStrength' to be less than - * or equal to~8 if bitmap is of pixel_mode @FT_PIXEL_MODE_MONO. + * The current implementation restricts `xStrength` to be less than or + * equal to~8 if bitmap is of pixel_mode @FT_PIXEL_MODE_MONO. * - * If you want to embolden the bitmap owned by a @FT_GlyphSlotRec, - * you should call @FT_GlyphSlot_Own_Bitmap on the slot first. + * If you want to embolden the bitmap owned by a @FT_GlyphSlotRec, you + * should call @FT_GlyphSlot_Own_Bitmap on the slot first. * - * Bitmaps in @FT_PIXEL_MODE_GRAY2 and @FT_PIXEL_MODE_GRAY@ format - * are converted to @FT_PIXEL_MODE_GRAY format (i.e., 8bpp). + * Bitmaps in @FT_PIXEL_MODE_GRAY2 and @FT_PIXEL_MODE_GRAY@ format are + * converted to @FT_PIXEL_MODE_GRAY format (i.e., 8bpp). */ FT_EXPORT( FT_Error ) FT_Bitmap_Embolden( FT_Library library, @@ -167,9 +167,9 @@ FT_BEGIN_HEADER * FT_Bitmap_Convert * * @description: - * Convert a bitmap object with depth 1bpp, 2bpp, 4bpp, 8bpp or 32bpp - * to a bitmap object with depth 8bpp, making the number of used - * bytes per line (a.k.a. the `pitch') a multiple of `alignment'. + * Convert a bitmap object with depth 1bpp, 2bpp, 4bpp, 8bpp or 32bpp to + * a bitmap object with depth 8bpp, making the number of used bytes per + * line (a.k.a. the 'pitch') a multiple of 'alignment'. * * @input: * library :: @@ -179,8 +179,8 @@ FT_BEGIN_HEADER * The source bitmap. * * alignment :: - * The pitch of the bitmap is a multiple of this - * argument. Common values are 1, 2, or 4. + * The pitch of the bitmap is a multiple of this argument. Common + * values are 1, 2, or 4. * * @output: * target :: @@ -195,10 +195,10 @@ FT_BEGIN_HEADER * * Use @FT_Bitmap_Done to finally remove the bitmap object. * - * The `library' argument is taken to have access to FreeType's - * memory handling functions. + * The 'library' argument is taken to have access to FreeType's memory + * handling functions. * - * `source->buffer' and `target->buffer' must neither be equal nor + * `source->buffer` and `target->buffer` must neither be equal nor * overlap. */ FT_EXPORT( FT_Error ) @@ -228,11 +228,11 @@ FT_BEGIN_HEADER * 26.6 pixel format. This can be a fractional pixel value. * * color :: - * The color used to draw `source' onto `target'. + * The color used to draw 'source' onto 'target'. * * @inout: * target :: - * A handle to an `FT_Bitmap' object. It should be either initialized + * A handle to an `FT_Bitmap` object. It should be either initialized * as empty with a call to @FT_Bitmap_Init, or it should be of type * @FT_PIXEL_MODE_BGRA. * @@ -247,14 +247,14 @@ FT_BEGIN_HEADER * @note: * This function doesn't perform clipping. * - * The bitmap in `target' gets allocated or reallocated as needed; the - * vector `atarget_offset' is updated accordingly. + * The bitmap in 'target' gets allocated or reallocated as needed; the + * vector `atarget_offset` is updated accordingly. * * In case of allocation or reallocation, the bitmap's pitch is set to - * `4~*~width'. Both `source' and `target' must have the same bitmap - * flow (as indicated by the sign of the `pitch' field). + * '4~*~width'. Both 'source' and 'target' must have the same bitmap + * flow (as indicated by the sign of the 'pitch' field). * - * `source->buffer' and `target->buffer' must neither be equal nor + * `source->buffer` and `target->buffer` must neither be equal nor * overlap. * * @since: @@ -275,7 +275,7 @@ FT_BEGIN_HEADER * FT_GlyphSlot_Own_Bitmap * * @description: - * Make sure that a glyph slot owns `slot->bitmap'. + * Make sure that a glyph slot owns `slot->bitmap`. * * @input: * slot :: @@ -285,8 +285,7 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * This function is to be used in combination with - * @FT_Bitmap_Embolden. + * This function is to be used in combination with @FT_Bitmap_Embolden. */ FT_EXPORT( FT_Error ) FT_GlyphSlot_Own_Bitmap( FT_GlyphSlot slot ); @@ -311,8 +310,8 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * The `library' argument is taken to have access to FreeType's - * memory handling functions. + * The 'library' argument is taken to have access to FreeType's memory + * handling functions. */ FT_EXPORT( FT_Error ) FT_Bitmap_Done( FT_Library library, diff --git a/include/freetype/ftbzip2.h b/include/freetype/ftbzip2.h index 07a73671d..039befb28 100644 --- a/include/freetype/ftbzip2.h +++ b/include/freetype/ftbzip2.h @@ -55,8 +55,8 @@ FT_BEGIN_HEADER * * @description: * Open a new stream to parse bzip2-compressed font files. This is - * mainly used to support the compressed `*.pcf.bz2' fonts that come - * with XFree86. + * mainly used to support the compressed `*.pcf.bz2` fonts that come with + * XFree86. * * @input: * stream :: @@ -71,9 +71,9 @@ 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 - * objects will be released to the heap. + * 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 * process each time seeking backwards is needed within the stream. @@ -81,10 +81,10 @@ FT_BEGIN_HEADER * In certain builds of the library, bzip2 compression recognition is * automatically handled when calling @FT_New_Face or @FT_Open_Face. * This means that if no font driver is capable of handling the raw - * compressed file, the library will try to open a bzip2 compressed stream - * from it and re-open the face with it. + * compressed file, the library will try to open a bzip2 compressed + * stream from it and re-open the face with it. * - * This function may return `FT_Err_Unimplemented_Feature' if your build + * This function may return `FT_Err_Unimplemented_Feature` if your build * of FreeType was not compiled with bzip2 support. */ FT_EXPORT( FT_Error ) diff --git a/include/freetype/ftcache.h b/include/freetype/ftcache.h index 5dedb52c0..e98c1dd0a 100644 --- a/include/freetype/ftcache.h +++ b/include/freetype/ftcache.h @@ -44,7 +44,7 @@ FT_BEGIN_HEADER * objects, as well as caching information like character maps and glyph * images while limiting their maximum memory usage. * - * Note that all types and functions begin with the `FTC_' prefix. + * 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 @@ -59,7 +59,7 @@ FT_BEGIN_HEADER * to convert an @FTC_FaceID into a new @FT_Face object. The latter is * then completely managed by the cache, including its termination * through @FT_Done_Face. To monitor termination of face objects, the - * finalizer callback in the `generic' field of the @FT_Face object can + * finalizer callback in the 'generic' field of the @FT_Face object can * be used, which might also be used to store the @FTC_FaceID of the * face. * @@ -69,14 +69,14 @@ FT_BEGIN_HEADER * possible. * * 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 + * **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), * 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 - * or even crashes. + * 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 or even + * crashes. * * 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 @@ -91,11 +91,11 @@ 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 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). + * 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. * @@ -151,8 +151,8 @@ FT_BEGIN_HEADER * 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. + * 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. @@ -166,8 +166,8 @@ FT_BEGIN_HEADER * 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. + * Failure to do so will result in incorrect behaviour or even memory + * leaks and crashes. */ typedef FT_Pointer FTC_FaceID; @@ -200,7 +200,7 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * The third parameter `req_data' is the same as the one passed by the + * 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 @@ -233,20 +233,20 @@ FT_BEGIN_HEADER * FTC_Manager * * @description: - * This object corresponds to one instance of the cache-subsystem. - * It is used to cache one or more @FT_Face objects, along with - * corresponding @FT_Size objects. + * This object corresponds to one instance of the cache-subsystem. 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 control 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 + * 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 - * for new ones. + * All limitations are enforced by keeping lists of managed objects in + * most-recently-used order, and flushing old nodes to make room for new + * ones. */ typedef struct FTC_ManagerRec_* FTC_Manager; @@ -258,13 +258,13 @@ FT_BEGIN_HEADER * * @description: * An opaque handle to a cache node object. Each cache node is - * reference-counted. A node with a count of~0 might be flushed - * out of a full cache whenever a lookup request is performed. + * reference-counted. A node with a count of~0 might be flushed out of a + * full cache whenever a lookup request is performed. * - * If you look up nodes, you have the ability to `acquire' them, - * i.e., to increment their reference count. This will prevent the - * node from being flushed out of the cache until you explicitly - * `release' it (see @FTC_Node_Unref). + * If you look up nodes, you have the ability to 'acquire' them, i.e., to + * increment their reference count. This will prevent the node from + * being flushed out of the cache until you explicitly 'release' it (see + * @FTC_Node_Unref). * * See also @FTC_SBitCache_Lookup and @FTC_ImageCache_Lookup. */ @@ -284,30 +284,29 @@ FT_BEGIN_HEADER * The parent FreeType library handle to use. * * max_faces :: - * Maximum number of opened @FT_Face objects managed by - * this cache instance. Use~0 for defaults. + * Maximum number of opened @FT_Face objects managed by this cache + * instance. Use~0 for defaults. * * max_sizes :: - * Maximum number of opened @FT_Size objects managed by - * this cache instance. Use~0 for defaults. + * Maximum number of opened @FT_Size objects managed by this cache + * instance. Use~0 for defaults. * * 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. + * 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. + * 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). + * A generic pointer that is passed to the requester each time it is + * called (see @FTC_Face_Requester). * * @output: * amanager :: - * A handle to a new manager object. 0~in case of - * failure. + * A handle to a new manager object. 0~in case of failure. * * @return: * FreeType error code. 0~means success. @@ -383,20 +382,20 @@ FT_BEGIN_HEADER * should never try to discard it yourself. * * The @FT_Face object doesn't necessarily have a current size object - * (i.e., face->size can be~0). If you need a specific `font size', - * use @FTC_Manager_LookupSize instead. + * (i.e., face->size can be~0). If you need a specific 'font size', use + * @FTC_Manager_LookupSize instead. * - * Never change the face's transformation matrix (i.e., never call - * the @FT_Set_Transform function) on a returned face! If you need - * to transform glyphs, do it yourself after glyph loading. + * Never change the face's transformation matrix (i.e., never call 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. + * 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. * - * If a lookup fails with `FT_Err_Out_Of_Memory' the cache has - * already been completely flushed, and still no memory was available - * for the operation. + * If a lookup fails with `FT_Err_Out_Of_Memory` the cache has already + * been completely flushed, and still no memory was available for the + * operation. */ FT_EXPORT( FT_Error ) FTC_Manager_LookupFace( FTC_Manager manager, @@ -410,9 +409,8 @@ FT_BEGIN_HEADER * FTC_ScalerRec * * @description: - * A structure used to describe a given character size in either - * pixels or points to the cache manager. See - * @FTC_Manager_LookupSize. + * A structure used to describe a given character size in either pixels + * or points to the cache manager. See @FTC_Manager_LookupSize. * * @fields: * face_id :: @@ -425,17 +423,17 @@ FT_BEGIN_HEADER * The character height. * * pixel :: - * A Boolean. If 1, the `width' and `height' fields are - * interpreted as integer pixel character sizes. - * Otherwise, they are expressed as 1/64th of points. + * A Boolean. If 1, the 'width' and 'height' fields are interpreted as + * integer pixel character sizes. Otherwise, they are expressed as + * 1/64th of points. * * x_res :: - * Only used when `pixel' is value~0 to indicate the - * horizontal resolution in dpi. + * Only used when 'pixel' is value~0 to indicate the horizontal + * resolution in dpi. * * y_res :: - * Only used when `pixel' is value~0 to indicate the - * vertical resolution in dpi. + * Only used when 'pixel' is value~0 to indicate the vertical + * resolution in dpi. * * @note: * This type is mainly used to retrieve @FT_Size objects through the @@ -491,18 +489,17 @@ FT_BEGIN_HEADER * The returned @FT_Size object is always owned by the manager. You * should never try to discard it by yourself. * - * You can access the parent @FT_Face object simply as `size->face' - * if you need it. Note that this object is also owned by the - * manager. + * You can access the parent @FT_Face object simply as `size->face` if + * you need it. Note that this object is also owned by the manager. * * @note: - * 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. + * 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. * - * If a lookup fails with `FT_Err_Out_Of_Memory' the cache has - * already been completely flushed, and still no memory is available - * for the operation. + * If a lookup fails with `FT_Err_Out_Of_Memory` the cache has already + * been completely flushed, and still no memory is available for the + * operation. */ FT_EXPORT( FT_Error ) FTC_Manager_LookupSize( FTC_Manager manager, @@ -538,9 +535,9 @@ FT_BEGIN_HEADER * FTC_Manager_RemoveFaceID * * @description: - * A special function used to indicate to the cache manager that - * a given @FTC_FaceID is no longer valid, either because its - * content changed, or because it was deallocated or uninstalled. + * A special function used to indicate to the cache manager that a given + * @FTC_FaceID is no longer valid, either because its content changed, or + * because it was deallocated or uninstalled. * * @input: * manager :: @@ -551,11 +548,11 @@ FT_BEGIN_HEADER * * @note: * This function flushes all nodes from the cache corresponding to this - * `face_id', with the exception of nodes with a non-null reference + * `face_id`, with the exception of nodes with a non-null reference * count. * - * Such nodes are however modified internally so as to never appear - * in later lookups with the same `face_id' value, and to be immediately + * Such nodes are however modified internally so as to never appear in + * later lookups with the same `face_id` value, and to be immediately * destroyed when released by all their users. * */ @@ -570,8 +567,8 @@ FT_BEGIN_HEADER * FTC_CMapCache * * @description: - * An opaque handle used to model a charmap cache. This cache is to - * hold character codes -> glyph indices mappings. + * An opaque handle used to model a charmap cache. This cache is to hold + * character codes -> glyph indices mappings. * */ typedef struct FTC_CMapCacheRec_* FTC_CMapCache; @@ -630,7 +627,7 @@ FT_BEGIN_HEADER * The character code (in the corresponding charmap). * * @return: - * Glyph index. 0~means `no glyph'. + * Glyph index. 0~means 'no glyph'. * */ FT_EXPORT( FT_UInt ) @@ -710,9 +707,9 @@ FT_BEGIN_HEADER * FTC_ImageCache * * @description: - * A handle to a glyph image cache object. They are designed to - * hold many distinct glyph images while not exceeding a certain - * memory threshold. + * A handle to a glyph image cache object. They are designed to hold + * many distinct glyph images while not exceeding a certain memory + * threshold. */ typedef struct FTC_ImageCacheRec_* FTC_ImageCache; @@ -761,32 +758,29 @@ FT_BEGIN_HEADER * * @output: * aglyph :: - * The corresponding @FT_Glyph object. 0~in case of - * failure. + * The corresponding @FT_Glyph object. 0~in case of failure. * * anode :: - * Used to return the address of the corresponding cache - * node after incrementing its reference count (see note - * below). + * Used to return the address of the corresponding cache node after + * incrementing its reference count (see note below). * * @return: * FreeType error code. 0~means success. * * @note: * The returned glyph is owned and managed by the glyph image cache. - * Never try to transform or discard it manually! You can however - * create a copy with @FT_Glyph_Copy and modify the new one. - * - * If `anode' is _not_ NULL, it receives the address of the cache - * node containing the glyph image, after increasing its reference - * count. This ensures that the node (as well as the @FT_Glyph) will - * always be kept in the cache until you call @FTC_Node_Unref to - * `release' it. - * - * If `anode' is NULL, the cache node is left unchanged, which means - * that the @FT_Glyph could be flushed out of the cache on the next - * call to one of the caching sub-system APIs. Don't assume that it - * is persistent! + * Never try to transform or discard it manually! You can however create + * a copy with @FT_Glyph_Copy and modify the new one. + * + * If 'anode' is _not_ NULL, it receives the address of the cache node + * containing the glyph image, after increasing its reference count. + * This ensures that the node (as well as the @FT_Glyph) will always be + * kept in the cache until you call @FTC_Node_Unref to 'release' it. + * + * If 'anode' is NULL, the cache node is left unchanged, which means that + * the @FT_Glyph could be flushed out of the cache on the next call to + * one of the caching sub-system APIs. Don't assume that it is + * persistent! */ FT_EXPORT( FT_Error ) FTC_ImageCache_Lookup( FTC_ImageCache cache, @@ -802,8 +796,8 @@ FT_BEGIN_HEADER * FTC_ImageCache_LookupScaler * * @description: - * A variant of @FTC_ImageCache_Lookup that uses an @FTC_ScalerRec - * to specify the face ID and its size. + * A variant of @FTC_ImageCache_Lookup that uses an @FTC_ScalerRec to + * specify the face ID and its size. * * @input: * cache :: @@ -820,32 +814,29 @@ FT_BEGIN_HEADER * * @output: * aglyph :: - * The corresponding @FT_Glyph object. 0~in case of - * failure. + * The corresponding @FT_Glyph object. 0~in case of failure. * * anode :: - * Used to return the address of the corresponding - * cache node after incrementing its reference count - * (see note below). + * Used to return the address of the corresponding cache node after + * incrementing its reference count (see note below). * * @return: * FreeType error code. 0~means success. * * @note: * The returned glyph is owned and managed by the glyph image cache. - * Never try to transform or discard it manually! You can however - * create a copy with @FT_Glyph_Copy and modify the new one. + * Never try to transform or discard it manually! You can however create + * a copy with @FT_Glyph_Copy and modify the new one. * - * If `anode' is _not_ NULL, it receives the address of the cache - * node containing the glyph image, after increasing its reference - * count. This ensures that the node (as well as the @FT_Glyph) will - * always be kept in the cache until you call @FTC_Node_Unref to - * `release' it. + * If 'anode' is _not_ NULL, it receives the address of the cache node + * containing the glyph image, after increasing its reference count. + * This ensures that the node (as well as the @FT_Glyph) will always be + * kept in the cache until you call @FTC_Node_Unref to 'release' it. * - * If `anode' is NULL, the cache node is left unchanged, which means - * that the @FT_Glyph could be flushed out of the cache on the next - * call to one of the caching sub-system APIs. Don't assume that it - * is persistent! + * If 'anode' is NULL, the cache node is left unchanged, which means that + * the @FT_Glyph could be flushed out of the cache on the next call to + * one of the caching sub-system APIs. Don't assume that it is + * persistent! * * Calls to @FT_Set_Char_Size and friends have no effect on cached * glyphs; you should always use the FreeType cache API instead. @@ -865,8 +856,8 @@ FT_BEGIN_HEADER * FTC_SBit * * @description: - * A handle to a small bitmap descriptor. See the @FTC_SBitRec - * structure for details. + * A handle to a small bitmap descriptor. See the @FTC_SBitRec structure + * for details. */ typedef struct FTC_SBitRec_* FTC_SBit; @@ -887,15 +878,13 @@ FT_BEGIN_HEADER * The bitmap height in pixels. * * left :: - * The horizontal distance from the pen position to the - * left bitmap border (a.k.a. `left side bearing', or - * `lsb'). + * The horizontal distance from the pen position to the left bitmap + * border (a.k.a. 'left side bearing', or 'lsb'). * * top :: - * The vertical distance from the pen position (on the - * baseline) to the upper bitmap border (a.k.a. `top - * side bearing'). The distance is positive for upwards - * y~coordinates. + * The vertical distance from the pen position (on the baseline) to the + * upper bitmap border (a.k.a. 'top side bearing'). The distance is + * positive for upwards y~coordinates. * * format :: * The format of the glyph bitmap (monochrome or gray). @@ -904,8 +893,7 @@ FT_BEGIN_HEADER * Maximum gray level value (in the range 1 to~255). * * pitch :: - * The number of bytes per bitmap line. May be positive - * or negative. + * The number of bytes per bitmap line. May be positive or negative. * * xadvance :: * The horizontal advance width in pixels. @@ -941,9 +929,9 @@ FT_BEGIN_HEADER * * @description: * A handle to a small bitmap cache. These are special cache objects - * used to store small glyph bitmaps (and anti-aliased pixmaps) in a - * much more efficient way than the traditional glyph image cache - * implemented by @FTC_ImageCache. + * used to store small glyph bitmaps (and anti-aliased pixmaps) in a much + * more efficient way than the traditional glyph image cache implemented + * by @FTC_ImageCache. */ typedef struct FTC_SBitCacheRec_* FTC_SBitCache; @@ -978,8 +966,8 @@ FT_BEGIN_HEADER * FTC_SBitCache_Lookup * * @description: - * Look up a given small glyph bitmap in a given sbit cache and - * `lock' it to prevent its flushing from the cache until needed. + * Look up a given small glyph bitmap in a given sbit cache and 'lock' it + * to prevent its flushing from the cache until needed. * * @input: * cache :: @@ -996,31 +984,29 @@ FT_BEGIN_HEADER * A handle to a small bitmap descriptor. * * anode :: - * Used to return the address of the corresponding cache - * node after incrementing its reference count (see note - * below). + * Used to return the address of the corresponding cache node after + * incrementing its reference count (see note below). * * @return: * FreeType error code. 0~means success. * * @note: - * The small bitmap descriptor and its bit buffer are owned by the - * cache and should never be freed by the application. They might - * as well disappear from memory on the next cache lookup, so don't - * treat them as persistent data. + * The small bitmap descriptor and its bit buffer are owned by the cache + * and should never be freed by the application. They might as well + * disappear from memory on the next cache lookup, so don't treat them as + * persistent data. * - * The descriptor's `buffer' field is set to~0 to indicate a missing + * The descriptor's 'buffer' field is set to~0 to indicate a missing * glyph bitmap. * - * If `anode' is _not_ NULL, it receives the address of the cache - * node containing the bitmap, after increasing its reference count. - * This ensures that the node (as well as the image) will always be - * kept in the cache until you call @FTC_Node_Unref to `release' it. + * If 'anode' is _not_ NULL, it receives the address of the cache node + * containing the bitmap, after increasing its reference count. This + * ensures that the node (as well as the image) will always be kept in + * the cache until you call @FTC_Node_Unref to 'release' it. * - * If `anode' is NULL, the cache node is left unchanged, which means - * that the bitmap could be flushed out of the cache on the next - * call to one of the caching sub-system APIs. Don't assume that it - * is persistent! + * If 'anode' is NULL, the cache node is left unchanged, which means that + * the bitmap could be flushed out of the cache on the next call to one + * of the caching sub-system APIs. Don't assume that it is persistent! */ FT_EXPORT( FT_Error ) FTC_SBitCache_Lookup( FTC_SBitCache cache, @@ -1036,8 +1022,8 @@ FT_BEGIN_HEADER * FTC_SBitCache_LookupScaler * * @description: - * A variant of @FTC_SBitCache_Lookup that uses an @FTC_ScalerRec - * to specify the face ID and its size. + * A variant of @FTC_SBitCache_Lookup that uses an @FTC_ScalerRec to + * specify the face ID and its size. * * @input: * cache :: @@ -1057,31 +1043,29 @@ FT_BEGIN_HEADER * A handle to a small bitmap descriptor. * * anode :: - * Used to return the address of the corresponding - * cache node after incrementing its reference count - * (see note below). + * Used to return the address of the corresponding cache node after + * incrementing its reference count (see note below). * * @return: * FreeType error code. 0~means success. * * @note: - * The small bitmap descriptor and its bit buffer are owned by the - * cache and should never be freed by the application. They might - * as well disappear from memory on the next cache lookup, so don't - * treat them as persistent data. + * The small bitmap descriptor and its bit buffer are owned by the cache + * and should never be freed by the application. They might as well + * disappear from memory on the next cache lookup, so don't treat them as + * persistent data. * - * The descriptor's `buffer' field is set to~0 to indicate a missing + * The descriptor's 'buffer' field is set to~0 to indicate a missing * glyph bitmap. * - * If `anode' is _not_ NULL, it receives the address of the cache - * node containing the bitmap, after increasing its reference count. - * This ensures that the node (as well as the image) will always be - * kept in the cache until you call @FTC_Node_Unref to `release' it. + * If 'anode' is _not_ NULL, it receives the address of the cache node + * containing the bitmap, after increasing its reference count. This + * ensures that the node (as well as the image) will always be kept in + * the cache until you call @FTC_Node_Unref to 'release' it. * - * If `anode' is NULL, the cache node is left unchanged, which means - * that the bitmap could be flushed out of the cache on the next - * call to one of the caching sub-system APIs. Don't assume that it - * is persistent! + * If 'anode' is NULL, the cache node is left unchanged, which means that + * the bitmap could be flushed out of the cache on the next call to one + * of the caching sub-system APIs. Don't assume that it is persistent! */ FT_EXPORT( FT_Error ) FTC_SBitCache_LookupScaler( FTC_SBitCache cache, diff --git a/include/freetype/ftcid.h b/include/freetype/ftcid.h index b427cbdfa..aac86f1e0 100644 --- a/include/freetype/ftcid.h +++ b/include/freetype/ftcid.h @@ -96,9 +96,9 @@ FT_BEGIN_HEADER * FT_Get_CID_Is_Internally_CID_Keyed * * @description: - * Retrieve the type of the input face, CID keyed or not. In - * contrast to the @FT_IS_CID_KEYED macro this function returns - * successfully also for CID-keyed fonts in an SFNT wrapper. + * Retrieve the type of the input face, CID keyed or not. In contrast + * to the @FT_IS_CID_KEYED macro this function returns successfully also + * for CID-keyed fonts in an SFNT wrapper. * * @input: * face :: @@ -112,8 +112,8 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * This function only works with CID faces and OpenType fonts, - * returning an error otherwise. + * This function only works with CID faces and OpenType fonts, returning + * an error otherwise. * * @since: * 2.3.9 @@ -146,8 +146,8 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * This function only works with CID faces and OpenType fonts, - * returning an error otherwise. + * This function only works with CID faces and OpenType fonts, returning + * an error otherwise. * * @since: * 2.3.9 diff --git a/include/freetype/ftcolor.h b/include/freetype/ftcolor.h index e4fa4afd4..f6e5a08e0 100644 --- a/include/freetype/ftcolor.h +++ b/include/freetype/ftcolor.h @@ -41,11 +41,11 @@ FT_BEGIN_HEADER * Glyph Color Management * * @abstract: - * Retrieving and manipulating OpenType's `CPAL' table data. + * Retrieving and manipulating OpenType's 'CPAL' table data. * * @description: * The functions described here allow access and manipulation of color - * palette entries in OpenType's `CPAL' tables. + * palette entries in OpenType's 'CPAL' tables. */ @@ -55,7 +55,7 @@ FT_BEGIN_HEADER * FT_Color * * @description: - * This structure models a BGRA color value of a `CPAL' palette entry. + * This structure models a BGRA color value of a 'CPAL' palette entry. * * The used color space is sRGB; the colors are not pre-multiplied, and * alpha values must be explicitly set. @@ -92,9 +92,9 @@ FT_BEGIN_HEADER * FT_PALETTE_XXX * * @description: - * A list of bit field constants used in the `palette_flags' array of - * the @FT_Palette_Data structure to indicate for which background a - * palette with a given index is usable. + * A list of bit field constants used in the `palette_flags` array of the + * @FT_Palette_Data structure to indicate for which background a palette + * with a given index is usable. * * @values: * FT_PALETTE_FOR_LIGHT_BACKGROUND :: @@ -102,8 +102,8 @@ FT_BEGIN_HEADER * light background such as white. * * FT_PALETTE_FOR_DARK_BACKGROUND :: - * The palette is appropriate to use when displaying the font on a - * dark background such as black. + * The palette is appropriate to use when displaying the font on a dark + * background such as black. * * @since: * 2.10 @@ -118,29 +118,29 @@ FT_BEGIN_HEADER * FT_Palette_Data * * @description: - * This structure holds the data of the `CPAL' table. + * This structure holds the data of the 'CPAL' table. * * @fields: * num_palettes :: * The number of palettes. * * palette_name_ids :: - * A read-only array of palette name IDs with `num_palettes' elements, - * corresponding to entries like `dark' or `light' in the font's - * `name' table. + * A read-only array of palette name IDs with `num_palettes` elements, + * corresponding to entries like 'dark' or 'light' in the font's 'name' + * table. * - * An empty name ID in the `CPAL' table gets represented as value + * An empty name ID in the 'CPAL' table gets represented as value * 0xFFFF. * - * NULL if the font's `CPAL' table doesn't contain appropriate data. + * NULL if the font's 'CPAL' table doesn't contain appropriate data. * * palette_flags :: - * A read-only array of palette flags with `num_palettes' elements. + * A read-only array of palette flags with `num_palettes` elements. * Possible values are an ORed combination of * @FT_PALETTE_FOR_LIGHT_BACKGROUND and * @FT_PALETTE_FOR_DARK_BACKGROUND. * - * NULL if the font's `CPAL' table doesn't contain appropriate data. + * NULL if the font's 'CPAL' table doesn't contain appropriate data. * * num_palette_entries :: * The number of entries in a single palette. All palettes have the @@ -148,17 +148,16 @@ FT_BEGIN_HEADER * * palette_entry_name_ids :: * A read-only array of palette entry name IDs with - * `num_palette_entries'. In each palette, entries with the same - * index have the same function. For example, index~0 might - * correspond to string `outline' in the font's `name' table to - * indicate that this palette entry is used for outlines, index~1 - * might correspond to `fill' to indicate the filling color palette - * entry, etc. + * `num_palette_entries`. In each palette, entries with the same index + * have the same function. For example, index~0 might correspond to + * string 'outline' in the font's 'name' table to indicate that this + * palette entry is used for outlines, index~1 might correspond to + * 'fill' to indicate the filling color palette entry, etc. * - * An empty entry name ID in the `CPAL' table gets represented as - * value 0xFFFF. + * An empty entry name ID in the 'CPAL' table gets represented as value + * 0xFFFF. * - * NULL if the font's `CPAL' table doesn't contain appropriate data. + * NULL if the font's 'CPAL' table doesn't contain appropriate data. * * @note: * Use function @FT_Get_Sfnt_Name to map name IDs and entry name IDs to @@ -201,7 +200,7 @@ FT_BEGIN_HEADER * All arrays in the returned @FT_Palette_Data structure are read-only. * * This function always returns an error if the config macro - * `TT_CONFIG_OPTION_COLOR_LAYERS' is not defined in `ftoption.h'. + * `TT_CONFIG_OPTION_COLOR_LAYERS` is not defined in `ftoption.h`. * * @since: * 2.10 @@ -227,7 +226,7 @@ FT_BEGIN_HEADER * * A corollary of (2) is that calling the function, then modifying some * values, then calling the function again with the same arguments resets - * all color entries to the original `CPAL' values; all user modifications + * all color entries to the original 'CPAL' values; all user modifications * are lost. * * @input: @@ -239,8 +238,8 @@ FT_BEGIN_HEADER * * @output: * apalette :: - * An array of color entries for a palette with index `palette_index'. - * If `apalette' is set to NULL, no array gets returned (and no color + * An array of color entries for a palette with index `palette_index`. + * If 'apalette' is set to NULL, no array gets returned (and no color * entries can be modified). * * In case the font doesn't support color palettes, NULL is returned. @@ -249,14 +248,14 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * The number of color entries is given by the `num_palette_entries' + * The number of color entries is given by the `num_palette_entries` * field in the @FT_Palette_Data structure. * - * The array pointed to by `apalette_entries' is owned and managed by + * The array pointed to by `apalette_entries` is owned and managed by * FreeType. * * This function always returns an error if the config macro - * `TT_CONFIG_OPTION_COLOR_LAYERS' is not defined in `ftoption.h'. + * `TT_CONFIG_OPTION_COLOR_LAYERS` is not defined in `ftoption.h`. * * @since: * 2.10 @@ -273,7 +272,7 @@ FT_BEGIN_HEADER * FT_Palette_Set_Foreground_Color * * @description: - * `COLR' uses palette index 0xFFFF to indicate a `text foreground + * 'COLR' uses palette index 0xFFFF to indicate a 'text foreground * color'. This function sets this value. * * @input: @@ -281,7 +280,7 @@ FT_BEGIN_HEADER * The source face handle. * * foreground_color :: - * An `FT_Color' structure to define the text foreground color. + * An `FT_Color` structure to define the text foreground color. * * @return: * FreeType error code. 0~means success. @@ -289,13 +288,12 @@ FT_BEGIN_HEADER * @note: * If this function isn't called, the text foreground color is set to * white opaque (BGRA value 0xFFFFFFFF) if - * @FT_PALETTE_FOR_DARK_BACKGROUND is present for the current - * palette, and black opaque (BGRA value 0x000000FF) otherwise, - * including the case that no palette types are available in the `CPAL' - * table. + * @FT_PALETTE_FOR_DARK_BACKGROUND is present for the current palette, + * and black opaque (BGRA value 0x000000FF) otherwise, including the case + * that no palette types are available in the 'CPAL' table. * * This function always returns an error if the config macro - * `TT_CONFIG_OPTION_COLOR_LAYERS' is not defined in `ftoption.h'. + * `TT_CONFIG_OPTION_COLOR_LAYERS` is not defined in `ftoption.h`. * * @since: * 2.10 diff --git a/include/freetype/ftdriver.h b/include/freetype/ftdriver.h index d70384585..b843a4d69 100644 --- a/include/freetype/ftdriver.h +++ b/include/freetype/ftdriver.h @@ -50,8 +50,8 @@ FT_BEGIN_HEADER * @FT_Property_Get. The following lists the available properties * together with the necessary macros and structures. * - * Note that the auto-hinter's module name is `autofitter' for - * historical reasons. + * Note that the auto-hinter's module name is 'autofitter' for historical + * reasons. * * Available properties are @increase-x-height, @no-stem-darkening * (experimental), @darkening-parameters (experimental), @warping @@ -74,18 +74,18 @@ FT_BEGIN_HEADER * Controlling the CFF driver module. * * @description: - * While FreeType's CFF driver doesn't expose API functions by itself, - * it is possible to control its behaviour with @FT_Property_Set and + * While FreeType's CFF driver doesn't expose API functions by itself, it + * is possible to control its behaviour with @FT_Property_Set and * @FT_Property_Get. * - * The CFF driver's module name is `cff'. + * The CFF driver's module name is 'cff'. * * Available properties are @hinting-engine, @no-stem-darkening, * @darkening-parameters, and @random-seed, as documented in the * @properties section. * * - * *Hinting* *and* *antialiasing* *principles* *of* *the* *new* *engine* + * **Hinting and antialiasing principles of the new engine** * * The rasterizer is positioning horizontal features (e.g., ascender * height & x-height, or crossbars) on the pixel grid and minimizing the @@ -93,35 +93,34 @@ FT_BEGIN_HEADER * features (vertical stems) on the pixel grid without hinting, thus * representing the stem position and weight accurately. Sometimes the * vertical stems may be only partially black. In this context, - * `antialiasing' means that stems are not positioned exactly on pixel + * 'antialiasing' means that stems are not positioned exactly on pixel * borders, causing a fuzzy appearance. * * There are two principles behind this approach. * - * 1) No hinting in the horizontal direction: Unlike `superhinted' + * 1) No hinting in the horizontal direction: Unlike 'superhinted' * TrueType, which changes glyph widths to accommodate regular - * inter-glyph spacing, Adobe's approach is `faithful to the design' in - * representing both the glyph width and the inter-glyph spacing - * designed for the font. This makes the screen display as close as it - * can be to the result one would get with infinite resolution, while - * preserving what is considered the key characteristics of each glyph. - * Note that the distances between unhinted and grid-fitted positions at - * small sizes are comparable to kerning values and thus would be - * noticeable (and distracting) while reading if hinting were applied. + * inter-glyph spacing, Adobe's approach is 'faithful to the design' in + * representing both the glyph width and the inter-glyph spacing designed + * for the font. This makes the screen display as close as it can be to + * the result one would get with infinite resolution, while preserving + * what is considered the key characteristics of each glyph. Note that + * the distances between unhinted and grid-fitted positions at small + * sizes are comparable to kerning values and thus would be noticeable + * (and distracting) while reading if hinting were applied. * * One of the reasons to not hint horizontally is antialiasing for LCD - * screens: The pixel geometry of modern displays supplies three - * vertical subpixels as the eye moves horizontally across each visible - * pixel. On devices where we can be certain this characteristic is - * present a rasterizer can take advantage of the subpixels to add - * increments of weight. In Western writing systems this turns out to - * be the more critical direction anyway; the weights and spacing of - * vertical stems (see above) are central to Armenian, Cyrillic, Greek, - * and Latin type designs. Even when the rasterizer uses greyscale - * antialiasing instead of color (a necessary compromise when one - * doesn't know the screen characteristics), the unhinted vertical - * features preserve the design's weight and spacing much better than - * aliased type would. + * screens: The pixel geometry of modern displays supplies three vertical + * subpixels as the eye moves horizontally across each visible pixel. On + * devices where we can be certain this characteristic is present a + * rasterizer can take advantage of the subpixels to add increments of + * weight. In Western writing systems this turns out to be the more + * critical direction anyway; the weights and spacing of vertical stems + * (see above) are central to Armenian, Cyrillic, Greek, and Latin type + * designs. Even when the rasterizer uses greyscale antialiasing instead + * of color (a necessary compromise when one doesn't know the screen + * characteristics), the unhinted vertical features preserve the design's + * weight and spacing much better than aliased type would. * * 2) Alignment in the vertical direction: Weights and spacing along the * y~axis are less critical; what is much more important is the visual @@ -132,16 +131,16 @@ FT_BEGIN_HEADER * * On the technical side, horizontal alignment zones for ascender, * x-height, and other important height values (traditionally called - * `blue zones') as defined in the font are positioned independently, - * each being rounded to the nearest pixel edge, taking care of - * overshoot suppression at small sizes, stem darkening, and scaling. + * 'blue zones') as defined in the font are positioned independently, + * each being rounded to the nearest pixel edge, taking care of overshoot + * suppression at small sizes, stem darkening, and scaling. * * Hstems (this is, hint values defined in the font to help align * horizontal features) that fall within a blue zone are said to be - * `captured' and are aligned to that zone. Uncaptured stems are moved + * 'captured' and are aligned to that zone. Uncaptured stems are moved * in one of four ways, top edge up or down, bottom edge up or down. - * Unless there are conflicting hstems, the smallest movement is taken - * to minimize distortion. + * Unless there are conflicting hstems, the smallest movement is taken to + * minimize distortion. * */ @@ -158,13 +157,13 @@ FT_BEGIN_HEADER * Controlling the PCF driver module. * * @description: - * While FreeType's PCF driver doesn't expose API functions by itself, - * it is possible to control its behaviour with @FT_Property_Set and + * While FreeType's PCF driver doesn't expose API functions by itself, it + * is possible to control its behaviour with @FT_Property_Set and * @FT_Property_Get. Right now, there is a single property * @no-long-family-names available if FreeType is compiled with * PCF_CONFIG_OPTION_LONG_FAMILY_NAMES. * - * The PCF driver's module name is `pcf'. + * The PCF driver's module name is 'pcf'. * */ @@ -187,15 +186,15 @@ FT_BEGIN_HEADER * Behind the scenes, both drivers use the Adobe CFF engine for hinting; * however, the used properties must be specified separately. * - * The Type~1 driver's module name is `type1'; the CID driver's module - * name is `t1cid'. + * The Type~1 driver's module name is 'type1'; the CID driver's module + * name is 't1cid'. * * Available properties are @hinting-engine, @no-stem-darkening, * @darkening-parameters, and @random-seed, as documented in the * @properties section. * - * Please see the @cff_driver section for more details on the new - * hinting engine. + * Please see the @cff_driver section for more details on the new hinting + * engine. * */ @@ -217,7 +216,7 @@ FT_BEGIN_HEADER * and @FT_Property_Get. The following lists the available properties * together with the necessary macros and structures. * - * The TrueType driver's module name is `truetype'. + * The TrueType driver's module name is 'truetype'. * * A single property @interpreter-version is available, as documented in * the @properties section. @@ -225,36 +224,36 @@ FT_BEGIN_HEADER * We start with a list of definitions, kindly provided by Greg * Hitchcock. * - * _Bi-Level_ _Rendering_ + * _Bi-Level Rendering_ * * Monochromatic rendering, exclusively used in the early days of * TrueType by both Apple and Microsoft. Microsoft's GDI interface * supported hinting of the right-side bearing point, such that the * advance width could be non-linear. Most often this was done to * achieve some level of glyph symmetry. To enable reasonable - * performance (e.g., not having to run hinting on all glyphs just to - * get the widths) there was a bit in the head table indicating if the - * side bearing was hinted, and additional tables, `hdmx' and `LTSH', to - * cache hinting widths across multiple sizes and device aspect ratios. + * performance (e.g., not having to run hinting on all glyphs just to get + * the widths) there was a bit in the head table indicating if the side + * bearing was hinted, and additional tables, 'hdmx' and 'LTSH', to cache + * hinting widths across multiple sizes and device aspect ratios. * - * _Font_ _Smoothing_ + * _Font Smoothing_ * * Microsoft's GDI implementation of anti-aliasing. Not traditional * anti-aliasing as the outlines were hinted before the sampling. The * widths matched the bi-level rendering. * - * _ClearType_ _Rendering_ + * _ClearType Rendering_ * * Technique that uses physical subpixels to improve rendering on LCD * (and other) displays. Because of the higher resolution, many methods - * of improving symmetry in glyphs through hinting the right-side - * bearing were no longer necessary. This lead to what GDI calls - * `natural widths' ClearType, see + * of improving symmetry in glyphs through hinting the right-side bearing + * were no longer necessary. This lead to what GDI calls 'natural + * widths' ClearType, see * http://www.beatstamm.com/typography/RTRCh4.htm#Sec21. Since hinting * has extra resolution, most non-linearity went away, but it is still * possible for hints to change the advance widths in this mode. * - * _ClearType_ _Compatible_ _Widths_ + * _ClearType Compatible Widths_ * * One of the earliest challenges with ClearType was allowing the * implementation in GDI to be selected without requiring all UI and @@ -267,37 +266,37 @@ FT_BEGIN_HEADER * definition, compatible width ClearType allows for non-linear widths, * but only when the bi-level version has non-linear widths. * - * _ClearType_ _Subpixel_ _Positioning_ + * _ClearType Subpixel Positioning_ * * One of the nice benefits of ClearType is the ability to more crisply * display fractional widths; unfortunately, the GDI model of integer * bitmaps did not support this. However, the WPF and Direct Write - * frameworks do support fractional widths. DWrite calls this `natural - * mode', not to be confused with GDI's `natural widths'. Subpixel + * frameworks do support fractional widths. DWrite calls this 'natural + * mode', not to be confused with GDI's 'natural widths'. Subpixel * positioning, in the current implementation of Direct Write, * unfortunately does not support hinted advance widths, see * http://www.beatstamm.com/typography/RTRCh4.htm#Sec22. Note that the * TrueType interpreter fully allows the advance width to be adjusted in * this mode, just the DWrite client will ignore those changes. * - * _ClearType_ _Backward_ _Compatibility_ + * _ClearType Backward Compatibility_ * * This is a set of exceptions made in the TrueType interpreter to * minimize hinting techniques that were problematic with the extra * resolution of ClearType; see * http://www.beatstamm.com/typography/RTRCh4.htm#Sec1 and * https://www.microsoft.com/typography/cleartype/truetypecleartype.aspx. - * This technique is not to be confused with ClearType compatible - * widths. ClearType backward compatibility has no direct impact on - * changing advance widths, but there might be an indirect impact on - * disabling some deltas. This could be worked around in backward - * compatibility mode. + * This technique is not to be confused with ClearType compatible widths. + * ClearType backward compatibility has no direct impact on changing + * advance widths, but there might be an indirect impact on disabling + * some deltas. This could be worked around in backward compatibility + * mode. * - * _Native_ _ClearType_ _Mode_ + * _Native ClearType Mode_ * - * (Not to be confused with `natural widths'.) This mode removes all - * the exceptions in the TrueType interpreter when running with - * ClearType. Any issues on widths would still apply, though. + * (Not to be confused with 'natural widths'.) This mode removes all the + * exceptions in the TrueType interpreter when running with ClearType. + * Any issues on widths would still apply, though. * */ @@ -328,8 +327,8 @@ FT_BEGIN_HEADER * FT_HINTING_XXX * * @description: - * A list of constants used for the @hinting-engine property to - * select the hinting engine for CFF, Type~1, and CID fonts. + * A list of constants used for the @hinting-engine property to select + * the hinting engine for CFF, Type~1, and CID fonts. * * @values: * FT_HINTING_FREETYPE :: @@ -356,32 +355,32 @@ FT_BEGIN_HEADER * hinting-engine * * @description: - * Thanks to Adobe, which contributed a new hinting (and parsing) - * engine, an application can select between `freetype' and `adobe' if - * compiled with CFF_CONFIG_OPTION_OLD_ENGINE. If this configuration - * macro isn't defined, `hinting-engine' does nothing. + * Thanks to Adobe, which contributed a new hinting (and parsing) engine, + * an application can select between 'freetype' and 'adobe' if compiled + * with CFF_CONFIG_OPTION_OLD_ENGINE. If this configuration macro isn't + * defined, 'hinting-engine' does nothing. * * The same holds for the Type~1 and CID modules if compiled with * T1_CONFIG_OPTION_OLD_ENGINE. * - * For the `cff' module, the default engine is `freetype' if - * CFF_CONFIG_OPTION_OLD_ENGINE is defined, and `adobe' otherwise. + * For the 'cff' module, the default engine is 'freetype' if + * CFF_CONFIG_OPTION_OLD_ENGINE is defined, and 'adobe' otherwise. * - * For both the `type1' and `t1cid' modules, the default engine is - * `freetype' if T1_CONFIG_OPTION_OLD_ENGINE is defined, and `adobe' + * For both the 'type1' and 't1cid' modules, the default engine is + * 'freetype' if T1_CONFIG_OPTION_OLD_ENGINE is defined, and 'adobe' * otherwise. * * @note: * This property can be used with @FT_Property_Get also. * - * This property can be set via the `FREETYPE_PROPERTIES' environment - * variable (using values `adobe' or `freetype'). + * This property can be set via the `FREETYPE_PROPERTIES` environment + * variable (using values 'adobe' or 'freetype'). * * @example: * The following example code demonstrates how to select Adobe's hinting - * engine for the `cff' module (omitting the error handling). + * engine for the 'cff' module (omitting the error handling). * - * { + * ``` * FT_Library library; * FT_UInt hinting_engine = FT_HINTING_ADOBE; * @@ -390,12 +389,12 @@ FT_BEGIN_HEADER * * FT_Property_Set( library, "cff", * "hinting-engine", &hinting_engine ); - * } + * ``` * * @since: - * 2.4.12 (for `cff' module) + * 2.4.12 (for 'cff' module) * - * 2.9 (for `type1' and `t1cid' modules) + * 2.9 (for 'type1' and 't1cid' modules) * */ @@ -406,10 +405,10 @@ FT_BEGIN_HEADER * no-stem-darkening * * @description: - * All glyphs that pass through the auto-hinter will be emboldened - * unless this property is set to TRUE. The same is true for the CFF, - * Type~1, and CID font modules if the `Adobe' engine is selected (which - * is the default). + * All glyphs that pass through the auto-hinter will be emboldened unless + * this property is set to TRUE. The same is true for the CFF, Type~1, + * and CID font modules if the 'Adobe' engine is selected (which is the + * default). * * Stem darkening emboldens glyphs at smaller sizes to make them more * readable on common low-DPI screens when using linear alpha blending @@ -420,39 +419,38 @@ FT_BEGIN_HEADER * Gamma correction essentially lightens fonts since shades of grey are * shifted to higher pixel values (=~higher brightness) to match the * original intention to the reality of our screens. The side-effect is - * that glyphs `thin out'. Mac OS~X and Adobe's proprietary font + * that glyphs 'thin out'. Mac OS~X and Adobe's proprietary font * rendering library implement a counter-measure: stem darkening at * smaller sizes where shades of gray dominate. By emboldening a glyph * slightly in relation to its pixel size, individual pixels get higher - * coverage of filled-in outlines and are therefore `blacker'. This - * counteracts the `thinning out' of glyphs, making text remain readable + * coverage of filled-in outlines and are therefore 'blacker'. This + * counteracts the 'thinning out' of glyphs, making text remain readable * at smaller sizes. * * By default, the Adobe engines for CFF, Type~1, and CID fonts darken * stems at smaller sizes, regardless of hinting, to enhance contrast. * Setting this property, stem darkening gets switched off. * - * For the auto-hinter, stem-darkening is experimental currently and - * thus switched off by default (this is, `no-stem-darkening' is set to - * TRUE by default). Total consistency with the CFF driver is not - * achieved right now because the emboldening method differs and glyphs - * must be scaled down on the Y-axis to keep outline points inside their + * For the auto-hinter, stem-darkening is experimental currently and thus + * switched off by default (this is, 'no-stem-darkening' is set to TRUE + * by default). Total consistency with the CFF driver is not achieved + * right now because the emboldening method differs and glyphs must be + * scaled down on the Y-axis to keep outline points inside their * precomputed blue zones. The smaller the size (especially 9ppem and * down), the higher the loss of emboldening versus the CFF driver. * - * Note that stem darkening is never applied if @FT_LOAD_NO_SCALE is - * set. + * Note that stem darkening is never applied if @FT_LOAD_NO_SCALE is set. * * @note: * This property can be used with @FT_Property_Get also. * - * This property can be set via the `FREETYPE_PROPERTIES' environment - * variable (using values 1 and 0 for `on' and `off', respectively). - * It can also be set per face using @FT_Face_Properties with + * This property can be set via the `FREETYPE_PROPERTIES` environment + * variable (using values 1 and 0 for 'on' and 'off', respectively). It + * can also be set per face using @FT_Face_Properties with * @FT_PARAM_TAG_STEM_DARKENING. * * @example: - * { + * ``` * FT_Library library; * FT_Bool no_stem_darkening = TRUE; * @@ -461,14 +459,14 @@ FT_BEGIN_HEADER * * FT_Property_Set( library, "cff", * "no-stem-darkening", &no_stem_darkening ); - * } + * ``` * * @since: - * 2.4.12 (for `cff' module) + * 2.4.12 (for 'cff' module) * - * 2.6.2 (for `autofitter' module) + * 2.6.2 (for 'autofitter' module) * - * 2.9 (for `type1' and `t1cid' modules) + * 2.9 (for 'type1' and 't1cid' modules) * */ @@ -480,29 +478,29 @@ FT_BEGIN_HEADER * * @description: * By default, the Adobe hinting engine, as used by the CFF, Type~1, and - * CID font drivers, darkens stems as follows (if the - * `no-stem-darkening' property isn't set): + * CID font drivers, darkens stems as follows (if the 'no-stem-darkening' + * property isn't set): * - * { + * ``` * stem width <= 0.5px: darkening amount = 0.4px * stem width = 1px: darkening amount = 0.275px * stem width = 1.667px: darkening amount = 0.275px * stem width >= 2.333px: darkening amount = 0px - * } + * ``` * * and piecewise linear in-between. At configuration time, these four * control points can be set with the macro - * `CFF_CONFIG_OPTION_DARKENING_PARAMETERS'; the CFF, Type~1, and CID + * `CFF_CONFIG_OPTION_DARKENING_PARAMETERS`; the CFF, Type~1, and CID * drivers share these values. At runtime, the control points can be - * changed using the `darkening-parameters' property (see the example + * changed using the 'darkening-parameters' property (see the example * below that demonstrates this for the Type~1 driver). * * The x~values give the stem width, and the y~values the darkening * amount. The unit is 1000th of pixels. All coordinate values must be - * positive; the x~values must be monotonically increasing; the - * y~values must be monotonically decreasing and smaller than or - * equal to 500 (corresponding to half a pixel); the slope of each - * linear piece must be shallower than -1 (e.g., -.4). + * positive; the x~values must be monotonically increasing; the y~values + * must be monotonically decreasing and smaller than or equal to 500 + * (corresponding to half a pixel); the slope of each linear piece must + * be shallower than -1 (e.g., -.4). * * The auto-hinter provides this property, too, as an experimental * feature. See @no-stem-darkening for more. @@ -510,17 +508,17 @@ FT_BEGIN_HEADER * @note: * This property can be used with @FT_Property_Get also. * - * This property can be set via the `FREETYPE_PROPERTIES' environment + * This property can be set via the `FREETYPE_PROPERTIES` environment * variable, using eight comma-separated integers without spaces. Here - * the above example, using `\' to break the line for readability. + * the above example, using '\' to break the line for readability. * - * { + * ``` * FREETYPE_PROPERTIES=\ * type1:darkening-parameters=500,300,1000,200,1500,100,2000,0 - * } + * ``` * * @example: - * { + * ``` * FT_Library library; * FT_Int darken_params[8] = { 500, 300, // x1, y1 * 1000, 200, // x2, y2 @@ -532,14 +530,14 @@ FT_BEGIN_HEADER * * FT_Property_Set( library, "type1", * "darkening-parameters", darken_params ); - * } + * ``` * * @since: - * 2.5.1 (for `cff' module) + * 2.5.1 (for 'cff' module) * - * 2.6.2 (for `autofitter' module) + * 2.6.2 (for 'autofitter' module) * - * 2.9 (for `type1' and `t1cid' modules) + * 2.9 (for 'type1' and 't1cid' modules) * */ @@ -550,29 +548,29 @@ FT_BEGIN_HEADER * random-seed * * @description: - * By default, the seed value for the CFF `random' operator and the - * similar `0 28 callothersubr pop' command for the Type~1 and CID + * By default, the seed value for the CFF 'random' operator and the + * similar '0 28 callothersubr pop' command for the Type~1 and CID * drivers is set to a random value. However, mainly for debugging - * purposes, it is often necessary to use a known value as a seed so - * that the pseudo-random number sequences generated by `random' are + * purposes, it is often necessary to use a known value as a seed so that + * the pseudo-random number sequences generated by 'random' are * repeatable. * - * The `random-seed' property does that. Its argument is a signed 32bit + * The 'random-seed' property does that. Its argument is a signed 32bit * integer; if the value is zero or negative, the seed given by the - * `intitialRandomSeed' private DICT operator in a CFF file gets used - * (or a default value if there is no such operator). If the value is - * positive, use it instead of `initialRandomSeed', which is - * consequently ignored. + * `intitialRandomSeed` private DICT operator in a CFF file gets used (or + * a default value if there is no such operator). If the value is + * positive, use it instead of `initialRandomSeed`, which is consequently + * ignored. * * @note: - * This property can be set via the `FREETYPE_PROPERTIES' environment + * This property can be set via the `FREETYPE_PROPERTIES` environment * variable. It can also be set per face using @FT_Face_Properties with * @FT_PARAM_TAG_RANDOM_SEED. * * @since: - * 2.8 (for `cff' module) + * 2.8 (for 'cff' module) * - * 2.9 (for `type1' and `t1cid' modules) + * 2.9 (for 'type1' and 't1cid' modules) * */ @@ -586,25 +584,25 @@ FT_BEGIN_HEADER * If PCF_CONFIG_OPTION_LONG_FAMILY_NAMES is active while compiling * FreeType, the PCF driver constructs long family names. * - * There are many PCF fonts just called `Fixed' which look completely + * There are many PCF fonts just called 'Fixed' which look completely * different, and which have nothing to do with each other. When - * selecting `Fixed' in KDE or Gnome one gets results that appear rather - * random, the style changes often if one changes the size and one - * cannot select some fonts at all. The improve this situation, the PCF - * module prepends the foundry name (plus a space) to the family name. - * It also checks whether there are `wide' characters; all put together, - * family names like `Sony Fixed' or `Misc Fixed Wide' are constructed. + * selecting 'Fixed' in KDE or Gnome one gets results that appear rather + * random, the style changes often if one changes the size and one cannot + * select some fonts at all. The improve this situation, the PCF module + * prepends the foundry name (plus a space) to the family name. It also + * checks whether there are 'wide' characters; all put together, family + * names like 'Sony Fixed' or 'Misc Fixed Wide' are constructed. * - * If `no-long-family-names' is set, this feature gets switched off. + * If 'no-long-family-names' is set, this feature gets switched off. * * @note: * This property can be used with @FT_Property_Get also. * - * This property can be set via the `FREETYPE_PROPERTIES' environment - * variable (using values 1 and 0 for `on' and `off', respectively). + * This property can be set via the `FREETYPE_PROPERTIES` environment + * variable (using values 1 and 0 for 'on' and 'off', respectively). * * @example: - * { + * ``` * FT_Library library; * FT_Bool no_long_family_names = TRUE; * @@ -614,7 +612,7 @@ FT_BEGIN_HEADER * FT_Property_Set( library, "pcf", * "no-long-family-names", * &no_long_family_names ); - * } + * ``` * * @since: * 2.8 @@ -630,8 +628,8 @@ FT_BEGIN_HEADER * A list of constants used for the @interpreter-version property to * select the hinting engine for Truetype fonts. * - * The numeric value in the constant names represents the version - * number as returned by the `GETINFO' bytecode instruction. + * The numeric value in the constant names represents the version number + * as returned by the 'GETINFO' bytecode instruction. * * @values: * TT_INTERPRETER_VERSION_35 :: @@ -642,38 +640,37 @@ FT_BEGIN_HEADER * Version~38 corresponds to MS rasterizer v.1.9; it is roughly * equivalent to the hinting provided by DirectWrite ClearType (as can * be found, for example, in the Internet Explorer~9 running on - * Windows~7). It is used in FreeType to select the `Infinality' - * subpixel hinting code. The code may be removed in a future - * version. + * Windows~7). It is used in FreeType to select the 'Infinality' + * subpixel hinting code. The code may be removed in a future version. * * TT_INTERPRETER_VERSION_40 :: * Version~40 corresponds to MS rasterizer v.2.1; it is roughly * equivalent to the hinting provided by DirectWrite ClearType (as can * be found, for example, in Microsoft's Edge Browser on Windows~10). - * It is used in FreeType to select the `minimal' subpixel hinting + * It is used in FreeType to select the 'minimal' subpixel hinting * code, a stripped-down and higher performance version of the - * `Infinality' code. + * 'Infinality' code. * * @note: - * This property controls the behaviour of the bytecode interpreter - * and thus how outlines get hinted. It does *not* control how glyph - * get rasterized! In particular, it does not control subpixel color + * This property controls the behaviour of the bytecode interpreter and + * thus how outlines get hinted. It does **not** control how glyph get + * rasterized! In particular, it does not control subpixel color * filtering. * * If FreeType has not been compiled with the configuration option * TT_CONFIG_OPTION_SUBPIXEL_HINTING, selecting version~38 or~40 causes - * an `FT_Err_Unimplemented_Feature' error. + * an `FT_Err_Unimplemented_Feature` error. * - * Depending on the graphics framework, Microsoft uses different - * bytecode and rendering engines. As a consequence, the version - * numbers returned by a call to the `GETINFO' bytecode instruction are - * more convoluted than desired. + * Depending on the graphics framework, Microsoft uses different bytecode + * and rendering engines. As a consequence, the version numbers returned + * by a call to the 'GETINFO' bytecode instruction are more convoluted + * than desired. * - * Here are two tables that try to shed some light on the possible - * values for the MS rasterizer engine, together with the additional - * features introduced by it. + * Here are two tables that try to shed some light on the possible values + * for the MS rasterizer engine, together with the additional features + * introduced by it. * - * { + * ``` * GETINFO framework version feature * ------------------------------------------------------------------- * 3 GDI (Win 3.1), v1.0 16-bit, first version @@ -696,15 +693,15 @@ FT_BEGIN_HEADER * 40 GDI+ (after Win 7), v2.1 Y-direction ClearType flag * DWrite (Win 8) in GETINFO opcode, * Gray ClearType - * } + * ``` * - * The `version' field gives a rough orientation only, since some + * The 'version' field gives a rough orientation only, since some * applications provided certain features much earlier (as an example, * Microsoft Reader used subpixel and Y-direction ClearType already in * Windows 2000). Similarly, updates to a given framework might include * improved hinting support. * - * { + * ``` * version sampling rendering comment * x y x y * -------------------------------------------------------------- @@ -714,38 +711,38 @@ FT_BEGIN_HEADER * v1.9 high high color-filter gray Color ClearType * v2.1 high normal gray B/W Gray ClearType * v2.1 high high gray gray Gray ClearType - * } + * ``` * * Color and Gray ClearType are the two available variants of - * `Y-direction ClearType', meaning grayscale rasterization along the + * 'Y-direction ClearType', meaning grayscale rasterization along the * Y-direction; the name used in the TrueType specification for this - * feature is `symmetric smoothing'. `Classic ClearType' is the - * original algorithm used before introducing a modified version in - * Win~XP. Another name for v1.6's grayscale rendering is `font - * smoothing', and `Color ClearType' is sometimes also called `DWrite - * ClearType'. To differentiate between today's Color ClearType and the - * earlier ClearType variant with B/W rendering along the vertical axis, - * the latter is sometimes called `GDI ClearType'. - * - * `Normal' and `high' sampling describe the (virtual) resolution to - * access the rasterized outline after the hinting process. `Normal' + * feature is 'symmetric smoothing'. 'Classic ClearType' is the original + * algorithm used before introducing a modified version in Win~XP. + * Another name for v1.6's grayscale rendering is 'font smoothing', and + * 'Color ClearType' is sometimes also called 'DWrite ClearType'. To + * differentiate between today's Color ClearType and the earlier + * ClearType variant with B/W rendering along the vertical axis, the + * latter is sometimes called 'GDI ClearType'. + * + * 'Normal' and 'high' sampling describe the (virtual) resolution to + * access the rasterized outline after the hinting process. 'Normal' * means 1 sample per grid line (i.e., B/W). In the current Microsoft - * implementation, `high' means an extra virtual resolution of 16x16 (or - * 16x1) grid lines per pixel for bytecode instructions like `MIRP'. + * implementation, 'high' means an extra virtual resolution of 16x16 (or + * 16x1) grid lines per pixel for bytecode instructions like 'MIRP'. * After hinting, these 16 grid lines are mapped to 6x5 (or 6x1) grid * lines for color filtering if Color ClearType is activated. * - * Note that `Gray ClearType' is essentially the same as v1.6's - * grayscale rendering. However, the GETINFO instruction handles it - * differently: v1.6 returns bit~12 (hinting for grayscale), while v2.1 - * returns bits~13 (hinting for ClearType), 18 (symmetrical smoothing), - * and~19 (Gray ClearType). Also, this mode respects bits 2 and~3 for - * the version~1 gasp table exclusively (like Color ClearType), while - * v1.6 only respects the values of version~0 (bits 0 and~1). + * Note that 'Gray ClearType' is essentially the same as v1.6's grayscale + * rendering. However, the GETINFO instruction handles it differently: + * v1.6 returns bit~12 (hinting for grayscale), while v2.1 returns + * bits~13 (hinting for ClearType), 18 (symmetrical smoothing), and~19 + * (Gray ClearType). Also, this mode respects bits 2 and~3 for the + * version~1 gasp table exclusively (like Color ClearType), while v1.6 + * only respects the values of version~0 (bits 0 and~1). * - * Keep in mind that the features of the above interpreter versions - * might not map exactly to FreeType features or behavior because it is - * a fundamentally different library with different internals. + * Keep in mind that the features of the above interpreter versions might + * not map exactly to FreeType features or behavior because it is a + * fundamentally different library with different internals. * */ #define TT_INTERPRETER_VERSION_35 35 @@ -759,25 +756,25 @@ FT_BEGIN_HEADER * interpreter-version * * @description: - * Currently, three versions are available, two representing the - * bytecode interpreter with subpixel hinting support (old `Infinality' - * code and new stripped-down and higher performance `minimal' code) and - * one without, respectively. The default is subpixel support if + * Currently, three versions are available, two representing the bytecode + * interpreter with subpixel hinting support (old 'Infinality' code and + * new stripped-down and higher performance 'minimal' code) and one + * without, respectively. The default is subpixel support if * TT_CONFIG_OPTION_SUBPIXEL_HINTING is defined, and no subpixel support * otherwise (since it isn't available then). * * If subpixel hinting is on, many TrueType bytecode instructions behave - * differently compared to B/W or grayscale rendering (except if `native + * differently compared to B/W or grayscale rendering (except if 'native * ClearType' is selected by the font). Microsoft's main idea is to * render at a much increased horizontal resolution, then sampling down * the created output to subpixel precision. However, many older fonts - * are not suited to this and must be specially taken care of by - * applying (hardcoded) tweaks in Microsoft's interpreter. + * are not suited to this and must be specially taken care of by applying + * (hardcoded) tweaks in Microsoft's interpreter. * * Details on subpixel hinting and some of the necessary tweaks can be * found in Greg Hitchcock's whitepaper at - * `https://www.microsoft.com/typography/cleartype/truetypecleartype.aspx'. - * Note that FreeType currently doesn't really `subpixel hint' (6x1, 6x2, + * 'https://www.microsoft.com/typography/cleartype/truetypecleartype.aspx'. + * Note that FreeType currently doesn't really 'subpixel hint' (6x1, 6x2, * or 6x5 supersampling) like discussed in the paper. Depending on the * chosen interpreter, it simply ignores instructions on vertical stems * to arrive at very similar results. @@ -785,14 +782,14 @@ FT_BEGIN_HEADER * @note: * This property can be used with @FT_Property_Get also. * - * This property can be set via the `FREETYPE_PROPERTIES' environment - * variable (using values `35', `38', or `40'). + * This property can be set via the `FREETYPE_PROPERTIES` environment + * variable (using values '35', '38', or '40'). * * @example: * The following example code demonstrates how to deactivate subpixel * hinting (omitting the error handling). * - * { + * ``` * FT_Library library; * FT_Face face; * FT_UInt interpreter_version = TT_INTERPRETER_VERSION_35; @@ -803,7 +800,7 @@ FT_BEGIN_HEADER * FT_Property_Set( library, "truetype", * "interpreter-version", * &interpreter_version ); - * } + * ``` * * @since: * 2.5 @@ -816,7 +813,7 @@ FT_BEGIN_HEADER * glyph-to-script-map * * @description: - * *Experimental* *only* + * **Experimental only** * * The auto-hinter provides various script modules to hint glyphs. * Examples of supported scripts are Latin or CJK. Before a glyph is @@ -824,26 +821,26 @@ FT_BEGIN_HEADER * the script is then determined based on Unicode character ranges, see * below. * - * OpenType fonts, however, often provide much more glyphs than - * character codes (small caps, superscripts, ligatures, swashes, etc.), - * to be controlled by so-called `features'. Handling OpenType features - * can be quite complicated and thus needs a separate library on top of + * OpenType fonts, however, often provide much more glyphs than character + * codes (small caps, superscripts, ligatures, swashes, etc.), to be + * controlled by so-called 'features'. Handling OpenType features can be + * quite complicated and thus needs a separate library on top of * FreeType. * * The mapping between glyph indices and scripts (in the auto-hinter - * sense, see the @FT_AUTOHINTER_SCRIPT_XXX values) is stored as an - * array with `num_glyphs' elements, as found in the font's @FT_Face - * structure. The `glyph-to-script-map' property returns a pointer to - * this array, which can be modified as needed. Note that the - * modification should happen before the first glyph gets processed by - * the auto-hinter so that the global analysis of the font shapes - * actually uses the modified mapping. + * sense, see the @FT_AUTOHINTER_SCRIPT_XXX values) is stored as an array + * with `num_glyphs` elements, as found in the font's @FT_Face structure. + * The 'glyph-to-script-map' property returns a pointer to this array, + * which can be modified as needed. Note that the modification should + * happen before the first glyph gets processed by the auto-hinter so + * that the global analysis of the font shapes actually uses the modified + * mapping. * * @example: - * The following example code demonstrates how to access it (omitting - * the error handling). + * The following example code demonstrates how to access it (omitting the + * error handling). * - * { + * ``` * FT_Library library; * FT_Face face; * FT_Prop_GlyphToScriptMap prop; @@ -860,7 +857,7 @@ FT_BEGIN_HEADER * // adjust `prop.map' as needed right here * * FT_Load_Glyph( face, ..., FT_LOAD_FORCE_AUTOHINT ); - * } + * ``` * * @since: * 2.4.11 @@ -874,7 +871,7 @@ FT_BEGIN_HEADER * FT_AUTOHINTER_SCRIPT_XXX * * @description: - * *Experimental* *only* + * **Experimental only** * * A list of constants used for the @glyph-to-script-map property to * specify the script submodule the auto-hinter should use for hinting a @@ -885,14 +882,14 @@ FT_BEGIN_HEADER * Don't auto-hint this glyph. * * FT_AUTOHINTER_SCRIPT_LATIN :: - * Apply the latin auto-hinter. For the auto-hinter, `latin' is a - * very broad term, including Cyrillic and Greek also since characters - * from those scripts share the same design constraints. + * Apply the latin auto-hinter. For the auto-hinter, 'latin' is a very + * broad term, including Cyrillic and Greek also since characters from + * those scripts share the same design constraints. * * By default, characters from the following Unicode ranges are * assigned to this submodule. * - * { + * ``` * U+0020 - U+007F // Basic Latin (no control characters) * U+00A0 - U+00FF // Latin-1 Supplement (no control characters) * U+0100 - U+017F // Latin Extended-A @@ -921,7 +918,7 @@ FT_BEGIN_HEADER * U+FB00 - U+FB06 // Alphab. Present. Forms (Latin Ligatures) * U+1D400 - U+1D7FF // Mathematical Alphanumeric Symbols * U+1F100 - U+1F1FF // Enclosed Alphanumeric Supplement - * } + * ``` * * FT_AUTOHINTER_SCRIPT_CJK :: * Apply the CJK auto-hinter, covering Chinese, Japanese, Korean, old @@ -930,7 +927,7 @@ FT_BEGIN_HEADER * By default, characters from the following Unicode ranges are * assigned to this submodule. * - * { + * ``` * U+1100 - U+11FF // Hangul Jamo * U+2E80 - U+2EFF // CJK Radicals Supplement * U+2F00 - U+2FDF // Kangxi Radicals @@ -963,7 +960,7 @@ FT_BEGIN_HEADER * U+2A700 - U+2B73F // CJK Unified Ideographs Extension C * U+2B740 - U+2B81F // CJK Unified Ideographs Extension D * U+2F800 - U+2FA1F // CJK Compatibility Ideographs Supplement - * } + * ``` * * FT_AUTOHINTER_SCRIPT_INDIC :: * Apply the indic auto-hinter, covering all major scripts from the @@ -973,7 +970,7 @@ FT_BEGIN_HEADER * By default, characters from the following Unicode ranges are * assigned to this submodule. * - * { + * ``` * U+0900 - U+0DFF // Indic Range * U+0F00 - U+0FFF // Tibetan * U+1900 - U+194F // Limbu @@ -981,7 +978,7 @@ FT_BEGIN_HEADER * U+A800 - U+A82F // Syloti Nagri * U+ABC0 - U+ABFF // Meetei Mayek * U+11800 - U+118DF // Sharada - * } + * ``` * * Note that currently Indic support is rudimentary only, missing blue * zone support. @@ -1002,7 +999,7 @@ FT_BEGIN_HEADER * FT_Prop_GlyphToScriptMap * * @description: - * *Experimental* *only* + * **Experimental only** * * The data exchange structure for the @glyph-to-script-map property. * @@ -1024,27 +1021,26 @@ FT_BEGIN_HEADER * fallback-script * * @description: - * *Experimental* *only* + * **Experimental only** * - * If no auto-hinter script module can be assigned to a glyph, a - * fallback script gets assigned to it (see also the - * @glyph-to-script-map property). By default, this is - * @FT_AUTOHINTER_SCRIPT_CJK. Using the `fallback-script' property, - * this fallback value can be changed. + * If no auto-hinter script module can be assigned to a glyph, a fallback + * script gets assigned to it (see also the @glyph-to-script-map + * property). By default, this is @FT_AUTOHINTER_SCRIPT_CJK. Using the + * 'fallback-script' property, this fallback value can be changed. * * @note: * This property can be used with @FT_Property_Get also. * * It's important to use the right timing for changing this value: The - * creation of the glyph-to-script map that eventually uses the - * fallback script value gets triggered either by setting or reading a + * creation of the glyph-to-script map that eventually uses the fallback + * script value gets triggered either by setting or reading a * face-specific property like @glyph-to-script-map, or by auto-hinting * any glyph from that face. In particular, if you have already created * an @FT_Face structure but not loaded any glyph (using the * auto-hinter), a change of the fallback script will affect this face. * * @example: - * { + * ``` * FT_Library library; * FT_UInt fallback_script = FT_AUTOHINTER_SCRIPT_NONE; * @@ -1053,7 +1049,7 @@ FT_BEGIN_HEADER * * FT_Property_Set( library, "autofitter", * "fallback-script", &fallback_script ); - * } + * ``` * * @since: * 2.4.11 @@ -1067,33 +1063,33 @@ FT_BEGIN_HEADER * default-script * * @description: - * *Experimental* *only* + * **Experimental only** * * If FreeType gets compiled with FT_CONFIG_OPTION_USE_HARFBUZZ to make - * the HarfBuzz library access OpenType features for getting better - * glyph coverages, this property sets the (auto-fitter) script to be - * used for the default (OpenType) script data of a font's GSUB table. - * Features for the default script are intended for all scripts not - * explicitly handled in GSUB; an example is a `dlig' feature, - * containing the combination of the characters `T', `E', and `L' to - * form a `TEL' ligature. + * the HarfBuzz library access OpenType features for getting better glyph + * coverages, this property sets the (auto-fitter) script to be used for + * the default (OpenType) script data of a font's GSUB table. Features + * for the default script are intended for all scripts not explicitly + * handled in GSUB; an example is a 'dlig' feature, containing the + * combination of the characters 'T', 'E', and 'L' to form a 'TEL' + * ligature. * * By default, this is @FT_AUTOHINTER_SCRIPT_LATIN. Using the - * `default-script' property, this default value can be changed. + * 'default-script' property, this default value can be changed. * * @note: * This property can be used with @FT_Property_Get also. * * It's important to use the right timing for changing this value: The - * creation of the glyph-to-script map that eventually uses the - * default script value gets triggered either by setting or reading a + * creation of the glyph-to-script map that eventually uses the default + * script value gets triggered either by setting or reading a * face-specific property like @glyph-to-script-map, or by auto-hinting * any glyph from that face. In particular, if you have already created * an @FT_Face structure but not loaded any glyph (using the * auto-hinter), a change of the default script will affect this face. * * @example: - * { + * ``` * FT_Library library; * FT_UInt default_script = FT_AUTOHINTER_SCRIPT_NONE; * @@ -1102,7 +1098,7 @@ FT_BEGIN_HEADER * * FT_Property_Set( library, "autofitter", * "default-script", &default_script ); - * } + * ``` * * @since: * 2.5.3 @@ -1116,9 +1112,9 @@ FT_BEGIN_HEADER * increase-x-height * * @description: - * For ppem values in the range 6~<= ppem <= `increase-x-height', round - * up the font's x~height much more often than normally. If the value - * is set to~0, which is the default, this feature is switched off. Use + * For ppem values in the range 6~<= ppem <= 'increase-x-height', round + * up the font's x~height much more often than normally. If the value is + * set to~0, which is the default, this feature is switched off. Use * this property to improve the legibility of small font sizes if * necessary. * @@ -1129,7 +1125,7 @@ FT_BEGIN_HEADER * loading any glyph (using the auto-hinter). * * @example: - * { + * ``` * FT_Library library; * FT_Face face; * FT_Prop_IncreaseXHeight prop; @@ -1144,7 +1140,7 @@ FT_BEGIN_HEADER * * FT_Property_Set( library, "autofitter", * "increase-x-height", &prop ); - * } + * ``` * * @since: * 2.4.11 @@ -1175,40 +1171,40 @@ FT_BEGIN_HEADER * warping * * @description: - * *Experimental* *only* + * **Experimental only** * * If FreeType gets compiled with option AF_CONFIG_OPTION_USE_WARPER to * activate the warp hinting code in the auto-hinter, this property * switches warping on and off. * - * Warping only works in `normal' auto-hinting mode replacing it. - * The idea of the code is to slightly scale and shift a glyph along - * the non-hinted dimension (which is usually the horizontal axis) so - * that as much of its segments are aligned (more or less) to the grid. - * To find out a glyph's optimal scaling and shifting value, various - * parameter combinations are tried and scored. + * Warping only works in 'normal' auto-hinting mode replacing it. The + * idea of the code is to slightly scale and shift a glyph along the + * non-hinted dimension (which is usually the horizontal axis) so that as + * much of its segments are aligned (more or less) to the grid. To find + * out a glyph's optimal scaling and shifting value, various parameter + * combinations are tried and scored. * * By default, warping is off. * * @note: * This property can be used with @FT_Property_Get also. * - * This property can be set via the `FREETYPE_PROPERTIES' environment - * variable (using values 1 and 0 for `on' and `off', respectively). + * This property can be set via the `FREETYPE_PROPERTIES` environment + * variable (using values 1 and 0 for 'on' and 'off', respectively). * * The warping code can also change advance widths. Have a look at the - * `lsb_delta' and `rsb_delta' fields in the @FT_GlyphSlotRec structure + * `lsb_delta` and `rsb_delta` fields in the @FT_GlyphSlotRec structure * for details on improving inter-glyph distances while rendering. * * Since warping is a global property of the auto-hinter it is best to * change its value before rendering any face. Otherwise, you should - * reload all faces that get auto-hinted in `normal' hinting mode. + * reload all faces that get auto-hinted in 'normal' hinting mode. * * @example: * This example shows how to switch on warping (omitting the error * handling). * - * { + * ``` * FT_Library library; * FT_Bool warping = 1; * @@ -1216,7 +1212,7 @@ FT_BEGIN_HEADER * FT_Init_FreeType( &library ); * * FT_Property_Set( library, "autofitter", "warping", &warping ); - * } + * ``` * * @since: * 2.6 diff --git a/include/freetype/fterrdef.h b/include/freetype/fterrdef.h index 3d91ed054..ca0c218c1 100644 --- a/include/freetype/fterrdef.h +++ b/include/freetype/fterrdef.h @@ -28,21 +28,20 @@ * All possible error codes returned by FreeType functions. * * @description: - * The list below is taken verbatim from the file `fterrdef.h' - * (loaded automatically by including `FT_FREETYPE_H'). The first - * argument of the `FT_ERROR_DEF_' macro is the error label; by - * default, the prefix `FT_Err_' gets added so that you get error - * names like `FT_Err_Cannot_Open_Resource'. The second argument is - * the error code, and the last argument an error string, which is not - * used by FreeType. + * The list below is taken verbatim from the file `fterrdef.h` (loaded + * automatically by including `FT_FREETYPE_H`). The first argument of the + * `FT_ERROR_DEF_` macro is the error label; by default, the prefix + * `FT_Err_` gets added so that you get error names like + * `FT_Err_Cannot_Open_Resource`. The second argument is the error code, + * and the last argument an error string, which is not used by FreeType. * - * Within your application you should *only* use error names and - * *never* its numeric values! The latter might (and actually do) + * Within your application you should **only** use error names and + * **never** its numeric values! The latter might (and actually do) * change in forthcoming FreeType versions. * - * Macro `FT_NOERRORDEF_' defines `FT_Err_Ok', which is always zero. - * See the `Error Enumerations' subsection how to automatically - * generate a list of error strings. + * Macro `FT_NOERRORDEF_` defines `FT_Err_Ok`, which is always zero. See + * the 'Error Enumerations' subsection how to automatically generate a + * list of error strings. * */ diff --git a/include/freetype/fterrors.h b/include/freetype/fterrors.h index d602bd51e..4b665cbb2 100644 --- a/include/freetype/fterrors.h +++ b/include/freetype/fterrors.h @@ -28,56 +28,56 @@ * How to handle errors and error strings. * * @description: - * The header file `fterrors.h' (which is automatically included by - * `freetype.h' defines the handling of FreeType's enumeration - * constants. It can also be used to generate error message strings - * with a small macro trick explained below. + * The header file `fterrors.h` (which is automatically included by + * `freetype.h` defines the handling of FreeType's enumeration constants. + * It can also be used to generate error message strings with a small + * macro trick explained below. * - * *Error* *Formats* + * **Error Formats** * * The configuration macro FT_CONFIG_OPTION_USE_MODULE_ERRORS can be - * defined in `ftoption.h' in order to make the higher byte indicate - * the module where the error has happened (this is not compatible - * with standard builds of FreeType~2, however). See the file - * `ftmoderr.h' for more details. + * defined in `ftoption.h` in order to make the higher byte indicate the + * module where the error has happened (this is not compatible with + * standard builds of FreeType~2, however). See the file `ftmoderr.h` for + * more details. * - * *Error* *Message* *Strings* + * **Error Message Strings** * * Error definitions are set up with special macros that allow client - * applications to build a table of error message strings. The - * strings are not included in a normal build of FreeType~2 to save - * space (most client applications do not use them). + * applications to build a table of error message strings. The strings + * are not included in a normal build of FreeType~2 to save space (most + * client applications do not use them). * - * To do so, you have to define the following macros before including - * this file. + * To do so, you have to define the following macros before including this + * file. * - * { + * ``` * FT_ERROR_START_LIST - * } + * ``` * - * This macro is called before anything else to define the start of - * the error list. It is followed by several FT_ERROR_DEF calls. + * This macro is called before anything else to define the start of the + * error list. It is followed by several FT_ERROR_DEF calls. * - * { + * ``` * FT_ERROR_DEF( e, v, s ) - * } + * ``` * - * This macro is called to define one single error. `e' is the error - * code identifier (e.g., `Invalid_Argument'), `v' is the error's - * numerical value, and `s' is the corresponding error string. + * This macro is called to define one single error. 'e' is the error code + * identifier (e.g., `Invalid_Argument`), 'v' is the error's numerical + * value, and 's' is the corresponding error string. * - * { + * ``` * FT_ERROR_END_LIST - * } + * ``` * * This macro ends the list. * - * Additionally, you have to undefine `FTERRORS_H_' before #including - * this file. + * Additionally, you have to undefine `FTERRORS_H_` before #including this + * file. * * Here is a simple example. * - * { + * ``` * #undef FTERRORS_H_ * #define FT_ERRORDEF( e, v, s ) { e, s }, * #define FT_ERROR_START_LIST { @@ -90,10 +90,10 @@ * } ft_errors[] = * * #include FT_ERRORS_H - * } + * ``` * - * Note that `FT_Err_Ok' is _not_ defined with `FT_ERRORDEF' but with - * `FT_NOERRORDEF'; it is always zero. + * Note that `FT_Err_Ok` is _not_ defined with `FT_ERRORDEF` but with + * `FT_NOERRORDEF`; it is always zero. * */ diff --git a/include/freetype/ftfntfmt.h b/include/freetype/ftfntfmt.h index 3f3d410ee..a0ea3b7fe 100644 --- a/include/freetype/ftfntfmt.h +++ b/include/freetype/ftfntfmt.h @@ -44,10 +44,10 @@ FT_BEGIN_HEADER * Getting the font format. * * @description: - * The single function in this section can be used to get the font - * format. Note that this information is not needed normally; - * however, there are special cases (like in PDF devices) where it is - * important to differentiate, in spite of FreeType's uniform API. + * The single function in this section can be used to get the font format. + * Note that this information is not needed normally; however, there are + * special cases (like in PDF devices) where it is important to + * differentiate, in spite of FreeType's uniform API. * */ @@ -58,9 +58,9 @@ FT_BEGIN_HEADER * FT_Get_Font_Format * * @description: - * Return a string describing the format of a given face. Possible - * values are `TrueType', `Type~1', `BDF', `PCF', `Type~42', - * `CID~Type~1', `CFF', `PFR', and `Windows~FNT'. + * Return a string describing the format of a given face. Possible values + * are 'TrueType', 'Type~1', 'BDF', 'PCF', 'Type~42', 'CID~Type~1', 'CFF', + * 'PFR', and 'Windows~FNT'. * * The return value is suitable to be used as an X11 FONT_PROPERTY. * @@ -72,8 +72,7 @@ FT_BEGIN_HEADER * Font format string. NULL in case of error. * * @note: - * A deprecated name for the same function is - * `FT_Get_X11_Font_Format'. + * A deprecated name for the same function is `FT_Get_X11_Font_Format`. */ FT_EXPORT( const char* ) FT_Get_Font_Format( FT_Face face ); diff --git a/include/freetype/ftgasp.h b/include/freetype/ftgasp.h index 605ff28c8..33d6bd049 100644 --- a/include/freetype/ftgasp.h +++ b/include/freetype/ftgasp.h @@ -2,7 +2,7 @@ * * ftgasp.h * - * Access of TrueType's `gasp' table (specification). + * Access of TrueType's 'gasp' table (specification). * * Copyright 2007-2018 by * David Turner, Robert Wilhelm, and Werner Lemberg. @@ -41,13 +41,13 @@ FT_BEGIN_HEADER * Gasp Table * * @abstract: - * Retrieving TrueType `gasp' table entries. + * Retrieving TrueType 'gasp' table entries. * * @description: * The function @FT_Get_Gasp can be used to query a TrueType or OpenType - * font for specific entries in its `gasp' table, if any. This is - * mainly useful when implementing native TrueType hinting with the - * bytecode interpreter to duplicate the Windows text rendering results. + * font for specific entries in its 'gasp' table, if any. This is mainly + * useful when implementing native TrueType hinting with the bytecode + * interpreter to duplicate the Windows text rendering results. */ /************************************************************************* @@ -66,7 +66,7 @@ FT_BEGIN_HEADER * * FT_GASP_DO_GRIDFIT :: * Grid-fitting and hinting should be performed at the specified ppem. - * This *really* means TrueType bytecode interpretation. If this bit + * This **really** means TrueType bytecode interpretation. If this bit * is not set, no hinting gets applied. * * FT_GASP_DO_GRAY :: @@ -80,13 +80,13 @@ FT_BEGIN_HEADER * Grid-fitting must be used with ClearType's symmetric smoothing. * * @note: - * The bit-flags `FT_GASP_DO_GRIDFIT' and `FT_GASP_DO_GRAY' are to be + * The bit-flags `FT_GASP_DO_GRIDFIT` and `FT_GASP_DO_GRAY` are to be * used for standard font rasterization only. Independently of that, - * `FT_GASP_SYMMETRIC_SMOOTHING' and `FT_GASP_SYMMETRIC_GRIDFIT' are to - * be used if ClearType is enabled (and `FT_GASP_DO_GRIDFIT' and - * `FT_GASP_DO_GRAY' are consequently ignored). + * `FT_GASP_SYMMETRIC_SMOOTHING` and `FT_GASP_SYMMETRIC_GRIDFIT` are to + * be used if ClearType is enabled (and `FT_GASP_DO_GRIDFIT` and + * `FT_GASP_DO_GRAY` are consequently ignored). * - * `ClearType' is Microsoft's implementation of LCD rendering, partly + * 'ClearType' is Microsoft's implementation of LCD rendering, partly * protected by patents. * * @since: @@ -106,8 +106,8 @@ FT_BEGIN_HEADER * * @description: * For a TrueType or OpenType font file, return the rasterizer behaviour - * flags from the font's `gasp' table corresponding to a given - * character pixel size. + * flags from the font's 'gasp' table corresponding to a given character + * pixel size. * * @input: * face :: @@ -118,12 +118,12 @@ FT_BEGIN_HEADER * * @return: * Bit flags (see @FT_GASP_XXX), or @FT_GASP_NO_TABLE if there is no - * `gasp' table in the face. + * 'gasp' table in the face. * * @note: * If you want to use the MM functionality of OpenType variation fonts * (i.e., using @FT_Set_Var_Design_Coordinates and friends), call this - * function *after* setting an instance since the return values can + * function **after** setting an instance since the return values can * change. * * @since: diff --git a/include/freetype/ftglyph.h b/include/freetype/ftglyph.h index be17a7764..d570b205c 100644 --- a/include/freetype/ftglyph.h +++ b/include/freetype/ftglyph.h @@ -18,13 +18,13 @@ /************************************************************************** * - * This file contains the definition of several convenience functions - * that can be used by client applications to easily retrieve glyph - * bitmaps and outlines from a given face. + * This file contains the definition of several convenience functions that + * can be used by client applications to easily retrieve glyph bitmaps and + * outlines from a given face. * - * These functions should be optional if you are writing a font server - * or text layout engine on top of FreeType. However, they are pretty - * handy for many other simple uses of the library. + * These functions should be optional if you are writing a font server or + * text layout engine on top of FreeType. However, they are pretty handy + * for many other simple uses of the library. * */ @@ -58,9 +58,9 @@ FT_BEGIN_HEADER * Generic interface to manage individual glyph data. * * @description: - * This section contains definitions used to manage glyph data - * through generic FT_Glyph objects. Each of them can contain a - * bitmap, a vector outline, or even images in other formats. + * This section contains definitions used to manage glyph data through + * generic FT_Glyph objects. Each of them can contain a bitmap, a vector + * outline, or even images in other formats. * */ @@ -76,8 +76,8 @@ FT_BEGIN_HEADER * * @description: * Handle to an object used to model generic glyph images. It is a - * pointer to the @FT_GlyphRec structure and can contain a glyph - * bitmap or pointer. + * pointer to the @FT_GlyphRec structure and can contain a glyph bitmap + * or pointer. * * @note: * Glyph objects are not owned by the library. You must thus release @@ -93,8 +93,8 @@ FT_BEGIN_HEADER * FT_GlyphRec * * @description: - * The root glyph structure contains a given glyph image plus its - * advance width in 16.16 fixed-point format. + * The root glyph structure contains a given glyph image plus its advance + * width in 16.16 fixed-point format. * * @fields: * library :: @@ -125,8 +125,8 @@ FT_BEGIN_HEADER * FT_BitmapGlyph * * @description: - * A handle to an object used to model a bitmap glyph image. This is - * a sub-class of @FT_Glyph, and a pointer to @FT_BitmapGlyphRec. + * A handle to an object used to model a bitmap glyph image. This is a + * sub-class of @FT_Glyph, and a pointer to @FT_BitmapGlyphRec. */ typedef struct FT_BitmapGlyphRec_* FT_BitmapGlyph; @@ -138,32 +138,31 @@ FT_BEGIN_HEADER * * @description: * A structure used for bitmap glyph images. This really is a - * `sub-class' of @FT_GlyphRec. + * 'sub-class' of @FT_GlyphRec. * * @fields: * root :: * The root @FT_Glyph fields. * * left :: - * The left-side bearing, i.e., the horizontal distance - * from the current pen position to the left border of the - * glyph bitmap. + * The left-side bearing, i.e., the horizontal distance from the + * current pen position to the left border of the glyph bitmap. * * top :: - * The top-side bearing, i.e., the vertical distance from - * the current pen position to the top border of the glyph - * bitmap. This distance is positive for upwards~y! + * The top-side bearing, i.e., the vertical distance from the current + * pen position to the top border of the glyph bitmap. This distance + * is positive for upwards~y! * * bitmap :: * A descriptor for the bitmap. * * @note: * You can typecast an @FT_Glyph to @FT_BitmapGlyph if you have - * `glyph->format == FT_GLYPH_FORMAT_BITMAP'. This lets you access - * the bitmap's contents easily. + * `glyph->format == FT_GLYPH_FORMAT_BITMAP`. This lets you access the + * bitmap's contents easily. * - * The corresponding pixel buffer is always owned by @FT_BitmapGlyph - * and is thus created and destroyed with it. + * The corresponding pixel buffer is always owned by @FT_BitmapGlyph and + * is thus created and destroyed with it. */ typedef struct FT_BitmapGlyphRec_ { @@ -181,8 +180,8 @@ FT_BEGIN_HEADER * FT_OutlineGlyph * * @description: - * A handle to an object used to model an outline glyph image. This - * is a sub-class of @FT_Glyph, and a pointer to @FT_OutlineGlyphRec. + * A handle to an object used to model an outline glyph image. This is a + * sub-class of @FT_Glyph, and a pointer to @FT_OutlineGlyphRec. */ typedef struct FT_OutlineGlyphRec_* FT_OutlineGlyph; @@ -193,8 +192,8 @@ FT_BEGIN_HEADER * FT_OutlineGlyphRec * * @description: - * A structure used for outline (vectorial) glyph images. This - * really is a `sub-class' of @FT_GlyphRec. + * A structure used for outline (vectorial) glyph images. This really is + * a 'sub-class' of @FT_GlyphRec. * * @fields: * root :: @@ -205,15 +204,15 @@ FT_BEGIN_HEADER * * @note: * You can typecast an @FT_Glyph to @FT_OutlineGlyph if you have - * `glyph->format == FT_GLYPH_FORMAT_OUTLINE'. This lets you access - * the outline's content easily. + * `glyph->format == FT_GLYPH_FORMAT_OUTLINE`. This lets you access the + * outline's content easily. * * As the outline is extracted from a glyph slot, its coordinates are - * expressed normally in 26.6 pixels, unless the flag - * @FT_LOAD_NO_SCALE was used in @FT_Load_Glyph() or @FT_Load_Char(). + * expressed normally in 26.6 pixels, unless the flag @FT_LOAD_NO_SCALE + * was used in @FT_Load_Glyph() or @FT_Load_Char(). * - * The outline's tables are always owned by the object and are - * destroyed with it. + * The outline's tables are always owned by the object and are destroyed + * with it. */ typedef struct FT_OutlineGlyphRec_ { @@ -261,8 +260,8 @@ FT_BEGIN_HEADER * FT_Get_Glyph * * @description: - * A function used to extract a glyph image from a slot. Note that - * the created @FT_Glyph object must be released with @FT_Done_Glyph. + * A function used to extract a glyph image from a slot. Note that the + * created @FT_Glyph object must be released with @FT_Done_Glyph. * * @input: * slot :: @@ -276,10 +275,9 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * Because `*aglyph->advance.x' and `*aglyph->advance.y' are 16.16 - * fixed-point numbers, `slot->advance.x' and `slot->advance.y' - * (which are in 26.6 fixed-point format) must be in the range - * ]-32768;32768[. + * Because `*aglyph->advance.x` and `*aglyph->advance.y` are 16.16 + * fixed-point numbers, `slot->advance.x` and `slot->advance.y` (which + * are in 26.6 fixed-point format) must be in the range ]-32768;32768[. */ FT_EXPORT( FT_Error ) FT_Get_Glyph( FT_GlyphSlot slot, @@ -301,8 +299,7 @@ FT_BEGIN_HEADER * * @output: * target :: - * A handle to the target glyph object. 0~in case of - * error. + * A handle to the target glyph object. 0~in case of error. * * @return: * FreeType error code. 0~means success. @@ -329,15 +326,15 @@ FT_BEGIN_HEADER * A pointer to a 2x2 matrix to apply. * * delta :: - * A pointer to a 2d vector to apply. Coordinates are - * expressed in 1/64th of a pixel. + * A pointer to a 2d vector to apply. Coordinates are expressed in + * 1/64th of a pixel. * * @return: * FreeType error code (if not 0, the glyph format is not scalable). * * @note: - * The 2x2 transformation matrix is also applied to the glyph's - * advance vector. + * The 2x2 transformation matrix is also applied to the glyph's advance + * vector. */ FT_EXPORT( FT_Error ) FT_Glyph_Transform( FT_Glyph glyph, @@ -395,71 +392,71 @@ FT_BEGIN_HEADER * FT_Glyph_Get_CBox * * @description: - * Return a glyph's `control box'. The control box encloses all the + * Return a glyph's 'control box'. The control box encloses all the * outline's points, including Bezier control points. Though it * coincides with the exact bounding box for most glyphs, it can be - * slightly larger in some situations (like when rotating an outline - * that contains Bezier outside arcs). + * slightly larger in some situations (like when rotating an outline that + * contains Bezier outside arcs). * - * Computing the control box is very fast, while getting the bounding - * box can take much more time as it needs to walk over all segments - * and arcs in the outline. To get the latter, you can use the - * `ftbbox' component, which is dedicated to this single task. + * Computing the control box is very fast, while getting the bounding box + * can take much more time as it needs to walk over all segments and arcs + * in the outline. To get the latter, you can use the 'ftbbox' + * component, which is dedicated to this single task. * * @input: * glyph :: * A handle to the source glyph object. * * mode :: - * The mode that indicates how to interpret the returned - * bounding box values. + * The mode that indicates how to interpret the returned bounding box + * values. * * @output: * acbox :: - * The glyph coordinate bounding box. Coordinates are - * expressed in 1/64th of pixels if it is grid-fitted. + * The glyph coordinate bounding box. Coordinates are expressed in + * 1/64th of pixels if it is grid-fitted. * * @note: * Coordinates are relative to the glyph origin, using the y~upwards * convention. * - * If the glyph has been loaded with @FT_LOAD_NO_SCALE, `bbox_mode' - * must be set to @FT_GLYPH_BBOX_UNSCALED to get unscaled font - * units in 26.6 pixel format. The value @FT_GLYPH_BBOX_SUBPIXELS - * is another name for this constant. + * If the glyph has been loaded with @FT_LOAD_NO_SCALE, `bbox_mode` must + * be set to @FT_GLYPH_BBOX_UNSCALED to get unscaled font units in 26.6 + * pixel format. The value @FT_GLYPH_BBOX_SUBPIXELS is another name for + * this constant. * * If the font is tricky and the glyph has been loaded with * @FT_LOAD_NO_SCALE, the resulting CBox is meaningless. To get - * reasonable values for the CBox it is necessary to load the glyph - * at a large ppem value (so that the hinting instructions can - * properly shift and scale the subglyphs), then extracting the CBox, - * which can be eventually converted back to font units. + * reasonable values for the CBox it is necessary to load the glyph at a + * large ppem value (so that the hinting instructions can properly shift + * and scale the subglyphs), then extracting the CBox, which can be + * eventually converted back to font units. * - * Note that the maximum coordinates are exclusive, which means that - * one can compute the width and height of the glyph image (be it in - * integer or 26.6 pixels) as: + * Note that the maximum coordinates are exclusive, which means that one + * can compute the width and height of the glyph image (be it in integer + * or 26.6 pixels) as: * - * { + * ``` * width = bbox.xMax - bbox.xMin; * height = bbox.yMax - bbox.yMin; - * } + * ``` * - * Note also that for 26.6 coordinates, if `bbox_mode' is set to + * Note also that for 26.6 coordinates, if `bbox_mode` is set to * @FT_GLYPH_BBOX_GRIDFIT, the coordinates will also be grid-fitted, * which corresponds to: * - * { + * ``` * bbox.xMin = FLOOR(bbox.xMin); * bbox.yMin = FLOOR(bbox.yMin); * bbox.xMax = CEILING(bbox.xMax); * bbox.yMax = CEILING(bbox.yMax); - * } + * ``` * - * To get the bbox in pixel coordinates, set `bbox_mode' to + * To get the bbox in pixel coordinates, set `bbox_mode` to * @FT_GLYPH_BBOX_TRUNCATE. * - * To get the bbox in grid-fitted pixel coordinates, set `bbox_mode' - * to @FT_GLYPH_BBOX_PIXELS. + * To get the bbox in grid-fitted pixel coordinates, set `bbox_mode` to + * @FT_GLYPH_BBOX_PIXELS. */ FT_EXPORT( void ) FT_Glyph_Get_CBox( FT_Glyph glyph, @@ -481,19 +478,16 @@ FT_BEGIN_HEADER * * @input: * render_mode :: - * An enumeration that describes how the data is - * rendered. + * An enumeration that describes how the data is rendered. * * origin :: - * A pointer to a vector used to translate the glyph - * image before rendering. Can be~0 (if no - * translation). The origin is expressed in - * 26.6 pixels. + * A pointer to a vector used to translate the glyph image before + * rendering. Can be~0 (if no translation). The origin is expressed + * in 26.6 pixels. * * destroy :: - * A boolean that indicates that the original glyph - * image should be destroyed by this function. It is - * never destroyed in case of error. + * A boolean that indicates that the original glyph image should be + * destroyed by this function. It is never destroyed in case of error. * * @return: * FreeType error code. 0~means success. @@ -501,14 +495,14 @@ FT_BEGIN_HEADER * @note: * This function does nothing if the glyph format isn't scalable. * - * The glyph image is translated with the `origin' vector before + * The glyph image is translated with the 'origin' vector before * rendering. * - * The first parameter is a pointer to an @FT_Glyph handle, that will - * be _replaced_ by this function (with newly allocated data). - * Typically, you would use (omitting error handling): + * The first parameter is a pointer to an @FT_Glyph handle, that will be + * _replaced_ by this function (with newly allocated data). Typically, + * you would use (omitting error handling): * - * { + * ``` * FT_Glyph glyph; * FT_BitmapGlyph glyph_bitmap; * @@ -536,11 +530,11 @@ FT_BEGIN_HEADER * * // discard glyph image (bitmap or not) * FT_Done_Glyph( glyph ); - * } + * ``` * * Here another example, again without error handling: * - * { + * ``` * FT_Glyph glyphs[MAX_GLYPHS] * * @@ -572,7 +566,7 @@ FT_BEGIN_HEADER * * for ( idx = 0; i < MAX_GLYPHS; i++ ) * FT_Done_Glyph( glyphs[idx] ); - * } + * ``` */ FT_EXPORT( FT_Error ) FT_Glyph_To_Bitmap( FT_Glyph* the_glyph, @@ -615,18 +609,18 @@ FT_BEGIN_HEADER * FT_Matrix_Multiply * * @description: - * Perform the matrix operation `b = a*b'. + * Perform the matrix operation 'b = a*b'. * * @input: * a :: - * A pointer to matrix `a'. + * A pointer to matrix 'a'. * * @inout: * b :: - * A pointer to matrix `b'. + * A pointer to matrix 'b'. * * @note: - * The result is undefined if either `a' or `b' is zero. + * The result is undefined if either 'a' or 'b' is zero. * * Since the function uses wrap-around arithmetic, results become * meaningless if the arguments are very large. @@ -646,8 +640,7 @@ FT_BEGIN_HEADER * * @inout: * matrix :: - * A pointer to the target matrix. Remains untouched in - * case of error. + * A pointer to the target matrix. Remains untouched in case of error. * * @return: * FreeType error code. 0~means success. diff --git a/include/freetype/ftgxval.h b/include/freetype/ftgxval.h index 532b48434..5a630edf1 100644 --- a/include/freetype/ftgxval.h +++ b/include/freetype/ftgxval.h @@ -53,9 +53,9 @@ FT_BEGIN_HEADER * An API to validate TrueTypeGX/AAT tables. * * @description: - * This section contains the declaration of functions to validate - * some TrueTypeGX tables (feat, mort, morx, bsln, just, kern, opbd, - * trak, prop, lcar). + * This section contains the declaration of functions to validate some + * TrueTypeGX tables (feat, mort, morx, bsln, just, kern, opbd, trak, + * prop, lcar). * * @order: * FT_TrueTypeGX_Validate @@ -99,7 +99,7 @@ FT_BEGIN_HEADER * * @description: * The number of tables checked in this module. Use it as a parameter - * for the `table-length' argument of function @FT_TrueTypeGX_Validate. + * for the 'table-length' argument of function @FT_TrueTypeGX_Validate. */ #define FT_VALIDATE_GX_LENGTH ( FT_VALIDATE_GX_LAST_INDEX + 1 ) @@ -123,34 +123,34 @@ FT_BEGIN_HEADER * * @values: * FT_VALIDATE_feat :: - * Validate `feat' table. + * Validate 'feat' table. * * FT_VALIDATE_mort :: - * Validate `mort' table. + * Validate 'mort' table. * * FT_VALIDATE_morx :: - * Validate `morx' table. + * Validate 'morx' table. * * FT_VALIDATE_bsln :: - * Validate `bsln' table. + * Validate 'bsln' table. * * FT_VALIDATE_just :: - * Validate `just' table. + * Validate 'just' table. * * FT_VALIDATE_kern :: - * Validate `kern' table. + * Validate 'kern' table. * * FT_VALIDATE_opbd :: - * Validate `opbd' table. + * Validate 'opbd' table. * * FT_VALIDATE_trak :: - * Validate `trak' table. + * Validate 'trak' table. * * FT_VALIDATE_prop :: - * Validate `prop' table. + * Validate 'prop' table. * * FT_VALIDATE_lcar :: - * Validate `lcar' table. + * Validate 'lcar' table. * * FT_VALIDATE_GX :: * Validate all TrueTypeGX tables (feat, mort, morx, bsln, just, kern, @@ -189,8 +189,8 @@ FT_BEGIN_HEADER * @description: * Validate various TrueTypeGX tables to assure that all offsets and * indices are valid. The idea is that a higher-level library that - * actually does the text layout can access those tables without - * error checking (which can be quite time consuming). + * actually does the text layout can access those tables without error + * checking (which can be quite time consuming). * * @input: * face :: @@ -201,13 +201,13 @@ 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: * tables :: - * The array where all validated sfnt tables are stored. - * The array itself must be allocated by a client. + * The array where all validated sfnt tables are stored. The array + * itself must be allocated by a client. * * @return: * FreeType error code. 0~means success. @@ -217,7 +217,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. @@ -242,8 +242,7 @@ FT_BEGIN_HEADER * A handle to the input face. * * table :: - * The pointer to the buffer allocated by - * @FT_TrueTypeGX_Validate. + * The pointer to the buffer allocated by @FT_TrueTypeGX_Validate. * * @note: * This function must be used to free the buffer allocated by @@ -260,20 +259,19 @@ FT_BEGIN_HEADER * FT_VALIDATE_CKERNXXX * * @description: - * A list of bit-field constants used with @FT_ClassicKern_Validate - * to indicate the classic kern dialect or dialects. If the selected - * type doesn't fit, @FT_ClassicKern_Validate regards the table as - * invalid. + * A list of bit-field constants used with @FT_ClassicKern_Validate to + * indicate the classic kern dialect or dialects. If the selected type + * doesn't fit, @FT_ClassicKern_Validate regards the table as invalid. * * @values: * FT_VALIDATE_MS :: - * Handle the `kern' table as a classic Microsoft kern table. + * Handle the 'kern' table as a classic Microsoft kern table. * * FT_VALIDATE_APPLE :: - * Handle the `kern' table as a classic Apple kern table. + * Handle the 'kern' table as a classic Apple kern table. * * FT_VALIDATE_CKERN :: - * Handle the `kern' as either classic Apple or Microsoft kern table. + * Handle the 'kern' as either classic Apple or Microsoft kern table. */ #define FT_VALIDATE_MS ( FT_VALIDATE_GX_START << 0 ) #define FT_VALIDATE_APPLE ( FT_VALIDATE_GX_START << 1 ) @@ -287,12 +285,12 @@ FT_BEGIN_HEADER * FT_ClassicKern_Validate * * @description: - * Validate classic (16-bit format) kern table to assure that the offsets - * and indices are valid. The idea is that a higher-level library that - * actually does the text layout can access those tables without error - * checking (which can be quite time consuming). + * Validate classic (16-bit format) kern table to assure that the + * offsets and indices are valid. The idea is that a higher-level + * library that actually does the text layout can access those tables + * without error checking (which can be quite time consuming). * - * The `kern' table validator in @FT_TrueTypeGX_Validate deals with both + * The 'kern' table validator in @FT_TrueTypeGX_Validate deals with both * the new 32-bit format and the classic 16-bit format, while * FT_ClassicKern_Validate only supports the classic 16-bit format. * @@ -313,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 ) diff --git a/include/freetype/ftgzip.h b/include/freetype/ftgzip.h index 378a365c5..f75326183 100644 --- a/include/freetype/ftgzip.h +++ b/include/freetype/ftgzip.h @@ -54,9 +54,9 @@ FT_BEGIN_HEADER * FT_Stream_OpenGzip * * @description: - * Open a new stream to parse gzip-compressed font files. This is - * mainly used to support the compressed `*.pcf.gz' fonts that come - * with XFree86. + * Open a new stream to parse gzip-compressed font files. This is mainly + * used to support the compressed `*.pcf.gz` fonts that come with + * XFree86. * * @input: * stream :: @@ -71,9 +71,9 @@ 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 - * objects will be released to the heap. + * 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 * process each time seeking backwards is needed within the stream. @@ -81,10 +81,10 @@ FT_BEGIN_HEADER * In certain builds of the library, gzip compression recognition is * automatically handled when calling @FT_New_Face or @FT_Open_Face. * This means that if no font driver is capable of handling the raw - * compressed file, the library will try to open a gzipped stream from - * it and re-open the face with it. + * 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_Feature' if your build + * This function may return `FT_Err_Unimplemented_Feature` if your build * of FreeType was not compiled with zlib support. */ FT_EXPORT( FT_Error ) @@ -99,7 +99,7 @@ FT_BEGIN_HEADER * * @description: * Decompress a zipped input buffer into an output buffer. This function - * is modeled after zlib's `uncompress' function. + * is modeled after zlib's 'uncompress' function. * * @input: * memory :: @@ -120,14 +120,14 @@ FT_BEGIN_HEADER * Before calling the function, this is the total size of the output * buffer, which must be large enough to hold the entire uncompressed * data (so the size of the uncompressed data must be known in - * advance). After calling the function, `output_len' is the size of - * the used data in `output'. + * advance). After calling the function, `output_len` is the size of + * the used data in 'output'. * * @return: * FreeType error code. 0~means success. * * @note: - * This function may return `FT_Err_Unimplemented_Feature' if your build + * This function may return `FT_Err_Unimplemented_Feature` if your build * of FreeType was not compiled with zlib support. * * @since: diff --git a/include/freetype/ftimage.h b/include/freetype/ftimage.h index 12db4b0b3..497359924 100644 --- a/include/freetype/ftimage.h +++ b/include/freetype/ftimage.h @@ -18,7 +18,7 @@ /************************************************************************** * - * Note: A `raster' is simply a scan-line converter, used to render + * Note: A 'raster' is simply a scan-line converter, used to render * FT_Outlines into FT_Bitmaps. * */ @@ -51,9 +51,9 @@ FT_BEGIN_HEADER * FT_Pos * * @description: - * The type FT_Pos is used to store vectorial coordinates. Depending - * on the context, these can represent distances in integer font - * units, or 16.16, or 26.6 fixed-point pixel coordinates. + * The type FT_Pos is used to store vectorial coordinates. Depending on + * the context, these can represent distances in integer font units, or + * 16.16, or 26.6 fixed-point pixel coordinates. */ typedef signed long FT_Pos; @@ -64,8 +64,8 @@ FT_BEGIN_HEADER * FT_Vector * * @description: - * A simple structure used to store a 2D vector; coordinates are of - * the FT_Pos type. + * A simple structure used to store a 2D vector; coordinates are of the + * FT_Pos type. * * @fields: * x :: @@ -88,8 +88,7 @@ FT_BEGIN_HEADER * * @description: * A structure used to hold an outline's bounding box, i.e., the - * coordinates of its extrema in the horizontal and vertical - * directions. + * coordinates of its extrema in the horizontal and vertical directions. * * @fields: * xMin :: @@ -105,18 +104,17 @@ FT_BEGIN_HEADER * The vertical maximum (top-most). * * @note: - * The bounding box is specified with the coordinates of the lower - * left and the upper right corner. In PostScript, those values are - * often called (llx,lly) and (urx,ury), respectively. - * - * If `yMin' is negative, this value gives the glyph's descender. - * Otherwise, the glyph doesn't descend below the baseline. - * Similarly, if `ymax' is positive, this value gives the glyph's - * ascender. - * - * `xMin' gives the horizontal distance from the glyph's origin to - * the left edge of the glyph's bounding box. If `xMin' is negative, - * the glyph extends to the left of the origin. + * The bounding box is specified with the coordinates of the lower left + * and the upper right corner. In PostScript, those values are often + * called (llx,lly) and (urx,ury), respectively. + * + * If `yMin` is negative, this value gives the glyph's descender. + * Otherwise, the glyph doesn't descend below the baseline. Similarly, + * if 'ymax' is positive, this value gives the glyph's ascender. + * + * `xMin` gives the horizontal distance from the glyph's origin to the + * left edge of the glyph's bounding box. If `xMin` is negative, the + * glyph extends to the left of the origin. */ typedef struct FT_BBox_ { @@ -132,56 +130,53 @@ FT_BEGIN_HEADER * FT_Pixel_Mode * * @description: - * An enumeration type used to describe the format of pixels in a - * given bitmap. Note that additional formats may be added in the - * future. + * An enumeration type used to describe the format of pixels in a given + * bitmap. Note that additional formats may be added in the future. * * @values: * FT_PIXEL_MODE_NONE :: * Value~0 is reserved. * * FT_PIXEL_MODE_MONO :: - * A monochrome bitmap, using 1~bit per pixel. Note that pixels - * are stored in most-significant order (MSB), which means that - * the left-most pixel in a byte has value 128. + * A monochrome bitmap, using 1~bit per pixel. Note that pixels are + * stored in most-significant order (MSB), which means that the + * left-most pixel in a byte has value 128. * * FT_PIXEL_MODE_GRAY :: * An 8-bit bitmap, generally used to represent anti-aliased glyph - * images. Each pixel is stored in one byte. Note that the number - * of `gray' levels is stored in the `num_grays' field of the - * @FT_Bitmap structure (it generally is 256). + * images. Each pixel is stored in one byte. Note that the number of + * 'gray' levels is stored in the `num_grays` field of the @FT_Bitmap + * structure (it generally is 256). * * FT_PIXEL_MODE_GRAY2 :: - * A 2-bit per pixel bitmap, used to represent embedded - * anti-aliased bitmaps in font files according to the OpenType - * specification. We haven't found a single font using this - * format, however. + * A 2-bit per pixel bitmap, used to represent embedded anti-aliased + * bitmaps in font files according to the OpenType specification. We + * haven't found a single font using this format, however. * * FT_PIXEL_MODE_GRAY4 :: - * A 4-bit per pixel bitmap, representing embedded anti-aliased - * bitmaps in font files according to the OpenType specification. - * We haven't found a single font using this format, however. + * A 4-bit per pixel bitmap, representing embedded anti-aliased bitmaps + * in font files according to the OpenType specification. We haven't + * found a single font using this format, however. * * FT_PIXEL_MODE_LCD :: - * An 8-bit bitmap, representing RGB or BGR decimated glyph images - * used for display on LCD displays; the bitmap is three times - * wider than the original glyph image. See also - * @FT_RENDER_MODE_LCD. + * An 8-bit bitmap, representing RGB or BGR decimated glyph images used + * for display on LCD displays; the bitmap is three times wider than + * the original glyph image. See also @FT_RENDER_MODE_LCD. * * FT_PIXEL_MODE_LCD_V :: - * An 8-bit bitmap, representing RGB or BGR decimated glyph images - * used for display on rotated LCD displays; the bitmap is three - * times taller than the original glyph image. See also + * An 8-bit bitmap, representing RGB or BGR decimated glyph images used + * for display on rotated LCD displays; the bitmap is three times + * taller than the original glyph image. See also * @FT_RENDER_MODE_LCD_V. * * FT_PIXEL_MODE_BGRA :: * [Since 2.5] An image with four 8-bit channels per pixel, - * representing a color image (such as emoticons) with alpha - * channel. For each pixel, the format is BGRA, which means, the - * blue channel comes first in memory. The color channels are - * pre-multiplied and in the sRGB colorspace. For example, full - * red at half-translucent opacity will be represented as - * `00,00,80,80', not `00,00,FF,80'. See also @FT_LOAD_COLOR. + * representing a color image (such as emoticons) with alpha channel. + * For each pixel, the format is BGRA, which means, the blue channel + * comes first in memory. The color channels are pre-multiplied and in + * the sRGB colorspace. For example, full red at half-translucent + * opacity will be represented as '00,00,80,80', not '00,00,FF,80'. + * See also @FT_LOAD_COLOR. */ typedef enum FT_Pixel_Mode_ { @@ -214,9 +209,9 @@ FT_BEGIN_HEADER * FT_Bitmap * * @description: - * A structure used to describe a bitmap or pixmap to the raster. - * Note that we now manage pixmaps of various depths through the - * `pixel_mode' field. + * A structure used to describe a bitmap or pixmap to the raster. Note + * that we now manage pixmaps of various depths through the `pixel_mode` + * field. * * @fields: * rows :: @@ -226,51 +221,42 @@ FT_BEGIN_HEADER * The number of pixels in bitmap row. * * pitch :: - * The pitch's absolute value is the number of bytes - * taken by one bitmap row, including padding. - * However, the pitch is positive when the bitmap has - * a `down' flow, and negative when it has an `up' - * flow. In all cases, the pitch is an offset to add - * to a bitmap pointer in order to go down one row. - * - * Note that `padding' means the alignment of a - * bitmap to a byte border, and FreeType functions - * normally align to the smallest possible integer - * value. - * - * For the B/W rasterizer, `pitch' is always an even - * number. - * - * To change the pitch of a bitmap (say, to make it a - * multiple of 4), use @FT_Bitmap_Convert. - * Alternatively, you might use callback functions to - * directly render to the application's surface; see - * the file `example2.cpp' in the tutorial for a - * demonstration. + * The pitch's absolute value is the number of bytes taken by one + * bitmap row, including padding. However, the pitch is positive when + * the bitmap has a 'down' flow, and negative when it has an 'up' flow. + * In all cases, the pitch is an offset to add to a bitmap pointer in + * order to go down one row. + * + * Note that 'padding' means the alignment of a bitmap to a byte + * border, and FreeType functions normally align to the smallest + * possible integer value. + * + * For the B/W rasterizer, 'pitch' is always an even number. + * + * To change the pitch of a bitmap (say, to make it a multiple of 4), + * use @FT_Bitmap_Convert. Alternatively, you might use callback + * functions to directly render to the application's surface; see the + * file `example2.cpp` in the tutorial for a demonstration. * * buffer :: - * A typeless pointer to the bitmap buffer. This - * value should be aligned on 32-bit boundaries in - * most cases. + * A typeless pointer to the bitmap buffer. This value should be + * aligned on 32-bit boundaries in most cases. * * num_grays :: - * This field is only used with - * @FT_PIXEL_MODE_GRAY; it gives the number of gray - * levels used in the bitmap. + * This field is only used with @FT_PIXEL_MODE_GRAY; it gives the + * number of gray levels used in the bitmap. * * pixel_mode :: - * The pixel mode, i.e., how pixel bits are stored. - * See @FT_Pixel_Mode for possible values. + * The pixel mode, i.e., how pixel bits are stored. See @FT_Pixel_Mode + * for possible values. * * palette_mode :: - * This field is intended for paletted pixel modes; - * it indicates how the palette is stored. Not - * used currently. + * This field is intended for paletted pixel modes; it indicates how + * the palette is stored. Not used currently. * * palette :: - * A typeless pointer to the bitmap palette; this - * field is intended for paletted pixel modes. Not - * used currently. + * A typeless pointer to the bitmap palette; this field is intended for + * paletted pixel modes. Not used currently. */ typedef struct FT_Bitmap_ { @@ -311,45 +297,42 @@ FT_BEGIN_HEADER * The number of points in the outline. * * points :: - * A pointer to an array of `n_points' @FT_Vector - * elements, giving the outline's point coordinates. + * A pointer to an array of `n_points` @FT_Vector elements, giving the + * outline's point coordinates. * * tags :: - * A pointer to an array of `n_points' chars, giving - * each outline point's type. + * A pointer to an array of `n_points` chars, giving each outline + * point's type. * - * If bit~0 is unset, the point is `off' the curve, - * i.e., a Bezier control point, while it is `on' if - * set. + * If bit~0 is unset, the point is 'off' the curve, i.e., a Bezier + * control point, while it is 'on' if set. * - * Bit~1 is meaningful for `off' points only. If set, - * it indicates a third-order Bezier arc control point; - * and a second-order control point if unset. + * Bit~1 is meaningful for 'off' points only. If set, it indicates a + * third-order Bezier arc control point; and a second-order control + * point if unset. * - * If bit~2 is set, bits 5-7 contain the drop-out mode - * (as defined in the OpenType specification; the value - * is the same as the argument to the SCANMODE - * instruction). + * If bit~2 is set, bits 5-7 contain the drop-out mode (as defined in + * the OpenType specification; the value is the same as the argument to + * the SCANMODE instruction). * * Bits 3 and~4 are reserved for internal purposes. * * contours :: - * An array of `n_contours' shorts, giving the end - * point of each contour within the outline. For - * example, the first contour is defined by the points - * `0' to `contours[0]', the second one is defined by - * the points `contours[0]+1' to `contours[1]', etc. + * An array of `n_contours` shorts, giving the end point of each + * contour within the outline. For example, the first contour is + * defined by the points '0' to 'contours[0]', the second one is + * defined by the points 'contours[0]+1' to 'contours[1]', etc. * * flags :: - * A set of bit flags used to characterize the outline - * and give hints to the scan-converter and hinter on - * how to convert/grid-fit it. See @FT_OUTLINE_XXX. + * A set of bit flags used to characterize the outline and give hints + * to the scan-converter and hinter on how to convert/grid-fit it. See + * @FT_OUTLINE_XXX. * * @note: - * The B/W rasterizer only checks bit~2 in the `tags' array for the - * first point of each contour. The drop-out mode as given with + * The B/W rasterizer only checks bit~2 in the 'tags' array for the first + * point of each contour. The drop-out mode as given with * @FT_OUTLINE_IGNORE_DROPOUTS, @FT_OUTLINE_SMART_DROPOUTS, and - * @FT_OUTLINE_INCLUDE_STUBS in `flags' is then overridden. + * @FT_OUTLINE_INCLUDE_STUBS in 'flags' is then overridden. */ typedef struct FT_Outline_ { @@ -379,21 +362,21 @@ FT_BEGIN_HEADER * * @description: * A list of bit-field constants used for the flags in an outline's - * `flags' field. + * 'flags' field. * * @values: * FT_OUTLINE_NONE :: * Value~0 is reserved. * * FT_OUTLINE_OWNER :: - * If set, this flag indicates that the outline's field arrays - * (i.e., `points', `flags', and `contours') are `owned' by the - * outline object, and should thus be freed when it is destroyed. + * If set, this flag indicates that the outline's field arrays (i.e., + * 'points', 'flags', and 'contours') are 'owned' by the outline + * object, and should thus be freed when it is destroyed. * * FT_OUTLINE_EVEN_ODD_FILL :: - * By default, outlines are filled using the non-zero winding rule. - * If set to 1, the outline will be filled using the even-odd fill - * rule (only works with the smooth rasterizer). + * By default, outlines are filled using the non-zero winding rule. If + * set to 1, the outline will be filled using the even-odd fill rule + * (only works with the smooth rasterizer). * * FT_OUTLINE_REVERSE_FILL :: * By default, outside contours of an outline are oriented in @@ -403,46 +386,44 @@ FT_BEGIN_HEADER * converter. * * FT_OUTLINE_IGNORE_DROPOUTS :: - * By default, the scan converter will try to detect drop-outs in - * an outline and correct the glyph bitmap to ensure consistent - * shape continuity. If set, this flag hints the scan-line - * converter to ignore such cases. See below for more information. + * By default, the scan converter will try to detect drop-outs in an + * outline and correct the glyph bitmap to ensure consistent shape + * continuity. If set, this flag hints the scan-line converter to + * ignore such cases. See below for more information. * * FT_OUTLINE_SMART_DROPOUTS :: - * Select smart dropout control. If unset, use simple dropout - * control. Ignored if @FT_OUTLINE_IGNORE_DROPOUTS is set. See - * below for more information. + * Select smart dropout control. If unset, use simple dropout control. + * Ignored if @FT_OUTLINE_IGNORE_DROPOUTS is set. See below for more + * information. * * FT_OUTLINE_INCLUDE_STUBS :: - * If set, turn pixels on for `stubs', otherwise exclude them. - * Ignored if @FT_OUTLINE_IGNORE_DROPOUTS is set. See below for - * more information. + * If set, turn pixels on for 'stubs', otherwise exclude them. Ignored + * if @FT_OUTLINE_IGNORE_DROPOUTS is set. See below for more + * information. * * FT_OUTLINE_HIGH_PRECISION :: * This flag indicates that the scan-line converter should try to - * convert this outline to bitmaps with the highest possible - * quality. It is typically set for small character sizes. Note - * that this is only a hint that might be completely ignored by a - * given scan-converter. + * convert this outline to bitmaps with the highest possible quality. + * It is typically set for small character sizes. Note that this is + * only a hint that might be completely ignored by a given + * scan-converter. * * FT_OUTLINE_SINGLE_PASS :: * This flag is set to force a given scan-converter to only use a * single pass over the outline to render a bitmap glyph image. - * Normally, it is set for very large character sizes. It is only - * a hint that might be completely ignored by a given - * scan-converter. + * Normally, it is set for very large character sizes. It is only a + * hint that might be completely ignored by a given scan-converter. * * @note: - * The flags @FT_OUTLINE_IGNORE_DROPOUTS, @FT_OUTLINE_SMART_DROPOUTS, - * and @FT_OUTLINE_INCLUDE_STUBS are ignored by the smooth - * rasterizer. + * The flags @FT_OUTLINE_IGNORE_DROPOUTS, @FT_OUTLINE_SMART_DROPOUTS, and + * @FT_OUTLINE_INCLUDE_STUBS are ignored by the smooth rasterizer. * - * There exists a second mechanism to pass the drop-out mode to the - * B/W rasterizer; see the `tags' field in @FT_Outline. + * There exists a second mechanism to pass the drop-out mode to the B/W + * rasterizer; see the 'tags' field in @FT_Outline. * - * Please refer to the description of the `SCANTYPE' instruction in - * the OpenType specification (in file `ttinst1.doc') how simple - * drop-outs, smart drop-outs, and stubs are defined. + * Please refer to the description of the 'SCANTYPE' instruction in the + * OpenType specification (in file `ttinst1.doc`) how simple drop-outs, + * smart drop-outs, and stubs are defined. */ #define FT_OUTLINE_NONE 0x0 #define FT_OUTLINE_OWNER 0x1 @@ -500,14 +481,14 @@ FT_BEGIN_HEADER * FT_Outline_MoveToFunc * * @description: - * A function pointer type used to describe the signature of a `move - * to' function during outline walking/decomposition. + * A function pointer type used to describe the signature of a 'move to' + * function during outline walking/decomposition. * - * A `move to' is emitted to start a new contour in an outline. + * A 'move to' is emitted to start a new contour in an outline. * * @input: * to :: - * A pointer to the target point of the `move to'. + * A pointer to the target point of the 'move to'. * * user :: * A typeless pointer, which is passed from the caller of the @@ -529,14 +510,14 @@ FT_BEGIN_HEADER * FT_Outline_LineToFunc * * @description: - * A function pointer type used to describe the signature of a `line - * to' function during outline walking/decomposition. + * A function pointer type used to describe the signature of a 'line to' + * function during outline walking/decomposition. * - * A `line to' is emitted to indicate a segment in the outline. + * A 'line to' is emitted to indicate a segment in the outline. * * @input: * to :: - * A pointer to the target point of the `line to'. + * A pointer to the target point of the 'line to'. * * user :: * A typeless pointer, which is passed from the caller of the @@ -558,23 +539,23 @@ FT_BEGIN_HEADER * FT_Outline_ConicToFunc * * @description: - * A function pointer type used to describe the signature of a `conic - * to' function during outline walking or decomposition. + * A function pointer type used to describe the signature of a 'conic to' + * function during outline walking or decomposition. * - * A `conic to' is emitted to indicate a second-order Bezier arc in - * the outline. + * A 'conic to' is emitted to indicate a second-order Bezier arc in the + * outline. * * @input: * control :: - * An intermediate control point between the last position - * and the new target in `to'. + * An intermediate control point between the last position and the new + * target in 'to'. * * to :: * A pointer to the target end point of the conic arc. * * user :: - * A typeless pointer, which is passed from the caller of - * the decomposition function. + * A typeless pointer, which is passed from the caller of the + * decomposition function. * * @return: * Error code. 0~means success. @@ -593,10 +574,10 @@ FT_BEGIN_HEADER * FT_Outline_CubicToFunc * * @description: - * A function pointer type used to describe the signature of a `cubic - * to' function during outline walking or decomposition. + * A function pointer type used to describe the signature of a 'cubic to' + * function during outline walking or decomposition. * - * A `cubic to' is emitted to indicate a third-order Bezier arc. + * A 'cubic to' is emitted to indicate a third-order Bezier arc. * * @input: * control1 :: @@ -609,8 +590,8 @@ FT_BEGIN_HEADER * A pointer to the target end point. * * user :: - * A typeless pointer, which is passed from the caller of - * the decomposition function. + * A typeless pointer, which is passed from the caller of the + * decomposition function. * * @return: * Error code. 0~means success. @@ -635,7 +616,7 @@ FT_BEGIN_HEADER * * @fields: * move_to :: - * The `move to' emitter. + * The 'move to' emitter. * * line_to :: * The segment emitter. @@ -647,25 +628,25 @@ FT_BEGIN_HEADER * The third-order Bezier arc emitter. * * shift :: - * The shift that is applied to coordinates before they - * are sent to the emitter. + * The shift that is applied to coordinates before they are sent to the + * emitter. * * delta :: - * The delta that is applied to coordinates before they - * are sent to the emitter, but after the shift. + * The delta that is applied to coordinates before they are sent to the + * emitter, but after the shift. * * @note: - * The point coordinates sent to the emitters are the transformed - * version of the original coordinates (this is important for high - * accuracy during scan-conversion). The transformation is simple: + * The point coordinates sent to the emitters are the transformed version + * of the original coordinates (this is important for high accuracy + * during scan-conversion). The transformation is simple: * - * { + * ``` * x' = (x << shift) - delta * y' = (y << shift) - delta - * } + * ``` * - * Set the values of `shift' and `delta' to~0 to get the original - * point coordinates. + * Set the values of 'shift' and 'delta' to~0 to get the original point + * coordinates. */ typedef struct FT_Outline_Funcs_ { @@ -697,13 +678,12 @@ FT_BEGIN_HEADER * This macro converts four-letter tags to an unsigned long type. * * @note: - * Since many 16-bit compilers don't like 32-bit enumerations, you - * should redefine this macro in case of problems to something like - * this: + * Since many 16-bit compilers don't like 32-bit enumerations, you should + * redefine this macro in case of problems to something like this: * - * { + * ``` * #define FT_IMAGE_TAG( value, _x1, _x2, _x3, _x4 ) value - * } + * ``` * * to get a simple enumeration without assigning special numbers. */ @@ -732,27 +712,26 @@ FT_BEGIN_HEADER * The value~0 is reserved. * * FT_GLYPH_FORMAT_COMPOSITE :: - * The glyph image is a composite of several other images. This - * format is _only_ used with @FT_LOAD_NO_RECURSE, and is used to - * report compound glyphs (like accented characters). + * The glyph image is a composite of several other images. This format + * is _only_ used with @FT_LOAD_NO_RECURSE, and is used to report + * compound glyphs (like accented characters). * * FT_GLYPH_FORMAT_BITMAP :: - * The glyph image is a bitmap, and can be described as an - * @FT_Bitmap. You generally need to access the `bitmap' field of - * the @FT_GlyphSlotRec structure to read it. + * The glyph image is a bitmap, and can be described as an @FT_Bitmap. + * You generally need to access the 'bitmap' field of the + * @FT_GlyphSlotRec structure to read it. * * FT_GLYPH_FORMAT_OUTLINE :: - * The glyph image is a vectorial outline made of line segments - * and Bezier arcs; it can be described as an @FT_Outline; you - * generally want to access the `outline' field of the - * @FT_GlyphSlotRec structure to read it. + * The glyph image is a vectorial outline made of line segments and + * Bezier arcs; it can be described as an @FT_Outline; you generally + * want to access the 'outline' field of the @FT_GlyphSlotRec structure + * to read it. * * FT_GLYPH_FORMAT_PLOTTER :: * The glyph image is a vectorial path with no inside and outside * contours. Some Type~1 fonts, like those in the Hershey family, - * contain glyphs in this format. These are described as - * @FT_Outline, but FreeType isn't currently capable of rendering - * them correctly. + * contain glyphs in this format. These are described as @FT_Outline, + * but FreeType isn't currently capable of rendering them correctly. */ typedef enum FT_Glyph_Format_ { @@ -788,12 +767,12 @@ FT_BEGIN_HEADER /************************************************************************** * - * A raster is a scan converter, in charge of rendering an outline into - * a bitmap. This section contains the public API for rasters. + * A raster is a scan converter, in charge of rendering an outline into a + * bitmap. This section contains the public API for rasters. * * Note that in FreeType 2, all rasters are now encapsulated within - * specific modules called `renderers'. See `ftrender.h' for more - * details on renderers. + * specific modules called 'renderers'. See `ftrender.h` for more details + * on renderers. * */ @@ -848,8 +827,8 @@ FT_BEGIN_HEADER * FT_Span * * @description: - * A structure used to model a single span of gray pixels when - * rendering an anti-aliased bitmap. + * A structure used to model a single span of gray pixels when rendering + * an anti-aliased bitmap. * * @fields: * x :: @@ -859,16 +838,15 @@ FT_BEGIN_HEADER * The span's length in pixels. * * coverage :: - * The span color/coverage, ranging from 0 (background) - * to 255 (foreground). + * The span color/coverage, ranging from 0 (background) to 255 + * (foreground). * * @note: * This structure is used by the span drawing callback type named - * @FT_SpanFunc that takes the y~coordinate of the span as a - * parameter. + * @FT_SpanFunc that takes the y~coordinate of the span as a parameter. * - * The coverage value is always between 0 and 255. If you want less - * gray values, the callback function has to reduce them. + * The coverage value is always between 0 and 255. If you want less gray + * values, the callback function has to reduce them. */ typedef struct FT_Span_ { @@ -885,9 +863,9 @@ FT_BEGIN_HEADER * FT_SpanFunc * * @description: - * A function used as a call-back by the anti-aliased renderer in - * order to let client applications draw themselves the gray pixel - * spans on each scan line. + * A function used as a call-back by the anti-aliased renderer in order + * to let client applications draw themselves the gray pixel spans on + * each scan line. * * @input: * y :: @@ -897,17 +875,17 @@ FT_BEGIN_HEADER * The number of spans to draw on this scanline. * * spans :: - * A table of `count' spans to draw on the scanline. + * A table of 'count' spans to draw on the scanline. * * user :: * User-supplied data that is passed to the callback. * * @note: - * This callback allows client applications to directly render the - * gray spans of the anti-aliased bitmap to any kind of surfaces. + * This callback allows client applications to directly render the gray + * spans of the anti-aliased bitmap to any kind of surfaces. * - * This can be used to write anti-aliased outlines directly to a - * given background bitmap, and even perform translucency. + * This can be used to write anti-aliased outlines directly to a given + * background bitmap, and even perform translucency. */ typedef void (*FT_SpanFunc)( int y, @@ -952,7 +930,7 @@ FT_BEGIN_HEADER * FT_RASTER_FLAG_XXX * * @description: - * A list of bit flag constants as used in the `flags' field of a + * A list of bit flag constants as used in the 'flags' field of a * @FT_Raster_Params structure. * * @values: @@ -960,35 +938,26 @@ FT_BEGIN_HEADER * This value is 0. * * FT_RASTER_FLAG_AA :: - * This flag is set to indicate that an - * anti-aliased glyph image should be - * generated. Otherwise, it will be - * monochrome (1-bit). + * This flag is set to indicate that an anti-aliased glyph image should + * be generated. Otherwise, it will be monochrome (1-bit). * * FT_RASTER_FLAG_DIRECT :: - * This flag is set to indicate direct - * rendering. In this mode, client - * applications must provide their own span - * callback. This lets them directly - * draw or compose over an existing bitmap. - * If this bit is not set, the target - * pixmap's buffer _must_ be zeroed before + * This flag is set to indicate direct rendering. In this mode, client + * applications must provide their own span callback. This lets them + * directly draw or compose over an existing bitmap. If this bit is + * not set, the target pixmap's buffer _must_ be zeroed before * rendering. * - * Direct rendering is only possible with - * anti-aliased glyphs. + * Direct rendering is only possible with anti-aliased glyphs. * * FT_RASTER_FLAG_CLIP :: - * This flag is only used in direct - * rendering mode. If set, the output will - * be clipped to a box specified in the - * `clip_box' field of the + * This flag is only used in direct rendering mode. If set, the output + * will be clipped to a box specified in the `clip_box` field of the * @FT_Raster_Params structure. * - * Note that by default, the glyph bitmap - * is clipped to the target pixmap, except - * in direct rendering mode where all spans - * are generated if no clipping box is set. + * Note that by default, the glyph bitmap is clipped to the target + * pixmap, except in direct rendering mode where all spans are + * generated if no clipping box is set. */ #define FT_RASTER_FLAG_DEFAULT 0x0 #define FT_RASTER_FLAG_AA 0x1 @@ -1009,16 +978,14 @@ FT_BEGIN_HEADER * FT_Raster_Params * * @description: - * A structure to hold the arguments used by a raster's render - * function. + * A structure to hold the arguments used by a raster's render function. * * @fields: * target :: * The target bitmap. * * source :: - * A pointer to the source glyph image (e.g., an - * @FT_Outline). + * A pointer to the source glyph image (e.g., an @FT_Outline). * * flags :: * The rendering flags. @@ -1036,25 +1003,23 @@ FT_BEGIN_HEADER * Unused. * * user :: - * User-supplied data that is passed to each drawing - * callback. + * User-supplied data that is passed to each drawing callback. * * clip_box :: - * An optional clipping box. It is only used in - * direct rendering mode. Note that coordinates here - * should be expressed in _integer_ pixels (and not in - * 26.6 fixed-point units). + * An optional clipping box. It is only used in direct rendering mode. + * Note that coordinates here should be expressed in _integer_ pixels + * (and not in 26.6 fixed-point units). * * @note: - * An anti-aliased glyph bitmap is drawn if the @FT_RASTER_FLAG_AA - * bit flag is set in the `flags' field, otherwise a monochrome - * bitmap is generated. - * - * If the @FT_RASTER_FLAG_DIRECT bit flag is set in `flags', the - * raster will call the `gray_spans' callback to draw gray pixel - * spans. This allows direct composition over a pre-existing bitmap - * through user-provided callbacks to perform the span drawing and - * composition. Not supported by the monochrome rasterizer. + * An anti-aliased glyph bitmap is drawn if the @FT_RASTER_FLAG_AA bit + * flag is set in the 'flags' field, otherwise a monochrome bitmap is + * generated. + * + * If the @FT_RASTER_FLAG_DIRECT bit flag is set in 'flags', the raster + * will call the `gray_spans` callback to draw gray pixel spans. This + * allows direct composition over a pre-existing bitmap through + * user-provided callbacks to perform the span drawing and composition. + * Not supported by the monochrome rasterizer. */ typedef struct FT_Raster_Params_ { @@ -1091,11 +1056,11 @@ FT_BEGIN_HEADER * Error code. 0~means success. * * @note: - * The `memory' parameter is a typeless pointer in order to avoid - * un-wanted dependencies on the rest of the FreeType code. In - * practice, it is an @FT_Memory object, i.e., a handle to the - * standard FreeType memory allocator. However, this field can be - * completely ignored by a given raster implementation. + * The 'memory' parameter is a typeless pointer in order to avoid + * un-wanted dependencies on the rest of the FreeType code. In practice, + * it is an @FT_Memory object, i.e., a handle to the standard FreeType + * memory allocator. However, this field can be completely ignored by a + * given raster implementation. */ typedef int (*FT_Raster_NewFunc)( void* memory, @@ -1128,9 +1093,9 @@ FT_BEGIN_HEADER * FT_Raster_ResetFunc * * @description: - * FreeType used to provide an area of memory called the `render - * pool' available to all registered rasterizers. This was not - * thread safe, however, and now FreeType never allocates this pool. + * FreeType used to provide an area of memory called the 'render pool' + * available to all registered rasterizers. This was not thread safe, + * however, and now FreeType never allocates this pool. * * This function is called after a new raster object is created. * @@ -1139,17 +1104,16 @@ FT_BEGIN_HEADER * A handle to the new raster object. * * pool_base :: - * Previously, the address in memory of the render pool. - * Set this to NULL. + * Previously, the address in memory of the render pool. Set this to + * NULL. * * pool_size :: - * Previously, the size in bytes of the render pool. - * Set this to 0. + * Previously, the size in bytes of the render pool. Set this to 0. * * @note: - * Rasterizers should rely on dynamic or stack allocation if they - * want to (a handle to the memory allocator is passed to the - * rasterizer constructor). + * Rasterizers should rely on dynamic or stack allocation if they want to + * (a handle to the memory allocator is passed to the rasterizer + * constructor). */ typedef void (*FT_Raster_ResetFunc)( FT_Raster raster, @@ -1165,10 +1129,9 @@ FT_BEGIN_HEADER * FT_Raster_SetModeFunc * * @description: - * This function is a generic facility to change modes or attributes - * in a given raster. This can be used for debugging purposes, or - * simply to allow implementation-specific `features' in a given - * raster module. + * This function is a generic facility to change modes or attributes in a + * given raster. This can be used for debugging purposes, or simply to + * allow implementation-specific 'features' in a given raster module. * * @input: * raster :: @@ -1202,8 +1165,8 @@ FT_BEGIN_HEADER * A handle to the raster object. * * params :: - * A pointer to an @FT_Raster_Params structure used to - * store the rendering parameters. + * A pointer to an @FT_Raster_Params structure used to store the + * rendering parameters. * * @return: * Error code. 0~means success. @@ -1215,13 +1178,13 @@ FT_BEGIN_HEADER * glyph formats. * * Note also that the render function can fail and return a - * `FT_Err_Unimplemented_Feature' error code if the raster used does - * not support direct composition. + * `FT_Err_Unimplemented_Feature` error code if the raster used does not + * support direct composition. * * XXX: For now, the standard raster doesn't support direct - * composition but this should change for the final release (see - * the files `demos/src/ftgrays.c' and `demos/src/ftgrays2.c' - * for examples of distinct implementations that support direct + * composition but this should change for the final release (see the + * files 'demos/src/ftgrays.c' and 'demos/src/ftgrays2.c' for + * examples of distinct implementations that support direct * composition). */ typedef int diff --git a/include/freetype/ftincrem.h b/include/freetype/ftincrem.h index b3a17c30a..df713559f 100644 --- a/include/freetype/ftincrem.h +++ b/include/freetype/ftincrem.h @@ -45,7 +45,7 @@ FT_BEGIN_HEADER * * @description: * This section contains various functions used to perform so-called - * `incremental' glyph loading. This is a mode where all glyphs loaded + * 'incremental' glyph loading. This is a mode where all glyphs loaded * from a given @FT_Face are provided by the client application. * * Apart from that, all other tables are loaded normally from the font @@ -67,16 +67,17 @@ 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), - * where the glyph data isn't in the font file, or must be overridden by - * different values. + * 'incremental' glyph loading within FreeType. This is used to support + * 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. * * @note: - * It is up to client applications to create and implement @FT_Incremental - * objects, as long as they provide implementations for the methods - * @FT_Incremental_GetGlyphDataFunc, @FT_Incremental_FreeGlyphDataFunc - * and @FT_Incremental_GetGlyphMetricsFunc. + * It is up to client applications to create and implement + * @FT_Incremental objects, as long as they provide implementations for + * the methods @FT_Incremental_GetGlyphDataFunc, + * @FT_Incremental_FreeGlyphDataFunc and + * @FT_Incremental_GetGlyphMetricsFunc. * * See the description of @FT_Incremental_InterfaceRec to understand how * to use incremental objects with FreeType. @@ -91,8 +92,8 @@ FT_BEGIN_HEADER * FT_Incremental_MetricsRec * * @description: - * A small structure used to contain the basic glyph metrics returned - * by the @FT_Incremental_GetGlyphMetricsFunc method. + * A small structure used to contain the basic glyph metrics returned by + * the @FT_Incremental_GetGlyphMetricsFunc method. * * @fields: * bearing_x :: @@ -109,7 +110,7 @@ FT_BEGIN_HEADER * * @note: * These correspond to horizontal or vertical metrics depending on the - * value of the `vertical' argument to the function + * value of the 'vertical' argument to the function * @FT_Incremental_GetGlyphMetricsFunc. * */ @@ -147,8 +148,8 @@ FT_BEGIN_HEADER * * Note that the format of the glyph's data bytes depends on the font * file format. For TrueType, it must correspond to the raw bytes within - * the `glyf' table. For PostScript formats, it must correspond to the - * *unencrypted* charstring bytes, without any `lenIV' header. It is + * the 'glyf' table. For PostScript formats, it must correspond to the + * **unencrypted** charstring bytes, without any `lenIV` header. It is * undefined for any other format. * * @input: @@ -169,8 +170,8 @@ FT_BEGIN_HEADER * * @note: * If this function returns successfully the method - * @FT_Incremental_FreeGlyphDataFunc will be called later to release - * the data bytes. + * @FT_Incremental_FreeGlyphDataFunc will be called later to release the + * data bytes. * * Nested calls to @FT_Incremental_GetGlyphDataFunc can happen for * compound glyphs. @@ -214,8 +215,8 @@ FT_BEGIN_HEADER * @description: * A function used to retrieve the basic metrics of a given glyph index * before accessing its data. This is necessary because, in certain - * formats like TrueType, the metrics are stored in a different place from - * the glyph images proper. + * formats like TrueType, the metrics are stored in a different place + * from the glyph images proper. * * @input: * incremental :: @@ -229,9 +230,9 @@ FT_BEGIN_HEADER * If true, return vertical metrics. * * ametrics :: - * This parameter is used for both input and output. - * The original glyph metrics, if any, in font units. If metrics are - * not available all the values must be set to zero. + * This parameter is used for both input and output. The original + * glyph metrics, if any, in font units. If metrics are not available + * all the values must be set to zero. * * @output: * ametrics :: @@ -252,8 +253,8 @@ FT_BEGIN_HEADER * FT_Incremental_FuncsRec * * @description: - * A table of functions for accessing fonts that load data - * incrementally. Used in @FT_Incremental_InterfaceRec. + * A table of functions for accessing fonts that load data incrementally. + * Used in @FT_Incremental_InterfaceRec. * * @fields: * get_glyph_data :: @@ -263,8 +264,8 @@ FT_BEGIN_HEADER * The function to release glyph data. Must not be null. * * get_glyph_metrics :: - * The function to get glyph metrics. May be null if the font does - * not provide overriding glyph metrics. + * The function to get glyph metrics. May be null if the font does not + * provide overriding glyph metrics. * */ typedef struct FT_Incremental_FuncsRec_ @@ -286,7 +287,7 @@ FT_BEGIN_HEADER * wants to support incremental glyph loading. You should use it with * @FT_PARAM_TAG_INCREMENTAL as in the following example: * - * { + * ``` * FT_Incremental_InterfaceRec inc_int; * FT_Parameter parameter; * FT_Open_Args open_args; @@ -309,7 +310,7 @@ FT_BEGIN_HEADER * // open the font * error = FT_Open_Face( library, &open_args, index, &face ); * ... - * } + * ``` * */ typedef struct FT_Incremental_InterfaceRec_ diff --git a/include/freetype/ftlcdfil.h b/include/freetype/ftlcdfil.h index 8d27135e3..02a37c959 100644 --- a/include/freetype/ftlcdfil.h +++ b/include/freetype/ftlcdfil.h @@ -47,7 +47,7 @@ FT_BEGIN_HEADER * @description: * FreeType provides two alternative subpixel rendering technologies. * Should you #define FT_CONFIG_OPTION_SUBPIXEL_RENDERING in your - * `ftoption.h', this enables patented ClearType-style rendering. + * `ftoption.h`, this enables patented ClearType-style rendering. * Otherwise, Harmony LCD rendering is enabled. These technologies are * controlled differently and API described below, although always * available, performs its function when appropriate method is enabled @@ -58,7 +58,8 @@ FT_BEGIN_HEADER * the stripe (usually horizontal RGB) by a factor of~3. Using the * subpixels coverages unfiltered can create severe color fringes * especially when rendering thin features. Indeed, to produce - * black-on-white text, the nearby color subpixels must be dimmed equally. + * black-on-white text, the nearby color subpixels must be dimmed + * equally. * * A good 5-tap FIR filter should be applied to subpixel coverages * regardless of pixel boundaries and should have these properties: @@ -82,32 +83,32 @@ FT_BEGIN_HEADER * subpixel-rendered bitmaps generated through @FT_Render_Glyph. * * Harmony LCD rendering is suitable to panels with any regular subpixel - * structure, not just monitors with 3 color striped subpixels, as long as - * the color subpixels have fixed positions relative to the pixel center. - * In this case, each color channel is then rendered separately after - * shifting the outline opposite to the subpixel shift so that the + * structure, not just monitors with 3 color striped subpixels, as long + * as the color subpixels have fixed positions relative to the pixel + * center. In this case, each color channel is then rendered separately + * after shifting the outline opposite to the subpixel shift so that the * coverage maps are aligned. This method is immune to color fringes * because the shifts do not change integral coverage. * * The subpixel geometry must be specified by xy-coordinates for each - * subpixel. By convention they may come in the RGB order: - * {{-1/3, 0}, {0, 0}, {1/3, 0}} for standard RGB striped panel or - * {{-1/6, 1/4}, {-1/6, -1/4}, {1/3, 0}} for a certain PenTile panel. + * subpixel. By convention they may come in the RGB order: {{-1/3, 0}, + * {0, 0}, {1/3, 0}} for standard RGB striped panel or {{-1/6, 1/4}, + * {-1/6, -1/4}, {1/3, 0}} for a certain PenTile panel. * * Use the @FT_Library_SetLcdGeometry API to specify subpixel positions. - * If one follows the RGB order convention, the same order applies - * to the resulting @FT_PIXEL_MODE_LCD and @FT_PIXEL_MODE_LCD_V bitmaps. - * Note, however, that the coordinate frame for the latter must be rotated + * If one follows the RGB order convention, the same order applies to the + * resulting @FT_PIXEL_MODE_LCD and @FT_PIXEL_MODE_LCD_V bitmaps. Note, + * however, that the coordinate frame for the latter must be rotated * clockwise. Harmony with default LCD geometry is equivalent to * ClearType with light filter. * - * As a result of ClearType filtering or Harmony rendering, the dimensions - * of LCD bitmaps can be either wider or taller than the dimensions of - * the corresponding outline with regard to the pixel grid. For example, - * for @FT_RENDER_MODE_LCD, the filter adds 2~subpixels to the left, and - * 2~subpixels to the right. The bitmap offset values are adjusted - * accordingly, so clients shouldn't need to modify their layout and - * glyph positioning code when enabling the filter. + * As a result of ClearType filtering or Harmony rendering, the + * dimensions of LCD bitmaps can be either wider or taller than the + * dimensions of the corresponding outline with regard to the pixel grid. + * For example, for @FT_RENDER_MODE_LCD, the filter adds 2~subpixels to + * the left, and 2~subpixels to the right. The bitmap offset values are + * adjusted accordingly, so clients shouldn't need to modify their layout + * and glyph positioning code when enabling the filter. * * The ClearType and Harmony rendering is applicable to glyph bitmaps * rendered through @FT_Render_Glyph, @FT_Load_Glyph, @FT_Load_Char, and @@ -116,10 +117,10 @@ FT_BEGIN_HEADER * @FT_Outline_Get_Bitmap. * * The described algorithms can completely remove color artefacts when - * combined with gamma-corrected alpha blending in linear space. - * Each of the 3~alpha values (subpixels) must by independently used to - * blend one color channel. That is, red alpha blends the red channel of - * the text color with the red channel of the background pixel. + * combined with gamma-corrected alpha blending in linear space. Each of + * the 3~alpha values (subpixels) must by independently used to blend one + * color channel. That is, red alpha blends the red channel of the text + * color with the red channel of the background pixel. */ @@ -141,8 +142,8 @@ FT_BEGIN_HEADER * with weights of [0x08 0x4D 0x56 0x4D 0x08] in 1/256th units. * * FT_LCD_FILTER_LIGHT :: - * this is a boxy, normalized, and color-balanced three-tap filter - * with weights of [0x00 0x55 0x56 0x55 0x00] in 1/256th units. + * this is a boxy, normalized, and color-balanced three-tap filter with + * weights of [0x00 0x55 0x56 0x55 0x00] in 1/256th units. * * FT_LCD_FILTER_LEGACY :: * FT_LCD_FILTER_LEGACY1 :: @@ -151,12 +152,11 @@ FT_BEGIN_HEADER * fringes if glyphs are not extremely well hinted to the pixel grid. * This filter is only provided for comparison purposes, and might be * disabled or stay unsupported in the future. The second value is - * provided for compatibility with FontConfig, which historically - * used different enumeration, sometimes incorrectly forwarded to - * FreeType. + * provided for compatibility with FontConfig, which historically used + * different enumeration, sometimes incorrectly forwarded to FreeType. * * @since: - * 2.3.0 (`FT_LCD_FILTER_LEGACY1' since 2.6.2) + * 2.3.0 (`FT_LCD_FILTER_LEGACY1` since 2.6.2) */ typedef enum FT_LcdFilter_ { @@ -189,22 +189,22 @@ FT_BEGIN_HEADER * The filter type. * * You can use @FT_LCD_FILTER_NONE here to disable this feature, or - * @FT_LCD_FILTER_DEFAULT to use a default filter that should work - * well on most LCD screens. + * @FT_LCD_FILTER_DEFAULT to use a default filter that should work well + * on most LCD screens. * * @return: * FreeType error code. 0~means success. * * @note: * This feature is always disabled by default. Clients must make an - * explicit call to this function with a `filter' value other than + * explicit call to this function with a 'filter' value other than * @FT_LCD_FILTER_NONE in order to enable it. * - * Due to *PATENTS* covering subpixel rendering, this function doesn't - * do anything except returning `FT_Err_Unimplemented_Feature' if the - * configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not - * defined in your build of the library, which should correspond to all - * default builds of FreeType. + * Due to **PATENTS** covering subpixel rendering, this function doesn't + * do anything except returning `FT_Err_Unimplemented_Feature` if the + * configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not defined + * in your build of the library, which should correspond to all default + * builds of FreeType. * * @since: * 2.3.0 @@ -235,11 +235,11 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * Due to *PATENTS* covering subpixel rendering, this function doesn't - * do anything except returning `FT_Err_Unimplemented_Feature' if the - * configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not - * defined in your build of the library, which should correspond to all - * default builds of FreeType. + * Due to **PATENTS** covering subpixel rendering, this function doesn't + * do anything except returning `FT_Err_Unimplemented_Feature` if the + * configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not defined + * in your build of the library, which should correspond to all default + * builds of FreeType. * * LCD filter weights can also be set per face using @FT_Face_Properties * with @FT_PARAM_TAG_LCD_FILTER_WEIGHTS. @@ -296,8 +296,8 @@ FT_BEGIN_HEADER * - {{-21, 0}, {0, 0}, {21, 0}} is the default, corresponding to 3 color * stripes shifted by a third of a pixel. This could be an RGB panel. * - * - {{21, 0}, {0, 0}, {-21, 0}} looks the same as the default but - * can specify a BGR panel instead, while keeping the bitmap in the same + * - {{21, 0}, {0, 0}, {-21, 0}} looks the same as the default but can + * specify a BGR panel instead, while keeping the bitmap in the same * RGB888 format. * * - {{0, 21}, {0, 0}, {0, -21}} is the vertical RGB, but the bitmap @@ -305,7 +305,7 @@ FT_BEGIN_HEADER * * - {{-11, 16}, {-11, -16}, {22, 0}} is a certain PenTile arrangement. * - * This function does nothing and returns `FT_Err_Unimplemented_Feature' + * This function does nothing and returns `FT_Err_Unimplemented_Feature` * in the context of ClearType-style subpixel rendering when * FT_CONFIG_OPTION_SUBPIXEL_RENDERING is defined in your build of the * library. diff --git a/include/freetype/ftlist.h b/include/freetype/ftlist.h index cdea89745..0da72f091 100644 --- a/include/freetype/ftlist.h +++ b/include/freetype/ftlist.h @@ -18,8 +18,8 @@ /************************************************************************** * - * This file implements functions relative to list processing. Its - * data structures are defined in `freetype.h'. + * This file implements functions relative to list processing. Its data + * structures are defined in `freetype.h`. * */ @@ -53,8 +53,8 @@ FT_BEGIN_HEADER * Simple management of lists. * * @description: - * This section contains various definitions related to list - * processing using doubly-linked nodes. + * This section contains various definitions related to list processing + * using doubly-linked nodes. * * @order: * FT_List @@ -141,8 +141,8 @@ FT_BEGIN_HEADER * FT_List_Remove * * @description: - * Remove a node from a list. This function doesn't check whether - * the node is in the list! + * Remove a node from a list. This function doesn't check whether the + * node is in the list! * * @input: * node :: @@ -163,8 +163,7 @@ FT_BEGIN_HEADER * FT_List_Up * * @description: - * Move a node to the head/top of a list. Used to maintain LRU - * lists. + * Move a node to the head/top of a list. Used to maintain LRU lists. * * @inout: * list :: @@ -183,16 +182,16 @@ FT_BEGIN_HEADER * FT_List_Iterator * * @description: - * An FT_List iterator function that is called during a list parse - * by @FT_List_Iterate. + * An FT_List iterator function that is called during a list parse by + * @FT_List_Iterate. * * @input: * node :: * The current iteration list node. * * user :: - * A typeless pointer passed to @FT_List_Iterate. - * Can be used to point to the iteration's state. + * A typeless pointer passed to @FT_List_Iterate. Can be used to point + * to the iteration's state. */ typedef FT_Error (*FT_List_Iterator)( FT_ListNode node, @@ -215,8 +214,8 @@ FT_BEGIN_HEADER * iterator :: * An iterator function, called on each node of the list. * user :: - * A user-supplied field that is passed as the second - * argument to the iterator. + * A user-supplied field that is passed as the second argument to the + * iterator. * * @return: * The result (a FreeType error code) of the last iterator call. @@ -234,8 +233,8 @@ FT_BEGIN_HEADER * * @description: * An @FT_List iterator function that is called during a list - * finalization by @FT_List_Finalize to destroy all elements in a - * given list. + * finalization by @FT_List_Finalize to destroy all elements in a given + * list. * * @input: * system :: @@ -245,8 +244,8 @@ FT_BEGIN_HEADER * The current object to destroy. * * user :: - * A typeless pointer passed to @FT_List_Iterate. It can - * be used to point to the iteration's state. + * A typeless pointer passed to @FT_List_Iterate. It can be used to + * point to the iteration's state. */ typedef void (*FT_List_Destructor)( FT_Memory memory, @@ -267,15 +266,15 @@ FT_BEGIN_HEADER * A handle to the list. * * destroy :: - * A list destructor that will be applied to each element - * of the list. Set this to NULL if not needed. + * A list destructor that will be applied to each element of the list. + * Set this to NULL if not needed. * * memory :: * The current memory object that handles deallocation. * * user :: - * A user-supplied field that is passed as the last - * argument to the destructor. + * A user-supplied field that is passed as the last argument to the + * destructor. * * @note: * This function expects that all nodes added by @FT_List_Add or diff --git a/include/freetype/ftlzw.h b/include/freetype/ftlzw.h index 01433cab5..e313c9842 100644 --- a/include/freetype/ftlzw.h +++ b/include/freetype/ftlzw.h @@ -53,9 +53,8 @@ FT_BEGIN_HEADER * FT_Stream_OpenLZW * * @description: - * Open a new stream to parse LZW-compressed font files. This is - * mainly used to support the compressed `*.pcf.Z' fonts that come - * with XFree86. + * Open a new stream to parse LZW-compressed font files. This is mainly + * used to support the compressed `*.pcf.Z` fonts that come with XFree86. * * @input: * stream :: @@ -70,9 +69,9 @@ 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 - * objects will be released to the heap. + * 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 * process each time seeking backwards is needed within the stream @@ -80,10 +79,10 @@ FT_BEGIN_HEADER * In certain builds of the library, LZW compression recognition is * automatically handled when calling @FT_New_Face or @FT_Open_Face. * This means that if no font driver is capable of handling the raw - * compressed file, the library will try to open a LZW stream from it - * and re-open the face with it. + * 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_Feature' if your build + * This function may return `FT_Err_Unimplemented_Feature` if your build * of FreeType was not compiled with LZW support. */ FT_EXPORT( FT_Error ) diff --git a/include/freetype/ftmac.h b/include/freetype/ftmac.h index 4249ff547..ae9171ec5 100644 --- a/include/freetype/ftmac.h +++ b/include/freetype/ftmac.h @@ -59,8 +59,8 @@ FT_BEGIN_HEADER * Only available on the Macintosh. * * @description: - * The following definitions are only available if FreeType is - * compiled on a Macintosh. + * The following definitions are only available if FreeType is compiled + * on a Macintosh. * */ @@ -82,8 +82,7 @@ FT_BEGIN_HEADER * A FOND resource. * * face_index :: - * Only supported for the -1 `sanity check' special - * case. + * Only supported for the -1 'sanity check' special case. * * @output: * aface :: @@ -93,13 +92,13 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @example: - * This function can be used to create @FT_Face objects from fonts - * that are installed in the system as follows. + * This function can be used to create @FT_Face objects from fonts that + * are installed in the system as follows. * - * { + * ``` * fond = GetResource( 'FOND', fontName ); * error = FT_New_Face_From_FOND( library, fond, 0, &face ); - * } + * ``` */ FT_EXPORT( FT_Error ) FT_New_Face_From_FOND( FT_Library library, @@ -119,17 +118,14 @@ FT_BEGIN_HEADER * * @input: * fontName :: - * Mac OS name of the font (e.g., Times New Roman - * Bold). + * Mac OS name of the font (e.g., Times New Roman Bold). * * @output: * pathSpec :: - * FSSpec to the file. For passing to - * @FT_New_Face_From_FSSpec. + * FSSpec to the file. For passing to @FT_New_Face_From_FSSpec. * * face_index :: - * Index of the face. For passing to - * @FT_New_Face_From_FSSpec. + * Index of the face. For passing to @FT_New_Face_From_FSSpec. * * @return: * FreeType error code. 0~means success. @@ -155,12 +151,10 @@ FT_BEGIN_HEADER * * @output: * pathSpec :: - * FSSpec to the file. For passing to - * @FT_New_Face_From_FSSpec. + * FSSpec to the file. For passing to @FT_New_Face_From_FSSpec. * * face_index :: - * Index of the face. For passing to - * @FT_New_Face_From_FSSpec. + * Index of the face. For passing to @FT_New_Face_From_FSSpec. * * @return: * FreeType error code. 0~means success. @@ -178,8 +172,8 @@ FT_BEGIN_HEADER * FT_GetFilePath_From_Mac_ATS_Name * * @description: - * Return a pathname of the disk file and face index for given font - * name that is handled by ATS framework. + * Return a pathname of the disk file and face index for given font name + * that is handled by ATS framework. * * @input: * fontName :: @@ -187,12 +181,11 @@ FT_BEGIN_HEADER * * @output: * path :: - * Buffer to store pathname of the file. For passing - * to @FT_New_Face. The client must allocate this - * buffer before calling this function. + * Buffer to store pathname of the file. For passing to @FT_New_Face. + * The client must allocate this buffer before calling this function. * * maxPathSize :: - * Lengths of the buffer `path' that client allocated. + * Lengths of the buffer 'path' that client allocated. * * face_index :: * Index of the face. For passing to @FT_New_Face. @@ -226,8 +219,8 @@ FT_BEGIN_HEADER * FSSpec to the font file. * * face_index :: - * The index of the face within the resource. The - * first face has index~0. + * The index of the face within the resource. The first face has + * index~0. * @output: * aface :: * A handle to a new face object. @@ -236,8 +229,8 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * @FT_New_Face_From_FSSpec is identical to @FT_New_Face except - * it accepts an FSSpec instead of a path. + * @FT_New_Face_From_FSSpec is identical to @FT_New_Face except it + * accepts an FSSpec instead of a path. */ FT_EXPORT( FT_Error ) FT_New_Face_From_FSSpec( FT_Library library, @@ -265,8 +258,8 @@ FT_BEGIN_HEADER * FSRef to the font file. * * face_index :: - * The index of the face within the resource. The - * first face has index~0. + * The index of the face within the resource. The first face has + * index~0. * @output: * aface :: * A handle to a new face object. @@ -275,8 +268,8 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * @FT_New_Face_From_FSRef is identical to @FT_New_Face except - * it accepts an FSRef instead of a path. + * @FT_New_Face_From_FSRef is identical to @FT_New_Face except it accepts + * an FSRef instead of a path. */ FT_EXPORT( FT_Error ) FT_New_Face_From_FSRef( FT_Library library, diff --git a/include/freetype/ftmm.h b/include/freetype/ftmm.h index a903241e3..7a47a50fa 100644 --- a/include/freetype/ftmm.h +++ b/include/freetype/ftmm.h @@ -39,14 +39,14 @@ FT_BEGIN_HEADER * How to manage Multiple Masters fonts. * * @description: - * The following types and functions are used to manage Multiple - * Master fonts, i.e., the selection of specific design instances by - * setting design axis coordinates. + * The following types and functions are used to manage Multiple Master + * fonts, i.e., the selection of specific design instances by setting + * design axis coordinates. * - * Besides Adobe MM fonts, the interface supports Apple's TrueType GX - * and OpenType variation fonts. Some of the routines only work with - * Adobe MM fonts, others will work with all three types. They are - * similar enough that a consistent interface makes sense. + * Besides Adobe MM fonts, the interface supports Apple's TrueType GX and + * OpenType variation fonts. Some of the routines only work with Adobe + * MM fonts, others will work with all three types. They are similar + * enough that a consistent interface makes sense. * */ @@ -57,8 +57,8 @@ FT_BEGIN_HEADER * FT_MM_Axis * * @description: - * A structure to model a given axis in design space for Multiple - * Masters fonts. + * A structure to model a given axis in design space for Multiple Masters + * fonts. * * This structure can't be used for TrueType GX or OpenType variation * fonts. @@ -88,8 +88,7 @@ FT_BEGIN_HEADER * FT_Multi_Master * * @description: - * A structure to model the axes and space of a Multiple Masters - * font. + * A structure to model the axes and space of a Multiple Masters font. * * This structure can't be used for TrueType GX or OpenType variation * fonts. @@ -99,10 +98,9 @@ FT_BEGIN_HEADER * Number of axes. Cannot exceed~4. * * num_designs :: - * Number of designs; should be normally 2^num_axis - * even though the Type~1 specification strangely - * allows for intermediate designs to be present. - * This number cannot exceed~16. + * Number of designs; should be normally 2^num_axis even though the + * Type~1 specification strangely allows for intermediate designs to be + * present. This number cannot exceed~16. * * axis :: * A table of axis descriptors. @@ -127,36 +125,33 @@ FT_BEGIN_HEADER * * @fields: * name :: - * The axis's name. - * Not always meaningful for TrueType GX or OpenType + * The axis's name. Not always meaningful for TrueType GX or OpenType * variation fonts. * * minimum :: * The axis's minimum design coordinate. * * def :: - * The axis's default design coordinate. - * FreeType computes meaningful default values for Adobe - * MM fonts. + * The axis's default design coordinate. FreeType computes meaningful + * default values for Adobe MM fonts. * * maximum :: * The axis's maximum design coordinate. * * tag :: - * The axis's tag (the equivalent to `name' for TrueType - * GX and OpenType variation fonts). FreeType provides - * default values for Adobe MM fonts if possible. + * The axis's tag (the equivalent to 'name' for TrueType GX and + * OpenType variation fonts). FreeType provides default values for + * Adobe MM fonts if possible. * * strid :: - * The axis name entry in the font's `name' table. This - * is another (and often better) version of the `name' - * field for TrueType GX or OpenType variation fonts. Not - * meaningful for Adobe MM fonts. + * The axis name entry in the font's 'name' table. This is another + * (and often better) version of the 'name' field for TrueType GX or + * OpenType variation fonts. Not meaningful for Adobe MM fonts. * * @note: - * The fields `minimum', `def', and `maximum' are 16.16 fractional - * values for TrueType GX and OpenType variation fonts. For Adobe MM - * fonts, the values are integers. + * The fields 'minimum', 'def', and 'maximum' are 16.16 fractional values + * for TrueType GX and OpenType variation fonts. For Adobe MM fonts, the + * values are integers. */ typedef struct FT_Var_Axis_ { @@ -185,16 +180,15 @@ FT_BEGIN_HEADER * * @fields: * coords :: - * The design coordinates for this instance. - * This is an array with one entry for each axis. + * The design coordinates for this instance. This is an array with one + * entry for each axis. * * strid :: - * The entry in `name' table identifying this instance. + * The entry in 'name' table identifying this instance. * * psid :: - * The entry in `name' table identifying a PostScript name - * for this instance. Value 0xFFFF indicates a missing - * entry. + * The entry in 'name' table identifying a PostScript name for this + * instance. Value 0xFFFF indicates a missing entry. */ typedef struct FT_Var_Named_Style_ { @@ -211,48 +205,40 @@ FT_BEGIN_HEADER * FT_MM_Var * * @description: - * A structure to model the axes and space of an Adobe MM, TrueType - * GX, or OpenType variation font. + * A structure to model the axes and space of an Adobe MM, TrueType GX, + * or OpenType variation font. * * Some fields are specific to one format and not to the others. * * @fields: * num_axis :: - * The number of axes. The maximum value is~4 for - * Adobe MM fonts; no limit in TrueType GX or - * OpenType variation fonts. + * The number of axes. The maximum value is~4 for Adobe MM fonts; no + * limit in TrueType GX or OpenType variation fonts. * * num_designs :: - * The number of designs; should be normally - * 2^num_axis for Adobe MM fonts. Not meaningful - * for TrueType GX or OpenType variation fonts - * (where every glyph could have a different - * number of designs). + * The number of designs; should be normally 2^num_axis for Adobe MM + * fonts. Not meaningful for TrueType GX or OpenType variation fonts + * (where every glyph could have a different number of designs). * * num_namedstyles :: - * The number of named styles; a `named style' is - * a tuple of design coordinates that has a string - * ID (in the `name' table) associated with it. - * The font can tell the user that, for example, - * [Weight=1.5,Width=1.1] is `Bold'. Another name - * for `named style' is `named instance'. + * The number of named styles; a 'named style' is a tuple of design + * coordinates that has a string ID (in the 'name' table) associated + * with it. The font can tell the user that, for example, + * [Weight=1.5,Width=1.1] is 'Bold'. Another name for 'named style' is + * 'named instance'. * - * For Adobe Multiple Masters fonts, this value is - * always zero because the format does not support - * named styles. + * For Adobe Multiple Masters fonts, this value is always zero because + * the format does not support named styles. * * axis :: - * An axis descriptor table. - * TrueType GX and OpenType variation fonts - * contain slightly more data than Adobe MM fonts. - * Memory management of this pointer is done - * internally by FreeType. + * An axis descriptor table. TrueType GX and OpenType variation fonts + * contain slightly more data than Adobe MM fonts. Memory management + * of this pointer is done internally by FreeType. * * namedstyle :: - * A named style (instance) table. - * Only meaningful for TrueType GX and OpenType - * variation fonts. Memory management of this - * pointer is done internally by FreeType. + * A named style (instance) table. Only meaningful for TrueType GX and + * OpenType variation fonts. Memory management of this pointer is done + * internally by FreeType. */ typedef struct FT_MM_Var_ { @@ -308,9 +294,8 @@ FT_BEGIN_HEADER * * @output: * amaster :: - * The variation descriptor. - * Allocates a data structure, which the user must - * deallocate with a call to @FT_Done_MM_Var after use. + * The variation descriptor. Allocates a data structure, which the + * user must deallocate with a call to @FT_Done_MM_Var after use. * * @return: * FreeType error code. 0~means success. @@ -330,8 +315,8 @@ FT_BEGIN_HEADER * * @input: * library :: - * A handle of the face's parent library object that was - * used in the call to @FT_Get_MM_Var to create `amaster'. + * A handle of the face's parent library object that was used in the + * call to @FT_Get_MM_Var to create 'amaster'. * * @return: * FreeType error code. 0~means success. @@ -347,8 +332,8 @@ FT_BEGIN_HEADER * FT_Set_MM_Design_Coordinates * * @description: - * For Adobe MM fonts, choose an interpolated font design through - * design coordinates. + * For Adobe MM fonts, choose an interpolated font design through design + * coordinates. * * This function can't be used with TrueType GX or OpenType variation * fonts. @@ -359,10 +344,9 @@ FT_BEGIN_HEADER * * @input: * num_coords :: - * The number of available design coordinates. If it - * is larger than the number of axes, ignore the excess - * values. If it is smaller than the number of axes, - * use default values for the remaining axes. + * The number of available design coordinates. If it is larger than + * the number of axes, ignore the excess values. If it is smaller than + * the number of axes, use default values for the remaining axes. * * coords :: * An array of design coordinates. @@ -372,12 +356,12 @@ FT_BEGIN_HEADER * * @note: * [Since 2.8.1] To reset all axes to the default values, call the - * function with `num_coords' set to zero and `coords' set to NULL. + * function with `num_coords` set to zero and 'coords' set to NULL. * - * [Since 2.9] If `num_coords' is larger than zero, this function - * sets the @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags' - * field (i.e., @FT_IS_VARIATION will return true). If `num_coords' - * is zero, this bit flag gets unset. + * [Since 2.9] If `num_coords` is larger than zero, this function sets + * the @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags` field + * (i.e., @FT_IS_VARIATION will return true). If `num_coords` is zero, + * this bit flag gets unset. */ FT_EXPORT( FT_Error ) FT_Set_MM_Design_Coordinates( FT_Face face, @@ -401,10 +385,9 @@ FT_BEGIN_HEADER * * @input: * num_coords :: - * The number of available design coordinates. If it - * is larger than the number of axes, ignore the excess - * values. If it is smaller than the number of axes, - * use default values for the remaining axes. + * The number of available design coordinates. If it is larger than + * the number of axes, ignore the excess values. If it is smaller than + * the number of axes, use default values for the remaining axes. * * coords :: * An array of design coordinates. @@ -414,14 +397,14 @@ FT_BEGIN_HEADER * * @note: * [Since 2.8.1] To reset all axes to the default values, call the - * function with `num_coords' set to zero and `coords' set to NULL. - * [Since 2.9] `Default values' means the currently selected named + * function with `num_coords` set to zero and 'coords' set to NULL. + * [Since 2.9] 'Default values' means the currently selected named * instance (or the base font if no named instance is selected). * - * [Since 2.9] If `num_coords' is larger than zero, this function - * sets the @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags' - * field (i.e., @FT_IS_VARIATION will return true). If `num_coords' - * is zero, this bit flag gets unset. + * [Since 2.9] If `num_coords` is larger than zero, this function sets + * the @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags` field + * (i.e., @FT_IS_VARIATION will return true). If `num_coords` is zero, + * this bit flag gets unset. */ FT_EXPORT( FT_Error ) FT_Set_Var_Design_Coordinates( FT_Face face, @@ -445,9 +428,8 @@ FT_BEGIN_HEADER * A handle to the source face. * * num_coords :: - * The number of design coordinates to retrieve. If it - * is larger than the number of axes, set the excess - * values to~0. + * The number of design coordinates to retrieve. If it is larger than + * the number of axes, set the excess values to~0. * * @output: * coords :: @@ -482,30 +464,28 @@ FT_BEGIN_HEADER * * @input: * num_coords :: - * The number of available design coordinates. If it - * is larger than the number of axes, ignore the excess - * values. If it is smaller than the number of axes, - * use default values for the remaining axes. + * The number of available design coordinates. If it is larger than + * the number of axes, ignore the excess values. If it is smaller than + * the number of axes, use default values for the remaining axes. * * coords :: - * The design coordinates array (each element must be - * between 0 and 1.0 for Adobe MM fonts, and between - * -1.0 and 1.0 for TrueType GX and OpenType variation - * fonts). + * The design coordinates array (each element must be between 0 and 1.0 + * for Adobe MM fonts, and between -1.0 and 1.0 for TrueType GX and + * OpenType variation fonts). * * @return: * FreeType error code. 0~means success. * * @note: * [Since 2.8.1] To reset all axes to the default values, call the - * function with `num_coords' set to zero and `coords' set to NULL. - * [Since 2.9] `Default values' means the currently selected named + * function with `num_coords` set to zero and 'coords' set to NULL. + * [Since 2.9] 'Default values' means the currently selected named * instance (or the base font if no named instance is selected). * - * [Since 2.9] If `num_coords' is larger than zero, this function - * sets the @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags' - * field (i.e., @FT_IS_VARIATION will return true). If `num_coords' - * is zero, this bit flag gets unset. + * [Since 2.9] If `num_coords` is larger than zero, this function sets + * the @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags` field + * (i.e., @FT_IS_VARIATION will return true). If `num_coords` is zero, + * this bit flag gets unset. */ FT_EXPORT( FT_Error ) FT_Set_MM_Blend_Coordinates( FT_Face face, @@ -529,10 +509,10 @@ FT_BEGIN_HEADER * A handle to the source face. * * num_coords :: - * The number of normalized blend coordinates to - * retrieve. If it is larger than the number of axes, - * set the excess values to~0.5 for Adobe MM fonts, and - * to~0 for TrueType GX and OpenType variation fonts. + * The number of normalized blend coordinates to retrieve. If it is + * larger than the number of axes, set the excess values to~0.5 for + * Adobe MM fonts, and to~0 for TrueType GX and OpenType variation + * fonts. * * @output: * coords :: @@ -606,9 +586,9 @@ FT_BEGIN_HEADER * FT_Get_Var_Axis_Flags * * @description: - * Get the `flags' field of an OpenType Variation Axis Record. + * Get the 'flags' field of an OpenType Variation Axis Record. * - * Not meaningful for Adobe MM fonts (`*flags' is always zero). + * Not meaningful for Adobe MM fonts ('*flags' is always zero). * * @input: * master :: @@ -619,8 +599,7 @@ FT_BEGIN_HEADER * * @output: * flags :: - * The `flags' field. See @FT_VAR_AXIS_FLAG_XXX for - * possible values. + * The 'flags' field. See @FT_VAR_AXIS_FLAG_XXX for possible values. * * @return: * FreeType error code. 0~means success. @@ -647,23 +626,22 @@ FT_BEGIN_HEADER * A handle to the source face. * * instance_index :: - * The index of the requested instance, starting - * with value 1. If set to value 0, FreeType - * switches to font access without a named + * The index of the requested instance, starting with value 1. If set + * to value 0, FreeType switches to font access without a named * instance. * * @return: * FreeType error code. 0~means success. * * @note: - * The function uses the value of `instance_index' to set bits 16-30 - * of the face's `face_index' field. It also resets any variation - * applied to the font, and the @FT_FACE_FLAG_VARIATION bit of the - * face's `face_flags' field gets reset to zero (i.e., - * @FT_IS_VARIATION will return false). - * - * For Adobe MM fonts (which don't have named instances) this - * function simply resets the current face to the default instance. + * The function uses the value of `instance_index` to set bits 16-30 of + * the face's `face_index` field. It also resets any variation applied + * to the font, and the @FT_FACE_FLAG_VARIATION bit of the face's + * `face_flags` field gets reset to zero (i.e., @FT_IS_VARIATION will + * return false). + * + * For Adobe MM fonts (which don't have named instances) this function + * simply resets the current face to the default instance. * * @since: * 2.9 diff --git a/include/freetype/ftmodapi.h b/include/freetype/ftmodapi.h index c50c9ce40..7bf643531 100644 --- a/include/freetype/ftmodapi.h +++ b/include/freetype/ftmodapi.h @@ -46,13 +46,13 @@ FT_BEGIN_HEADER * * @description: * The definitions below are used to manage modules within FreeType. - * Modules can be added, upgraded, and removed at runtime. - * Additionally, some module properties can be controlled also. + * Modules can be added, upgraded, and removed at runtime. Additionally, + * some module properties can be controlled also. * - * Here is a list of possible values of the `module_name' field in - * the @FT_Module_Class structure. + * Here is a list of possible values of the `module_name` field in the + * @FT_Module_Class structure. * - * { + * ``` * autofitter * bdf * cff @@ -71,7 +71,7 @@ FT_BEGIN_HEADER * type42 * t1cid * winfonts - * } + * ``` * * Note that the FreeType Cache sub-system is not a FreeType module. * @@ -195,9 +195,9 @@ FT_BEGIN_HEADER * FT_Module_Class * * @description: - * The module class descriptor. While being a public structure - * necessary for FreeType's module bookkeeping, most of the fields are - * essentially internal, not to be used directly by an application. + * The module class descriptor. While being a public structure necessary + * for FreeType's module bookkeeping, most of the fields are essentially + * internal, not to be used directly by an application. * * @fields: * module_flags :: @@ -219,7 +219,7 @@ FT_BEGIN_HEADER * module_interface :: * A typeless pointer to a structure (which varies between different * modules) that holds the module's interface functions. This is - * essentially what `get_interface' returns. + * essentially what `get_interface` returns. * * module_init :: * The initializing function. @@ -267,8 +267,8 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * 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. + * 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. */ FT_EXPORT( FT_Error ) FT_Add_Module( FT_Library library, @@ -352,37 +352,35 @@ FT_BEGIN_HEADER * * value :: * A generic pointer to a variable or structure that gives the new - * value of the property. The exact definition of `value' is + * value of the property. The exact definition of 'value' is * dependent on the property; see section @properties. * * @return: * FreeType error code. 0~means success. * * @note: - * If `module_name' isn't a valid module name, or `property_name' - * doesn't specify a valid property, or if `value' doesn't represent a + * If `module_name` isn't a valid module name, or `property_name` + * doesn't specify a valid property, or if 'value' doesn't represent a * valid value for the given property, an error is returned. * - * The following example sets property `bar' (a simple integer) in - * module `foo' to value~1. + * The following example sets property 'bar' (a simple integer) in + * module 'foo' to value~1. * - * { + * ``` * FT_UInt bar; * * * bar = 1; * FT_Property_Set( library, "foo", "bar", &bar ); - * } + * ``` * * Note that the FreeType Cache sub-system doesn't recognize module * property changes. To avoid glyph lookup confusion within the cache - * you should call @FTC_Manager_Reset to completely flush the cache if - * a module property gets changed after @FTC_Manager_New has been - * called. + * you should call @FTC_Manager_Reset to completely flush the cache if a + * module property gets changed after @FTC_Manager_New has been called. * - * It is not possible to set properties of the FreeType Cache - * sub-system itself with FT_Property_Set; use @FTC_Property_Set - * instead. + * It is not possible to set properties of the FreeType Cache sub-system + * itself with FT_Property_Set; use @FTC_Property_Set instead. * * @since: * 2.4.11 @@ -416,21 +414,21 @@ FT_BEGIN_HEADER * * @inout: * value :: - * A generic pointer to a variable or structure that gives the - * value of the property. The exact definition of `value' is - * dependent on the property; see section @properties. + * A generic pointer to a variable or structure that gives the value + * of the property. The exact definition of 'value' is dependent on + * the property; see section @properties. * * @return: * FreeType error code. 0~means success. * * @note: - * If `module_name' isn't a valid module name, or `property_name' - * doesn't specify a valid property, or if `value' doesn't represent a + * If `module_name` isn't a valid module name, or `property_name` + * doesn't specify a valid property, or if 'value' doesn't represent a * valid value for the given property, an error is returned. * - * The following example gets property `baz' (a range) in module `foo'. + * The following example gets property 'baz' (a range) in module 'foo'. * - * { + * ``` * typedef range_ * { * FT_Int32 min; @@ -442,7 +440,7 @@ FT_BEGIN_HEADER * * * FT_Property_Get( library, "foo", "baz", &baz ); - * } + * ``` * * It is not possible to retrieve properties of the FreeType Cache * sub-system with FT_Property_Get; use @FTC_Property_Get instead. @@ -464,17 +462,16 @@ FT_BEGIN_HEADER * FT_Set_Default_Properties * * @description: - * If compilation option FT_CONFIG_OPTION_ENVIRONMENT_PROPERTIES is - * set, this function reads the `FREETYPE_PROPERTIES' environment - * variable to control driver properties. See section @properties - * for more. + * If compilation option FT_CONFIG_OPTION_ENVIRONMENT_PROPERTIES is set, + * this function reads the `FREETYPE_PROPERTIES` environment variable to + * control driver properties. See section @properties for more. * * If the compilation option is not set, this function does nothing. * - * `FREETYPE_PROPERTIES' has the following syntax form (broken here - * into multiple lines for better readability). + * `FREETYPE_PROPERTIES` has the following syntax form (broken here into + * multiple lines for better readability). * - * { + * ``` * <optional whitespace> * <module-name1> ':' * <property-name1> '=' <property-value1> @@ -482,15 +479,15 @@ FT_BEGIN_HEADER * <module-name2> ':' * <property-name2> '=' <property-value2> * ... - * } + * ``` * * Example: * - * { + * ``` * FREETYPE_PROPERTIES=truetype:interpreter-version=35 \ * cff:no-stem-darkening=1 \ * autofitter:warping=1 - * } + * ``` * * @inout: * library :: @@ -509,10 +506,10 @@ FT_BEGIN_HEADER * FT_Reference_Library * * @description: - * A counter gets initialized to~1 at the time an @FT_Library - * structure is created. This function increments the counter. - * @FT_Done_Library then only destroys a library if the counter is~1, - * otherwise it simply decrements the counter. + * A counter gets initialized to~1 at the time an @FT_Library structure + * is created. This function increments the counter. @FT_Done_Library + * then only destroys a library if the counter is~1, otherwise it simply + * decrements the counter. * * This function helps in managing life-cycles of structures that * reference @FT_Library objects. @@ -537,19 +534,19 @@ FT_BEGIN_HEADER * FT_New_Library * * @description: - * This function is used to create a new FreeType library instance - * from a given memory object. It is thus possible to use libraries - * with distinct memory allocators within the same program. Note, - * however, that the used @FT_Memory structure is expected to remain - * valid for the life of the @FT_Library object. + * This function is used to create a new FreeType library instance from a + * given memory object. It is thus possible to use libraries with + * distinct memory allocators within the same program. Note, however, + * that the used @FT_Memory structure is expected to remain valid for the + * life of the @FT_Library object. * * Normally, you would call this function (followed by a call to - * @FT_Add_Default_Modules or a series of calls to @FT_Add_Module, - * and a call to @FT_Set_Default_Properties) instead of - * @FT_Init_FreeType to initialize the FreeType library. + * @FT_Add_Default_Modules or a series of calls to @FT_Add_Module, and a + * call to @FT_Set_Default_Properties) instead of @FT_Init_FreeType to + * initialize the FreeType library. * - * Don't use @FT_Done_FreeType but @FT_Done_Library to destroy a - * library instance. + * Don't use @FT_Done_FreeType but @FT_Done_Library to destroy a library + * instance. * * @input: * memory :: @@ -577,8 +574,8 @@ FT_BEGIN_HEADER * FT_Done_Library * * @description: - * Discard a given library object. This closes all drivers and - * discards all resource objects. + * Discard a given library object. This closes all drivers and discards + * all resource objects. * * @input: * library :: @@ -615,20 +612,19 @@ 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'. + * The index of the debug hook. You should use the values defined in + * `ftobjs.h`, e.g., `FT_DEBUG_HOOK_TRUETYPE`. * * debug_hook :: * The function used to debug the interpreter. * * @note: - * Currently, four debug hook slots are available, but only two (for - * the TrueType and the Type~1 interpreter) are defined. + * 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. + * 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, @@ -642,9 +638,9 @@ FT_BEGIN_HEADER * FT_Add_Default_Modules * * @description: - * Add 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). + * Add 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). * * @inout: * library :: @@ -679,9 +675,9 @@ FT_BEGIN_HEADER * FT_TrueTypeEngineType * * @description: - * 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. + * 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. * * @values: * FT_TRUETYPE_ENGINE_TYPE_NONE :: @@ -691,9 +687,9 @@ FT_BEGIN_HEADER * Deprecated and removed. * * FT_TRUETYPE_ENGINE_TYPE_PATENTED :: - * The library implements a bytecode interpreter that covers - * the full instruction set of the TrueType virtual machine (this - * was governed by patents until May 2010, hence the name). + * The library implements a bytecode interpreter that covers the full + * instruction set of the TrueType virtual machine (this was governed + * by patents until May 2010, hence the name). * * @since: * 2.2 @@ -714,8 +710,8 @@ FT_BEGIN_HEADER * FT_Get_TrueType_Engine_Type * * @description: - * Return an @FT_TrueTypeEngineType value to indicate which level of - * the TrueType virtual machine a given library instance supports. + * Return an @FT_TrueTypeEngineType value to indicate which level of the + * TrueType virtual machine a given library instance supports. * * @input: * library :: diff --git a/include/freetype/ftmoderr.h b/include/freetype/ftmoderr.h index 661b0da0e..af651c225 100644 --- a/include/freetype/ftmoderr.h +++ b/include/freetype/ftmoderr.h @@ -20,26 +20,25 @@ * * This file is used to define the FreeType module error codes. * - * If the macro FT_CONFIG_OPTION_USE_MODULE_ERRORS in `ftoption.h' is - * set, the lower byte of an error value identifies the error code as - * usual. In addition, the higher byte identifies the module. For - * example, the error `FT_Err_Invalid_File_Format' has value 0x0003, the - * error `TT_Err_Invalid_File_Format' has value 0x1303, the error - * `T1_Err_Invalid_File_Format' has value 0x1403, etc. - * - * Note that `FT_Err_Ok', `TT_Err_Ok', etc. are always equal to zero, + * If the macro FT_CONFIG_OPTION_USE_MODULE_ERRORS in `ftoption.h` is set, + * the lower byte of an error value identifies the error code as usual. In + * addition, the higher byte identifies the module. For example, the error + * `FT_Err_Invalid_File_Format` has value 0x0003, the error + * `TT_Err_Invalid_File_Format` has value 0x1303, the error + * `T1_Err_Invalid_File_Format` has value 0x1403, etc. + * + * Note that `FT_Err_Ok`, `TT_Err_Ok`, etc. are always equal to zero, * including the high byte. * - * If FT_CONFIG_OPTION_USE_MODULE_ERRORS isn't set, the higher byte of - * an error value is set to zero. + * If FT_CONFIG_OPTION_USE_MODULE_ERRORS isn't set, the higher byte of an + * error value is set to zero. * - * To hide the various `XXX_Err_' prefixes in the source code, FreeType - * provides some macros in `fttypes.h'. + * To hide the various `XXX_Err_` prefixes in the source code, FreeType + * provides some macros in `fttypes.h`. * * FT_ERR( err ) - * Add current error module prefix (as defined with the - * `FT_ERR_PREFIX' macro) to `err'. For example, in the BDF module - * the line + * Add current error module prefix (as defined with the `FT_ERR_PREFIX` + * macro) to 'err'. For example, in the BDF module the line * * error = FT_ERR( Invalid_Outline ); * @@ -47,33 +46,31 @@ * * error = BDF_Err_Invalid_Outline; * - * For simplicity, you can always use `FT_Err_Ok' directly instead - * of `FT_ERR( Ok )'. + * For simplicity, you can always use `FT_Err_Ok` directly instead of + * 'FT_ERR( Ok )'. * - * FT_ERR_EQ( errcode, err ) - * FT_ERR_NEQ( errcode, err ) - * Compare error code `errcode' with the error `err' for equality - * and inequality, respectively. Example: + * FT_ERR_EQ( errcode, err ) FT_ERR_NEQ( errcode, err ) + * Compare error code 'errcode' with the error 'err' for equality and + * inequality, respectively. Example: * * if ( FT_ERR_EQ( error, Invalid_Outline ) ) * ... * - * Using this macro you don't have to think about error prefixes. - * Of course, if module errors are not active, the above example is - * the same as + * Using this macro you don't have to think about error prefixes. Of + * course, if module errors are not active, the above example is the + * same as * * if ( error == FT_Err_Invalid_Outline ) * ... * - * FT_ERROR_BASE( errcode ) - * FT_ERROR_MODULE( errcode ) + * FT_ERROR_BASE( errcode ) FT_ERROR_MODULE( errcode ) * Get base error and module error code, respectively. * * - * It can also be used to create a module error message table easily - * with something like + * It can also be used to create a module error message table easily with + * something like * - * { + * ``` * #undef FTMODERR_H_ * #define FT_MODERRDEF( e, v, s ) { FT_Mod_Err_ ## e, s }, * #define FT_MODERR_START_LIST { @@ -86,7 +83,7 @@ * } ft_mod_errors[] = * * #include FT_MODULE_ERRORS_H - * } + * ``` * */ diff --git a/include/freetype/ftotval.h b/include/freetype/ftotval.h index 698b429a1..20d33e0b6 100644 --- a/include/freetype/ftotval.h +++ b/include/freetype/ftotval.h @@ -55,8 +55,8 @@ FT_BEGIN_HEADER * An API to validate OpenType tables. * * @description: - * This section contains the declaration of functions to validate - * some OpenType tables (BASE, GDEF, GPOS, GSUB, JSTF, MATH). + * This section contains the declaration of functions to validate some + * OpenType tables (BASE, GDEF, GPOS, GSUB, JSTF, MATH). * * @order: * FT_OpenType_Validate @@ -122,8 +122,8 @@ FT_BEGIN_HEADER * @description: * Validate various OpenType tables to assure that all offsets and * indices are valid. The idea is that a higher-level library that - * actually does the text layout can access those tables without - * error checking (which can be quite time consuming). + * actually does the text layout can access those tables without error + * checking (which can be quite time consuming). * * @input: * face :: diff --git a/include/freetype/ftoutln.h b/include/freetype/ftoutln.h index 9dae104de..bbab07c80 100644 --- a/include/freetype/ftoutln.h +++ b/include/freetype/ftoutln.h @@ -47,7 +47,7 @@ FT_BEGIN_HEADER * * @description: * This section contains routines used to create and destroy scalable - * glyph images known as `outlines'. These can also be measured, + * glyph images known as 'outlines'. These can also be measured, * transformed, and converted into bitmaps and pixmaps. * * @order: @@ -89,7 +89,7 @@ FT_BEGIN_HEADER * * @description: * Walk over an outline's structure to decompose it into individual - * segments and Bezier arcs. This function also emits `move to' + * segments and Bezier arcs. This function also emits 'move to' * operations to indicate the start of new contours in the outline. * * @input: @@ -97,30 +97,28 @@ FT_BEGIN_HEADER * A pointer to the source target. * * func_interface :: - * A table of `emitters', i.e., function pointers - * called during decomposition to indicate path - * operations. + * A table of 'emitters', i.e., function pointers called during + * decomposition to indicate path operations. * * @inout: * user :: - * A typeless pointer that is passed to each - * emitter during the decomposition. It can be - * used to store the state during the + * A typeless pointer that is passed to each emitter during the + * decomposition. It can be used to store the state during the * decomposition. * * @return: * FreeType error code. 0~means success. * * @note: - * A contour that contains a single point only is represented by a - * `move to' operation followed by `line to' to the same point. In - * most cases, it is best to filter this out before using the - * outline for stroking purposes (otherwise it would result in a - * visible dot when round caps are used). + * A contour that contains a single point only is represented by a 'move + * to' operation followed by 'line to' to the same point. In most cases, + * it is best to filter this out before using the outline for stroking + * purposes (otherwise it would result in a visible dot when round caps + * are used). * * Similarly, the function returns success for an empty outline also - * (doing nothing, this is, not calling any emitter); if necessary, - * you should filter this out, too. + * (doing nothing, this is, not calling any emitter); if necessary, you + * should filter this out, too. */ FT_EXPORT( FT_Error ) FT_Outline_Decompose( FT_Outline* outline, @@ -138,18 +136,17 @@ FT_BEGIN_HEADER * * @input: * library :: - * A handle to the library object from where the - * outline is allocated. Note however that the new - * outline will *not* necessarily be *freed*, when - * destroying the library, by @FT_Done_FreeType. + * A handle to the library object from where the outline is allocated. + * Note however that the new outline will **not** necessarily be + * **freed**, when destroying the library, by @FT_Done_FreeType. * * numPoints :: - * The maximum number of points within the outline. - * Must be smaller than or equal to 0xFFFF (65535). + * The maximum number of points within the outline. Must be smaller + * than or equal to 0xFFFF (65535). * * numContours :: - * The maximum number of contours within the outline. - * This value must be in the range 0 to `numPoints'. + * The maximum number of contours within the outline. This value must + * be in the range 0 to `numPoints`. * * @output: * anoutline :: @@ -159,8 +156,8 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * The reason why this function takes a `library' parameter is simply - * to use the library's memory allocator. + * The reason why this function takes a 'library' parameter is simply to + * use the library's memory allocator. */ FT_EXPORT( FT_Error ) FT_Outline_New( FT_Library library, @@ -186,8 +183,7 @@ FT_BEGIN_HEADER * * @input: * library :: - * A handle of the library object used to allocate the - * outline. + * A handle of the library object used to allocate the outline. * * outline :: * A pointer to the outline object to be discarded. @@ -196,8 +192,8 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * If the outline's `owner' field is not set, only the outline - * descriptor will be released. + * If the outline's 'owner' field is not set, only the outline descriptor + * will be released. */ FT_EXPORT( FT_Error ) FT_Outline_Done( FT_Library library, @@ -238,16 +234,16 @@ FT_BEGIN_HEADER * FT_Outline_Get_CBox * * @description: - * Return an outline's `control box'. The control box encloses all - * the outline's points, including Bezier control points. Though it + * Return an outline's 'control box'. The control box encloses all the + * outline's points, including Bezier control points. Though it * coincides with the exact bounding box for most glyphs, it can be - * slightly larger in some situations (like when rotating an outline - * that contains Bezier outside arcs). + * slightly larger in some situations (like when rotating an outline that + * contains Bezier outside arcs). * - * Computing the control box is very fast, while getting the bounding - * box can take much more time as it needs to walk over all segments - * and arcs in the outline. To get the latter, you can use the - * `ftbbox' component, which is dedicated to this single task. + * Computing the control box is very fast, while getting the bounding box + * can take much more time as it needs to walk over all segments and arcs + * in the outline. To get the latter, you can use the 'ftbbox' + * component, which is dedicated to this single task. * * @input: * outline :: @@ -296,9 +292,9 @@ FT_BEGIN_HEADER * FT_Outline_Copy * * @description: - * Copy an outline into another one. Both objects must have the - * same sizes (number of points & number of contours) when this - * function is called. + * Copy an outline into another one. Both objects must have the same + * sizes (number of points & number of contours) when this function is + * called. * * @input: * source :: @@ -322,8 +318,8 @@ FT_BEGIN_HEADER * FT_Outline_Transform * * @description: - * Apply a simple 2x2 matrix to all of an outline's points. Useful - * for applying rotations, slanting, flipping, etc. + * Apply a simple 2x2 matrix to all of an outline's points. Useful for + * applying rotations, slanting, flipping, etc. * * @inout: * outline :: @@ -349,10 +345,10 @@ FT_BEGIN_HEADER * * @description: * Embolden an outline. The new outline will be at most 4~times - * `strength' pixels wider and higher. You may think of the left and + * 'strength' pixels wider and higher. You may think of the left and * bottom borders as unchanged. * - * Negative `strength' values to reduce the outline thickness are + * Negative 'strength' values to reduce the outline thickness are * possible also. * * @inout: @@ -361,31 +357,30 @@ FT_BEGIN_HEADER * * @input: * strength :: - * How strong the glyph is emboldened. Expressed in - * 26.6 pixel format. + * How strong the glyph is emboldened. Expressed in 26.6 pixel format. * * @return: * FreeType error code. 0~means success. * * @note: - * The used algorithm to increase or decrease the thickness of the - * glyph doesn't change the number of points; this means that certain - * situations like acute angles or intersections are sometimes - * handled incorrectly. + * The used algorithm to increase or decrease the thickness of the glyph + * doesn't change the number of points; this means that certain + * situations like acute angles or intersections are sometimes handled + * incorrectly. * - * If you need `better' metrics values you should call + * If you need 'better' metrics values you should call * @FT_Outline_Get_CBox or @FT_Outline_Get_BBox. * * To get meaningful results, font scaling values must be set with * functions like @FT_Set_Char_Size before calling FT_Render_Glyph. * * @example: - * { + * ``` * FT_Load_Glyph( face, index, FT_LOAD_DEFAULT ); * * if ( face->glyph->format == FT_GLYPH_FORMAT_OUTLINE ) * FT_Outline_Embolden( &face->glyph->outline, strength ); - * } + * ``` * */ FT_EXPORT( FT_Error ) @@ -399,10 +394,9 @@ FT_BEGIN_HEADER * FT_Outline_EmboldenXY * * @description: - * Embolden an outline. The new outline will be `xstrength' pixels - * wider and `ystrength' pixels higher. Otherwise, it is similar to - * @FT_Outline_Embolden, which uses the same strength in both - * directions. + * Embolden an outline. The new outline will be 'xstrength' pixels wider + * and 'ystrength' pixels higher. Otherwise, it is similar to + * @FT_Outline_Embolden, which uses the same strength in both directions. * * @since: * 2.4.10 @@ -419,19 +413,19 @@ FT_BEGIN_HEADER * FT_Outline_Reverse * * @description: - * Reverse the drawing direction of an outline. This is used to - * ensure consistent fill conventions for mirrored glyphs. + * Reverse the drawing direction of an outline. This is used to ensure + * consistent fill conventions for mirrored glyphs. * * @inout: * outline :: * A pointer to the target outline descriptor. * * @note: - * This function toggles the bit flag @FT_OUTLINE_REVERSE_FILL in - * the outline's `flags' field. + * This function toggles the bit flag @FT_OUTLINE_REVERSE_FILL in the + * outline's 'flags' field. * - * It shouldn't be used by a normal client application, unless it - * knows what it is doing. + * It shouldn't be used by a normal client application, unless it knows + * what it is doing. */ FT_EXPORT( void ) FT_Outline_Reverse( FT_Outline* outline ); @@ -461,15 +455,15 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * This function does NOT CREATE the bitmap, it only renders an - * outline image within the one you pass to it! Consequently, the - * various fields in `abitmap' should be set accordingly. + * This function does NOT CREATE the bitmap, it only renders an outline + * image within the one you pass to it! Consequently, the various fields + * in 'abitmap' should be set accordingly. * * It will use the raster corresponding to the default glyph format. * - * The value of the `num_grays' field in `abitmap' is ignored. If - * you select the gray-level rasterizer, and you want less than 256 - * gray levels, you have to use @FT_Outline_Render directly. + * The value of the `num_grays` field in 'abitmap' is ignored. If you + * select the gray-level rasterizer, and you want less than 256 gray + * levels, you have to use @FT_Outline_Render directly. */ FT_EXPORT( FT_Error ) FT_Outline_Get_Bitmap( FT_Library library, @@ -485,8 +479,7 @@ FT_BEGIN_HEADER * @description: * Render an outline within a bitmap using the current scan-convert. * This function uses an @FT_Raster_Params structure as an argument, - * allowing advanced features like direct composition, translucency, - * etc. + * allowing advanced features like direct composition, translucency, etc. * * @input: * library :: @@ -497,23 +490,23 @@ FT_BEGIN_HEADER * * @inout: * params :: - * A pointer to an @FT_Raster_Params structure used to - * describe the rendering operation. + * A pointer to an @FT_Raster_Params structure used to describe the + * rendering operation. * * @return: * FreeType error code. 0~means success. * * @note: - * You should know what you are doing and how @FT_Raster_Params works - * to use this function. + * You should know what you are doing and how @FT_Raster_Params works to + * use this function. * - * The field `params.source' will be set to `outline' before the scan + * The field `params.source` will be set to 'outline' before the scan * converter is called, which means that the value you give to it is * actually ignored. * - * The gray-level rasterizer always uses 256 gray levels. If you - * want less gray levels, you have to provide your own span callback. - * See the @FT_RASTER_FLAG_DIRECT value of the `flags' field in the + * The gray-level rasterizer always uses 256 gray levels. If you want + * less gray levels, you have to provide your own span callback. See the + * @FT_RASTER_FLAG_DIRECT value of the 'flags' field in the * @FT_Raster_Params structure for more details. */ FT_EXPORT( FT_Error ) @@ -535,22 +528,22 @@ FT_BEGIN_HEADER * * @values: * FT_ORIENTATION_TRUETYPE :: - * According to the TrueType specification, clockwise contours must - * be filled, and counter-clockwise ones must be unfilled. + * According to the TrueType specification, clockwise contours must be + * filled, and counter-clockwise ones must be unfilled. * * FT_ORIENTATION_POSTSCRIPT :: - * According to the PostScript specification, counter-clockwise contours - * must be filled, and clockwise ones must be unfilled. + * According to the PostScript specification, counter-clockwise + * contours must be filled, and clockwise ones must be unfilled. * * FT_ORIENTATION_FILL_RIGHT :: * This is identical to @FT_ORIENTATION_TRUETYPE, but is used to - * remember that in TrueType, everything that is to the right of - * the drawing direction of a contour must be filled. + * remember that in TrueType, everything that is to the right of the + * drawing direction of a contour must be filled. * * FT_ORIENTATION_FILL_LEFT :: * This is identical to @FT_ORIENTATION_POSTSCRIPT, but is used to - * remember that in PostScript, everything that is to the left of - * the drawing direction of a contour must be filled. + * remember that in PostScript, everything that is to the left of the + * drawing direction of a contour must be filled. * * FT_ORIENTATION_NONE :: * The orientation cannot be determined. That is, different parts of @@ -574,11 +567,11 @@ FT_BEGIN_HEADER * FT_Outline_Get_Orientation * * @description: - * This function analyzes a glyph outline and tries to compute its - * fill orientation (see @FT_Orientation). This is done by integrating - * the total area covered by the outline. The positive integral - * corresponds to the clockwise orientation and @FT_ORIENTATION_POSTSCRIPT - * is returned. The negative integral corresponds to the counter-clockwise + * This function analyzes a glyph outline and tries to compute its fill + * orientation (see @FT_Orientation). This is done by integrating the + * total area covered by the outline. The positive integral corresponds + * to the clockwise orientation and @FT_ORIENTATION_POSTSCRIPT is + * returned. The negative integral corresponds to the counter-clockwise * orientation and @FT_ORIENTATION_TRUETYPE is returned. * * Note that this will return @FT_ORIENTATION_TRUETYPE for empty diff --git a/include/freetype/ftparams.h b/include/freetype/ftparams.h index 004eaf5bf..cb6ac109a 100644 --- a/include/freetype/ftparams.h +++ b/include/freetype/ftparams.h @@ -58,9 +58,9 @@ FT_BEGIN_HEADER * * @description: * A tag for @FT_Parameter to make @FT_Open_Face ignore typographic - * family names in the `name' table (introduced in OpenType version - * 1.4). Use this for backward compatibility with legacy systems that - * have a four-faces-per-family restriction. + * family names in the 'name' table (introduced in OpenType version 1.4). + * Use this for backward compatibility with legacy systems that have a + * four-faces-per-family restriction. * * @since: * 2.8 @@ -82,7 +82,7 @@ FT_BEGIN_HEADER * * @description: * A tag for @FT_Parameter to make @FT_Open_Face ignore typographic - * subfamily names in the `name' table (introduced in OpenType version + * subfamily names in the 'name' table (introduced in OpenType version * 1.4). Use this for backward compatibility with legacy systems that * have a four-faces-per-family restriction. * @@ -121,8 +121,8 @@ FT_BEGIN_HEADER * @description: * An @FT_Parameter tag to be used with @FT_Face_Properties. The * corresponding argument specifies the five LCD filter weights for a - * given face (if using @FT_LOAD_TARGET_LCD, for example), overriding - * the global default values or the values set up with + * given face (if using @FT_LOAD_TARGET_LCD, for example), overriding the + * global default values or the values set up with * @FT_Library_SetLcdFilterWeights. * * @since: @@ -141,8 +141,7 @@ FT_BEGIN_HEADER * @description: * An @FT_Parameter tag to be used with @FT_Face_Properties. The * corresponding 32bit signed integer argument overrides the font - * driver's random seed value with a face-specific one; see - * @random-seed. + * driver's random seed value with a face-specific one; see @random-seed. * * @since: * 2.8 @@ -163,10 +162,10 @@ FT_BEGIN_HEADER * darkening, overriding the global default values or the values set up * with @FT_Property_Set (see @no-stem-darkening). * - * This is a passive setting that only takes effect if the font driver - * or autohinter honors it, which the CFF, Type~1, and CID drivers - * always do, but the autohinter only in `light' hinting mode (as of - * version 2.9). + * This is a passive setting that only takes effect if the font driver or + * autohinter honors it, which the CFF, Type~1, and CID drivers always + * do, but the autohinter only in 'light' hinting mode (as of version + * 2.9). * * @since: * 2.8 @@ -184,9 +183,9 @@ FT_BEGIN_HEADER * @description: * Deprecated, no effect. * - * Previously: A constant used as the tag of an @FT_Parameter structure to - * indicate that unpatented methods only should be used by the TrueType - * bytecode interpreter for a typeface opened by @FT_Open_Face. + * Previously: A constant used as the tag of an @FT_Parameter structure + * to indicate that unpatented methods only should be used by the + * TrueType bytecode interpreter for a typeface opened by @FT_Open_Face. * */ #define FT_PARAM_TAG_UNPATENTED_HINTING \ diff --git a/include/freetype/ftpfr.h b/include/freetype/ftpfr.h index deaae6122..d68c28f85 100644 --- a/include/freetype/ftpfr.h +++ b/include/freetype/ftpfr.h @@ -63,21 +63,21 @@ FT_BEGIN_HEADER * * @output: * aoutline_resolution :: - * Outline resolution. This is equivalent to `face->units_per_EM' - * for non-PFR fonts. Optional (parameter can be NULL). + * Outline resolution. This is equivalent to `face->units_per_EM` for + * non-PFR fonts. Optional (parameter can be NULL). * * ametrics_resolution :: - * Metrics resolution. This is equivalent to `outline_resolution' - * for non-PFR fonts. Optional (parameter can be NULL). + * Metrics resolution. This is equivalent to `outline_resolution` for + * non-PFR fonts. Optional (parameter can be NULL). * * ametrics_x_scale :: - * A 16.16 fixed-point number used to scale distance expressed - * in metrics units to device subpixels. This is equivalent to - * `face->size->x_scale', but for metrics only. Optional (parameter + * A 16.16 fixed-point number used to scale distance expressed in + * metrics units to device subpixels. This is equivalent to + * `face->size->x_scale`, but for metrics only. Optional (parameter * can be NULL). * * ametrics_y_scale :: - * Same as `ametrics_x_scale' but for the vertical direction. + * Same as `ametrics_x_scale` but for the vertical direction. * optional (parameter can be NULL). * * @return: @@ -123,11 +123,11 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * This function always return distances in original PFR metrics - * units. This is unlike @FT_Get_Kerning with the @FT_KERNING_UNSCALED - * mode, which always returns distances converted to outline units. + * This function always return distances in original PFR metrics units. + * This is unlike @FT_Get_Kerning with the @FT_KERNING_UNSCALED mode, + * which always returns distances converted to outline units. * - * You can use the value of the `x_scale' and `y_scale' parameters + * You can use the value of the `x_scale` and `y_scale` parameters * returned by @FT_Get_PFR_Metrics to scale these to device subpixels. */ FT_EXPORT( FT_Error ) @@ -161,7 +161,7 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * You can use the `x_scale' or `y_scale' results of @FT_Get_PFR_Metrics + * You can use the `x_scale` or `y_scale` results of @FT_Get_PFR_Metrics * to convert the advance to device subpixels (i.e., 1/64th of pixels). */ FT_EXPORT( FT_Error ) diff --git a/include/freetype/ftrender.h b/include/freetype/ftrender.h index 2b7e5c840..74e83d014 100644 --- a/include/freetype/ftrender.h +++ b/include/freetype/ftrender.h @@ -132,12 +132,11 @@ FT_BEGIN_HEADER * The glyph image format this renderer handles. * * render_glyph :: - * A method used to render the image that is in a - * given glyph slot into a bitmap. + * A method used to render the image that is in a given glyph slot into + * a bitmap. * * transform_glyph :: - * A method used to transform the image that is in - * a given glyph slot. + * A method used to transform the image that is in a given glyph slot. * * get_glyph_cbox :: * A method used to access the glyph's cbox. @@ -146,8 +145,8 @@ FT_BEGIN_HEADER * A method used to pass additional parameters. * * raster_class :: - * For @FT_GLYPH_FORMAT_OUTLINE renderers only. - * This is a pointer to its raster's class. + * For @FT_GLYPH_FORMAT_OUTLINE renderers only. This is a pointer to + * its raster's class. */ typedef struct FT_Renderer_Class_ { @@ -184,8 +183,8 @@ FT_BEGIN_HEADER * A renderer handle. 0~if none found. * * @note: - * 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. + * 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. @@ -221,13 +220,13 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * In case of success, the renderer will be used to convert glyph - * images in the renderer's known format into bitmaps. + * In case of success, the renderer will be used to convert glyph images + * in the renderer's known format into bitmaps. * * This doesn't change the current renderer for other formats. * - * Currently, no FreeType renderer module uses `parameters'; you - * should thus always pass NULL as the value. + * Currently, no FreeType renderer module uses 'parameters'; you should + * thus always pass NULL as the value. */ FT_EXPORT( FT_Error ) FT_Set_Renderer( FT_Library library, diff --git a/include/freetype/ftsizes.h b/include/freetype/ftsizes.h index 481a053b1..0382c29cb 100644 --- a/include/freetype/ftsizes.h +++ b/include/freetype/ftsizes.h @@ -19,8 +19,8 @@ /************************************************************************** * * Typical application would normally not need to use these functions. - * However, they have been placed in a public API for the rare cases - * where they are needed. + * However, they have been placed in a public API for the rare cases where + * they are needed. * */ @@ -54,22 +54,20 @@ FT_BEGIN_HEADER * Managing multiple sizes per face. * * @description: - * When creating a new face object (e.g., with @FT_New_Face), an - * @FT_Size object is automatically created and used to store all - * pixel-size dependent information, available in the `face->size' - * field. + * When creating a new face object (e.g., with @FT_New_Face), an @FT_Size + * object is automatically created and used to store all pixel-size + * dependent information, available in the `face->size` field. * - * It is however possible to create more sizes for a given face, - * mostly in order to manage several character pixel sizes of the - * same font family and style. See @FT_New_Size and @FT_Done_Size. + * It is however possible to create more sizes for a given face, mostly + * in order to manage several character pixel sizes of the same font + * family and style. See @FT_New_Size and @FT_Done_Size. * - * Note that @FT_Set_Pixel_Sizes and @FT_Set_Char_Size only - * modify the contents of the current `active' size; you thus need - * to use @FT_Activate_Size to change it. + * Note that @FT_Set_Pixel_Sizes and @FT_Set_Char_Size only modify the + * contents of the current 'active' size; you thus need to use + * @FT_Activate_Size to change it. * - * 99% of applications won't need the functions provided here, - * especially if they use the caching sub-system, so be cautious - * when using these. + * 99% of applications won't need the functions provided here, especially + * if they use the caching sub-system, so be cautious when using these. * */ @@ -94,8 +92,8 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * You need to call @FT_Activate_Size in order to select the new size - * for upcoming calls to @FT_Set_Pixel_Sizes, @FT_Set_Char_Size, + * You need to call @FT_Activate_Size in order to select the new size for + * upcoming calls to @FT_Set_Pixel_Sizes, @FT_Set_Char_Size, * @FT_Load_Glyph, @FT_Load_Char, etc. */ FT_EXPORT( FT_Error ) @@ -109,9 +107,8 @@ FT_BEGIN_HEADER * FT_Done_Size * * @description: - * Discard a given size object. Note that @FT_Done_Face - * automatically discards all size objects allocated with - * @FT_New_Size. + * Discard a given size object. Note that @FT_Done_Face automatically + * discards all size objects allocated with @FT_New_Size. * * @input: * size :: @@ -130,12 +127,12 @@ FT_BEGIN_HEADER * FT_Activate_Size * * @description: - * Even though it is possible to create several size objects for a - * given face (see @FT_New_Size for details), functions like - * @FT_Load_Glyph or @FT_Load_Char only use the one that has been - * activated last to determine the `current character pixel size'. + * Even though it is possible to create several size objects for a given + * face (see @FT_New_Size for details), functions like @FT_Load_Glyph or + * @FT_Load_Char only use the one that has been activated last to + * determine the 'current character pixel size'. * - * This function can be used to `activate' a previously created size + * This function can be used to 'activate' a previously created size * object. * * @input: @@ -146,8 +143,8 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * If `face' is the size's parent face object, this function changes - * the value of `face->size' to the input size handle. + * If 'face' is the size's parent face object, this function changes the + * value of `face->size` to the input size handle. */ FT_EXPORT( FT_Error ) FT_Activate_Size( FT_Size size ); diff --git a/include/freetype/ftsnames.h b/include/freetype/ftsnames.h index 0a0ac31eb..4df787e8d 100644 --- a/include/freetype/ftsnames.h +++ b/include/freetype/ftsnames.h @@ -2,7 +2,7 @@ * * ftsnames.h * - * Simple interface to access SFNT `name' tables (which are used + * Simple interface to access SFNT 'name' tables (which are used * to hold font names, copyright info, notices, etc.) (specification). * * This is _not_ used to retrieve glyph names! @@ -49,10 +49,10 @@ FT_BEGIN_HEADER * Access the names embedded in TrueType and OpenType files. * * @description: - * The TrueType and OpenType specifications allow the inclusion of - * a special names table (`name') in font files. This table contains - * textual (and internationalized) information regarding the font, - * like family name, copyright, version, etc. + * The TrueType and OpenType specifications allow the inclusion of a + * special names table ('name') in font files. This table contains + * textual (and internationalized) information regarding the font, like + * family name, copyright, version, etc. * * The definitions below are used to access them if available. * @@ -67,43 +67,39 @@ FT_BEGIN_HEADER * FT_SfntName * * @description: - * A structure used to model an SFNT `name' table entry. + * A structure used to model an SFNT 'name' table entry. * * @fields: * platform_id :: - * The platform ID for `string'. - * See @TT_PLATFORM_XXX for possible values. + * The platform ID for 'string'. See @TT_PLATFORM_XXX for possible + * values. * * encoding_id :: - * The encoding ID for `string'. - * See @TT_APPLE_ID_XXX, @TT_MAC_ID_XXX, - * @TT_ISO_ID_XXX, @TT_MS_ID_XXX, and @TT_ADOBE_ID_XXX - * for possible values. + * The encoding ID for 'string'. See @TT_APPLE_ID_XXX, @TT_MAC_ID_XXX, + * @TT_ISO_ID_XXX, @TT_MS_ID_XXX, and @TT_ADOBE_ID_XXX for possible + * values. * * language_id :: - * The language ID for `string'. - * See @TT_MAC_LANGID_XXX and @TT_MS_LANGID_XXX for - * possible values. + * The language ID for 'string'. See @TT_MAC_LANGID_XXX and + * @TT_MS_LANGID_XXX for possible values. * - * Registered OpenType values for `language_id' are - * always smaller than 0x8000; values equal or larger - * than 0x8000 usually indicate a language tag string - * (introduced in OpenType version 1.6). Use function - * @FT_Get_Sfnt_LangTag with `language_id' as its - * argument to retrieve the associated language tag. + * Registered OpenType values for `language_id` are always smaller than + * 0x8000; values equal or larger than 0x8000 usually indicate a + * language tag string (introduced in OpenType version 1.6). Use + * function @FT_Get_Sfnt_LangTag with `language_id` as its argument to + * retrieve the associated language tag. * * name_id :: - * An identifier for `string'. - * See @TT_NAME_ID_XXX for possible values. + * An identifier for 'string'. See @TT_NAME_ID_XXX for possible + * values. * * string :: - * The `name' string. Note that its format differs - * depending on the (platform,encoding) pair, being - * either a string of bytes (without a terminating - * NULL byte) or containing UTF-16BE entities. + * The 'name' string. Note that its format differs depending on the + * (platform,encoding) pair, being either a string of bytes (without a + * terminating NULL byte) or containing UTF-16BE entities. * * string_len :: - * The length of `string' in bytes. + * The length of 'string' in bytes. * * @note: * Please refer to the TrueType or OpenType specification for more @@ -128,18 +124,18 @@ FT_BEGIN_HEADER * FT_Get_Sfnt_Name_Count * * @description: - * Retrieve the number of name strings in the SFNT `name' table. + * Retrieve the number of name strings in the SFNT 'name' table. * * @input: * face :: * A handle to the source face. * * @return: - * The number of strings in the `name' table. + * The number of strings in the 'name' table. * * @note: * This function always returns an error if the config macro - * `TT_CONFIG_OPTION_SFNT_NAMES' is not defined in `ftoption.h'. + * `TT_CONFIG_OPTION_SFNT_NAMES` is not defined in `ftoption.h`. */ FT_EXPORT( FT_UInt ) FT_Get_Sfnt_Name_Count( FT_Face face ); @@ -151,14 +147,14 @@ FT_BEGIN_HEADER * FT_Get_Sfnt_Name * * @description: - * Retrieve a string of the SFNT `name' table for a given index. + * Retrieve a string of the SFNT 'name' table for a given index. * * @input: * face :: * A handle to the source face. * * idx :: - * The index of the `name' string. + * The index of the 'name' string. * * @output: * aname :: @@ -168,19 +164,19 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * The `string' array returned in the `aname' structure is not - * null-terminated. Note that you don't have to deallocate `string' - * by yourself; FreeType takes care of it if you call @FT_Done_Face. + * The 'string' array returned in the 'aname' structure is not + * null-terminated. Note that you don't have to deallocate 'string' by + * yourself; FreeType takes care of it if you call @FT_Done_Face. * * Use @FT_Get_Sfnt_Name_Count to get the total number of available - * `name' table entries, then do a loop until you get the right - * platform, encoding, and name ID. + * 'name' table entries, then do a loop until you get the right platform, + * encoding, and name ID. * - * `name' table format~1 entries can use language tags also, see + * 'name' table format~1 entries can use language tags also, see * @FT_Get_Sfnt_LangTag. * * This function always returns an error if the config macro - * `TT_CONFIG_OPTION_SFNT_NAMES' is not defined in `ftoption.h'. + * `TT_CONFIG_OPTION_SFNT_NAMES` is not defined in `ftoption.h`. */ FT_EXPORT( FT_Error ) FT_Get_Sfnt_Name( FT_Face face, @@ -194,16 +190,15 @@ FT_BEGIN_HEADER * FT_SfntLangTag * * @description: - * A structure to model a language tag entry from an SFNT `name' - * table. + * A structure to model a language tag entry from an SFNT 'name' table. * * @fields: * string :: - * The language tag string, encoded in UTF-16BE - * (without trailing NULL bytes). + * The language tag string, encoded in UTF-16BE (without trailing NULL + * bytes). * * string_len :: - * The length of `string' in *bytes*. + * The length of 'string' in **bytes**. * * @note: * Please refer to the TrueType or OpenType specification for more @@ -227,36 +222,36 @@ FT_BEGIN_HEADER * * @description: * Retrieve the language tag associated with a language ID of an SFNT - * `name' table entry. + * 'name' table entry. * * @input: * face :: * A handle to the source face. * * langID :: - * The language ID, as returned by @FT_Get_Sfnt_Name. - * This is always a value larger than 0x8000. + * The language ID, as returned by @FT_Get_Sfnt_Name. This is always a + * value larger than 0x8000. * * @output: * alangTag :: - * The language tag associated with the `name' table - * entry's language ID. + * The language tag associated with the 'name' table entry's language + * ID. * * @return: * FreeType error code. 0~means success. * * @note: - * The `string' array returned in the `alangTag' structure is not - * null-terminated. Note that you don't have to deallocate `string' - * by yourself; FreeType takes care of it if you call @FT_Done_Face. + * The 'string' array returned in the `alangTag` structure is not + * null-terminated. Note that you don't have to deallocate 'string' by + * yourself; FreeType takes care of it if you call @FT_Done_Face. * - * Only `name' table format~1 supports language tags. For format~0 + * Only 'name' table format~1 supports language tags. For format~0 * tables, this function always returns FT_Err_Invalid_Table. For * invalid format~1 language ID values, FT_Err_Invalid_Argument is * returned. * * This function always returns an error if the config macro - * `TT_CONFIG_OPTION_SFNT_NAMES' is not defined in `ftoption.h'. + * `TT_CONFIG_OPTION_SFNT_NAMES` is not defined in `ftoption.h`. * * @since: * 2.8 diff --git a/include/freetype/ftstroke.h b/include/freetype/ftstroke.h index 91d277656..d22ddd022 100644 --- a/include/freetype/ftstroke.h +++ b/include/freetype/ftstroke.h @@ -39,11 +39,11 @@ FT_BEGIN_HEADER * Generating bordered and stroked glyphs. * * @description: - * This component generates stroked outlines of a given vectorial - * glyph. It also allows you to retrieve the `outside' and/or the - * `inside' borders of the stroke. + * This component generates stroked outlines of a given vectorial glyph. + * It also allows you to retrieve the 'outside' and/or the 'inside' + * borders of the stroke. * - * This can be useful to generate `bordered' glyph, i.e., glyphs + * This can be useful to generate 'bordered' glyph, i.e., glyphs * displayed with a coloured (and anti-aliased) border around their * shape. * @@ -98,45 +98,42 @@ FT_BEGIN_HEADER * FT_Stroker_LineJoin * * @description: - * These values determine how two joining lines are rendered - * in a stroker. + * These values determine how two joining lines are rendered in a + * stroker. * * @values: * FT_STROKER_LINEJOIN_ROUND :: - * Used to render rounded line joins. Circular arcs are used - * to join two lines smoothly. + * Used to render rounded line joins. Circular arcs are used to join + * two lines smoothly. * * FT_STROKER_LINEJOIN_BEVEL :: - * Used to render beveled line joins. The outer corner of - * the joined lines is filled by enclosing the triangular - * region of the corner with a straight line between the - * outer corners of each stroke. + * Used to render beveled line joins. The outer corner of the joined + * lines is filled by enclosing the triangular region of the corner + * with a straight line between the outer corners of each stroke. * * FT_STROKER_LINEJOIN_MITER_FIXED :: - * Used to render mitered line joins, with fixed bevels if the - * miter limit is exceeded. The outer edges of the strokes - * for the two segments are extended until they meet at an - * angle. If the segments meet at too sharp an angle (such - * that the miter would extend from the intersection of the - * segments a distance greater than the product of the miter - * limit value and the border radius), then a bevel join (see - * above) is used instead. This prevents long spikes being - * created. FT_STROKER_LINEJOIN_MITER_FIXED generates a miter - * line join as used in PostScript and PDF. + * Used to render mitered line joins, with fixed bevels if the miter + * limit is exceeded. The outer edges of the strokes for the two + * segments are extended until they meet at an angle. If the segments + * meet at too sharp an angle (such that the miter would extend from + * the intersection of the segments a distance greater than the product + * of the miter limit value and the border radius), then a bevel join + * (see above) is used instead. This prevents long spikes being + * created. FT_STROKER_LINEJOIN_MITER_FIXED generates a miter line + * join as used in PostScript and PDF. * * FT_STROKER_LINEJOIN_MITER_VARIABLE :: * FT_STROKER_LINEJOIN_MITER :: - * Used to render mitered line joins, with variable bevels if - * the miter limit is exceeded. The intersection of the - * strokes is clipped at a line perpendicular to the bisector - * of the angle between the strokes, at the distance from the - * intersection of the segments equal to the product of the - * miter limit value and the border radius. This prevents - * long spikes being created. - * FT_STROKER_LINEJOIN_MITER_VARIABLE generates a mitered line - * join as used in XPS. FT_STROKER_LINEJOIN_MITER is an alias - * for FT_STROKER_LINEJOIN_MITER_VARIABLE, retained for - * backward compatibility. + * Used to render mitered line joins, with variable bevels if the miter + * limit is exceeded. The intersection of the strokes is clipped at a + * line perpendicular to the bisector of the angle between the strokes, + * at the distance from the intersection of the segments equal to the + * product of the miter limit value and the border radius. This + * prevents long spikes being created. + * FT_STROKER_LINEJOIN_MITER_VARIABLE generates a mitered line join as + * used in XPS. FT_STROKER_LINEJOIN_MITER is an alias for + * FT_STROKER_LINEJOIN_MITER_VARIABLE, retained for backward + * compatibility. */ typedef enum FT_Stroker_LineJoin_ { @@ -155,21 +152,19 @@ FT_BEGIN_HEADER * FT_Stroker_LineCap * * @description: - * These values determine how the end of opened sub-paths are - * rendered in a stroke. + * These values determine how the end of opened sub-paths are rendered in + * a stroke. * * @values: * FT_STROKER_LINECAP_BUTT :: - * The end of lines is rendered as a full stop on the last - * point itself. + * The end of lines is rendered as a full stop on the last point + * itself. * * FT_STROKER_LINECAP_ROUND :: - * The end of lines is rendered as a half-circle around the - * last point. + * The end of lines is rendered as a half-circle around the last point. * * FT_STROKER_LINECAP_SQUARE :: - * The end of lines is rendered as a square around the - * last point. + * The end of lines is rendered as a square around the last point. */ typedef enum FT_Stroker_LineCap_ { @@ -186,8 +181,8 @@ FT_BEGIN_HEADER * FT_StrokerBorder * * @description: - * These values are used to select a given stroke border - * in @FT_Stroker_GetBorderCounts and @FT_Stroker_ExportBorder. + * These values are used to select a given stroke border in + * @FT_Stroker_GetBorderCounts and @FT_Stroker_ExportBorder. * * @values: * FT_STROKER_BORDER_LEFT :: @@ -197,9 +192,9 @@ FT_BEGIN_HEADER * Select the right border, relative to the drawing direction. * * @note: - * Applications are generally interested in the `inside' and `outside' + * Applications are generally interested in the 'inside' and 'outside' * borders. However, there is no direct mapping between these and the - * `left' and `right' ones, since this really depends on the glyph's + * '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 @@ -219,8 +214,8 @@ FT_BEGIN_HEADER * FT_Outline_GetInsideBorder * * @description: - * Retrieve the @FT_StrokerBorder value corresponding to the - * `inside' borders of a given outline. + * Retrieve the @FT_StrokerBorder value corresponding to the 'inside' + * borders of a given outline. * * @input: * outline :: @@ -240,8 +235,8 @@ FT_BEGIN_HEADER * FT_Outline_GetOutsideBorder * * @description: - * Retrieve the @FT_StrokerBorder value corresponding to the - * `outside' borders of a given outline. + * Retrieve the @FT_StrokerBorder value corresponding to the 'outside' + * borders of a given outline. * * @input: * outline :: @@ -302,12 +297,11 @@ FT_BEGIN_HEADER * * miter_limit :: * The miter limit for the FT_STROKER_LINEJOIN_MITER_FIXED and - * FT_STROKER_LINEJOIN_MITER_VARIABLE line join styles, - * expressed as 16.16 fixed-point value. + * FT_STROKER_LINEJOIN_MITER_VARIABLE line join styles, expressed as + * 16.16 fixed-point value. * * @note: - * The radius is expressed in the same units as the outline - * coordinates. + * The radius is expressed in the same units as the outline coordinates. * * This function calls @FT_Stroker_Rewind automatically. */ @@ -325,10 +319,9 @@ FT_BEGIN_HEADER * FT_Stroker_Rewind * * @description: - * Reset a stroker object without changing its attributes. - * You should call this function before beginning a new - * series of calls to @FT_Stroker_BeginSubPath or - * @FT_Stroker_EndSubPath. + * Reset a stroker object without changing its attributes. You should + * call this function before beginning a new series of calls to + * @FT_Stroker_BeginSubPath or @FT_Stroker_EndSubPath. * * @input: * stroker :: @@ -344,9 +337,9 @@ FT_BEGIN_HEADER * FT_Stroker_ParseOutline * * @description: - * A convenience function used to parse a whole outline with - * the stroker. The resulting outline(s) can be retrieved - * later by functions like @FT_Stroker_GetCounts and @FT_Stroker_Export. + * A convenience function used to parse a whole outline with the stroker. + * The resulting outline(s) can be retrieved later by functions like + * @FT_Stroker_GetCounts and @FT_Stroker_Export. * * @input: * stroker :: @@ -356,18 +349,18 @@ FT_BEGIN_HEADER * The source outline. * * opened :: - * A boolean. If~1, the outline is treated as an open path instead - * of a closed one. + * A boolean. If~1, the outline is treated as an open path instead of + * a closed one. * * @return: * FreeType error code. 0~means success. * * @note: - * If `opened' is~0 (the default), the outline is treated as a closed - * path, and the stroker generates two distinct `border' outlines. + * If 'opened' is~0 (the default), the outline is treated as a closed + * path, and the stroker generates two distinct 'border' outlines. * - * If `opened' is~1, the outline is processed as an open path, and the - * stroker generates a single `stroke' outline. + * If 'opened' is~1, the outline is processed as an open path, and the + * stroker generates a single 'stroke' outline. * * This function calls @FT_Stroker_Rewind automatically. */ @@ -399,8 +392,8 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * This function is useful when you need to stroke a path that is - * not stored as an @FT_Outline object. + * This function is useful when you need to stroke a path that is not + * stored as an @FT_Outline object. */ FT_EXPORT( FT_Error ) FT_Stroker_BeginSubPath( FT_Stroker stroker, @@ -424,9 +417,9 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * You should call this function after @FT_Stroker_BeginSubPath. - * If the subpath was not `opened', this function `draws' a - * single line segment to the start position when needed. + * You should call this function after @FT_Stroker_BeginSubPath. If the + * subpath was not 'opened', this function 'draws' a single line segment + * to the start position when needed. */ FT_EXPORT( FT_Error ) FT_Stroker_EndSubPath( FT_Stroker stroker ); @@ -438,8 +431,8 @@ FT_BEGIN_HEADER * FT_Stroker_LineTo * * @description: - * `Draw' a single line segment in the stroker's current sub-path, - * from the last position. + * 'Draw' a single line segment in the stroker's current sub-path, from + * the last position. * * @input: * stroker :: @@ -466,7 +459,7 @@ FT_BEGIN_HEADER * FT_Stroker_ConicTo * * @description: - * `Draw' a single quadratic Bezier in the stroker's current sub-path, + * 'Draw' a single quadratic Bezier in the stroker's current sub-path, * from the last position. * * @input: @@ -498,8 +491,8 @@ FT_BEGIN_HEADER * FT_Stroker_CubicTo * * @description: - * `Draw' a single cubic Bezier in the stroker's current sub-path, - * from the last position. + * 'Draw' a single cubic Bezier in the stroker's current sub-path, from + * the last position. * * @input: * stroker :: @@ -534,10 +527,10 @@ FT_BEGIN_HEADER * FT_Stroker_GetBorderCounts * * @description: - * Call this function once you have finished parsing your paths - * with the stroker. It returns the number of points and - * contours necessary to export one of the `border' or `stroke' - * outlines generated by the stroker. + * Call this function once you have finished parsing your paths with the + * stroker. It returns the number of points and contours necessary to + * export one of the 'border' or 'stroke' outlines generated by the + * stroker. * * @input: * stroker :: @@ -557,15 +550,15 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * When an outline, or a sub-path, is `closed', the stroker generates - * two independent `border' outlines, named `left' and `right'. + * When an outline, or a sub-path, is 'closed', the stroker generates two + * independent 'border' outlines, named 'left' and 'right'. * - * When the outline, or a sub-path, is `opened', the stroker merges - * the `border' outlines with caps. The `left' border receives all - * points, while the `right' border becomes empty. + * When the outline, or a sub-path, is 'opened', the stroker merges the + * 'border' outlines with caps. The 'left' border receives all points, + * while the 'right' border becomes empty. * - * Use the function @FT_Stroker_GetCounts instead if you want to - * retrieve the counts associated to both borders. + * Use the function @FT_Stroker_GetCounts instead if you want to retrieve + * the counts associated to both borders. */ FT_EXPORT( FT_Error ) FT_Stroker_GetBorderCounts( FT_Stroker stroker, @@ -580,13 +573,11 @@ FT_BEGIN_HEADER * FT_Stroker_ExportBorder * * @description: - * Call this function after @FT_Stroker_GetBorderCounts to - * export the corresponding border to your own @FT_Outline - * structure. + * Call this function after @FT_Stroker_GetBorderCounts to export the + * corresponding border to your own @FT_Outline structure. * - * Note that this function appends the border points and - * contours to your outline, but does not try to resize its - * arrays. + * Note that this function appends the border points and contours to your + * outline, but does not try to resize its arrays. * * @input: * stroker :: @@ -599,19 +590,19 @@ FT_BEGIN_HEADER * The target outline handle. * * @note: - * Always call this function after @FT_Stroker_GetBorderCounts to - * get sure that there is enough room in your @FT_Outline object to - * receive all new data. + * Always call this function after @FT_Stroker_GetBorderCounts to get + * sure that there is enough room in your @FT_Outline object to receive + * all new data. * - * When an outline, or a sub-path, is `closed', the stroker generates - * two independent `border' outlines, named `left' and `right'. + * When an outline, or a sub-path, is 'closed', the stroker generates two + * independent 'border' outlines, named 'left' and 'right'. * - * When the outline, or a sub-path, is `opened', the stroker merges - * the `border' outlines with caps. The `left' border receives all - * points, while the `right' border becomes empty. + * When the outline, or a sub-path, is 'opened', the stroker merges the + * 'border' outlines with caps. The 'left' border receives all points, + * while the 'right' border becomes empty. * - * Use the function @FT_Stroker_Export instead if you want to - * retrieve all borders at once. + * Use the function @FT_Stroker_Export instead if you want to retrieve + * all borders at once. */ FT_EXPORT( void ) FT_Stroker_ExportBorder( FT_Stroker stroker, @@ -625,10 +616,9 @@ FT_BEGIN_HEADER * FT_Stroker_GetCounts * * @description: - * Call this function once you have finished parsing your paths - * with the stroker. It returns the number of points and - * contours necessary to export all points/borders from the stroked - * outline/path. + * Call this function once you have finished parsing your paths with the + * stroker. It returns the number of points and contours necessary to + * export all points/borders from the stroked outline/path. * * @input: * stroker :: @@ -656,12 +646,11 @@ FT_BEGIN_HEADER * FT_Stroker_Export * * @description: - * Call this function after @FT_Stroker_GetBorderCounts to - * export all borders to your own @FT_Outline structure. + * Call this function after @FT_Stroker_GetBorderCounts to export all + * borders to your own @FT_Outline structure. * - * Note that this function appends the border points and - * contours to your outline, but does not try to resize its - * arrays. + * Note that this function appends the border points and contours to your + * outline, but does not try to resize its arrays. * * @input: * stroker :: @@ -708,8 +697,7 @@ FT_BEGIN_HEADER * A stroker handle. * * destroy :: - * A Boolean. If~1, the source glyph object is destroyed - * on success. + * A Boolean. If~1, the source glyph object is destroyed on success. * * @return: * FreeType error code. 0~means success. @@ -719,8 +707,8 @@ FT_BEGIN_HEADER * * Adding stroke may yield a significantly wider and taller glyph * depending on how large of a radius was used to stroke the glyph. You - * may need to manually adjust horizontal and vertical advance amounts - * to account for this added size. + * may need to manually adjust horizontal and vertical advance amounts to + * account for this added size. */ FT_EXPORT( FT_Error ) FT_Glyph_Stroke( FT_Glyph *pglyph, @@ -734,8 +722,8 @@ FT_BEGIN_HEADER * FT_Glyph_StrokeBorder * * @description: - * Stroke a given outline glyph object with a given stroker, but - * only return either its inside or outside border. + * Stroke a given outline glyph object with a given stroker, but only + * return either its inside or outside border. * * @inout: * pglyph :: @@ -746,12 +734,11 @@ FT_BEGIN_HEADER * A stroker handle. * * inside :: - * A Boolean. If~1, return the inside border, otherwise - * the outside border. + * A Boolean. If~1, return the inside border, otherwise the outside + * border. * * destroy :: - * A Boolean. If~1, the source glyph object is destroyed - * on success. + * A Boolean. If~1, the source glyph object is destroyed on success. * * @return: * FreeType error code. 0~means success. @@ -761,8 +748,8 @@ FT_BEGIN_HEADER * * Adding stroke may yield a significantly wider and taller glyph * depending on how large of a radius was used to stroke the glyph. You - * may need to manually adjust horizontal and vertical advance amounts - * to account for this added size. + * may need to manually adjust horizontal and vertical advance amounts to + * account for this added size. */ FT_EXPORT( FT_Error ) FT_Glyph_StrokeBorder( FT_Glyph *pglyph, diff --git a/include/freetype/ftsystem.h b/include/freetype/ftsystem.h index 0b415b6b1..91cb2fae5 100644 --- a/include/freetype/ftsystem.h +++ b/include/freetype/ftsystem.h @@ -38,10 +38,9 @@ FT_BEGIN_HEADER * How FreeType manages memory and i/o. * * @description: - * 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 - * i/o streams. + * 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 i/o streams. * */ @@ -72,7 +71,7 @@ FT_BEGIN_HEADER * FT_Alloc_Func * * @description: - * A function used to allocate `size' bytes from `memory'. + * A function used to allocate 'size' bytes from 'memory'. * * @input: * memory :: @@ -193,8 +192,8 @@ FT_BEGIN_HEADER * A handle to an input stream. * * @also: - * See @FT_StreamRec for the publicly accessible fields of a given - * stream object. + * See @FT_StreamRec for the publicly accessible fields of a given stream + * object. * */ typedef struct FT_StreamRec_* FT_Stream; @@ -207,7 +206,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_ @@ -243,9 +242,8 @@ FT_BEGIN_HEADER * The number of bytes effectively read by the stream. * * @note: - * This function might be called to perform a seek or skip operation - * with a `count' of~0. A non-zero return value then indicates an - * error. + * This function might be called to perform a seek or skip operation with + * a 'count' of~0. A non-zero return value then indicates an error. * */ typedef unsigned long @@ -299,7 +297,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 :: @@ -314,14 +312,13 @@ FT_BEGIN_HEADER * The stream's close function. * * memory :: - * The memory manager to use to preload frames. This is set - * internally by FreeType and shouldn't be touched by stream - * implementations. + * The memory manager to use to preload frames. This is set internally + * by FreeType and shouldn't be touched by stream implementations. * * cursor :: * This field is set and used internally by FreeType when parsing - * frames. In particular, the `FT_GET_XXX' macros use this instead - * of the `pos' field. + * frames. In particular, the `FT_GET_XXX` macros use this instead of + * the 'pos' field. * * limit :: * This field is set and used internally by FreeType when parsing diff --git a/include/freetype/fttrigon.h b/include/freetype/fttrigon.h index 7a27bb216..430aba45f 100644 --- a/include/freetype/fttrigon.h +++ b/include/freetype/fttrigon.h @@ -174,8 +174,8 @@ FT_BEGIN_HEADER * FT_Atan2 * * @description: - * Return the arc-tangent corresponding to a given vector (x,y) in - * the 2d plane. + * Return the arc-tangent corresponding to a given vector (x,y) in the 2d + * plane. * * @input: * x :: @@ -210,7 +210,7 @@ FT_BEGIN_HEADER * Second angle. * * @return: - * Constrained value of `value2-value1'. + * Constrained value of 'value2-value1'. * */ FT_EXPORT( FT_Angle ) @@ -225,8 +225,8 @@ FT_BEGIN_HEADER * * @description: * Return the unit vector corresponding to a given angle. After the - * call, the value of `vec.x' will be `cos(angle)', and the value of - * `vec.y' will be `sin(angle)'. + * call, the value of `vec.x` will be 'cos(angle)', and the value of + * `vec.y` will be 'sin(angle)'. * * This function is useful to retrieve both the sinus and cosinus of a * given angle quickly. diff --git a/include/freetype/fttypes.h b/include/freetype/fttypes.h index 9da08a0c9..a311b87da 100644 --- a/include/freetype/fttypes.h +++ b/include/freetype/fttypes.h @@ -126,8 +126,8 @@ FT_BEGIN_HEADER * FT_UFWord * * @description: - * An unsigned 16-bit integer used to store a distance in original - * font units. + * An unsigned 16-bit integer used to store a distance in original font + * units. */ typedef unsigned short FT_UFWord; /* unsigned distance */ @@ -270,8 +270,7 @@ FT_BEGIN_HEADER * FT_F26Dot6 * * @description: - * A signed 26.6 fixed-point type used for vectorial pixel - * coordinates. + * A signed 26.6 fixed-point type used for vectorial pixel coordinates. */ typedef signed long FT_F26Dot6; @@ -294,8 +293,8 @@ FT_BEGIN_HEADER * FT_Error * * @description: - * The FreeType error code type. A value of~0 is always interpreted - * as a successful operation. + * The FreeType error code type. A value of~0 is always interpreted as a + * successful operation. */ typedef int FT_Error; @@ -317,9 +316,9 @@ FT_BEGIN_HEADER * FT_Offset * * @description: - * This is equivalent to the ANSI~C `size_t' type, i.e., the largest - * _unsigned_ integer type used to express a file size or position, - * or a memory block size. + * This is equivalent to the ANSI~C `size_t` type, i.e., the largest + * _unsigned_ integer type used to express a file size or position, or a + * memory block size. */ typedef size_t FT_Offset; @@ -330,9 +329,9 @@ FT_BEGIN_HEADER * FT_PtrDist * * @description: - * This is equivalent to the ANSI~C `ptrdiff_t' type, i.e., the - * largest _signed_ integer type used to express the distance - * between two pointers. + * This is equivalent to the ANSI~C `ptrdiff_t` type, i.e., the largest + * _signed_ integer type used to express the distance between two + * pointers. */ typedef ft_ptrdiff_t FT_PtrDist; @@ -367,13 +366,13 @@ FT_BEGIN_HEADER * FT_Matrix * * @description: - * A simple structure used to store a 2x2 matrix. Coefficients are - * in 16.16 fixed-point format. The computation performed is: + * A simple structure used to store a 2x2 matrix. Coefficients are in + * 16.16 fixed-point format. The computation performed is: * - * { + * ``` * x' = x*xx + y*xy * y' = x*yx + y*yy - * } + * ``` * * @fields: * xx :: @@ -425,13 +424,13 @@ FT_BEGIN_HEADER * FT_Generic_Finalizer * * @description: - * Describe a function used to destroy the `client' data of any - * FreeType object. See the description of the @FT_Generic type for - * details of usage. + * Describe a function used to destroy the 'client' data of any FreeType + * object. See the description of the @FT_Generic type for details of + * usage. * * @input: - * The address of the FreeType object that is under finalization. - * Its client data is accessed through its `generic' field. + * The address of the FreeType object that is under finalization. Its + * client data is accessed through its 'generic' field. */ typedef void (*FT_Generic_Finalizer)( void* object ); @@ -446,25 +445,24 @@ FT_BEGIN_HEADER * variety of FreeType core objects. For example, a text layout API * might want to associate a glyph cache to a given size object. * - * Some FreeType object contains a `generic' field, of type - * FT_Generic, which usage is left to client applications and font - * servers. + * Some FreeType object contains a 'generic' field, of type FT_Generic, + * which usage is left to client applications and font servers. * - * It can be used to store a pointer to client-specific data, as well - * as the address of a `finalizer' function, which will be called by + * It can be used to store a pointer to client-specific data, as well as + * the address of a 'finalizer' function, which will be called by * FreeType when the object is destroyed (for example, the previous - * client example would put the address of the glyph cache destructor - * in the `finalizer' field). + * client example would put the address of the glyph cache destructor in + * the 'finalizer' field). * * @fields: * data :: - * A typeless pointer to any client-specified data. This - * field is completely ignored by the FreeType library. + * A typeless pointer to any client-specified data. This field is + * completely ignored by the FreeType library. * * finalizer :: - * A pointer to a `generic finalizer' function, which - * will be called when the object is destroyed. If this - * field is set to NULL, no code will be called. + * A pointer to a 'generic finalizer' function, which will be called + * when the object is destroyed. If this field is set to NULL, no code + * will be called. */ typedef struct FT_Generic_ { @@ -480,12 +478,12 @@ FT_BEGIN_HEADER * FT_MAKE_TAG * * @description: - * This macro converts four-letter tags that are used to label - * TrueType tables into an unsigned long, to be used within FreeType. + * This macro converts four-letter tags that are used to label TrueType + * tables into an unsigned long, to be used within FreeType. * * @note: - * The produced values *must* be 32-bit integers. Don't redefine - * this macro. + * The produced values **must** be 32-bit integers. Don't redefine this + * macro. */ #define FT_MAKE_TAG( _x1, _x2, _x3, _x4 ) \ (FT_Tag) \ @@ -518,9 +516,9 @@ FT_BEGIN_HEADER * FT_ListNode * * @description: - * Many elements and objects in FreeType are listed through an - * @FT_List record (see @FT_ListRec). As its name suggests, an - * FT_ListNode is a handle to a single list element. + * Many elements and objects in FreeType are listed through an @FT_List + * record (see @FT_ListRec). As its name suggests, an FT_ListNode is a + * handle to a single list element. */ typedef struct FT_ListNodeRec_* FT_ListNode; @@ -569,8 +567,8 @@ FT_BEGIN_HEADER * FT_ListRec * * @description: - * A structure used to hold a simple doubly-linked list. These are - * used in many parts of FreeType. + * A structure used to hold a simple doubly-linked list. These are used + * in many parts of FreeType. * * @fields: * head :: diff --git a/include/freetype/ftwinfnt.h b/include/freetype/ftwinfnt.h index 5d0eb0f27..057f73d5e 100644 --- a/include/freetype/ftwinfnt.h +++ b/include/freetype/ftwinfnt.h @@ -56,20 +56,19 @@ FT_BEGIN_HEADER * FT_WinFNT_ID_XXX * * @description: - * A list of valid values for the `charset' byte in - * @FT_WinFNT_HeaderRec. Exact mapping tables for the various cpXXXX - * encodings (except for cp1361) can be found at - * ftp://ftp.unicode.org/Public in the MAPPINGS/VENDORS/MICSFT/WINDOWS - * subdirectory. cp1361 is roughly a superset of - * MAPPINGS/OBSOLETE/EASTASIA/KSC/JOHAB.TXT. + * A list of valid values for the 'charset' byte in @FT_WinFNT_HeaderRec. + * Exact mapping tables for the various cpXXXX encodings (except for + * cp1361) can be found at ftp://ftp.unicode.org/Public in the + * MAPPINGS/VENDORS/MICSFT/WINDOWS subdirectory. cp1361 is roughly a + * superset of MAPPINGS/OBSOLETE/EASTASIA/KSC/JOHAB.TXT. * * @values: * FT_WinFNT_ID_DEFAULT :: - * This is used for font enumeration and font creation as a - * `don't care' value. Valid font files don't contain this value. - * When querying for information about the character set of the font - * that is currently selected into a specified device context, this - * return value (of the related Windows API) simply denotes failure. + * This is used for font enumeration and font creation as a 'don't + * care' value. Valid font files don't contain this value. When + * querying for information about the character set of the font that is + * currently selected into a specified device context, this return + * value (of the related Windows API) simply denotes failure. * * FT_WinFNT_ID_SYMBOL :: * There is no known mapping table available. @@ -80,26 +79,27 @@ FT_BEGIN_HEADER * FT_WinFNT_ID_OEM :: * From Michael Poettgen <michael@poettgen.de>: * - * The `Windows Font Mapping' article says that FT_WinFNT_ID_OEM - * is used for the charset of vector fonts, like `modern.fon', - * `roman.fon', and `script.fon' on Windows. + * The 'Windows Font Mapping' article says that FT_WinFNT_ID_OEM is + * used for the charset of vector fonts, like `modern.fon`, + * `roman.fon`, and `script.fon` on Windows. * - * The `CreateFont' documentation says: The FT_WinFNT_ID_OEM value + * The 'CreateFont' documentation says: The FT_WinFNT_ID_OEM value * specifies a character set that is operating-system dependent. * - * The `IFIMETRICS' documentation from the `Windows Driver - * Development Kit' says: This font supports an OEM-specific - * character set. The OEM character set is system dependent. + * The 'IFIMETRICS' documentation from the 'Windows Driver Development + * Kit' says: This font supports an OEM-specific character set. The + * OEM character set is system dependent. * * In general OEM, as opposed to ANSI (i.e., cp1252), denotes the - * second default codepage that most international versions of - * Windows have. It is one of the OEM codepages from + * second default codepage that most international versions of Windows + * have. It is one of the OEM codepages from * - * https://docs.microsoft.com/en-us/windows/desktop/intl/code-page-identifiers , + * https://docs.microsoft.com/en-us/windows/desktop/intl/code-page-identifiers + * , * - * and is used for the `DOS boxes', to support legacy applications. - * A German Windows version for example usually uses ANSI codepage - * 1252 and OEM codepage 850. + * and is used for the 'DOS boxes', to support legacy applications. A + * German Windows version for example usually uses ANSI codepage 1252 + * and OEM codepage 850. * * FT_WinFNT_ID_CP874 :: * A superset of Thai TIS 620 and ISO 8859-11. @@ -112,8 +112,8 @@ FT_BEGIN_HEADER * ordering and minor deviations). * * FT_WinFNT_ID_CP949 :: - * A superset of Korean Hangul KS~C 5601-1987 (with different - * ordering and minor deviations). + * A superset of Korean Hangul KS~C 5601-1987 (with different ordering + * and minor deviations). * * FT_WinFNT_ID_CP950 :: * A superset of traditional Chinese Big~5 ETen (with different diff --git a/include/freetype/internal/autohint.h b/include/freetype/internal/autohint.h index c20a18e2e..42c9b830c 100644 --- a/include/freetype/internal/autohint.h +++ b/include/freetype/internal/autohint.h @@ -2,7 +2,7 @@ * * autohint.h * - * High-level `autohint' module-specific interface (specification). + * High-level 'autohint' module-specific interface (specification). * * Copyright 1996-2018 by * David Turner, Robert Wilhelm, and Werner Lemberg. @@ -30,31 +30,31 @@ /************************************************************************** * - * A small technical note regarding automatic hinting in order to - * clarify this module interface. + * A small technical note regarding automatic hinting in order to clarify + * this module interface. * * An automatic hinter might compute two kinds of data for a given face: * * - global hints: Usually some metrics that describe global properties * of the face. It is computed by scanning more or less * aggressively the glyphs in the face, and thus can be - * very slow to compute (even if the size of global - * hints is really small). + * very slow to compute (even if the size of global hints + * is really small). * - * - glyph hints: These describe some important features of the glyph + * - glyph hints: These describe some important features of the glyph * outline, as well as how to align them. They are * generally much faster to compute than global hints. * - * The current FreeType auto-hinter does a pretty good job while - * performing fast computations for both global and glyph hints. - * However, we might be interested in introducing more complex and - * powerful algorithms in the future, like the one described in the John - * D. Hobby paper, which unfortunately requires a lot more horsepower. + * The current FreeType auto-hinter does a pretty good job while performing + * fast computations for both global and glyph hints. However, we might be + * interested in introducing more complex and powerful algorithms in the + * future, like the one described in the John D. Hobby paper, which + * unfortunately requires a lot more horsepower. * * Because a sufficiently sophisticated font management system would - * typically implement an LRU cache of opened face objects to reduce - * memory usage, it is a good idea to be able to avoid recomputing - * global hints every time the same face is re-opened. + * typically implement an LRU cache of opened face objects to reduce memory + * usage, it is a good idea to be able to avoid recomputing global hints + * every time the same face is re-opened. * * We thus provide the ability to cache global hints outside of the face * object, in order to speed up font re-opening time. Of course, this @@ -62,10 +62,10 @@ * it. * * I initially thought that it would be a good idea to cache the glyph - * hints too. However, my general idea now is that if you really need - * to cache these too, you are simply in need of a new font format, - * where all this information could be stored within the font file and - * decoded on the fly. + * hints too. However, my general idea now is that if you really need to + * cache these too, you are simply in need of a new font format, where all + * this information could be stored within the font file and decoded on the + * fly. * */ @@ -87,8 +87,8 @@ FT_BEGIN_HEADER * * @description: * Retrieve the global hints computed for a given face object. The - * resulting data is dissociated from the face and will survive a - * call to FT_Done_Face(). It must be discarded through the API + * resulting data is dissociated from the face and will survive a call to + * FT_Done_Face(). It must be discarded through the API * FT_AutoHinter_GlobalDoneFunc(). * * @input: @@ -119,8 +119,8 @@ FT_BEGIN_HEADER * * @description: * Discard the global hints retrieved through - * FT_AutoHinter_GlobalGetFunc(). This is the only way these hints - * are freed from memory. + * FT_AutoHinter_GlobalGetFunc(). This is the only way these hints are + * freed from memory. * * @input: * hinter :: @@ -140,9 +140,9 @@ FT_BEGIN_HEADER * FT_AutoHinter_GlobalResetFunc * * @description: - * This function is used to recompute the global metrics in a given - * font. This is useful when global font data changes (e.g. Multiple - * Masters fonts where blend coordinates change). + * This function is used to recompute the global metrics in a given font. + * This is useful when global font data changes (e.g. Multiple Masters + * fonts where blend coordinates change). * * @input: * hinter :: @@ -162,8 +162,8 @@ FT_BEGIN_HEADER * FT_AutoHinter_GlyphLoadFunc * * @description: - * This function is used to load, scale, and automatically hint a - * glyph from a given face. + * This function is used to load, scale, and automatically hint a glyph + * from a given face. * * @input: * face :: @@ -176,8 +176,8 @@ FT_BEGIN_HEADER * The load flags. * * @note: - * This function is capable of loading composite glyphs by hinting - * each sub-glyph independently (which improves quality). + * This function is capable of loading composite glyphs by hinting each + * sub-glyph independently (which improves quality). * * It will call the font driver with @FT_Load_Glyph, with * @FT_LOAD_NO_SCALE set. diff --git a/include/freetype/internal/cffotypes.h b/include/freetype/internal/cffotypes.h index c01dba4f8..235a12584 100644 --- a/include/freetype/internal/cffotypes.h +++ b/include/freetype/internal/cffotypes.h @@ -76,7 +76,7 @@ FT_BEGIN_HEADER * CFF_Internal * * @description: - * The interface to the `internal' field of `FT_Size'. + * The interface to the 'internal' field of `FT_Size`. */ typedef struct CFF_InternalRec_ { diff --git a/include/freetype/internal/cfftypes.h b/include/freetype/internal/cfftypes.h index 534ee1674..e580eaf79 100644 --- a/include/freetype/internal/cfftypes.h +++ b/include/freetype/internal/cfftypes.h @@ -46,8 +46,7 @@ FT_BEGIN_HEADER * The source input stream. * * start :: - * The position of the first index byte in the - * input stream. + * The position of the first index byte in the input stream. * * count :: * The number of elements in the index. @@ -56,15 +55,13 @@ FT_BEGIN_HEADER * The size in bytes of object offsets in index. * * data_offset :: - * The position of first data byte in the index's - * bytes. + * The position of first data byte in the index's bytes. * * data_size :: * The size of the data table in this index. * * offsets :: - * A table of element offsets in the index. Must be - * loaded explicitly. + * A table of element offsets in the index. Must be loaded explicitly. * * bytes :: * If the index is loaded in memory, its bytes. diff --git a/include/freetype/internal/ftcalc.h b/include/freetype/internal/ftcalc.h index dc1b66441..48c5d039c 100644 --- a/include/freetype/internal/ftcalc.h +++ b/include/freetype/internal/ftcalc.h @@ -252,7 +252,7 @@ FT_BEGIN_HEADER * FT_MulDiv_No_Round * * @description: - * A very simple function used to perform the computation `(a*b)/c' + * A very simple function used to perform the computation '(a*b)/c' * (without rounding) with maximum accuracy (it uses a 64-bit * intermediate integer whenever necessary). * @@ -268,9 +268,9 @@ FT_BEGIN_HEADER * The divisor. * * @return: - * The result of `(a*b)/c'. This function never traps when trying to - * divide by zero; it simply returns `MaxInt' or `MinInt' depending - * on the signs of `a' and `b'. + * The result of '(a*b)/c'. This function never traps when trying to + * divide by zero; it simply returns 'MaxInt' or 'MinInt' depending on + * the signs of 'a' and 'b'. */ FT_BASE( FT_Long ) FT_MulDiv_No_Round( FT_Long a, @@ -279,12 +279,11 @@ FT_BEGIN_HEADER /* - * A variant of FT_Matrix_Multiply which scales its result afterwards. - * The idea is that both `a' and `b' are scaled by factors of 10 so that - * the values are as precise as possible to get a correct result during - * the 64bit multiplication. Let `sa' and `sb' be the scaling factors of - * `a' and `b', respectively, then the scaling factor of the result is - * `sa*sb'. + * A variant of FT_Matrix_Multiply which scales its result afterwards. The + * idea is that both `a' and `b' are scaled by factors of 10 so that the + * values are as precise as possible to get a correct result during the + * 64bit multiplication. Let `sa' and `sb' be the scaling factors of `a' + * and `b', respectively, then the scaling factor of the result is `sa*sb'. */ FT_BASE( void ) FT_Matrix_Multiply_Scaled( const FT_Matrix* a, @@ -318,22 +317,22 @@ FT_BEGIN_HEADER /* - * This function normalizes a vector and returns its original length. - * The normalized vector is a 16.16 fixed-point unit vector with length - * close to 0x10000. The accuracy of the returned length is limited to - * 16 bits also. The function utilizes quick inverse square root - * approximation without divisions and square roots relying on Newton's - * iterations instead. + * This function normalizes a vector and returns its original length. The + * normalized vector is a 16.16 fixed-point unit vector with length close + * to 0x10000. The accuracy of the returned length is limited to 16 bits + * also. The function utilizes quick inverse square root approximation + * without divisions and square roots relying on Newton's iterations + * instead. */ FT_BASE( FT_UInt32 ) FT_Vector_NormLen( FT_Vector* vector ); /* - * Return -1, 0, or +1, depending on the orientation of a given corner. - * We use the Cartesian coordinate system, with positive vertical values - * going upwards. The function returns +1 if the corner turns to the - * left, -1 to the right, and 0 for undecidable cases. + * Return -1, 0, or +1, depending on the orientation of a given corner. We + * use the Cartesian coordinate system, with positive vertical values going + * upwards. The function returns +1 if the corner turns to the left, -1 to + * the right, and 0 for undecidable cases. */ FT_BASE( FT_Int ) ft_corner_orientation( FT_Pos in_x, @@ -433,7 +432,7 @@ FT_BEGIN_HEADER * The value to compute the root for. * * @return: - * The result of `sqrt(x)'. + * The result of 'sqrt(x)'. * * @note: * This function is not very fast. diff --git a/include/freetype/internal/ftdebug.h b/include/freetype/internal/ftdebug.h index 34f8a00ab..98b45df2b 100644 --- a/include/freetype/internal/ftdebug.h +++ b/include/freetype/internal/ftdebug.h @@ -15,7 +15,7 @@ * * * IMPORTANT: A description of FreeType's debugging support can be - * found in `docs/DEBUG.TXT'. Read it if you need to use or + * found in 'docs/DEBUG.TXT'. Read it if you need to use or * understand this code. * */ @@ -44,8 +44,8 @@ FT_BEGIN_HEADER /************************************************************************** * - * Define the trace enums as well as the trace levels array when they - * are needed. + * Define the trace enums as well as the trace levels array when they are + * needed. * */ @@ -115,8 +115,8 @@ FT_BEGIN_HEADER * FT_DEBUG_LEVEL_TRACE definition. * * @note: - * This function may be useful if you want to access elements of - * the internal trace levels array by an index. + * This function may be useful if you want to access elements of the + * internal trace levels array by an index. */ FT_BASE( FT_Int ) FT_Trace_Get_Count( void ); @@ -213,8 +213,8 @@ FT_BEGIN_HEADER /************************************************************************** * - * Define the FT_ASSERT and FT_THROW macros. The call to `FT_Throw' - * makes it possible to easily set a breakpoint at this function. + * Define the FT_ASSERT and FT_THROW macros. The call to `FT_Throw` makes + * it possible to easily set a breakpoint at this function. * */ @@ -245,7 +245,7 @@ FT_BEGIN_HEADER /************************************************************************** * - * Define `FT_Message' and `FT_Panic' when needed. + * Define `FT_Message` and `FT_Panic` when needed. * */ diff --git a/include/freetype/internal/ftdrv.h b/include/freetype/internal/ftdrv.h index 745b78a40..2886d4e0d 100644 --- a/include/freetype/internal/ftdrv.h +++ b/include/freetype/internal/ftdrv.h @@ -129,46 +129,37 @@ FT_BEGIN_HEADER * * * load_glyph :: - * A function handle to load a glyph to a slot. - * This field is mandatory! + * A function handle to load a glyph to a slot. This field is + * mandatory! * * get_kerning :: - * A function handle to return the unscaled - * kerning for a given pair of glyphs. Can be - * set to 0 if the format doesn't support - * kerning. + * A function handle to return the unscaled kerning for a given pair of + * glyphs. Can be set to 0 if the format doesn't support kerning. * * attach_file :: - * This function handle is used to read - * additional data for a face from another - * file/stream. For example, this can be used to - * add data from AFM or PFM files on a Type 1 - * face, or a CIDMap on a CID-keyed face. + * This function handle is used to read additional data for a face from + * another file/stream. For example, this can be used to add data from + * AFM or PFM files on a Type 1 face, or a CIDMap on a CID-keyed face. * * get_advances :: - * A function handle used to return advance - * widths of `count' glyphs (in font units), - * starting at `first'. The `vertical' flag must - * be set to get vertical advance heights. The - * `advances' buffer is caller-allocated. - * The idea of this function is to be able to - * perform device-independent text layout without - * loading a single glyph image. + * A function handle used to return advance widths of 'count' glyphs + * (in font units), starting at 'first'. The 'vertical' flag must be + * set to get vertical advance heights. The 'advances' buffer is + * caller-allocated. The idea of this function is to be able to + * perform device-independent text layout without loading a single + * glyph image. * * request_size :: - * A handle to a function used to request the new - * character size. Can be set to 0 if the - * scaling done in the base layer suffices. + * A handle to a function used to request the new character size. Can + * be set to 0 if the scaling done in the base layer suffices. * * select_size :: - * A handle to a function used to select a new - * fixed size. It is used only if - * @FT_FACE_FLAG_FIXED_SIZES is set. Can be set - * to 0 if the scaling done in the base layer - * suffices. + * A handle to a function used to select a new fixed size. It is used + * only if @FT_FACE_FLAG_FIXED_SIZES is set. Can be set to 0 if the + * scaling done in the base layer suffices. * @note: - * Most function pointers, with the exception of `load_glyph', can be - * set to 0 to indicate a default behaviour. + * Most function pointers, with the exception of `load_glyph`, can be set + * to 0 to indicate a default behaviour. */ typedef struct FT_Driver_ClassRec_ { @@ -206,8 +197,8 @@ FT_BEGIN_HEADER * FT_DECLARE_DRIVER * * @description: - * Used to create a forward declaration of an FT_Driver_ClassRec - * struct instance. + * Used to create a forward declaration of an FT_Driver_ClassRec struct + * instance. * * @macro: * FT_DEFINE_DRIVER @@ -215,12 +206,12 @@ FT_BEGIN_HEADER * @description: * Used to initialize an instance of FT_Driver_ClassRec struct. * - * `ftinit.c' (ft_create_default_module_classes) already contains a - * mechanism to call these functions for the default modules - * described in `ftmodule.h'. + * `ftinit.c` (ft_create_default_module_classes) already contains a + * mechanism to call these functions for the default modules described in + * `ftmodule.h`. * - * The struct will be allocated in the global scope (or the scope - * where the macro is used). + * The struct will be allocated in the global scope (or the scope where + * the macro is used). */ #define FT_DECLARE_DRIVER( class_ ) \ FT_CALLBACK_TABLE \ diff --git a/include/freetype/internal/ftmemory.h b/include/freetype/internal/ftmemory.h index f15c77dfd..ef069a314 100644 --- a/include/freetype/internal/ftmemory.h +++ b/include/freetype/internal/ftmemory.h @@ -34,7 +34,7 @@ FT_BEGIN_HEADER * FT_SET_ERROR * * @description: - * This macro is used to set an implicit `error' variable to a given + * This macro is used to set an implicit 'error' variable to a given * expression's value (usually a function call), and convert it to a * boolean which is set whenever the value is != 0. */ @@ -59,8 +59,8 @@ FT_BEGIN_HEADER /* * C++ refuses to handle statements like p = (void*)anything, with `p' a - * typed pointer. Since we don't have a `typeof' operator in standard - * C++, we have to use a template to emulate it. + * typed pointer. Since we don't have a `typeof' operator in standard C++, + * we have to use a template to emulate it. */ #ifdef __cplusplus @@ -107,8 +107,8 @@ extern "C++" /* - * The allocation functions return a pointer, and the error code - * is written to through the `p_error' parameter. + * The allocation functions return a pointer, and the error code is written + * to through the `p_error' parameter. */ /* The `q' variants of the functions below (`q' for `quick') don't fill */ @@ -253,9 +253,8 @@ extern "C++" /* - * Return the maximum number of addressable elements in an array. - * We limit ourselves to INT_MAX, rather than UINT_MAX, to avoid - * any problems. + * Return the maximum number of addressable elements in an array. We limit + * ourselves to INT_MAX, rather than UINT_MAX, to avoid any problems. */ #define FT_ARRAY_MAX( ptr ) ( FT_INT_MAX / sizeof ( *(ptr) ) ) diff --git a/include/freetype/internal/ftobjs.h b/include/freetype/internal/ftobjs.h index 88ced183f..eaae53eac 100644 --- a/include/freetype/internal/ftobjs.h +++ b/include/freetype/internal/ftobjs.h @@ -73,9 +73,9 @@ FT_BEGIN_HEADER #define FT_ABS( a ) ( (a) < 0 ? -(a) : (a) ) /* - * Approximate sqrt(x*x+y*y) using the `alpha max plus beta min' - * algorithm. We use alpha = 1, beta = 3/8, giving us results with a - * largest error less than 7% compared to the exact value. + * Approximate sqrt(x*x+y*y) using the `alpha max plus beta min' algorithm. + * We use alpha = 1, beta = 3/8, giving us results with a largest error + * less than 7% compared to the exact value. */ #define FT_HYPOT( x, y ) \ ( x = FT_ABS( x ), \ @@ -110,9 +110,8 @@ FT_BEGIN_HEADER /* - * character classification functions -- since these are used to parse - * font files, we must not use those in <ctypes.h> which are - * locale-dependent + * character classification functions -- since these are used to parse font + * files, we must not use those in <ctypes.h> which are locale-dependent */ #define ft_isdigit( x ) ( ( (unsigned)(x) - '0' ) < 10U ) @@ -297,67 +296,65 @@ FT_BEGIN_HEADER * FT_Face_InternalRec * * @description: - * This structure contains the internal fields of each FT_Face - * object. These fields may change between different releases of - * FreeType. + * This structure contains the internal fields of each FT_Face object. + * These fields may change between different releases of FreeType. * * @fields: * max_points :: - * The maximum number of points used to store the vectorial outline + * The maximum number of points used to store the vectorial outline of + * any glyph in this face. If this value cannot be known in advance, + * or if the face isn't scalable, this should be set to 0. Only + * relevant for scalable formats. + * + * max_contours :: + * The maximum number of contours used to store the vectorial outline * of any glyph in this face. If this value cannot be known in * advance, or if the face isn't scalable, this should be set to 0. * Only relevant for scalable formats. * - * max_contours :: - * The maximum number of contours used to store the vectorial - * outline of any glyph in this face. If this value cannot be - * known in advance, or if the face isn't scalable, this should be - * set to 0. Only relevant for scalable formats. - * * transform_matrix :: - * A 2x2 matrix of 16.16 coefficients used to transform glyph - * outlines after they are loaded from the font. Only used by the - * convenience functions. + * A 2x2 matrix of 16.16 coefficients used to transform glyph outlines + * after they are loaded from the font. Only used by the convenience + * functions. * * transform_delta :: - * A translation vector used to transform glyph outlines after they - * are loaded from the font. Only used by the convenience - * functions. + * A translation vector used to transform glyph outlines after they are + * loaded from the font. Only used by the convenience functions. * * transform_flags :: * Some flags used to classify the transform. Only used by the * convenience functions. * * services :: - * A cache for frequently used services. It should be only - * accessed with the macro `FT_FACE_LOOKUP_SERVICE'. + * A cache for frequently used services. It should be only accessed + * with the macro `FT_FACE_LOOKUP_SERVICE`. * * incremental_interface :: - * If non-null, the interface through which glyph data and metrics - * are loaded incrementally for faces that do not provide all of - * this data when first opened. This field exists only if + * If non-null, the interface through which glyph data and metrics are + * loaded incrementally for faces that do not provide all of this data + * when first opened. This field exists only if * @FT_CONFIG_OPTION_INCREMENTAL is defined. * * no_stem_darkening :: - * Overrides the module-level default, see @stem-darkening[cff], - * for example. FALSE and TRUE toggle stem darkening on and off, + * Overrides the module-level default, see @stem-darkening[cff], for + * example. FALSE and TRUE toggle stem darkening on and off, * respectively, value~-1 means to use the module/driver default. * * random_seed :: - * If positive, override the seed value for the CFF `random' - * operator. Value~0 means to use the font's value. Value~-1 - * means to use the CFF driver's default. + * If positive, override the seed value for the CFF 'random' operator. + * Value~0 means to use the font's value. Value~-1 means to use the + * CFF driver's default. * * lcd_weights :: * lcd_filter_func :: - * These fields specify the LCD filtering weights and callback - * function for ClearType-style subpixel rendering. + * These fields specify the LCD filtering weights and callback function + * for ClearType-style subpixel rendering. * * refcount :: * A counter initialized to~1 at the time an @FT_Face structure is * created. @FT_Reference_Face increments this counter, and - * @FT_Done_Face only destroys a face if the counter is~1, - * otherwise it simply decrements it. + * @FT_Done_Face only destroys a face if the counter is~1, otherwise it + * simply decrements it. */ typedef struct FT_Face_InternalRec_ { @@ -396,29 +393,24 @@ FT_BEGIN_HEADER * * @fields: * loader :: - * The glyph loader object used to load outlines - * into the glyph slot. + * The glyph loader object used to load outlines into the glyph slot. * * flags :: - * Possible values are zero or - * FT_GLYPH_OWN_BITMAP. The latter indicates - * that the FT_GlyphSlot structure owns the - * bitmap buffer. + * Possible values are zero or FT_GLYPH_OWN_BITMAP. The latter + * indicates that the FT_GlyphSlot structure owns the bitmap buffer. * * glyph_transformed :: - * Boolean. Set to TRUE when the loaded glyph - * must be transformed through a specific - * font transformation. This is _not_ the same - * as the face transform set through - * FT_Set_Transform(). + * Boolean. Set to TRUE when the loaded glyph must be transformed + * through a specific font transformation. This is _not_ the same as + * the face transform set through FT_Set_Transform(). * * glyph_matrix :: - * The 2x2 matrix corresponding to the glyph - * transformation, if necessary. + * The 2x2 matrix corresponding to the glyph transformation, if + * necessary. * * glyph_delta :: - * The 2d translation vector corresponding to - * the glyph transformation, if necessary. + * The 2d translation vector corresponding to the glyph transformation, + * if necessary. * * glyph_hints :: * Format-specific glyph hints management. @@ -450,8 +442,7 @@ FT_BEGIN_HEADER * FT_Size_InternalRec * * @description: - * This structure contains the internal fields of each FT_Size - * object. + * This structure contains the internal fields of each FT_Size object. * * @fields: * module_data :: @@ -568,8 +559,8 @@ FT_BEGIN_HEADER * A module-specific interface if available, 0 otherwise. * * @note: - * You should better be familiar with FreeType internals to know - * which module to look for, and what its interface is :-) + * You should better be familiar with FreeType internals to know which + * module to look for, and what its interface is :-) */ FT_BASE( const void* ) FT_Get_Module_Interface( FT_Library library, @@ -627,10 +618,9 @@ FT_BEGIN_HEADER * FT_New_GlyphSlot * * @description: - * It is sometimes useful to have more than one glyph slot for a - * given face object. This function is used to create additional - * slots. All of them are automatically discarded when the face is - * destroyed. + * It is sometimes useful to have more than one glyph slot for a given + * face object. This function is used to create additional slots. All + * of them are automatically discarded when the face is destroyed. * * @input: * face :: @@ -655,8 +645,8 @@ FT_BEGIN_HEADER * * @description: * Destroys a given glyph slot. Remember however that all slots are - * automatically destroyed with its parent. Using this function is - * not always mandatory. + * automatically destroyed with its parent. Using this function is not + * always mandatory. * * @input: * slot :: @@ -789,25 +779,23 @@ FT_BEGIN_HEADER * FT_DriverRec * * @description: - * The root font driver class. A font driver is responsible for - * managing and loading font files of a given format. + * The root font driver class. A font driver is responsible for managing + * and loading font files of a given format. * * @fields: * root :: * Contains the fields of the root module class. * * clazz :: - * A pointer to the font driver's class. Note that - * this is NOT root.clazz. `class' wasn't used - * as it is a reserved word in C++. + * A pointer to the font driver's class. Note that this is NOT + * root.clazz. 'class' wasn't used as it is a reserved word in C++. * * faces_list :: - * The list of faces currently opened by this - * driver. + * The list of faces currently opened by this driver. * * glyph_loader :: - * Unused. Used to be glyph loader for all faces - * managed by this driver. + * Unused. Used to be glyph loader for all faces managed by this + * driver. */ typedef struct FT_DriverRec_ { @@ -843,14 +831,13 @@ FT_BEGIN_HEADER * FT_LibraryRec * * @description: - * The FreeType library class. This is the root of all FreeType - * data. Use FT_New_Library() to create a library object, and - * FT_Done_Library() to discard it and all child objects. + * The FreeType library class. This is the root of all FreeType data. + * Use FT_New_Library() to create a library object, and FT_Done_Library() + * to discard it and all child objects. * * @fields: * memory :: - * The library's memory object. Manages memory - * allocation. + * The library's memory object. Manages memory allocation. * * version_major :: * The major version number of the library. @@ -862,60 +849,52 @@ FT_BEGIN_HEADER * The current patch level of the library. * * num_modules :: - * The number of modules currently registered - * within this library. This is set to 0 for new - * libraries. New modules are added through the - * FT_Add_Module() API function. + * The number of modules currently registered within this library. + * This is set to 0 for new libraries. New modules are added through + * the FT_Add_Module() API function. * * modules :: - * A table used to store handles to the currently - * registered modules. Note that each font driver - * contains a list of its opened faces. + * A table used to store handles to the currently registered + * modules. Note that each font driver contains a list of its opened + * faces. * * renderers :: - * The list of renderers currently registered - * within the library. + * The list of renderers currently registered within the library. * * cur_renderer :: - * The current outline renderer. This is a - * shortcut used to avoid parsing the list on - * each call to FT_Outline_Render(). It is a - * handle to the current renderer for the - * FT_GLYPH_FORMAT_OUTLINE format. + * The current outline renderer. This is a shortcut used to avoid + * parsing the list on each call to FT_Outline_Render(). It is a + * handle to the current renderer for the FT_GLYPH_FORMAT_OUTLINE + * format. * * auto_hinter :: * The auto-hinter module interface. * * debug_hooks :: - * An array of four function pointers that allow - * debuggers to hook into a font format's - * interpreter. Currently, only the TrueType - * bytecode debugger uses this. + * An array of four function pointers that allow debuggers to hook into + * a font format's interpreter. Currently, only the TrueType bytecode + * debugger uses this. * * lcd_weights :: - * The LCD filter weights for ClearType-style - * subpixel rendering. + * The LCD filter weights for ClearType-style subpixel rendering. * * lcd_filter_func :: - * The LCD filtering callback function for - * for ClearType-style subpixel rendering. + * The LCD filtering callback function for for ClearType-style subpixel + * rendering. * * lcd_geometry :: - * This array specifies LCD subpixel geometry - * and controls Harmony LCD rendering technique, - * alternative to ClearType. + * This array specifies LCD subpixel geometry and controls Harmony LCD + * rendering technique, alternative to ClearType. * * pic_container :: - * Contains global structs and tables, instead - * of defining them globally. + * Contains global structs and tables, instead of defining them + * globally. * * refcount :: - * A counter initialized to~1 at the time an - * @FT_Library structure is created. - * @FT_Reference_Library increments this counter, - * and @FT_Done_Library only destroys a library - * if the counter is~1, otherwise it simply - * decrements it. + * A counter initialized to~1 at the time an @FT_Library structure is + * created. @FT_Reference_Library increments this counter, and + * @FT_Done_Library only destroys a library if the counter is~1, + * otherwise it simply decrements it. */ typedef struct FT_LibraryRec_ { @@ -1022,9 +1001,9 @@ FT_BEGIN_HEADER * FT_DEFINE_OUTLINE_FUNCS * * @description: - * Used to initialize an instance of FT_Outline_Funcs struct. - * The struct will be allocated in the global scope (or the scope - * where the macro is used). + * Used to initialize an instance of FT_Outline_Funcs struct. The struct + * will be allocated in the global scope (or the scope where the macro is + * used). */ #define FT_DEFINE_OUTLINE_FUNCS( \ class_, \ @@ -1051,9 +1030,9 @@ FT_BEGIN_HEADER * FT_DEFINE_RASTER_FUNCS * * @description: - * Used to initialize an instance of FT_Raster_Funcs struct. - * The struct will be allocated in the global scope (or the scope - * where the macro is used). + * Used to initialize an instance of FT_Raster_Funcs struct. The struct + * will be allocated in the global scope (or the scope where the macro is + * used). */ #define FT_DEFINE_RASTER_FUNCS( \ class_, \ @@ -1081,8 +1060,8 @@ FT_BEGIN_HEADER * FT_DEFINE_GLYPH * * @description: - * The struct will be allocated in the global scope (or the scope - * where the macro is used). + * The struct will be allocated in the global scope (or the scope where + * the macro is used). */ #define FT_DEFINE_GLYPH( \ class_, \ @@ -1114,8 +1093,8 @@ FT_BEGIN_HEADER * FT_DECLARE_RENDERER * * @description: - * Used to create a forward declaration of a - * FT_Renderer_Class struct instance. + * Used to create a forward declaration of a FT_Renderer_Class struct + * instance. * * @macro: * FT_DEFINE_RENDERER @@ -1123,8 +1102,8 @@ FT_BEGIN_HEADER * @description: * Used to initialize an instance of FT_Renderer_Class struct. * - * The struct will be allocated in the global scope (or the scope - * where the macro is used). + * The struct will be allocated in the global scope (or the scope where + * the macro is used). */ #define FT_DECLARE_RENDERER( class_ ) \ FT_EXPORT_VAR( const FT_Renderer_Class ) class_; @@ -1175,8 +1154,8 @@ FT_BEGIN_HEADER * FT_DECLARE_MODULE * * @description: - * Used to create a forward declaration of a - * FT_Module_Class struct instance. + * Used to create a forward declaration of a FT_Module_Class struct + * instance. * * @macro: * FT_DEFINE_MODULE @@ -1184,16 +1163,16 @@ FT_BEGIN_HEADER * @description: * Used to initialize an instance of an FT_Module_Class struct. * - * The struct will be allocated in the global scope (or the scope - * where the macro is used). + * The struct will be allocated in the global scope (or the scope where + * the macro is used). * * @macro: * FT_DEFINE_ROOT_MODULE * * @description: * Used to initialize an instance of an FT_Module_Class struct inside - * another struct that contains it or in a function that initializes - * that containing struct. + * another struct that contains it or in a function that initializes that + * containing struct. */ #define FT_DECLARE_MODULE( class_ ) \ FT_CALLBACK_TABLE \ diff --git a/include/freetype/internal/ftrfork.h b/include/freetype/internal/ftrfork.h index a056171bc..b9f30c032 100644 --- a/include/freetype/internal/ftrfork.h +++ b/include/freetype/internal/ftrfork.h @@ -72,8 +72,8 @@ FT_BEGIN_HEADER } FT_RFork_Rule; /* For fast translation between rule index and rule type, - * the macros FT_RFORK_xxx should be kept consistent with - * the raccess_guess_funcs table + * the macros FT_RFORK_xxx should be kept consistent with the + * raccess_guess_funcs table */ typedef struct ft_raccess_guess_rec_ { ft_raccess_guess_func func; @@ -98,11 +98,11 @@ FT_BEGIN_HEADER * FT_Raccess_Guess * * @description: - * Guess a file name and offset where the actual resource fork is - * stored. The macro FT_RACCESS_N_RULES holds the number of - * guessing rules; the guessed result for the Nth rule is - * represented as a triplet: a new file name (new_names[N]), a file - * offset (offsets[N]), and an error code (errors[N]). + * Guess a file name and offset where the actual resource fork is stored. + * The macro FT_RACCESS_N_RULES holds the number of guessing rules; the + * guessed result for the Nth rule is represented as a triplet: a new + * file name (new_names[N]), a file offset (offsets[N]), and an error + * code (errors[N]). * * @input: * library :: @@ -112,24 +112,24 @@ FT_BEGIN_HEADER * A file stream containing the resource fork. * * base_name :: - * The (base) file name of the resource fork used for some - * guessing rules. + * The (base) file name of the resource fork used for some guessing + * rules. * * @output: * new_names :: * An array of guessed file names in which the resource forks may - * exist. If `new_names[N]' is NULL, the guessed file name is - * equal to `base_name'. + * exist. If 'new_names[N]' is NULL, the guessed file name is equal to + * `base_name`. * * offsets :: - * An array of guessed file offsets. `offsets[N]' holds the file + * An array of guessed file offsets. 'offsets[N]' holds the file * offset of the possible start of the resource fork in file - * `new_names[N]'. + * 'new_names[N]'. * * errors :: - * An array of FreeType error codes. `errors[N]' is the error - * code of Nth guessing rule function. If `errors[N]' is not - * FT_Err_Ok, `new_names[N]' and `offsets[N]' are meaningless. + * An array of FreeType error codes. 'errors[N]' is the error code of + * Nth guessing rule function. If 'errors[N]' is not FT_Err_Ok, + * 'new_names[N]' and 'offsets[N]' are meaningless. */ FT_BASE( void ) FT_Raccess_Guess( FT_Library library, @@ -146,10 +146,10 @@ FT_BEGIN_HEADER * FT_Raccess_Get_HeaderInfo * * @description: - * Get the information from the header of resource fork. The - * information includes the file offset where the resource map - * starts, and the file offset where the resource data starts. - * `FT_Raccess_Get_DataOffsets' requires these two data. + * Get the information from the header of resource fork. The information + * includes the file offset where the resource map starts, and the file + * offset where the resource data starts. `FT_Raccess_Get_DataOffsets` + * requires these two data. * * @input: * library :: @@ -185,9 +185,9 @@ FT_BEGIN_HEADER * FT_Raccess_Get_DataOffsets * * @description: - * Get the data offsets for a tag in a resource fork. Offsets are - * stored in an array because, in some cases, resources in a resource - * fork have the same tag. + * Get the data offsets for a tag in a resource fork. Offsets are stored + * in an array because, in some cases, resources in a resource fork have + * the same tag. * * @input: * library :: @@ -206,17 +206,16 @@ FT_BEGIN_HEADER * The resource tag. * * sort_by_res_id :: - * A Boolean to sort the fragmented resource by their ids. - * The fragmented resources for `POST' resource should be sorted - * to restore Type1 font properly. For `sfnt' resources, sorting - * may induce a different order of the faces in comparison to that - * by QuickDraw API. + * A Boolean to sort the fragmented resource by their ids. The + * fragmented resources for 'POST' resource should be sorted to restore + * Type1 font properly. For 'sfnt' resources, sorting may induce a + * different order of the faces in comparison to that by QuickDraw API. * * @output: * offsets :: - * The stream offsets for the resource data specified by `tag'. - * This array is allocated by the function, so you have to call - * @ft_mem_free after use. + * The stream offsets for the resource data specified by 'tag'. This + * array is allocated by the function, so you have to call @ft_mem_free + * after use. * * count :: * The length of offsets array. @@ -225,8 +224,8 @@ FT_BEGIN_HEADER * FreeType error code. FT_Err_Ok means success. * * @note: - * Normally you should use `FT_Raccess_Get_HeaderInfo' to get the - * value for `map_offset' and `rdata_pos'. + * Normally you should use `FT_Raccess_Get_HeaderInfo` to get the value + * for `map_offset` and `rdata_pos`. */ FT_BASE( FT_Error ) FT_Raccess_Get_DataOffsets( FT_Library library, diff --git a/include/freetype/internal/ftserv.h b/include/freetype/internal/ftserv.h index 3f493b5bf..1f410c4f7 100644 --- a/include/freetype/internal/ftserv.h +++ b/include/freetype/internal/ftserv.h @@ -17,13 +17,13 @@ /************************************************************************** * - * Each module can export one or more `services'. Each service is + * Each module can export one or more 'services'. Each service is * identified by a constant string and modeled by a pointer; the latter * generally corresponds to a structure containing function pointers. * - * Note that a service's data cannot be a mere function pointer because - * in C it is possible that function pointers might be implemented - * differently than data pointers (e.g. 48 bits instead of 32). + * Note that a service's data cannot be a mere function pointer because in + * C it is possible that function pointers might be implemented differently + * than data pointers (e.g. 48 bits instead of 32). * */ @@ -47,15 +47,15 @@ FT_BEGIN_HEADER * The source face handle. * * id :: - * A string describing the service as defined in the service's - * header files (e.g. FT_SERVICE_ID_MULTI_MASTERS which expands to - * `multi-masters'). It is automatically prefixed with - * `FT_SERVICE_ID_'. + * A string describing the service as defined in the service's header + * files (e.g. FT_SERVICE_ID_MULTI_MASTERS which expands to + * 'multi-masters'). It is automatically prefixed with + * `FT_SERVICE_ID_`. * * @output: * ptr :: - * A variable that receives the service pointer. Will be NULL - * if not found. + * A variable that receives the service pointer. Will be NULL if not + * found. */ #ifdef __cplusplus @@ -99,15 +99,15 @@ FT_BEGIN_HEADER * The source face handle. * * id :: - * A string describing the service as defined in the service's - * header files (e.g. FT_SERVICE_ID_MULTI_MASTERS which expands to - * `multi-masters'). It is automatically prefixed with - * `FT_SERVICE_ID_'. + * A string describing the service as defined in the service's header + * files (e.g. FT_SERVICE_ID_MULTI_MASTERS which expands to + * 'multi-masters'). It is automatically prefixed with + * `FT_SERVICE_ID_`. * * @output: * ptr :: - * A variable that receives the service pointer. Will be NULL - * if not found. + * A variable that receives the service pointer. Will be NULL if not + * found. */ #ifdef __cplusplus @@ -146,8 +146,8 @@ FT_BEGIN_HEADER /*************************************************************************/ /* - * The following structure is used to _describe_ a given service - * to the library. This is useful to build simple static service lists. + * The following structure is used to _describe_ a given service to the + * library. This is useful to build simple static service lists. */ typedef struct FT_ServiceDescRec_ { @@ -176,8 +176,8 @@ FT_BEGIN_HEADER * @description: * Used to initialize an array of FT_ServiceDescRec structures. * - * The array will be allocated in the global scope (or the scope - * where the macro is used). + * The array will be allocated in the global scope (or the scope where + * the macro is used). */ #define FT_DEFINE_SERVICEDESCREC1( class_, \ serv_id_1, serv_data_1 ) \ @@ -351,13 +351,13 @@ FT_BEGIN_HEADER /* - * Parse a list of FT_ServiceDescRec descriptors and look for - * a specific service by ID. Note that the last element in the - * array must be { NULL, NULL }, and that the function should - * return NULL if the service isn't available. + * Parse a list of FT_ServiceDescRec descriptors and look for a specific + * service by ID. Note that the last element in the array must be { NULL, + * NULL }, and that the function should return NULL if the service isn't + * available. * - * This function can be used by modules to implement their - * `get_service' method. + * This function can be used by modules to implement their `get_service' + * method. */ FT_BASE( FT_Pointer ) ft_service_list_lookup( FT_ServiceDesc service_descriptors, @@ -374,14 +374,14 @@ FT_BEGIN_HEADER /* * This structure is used to store a cache for several frequently used - * services. It is the type of `face->internal->services'. You - * should only use FT_FACE_LOOKUP_SERVICE to access it. + * services. It is the type of `face->internal->services'. You should + * only use FT_FACE_LOOKUP_SERVICE to access it. * * All fields should have the type FT_Pointer to relax compilation * dependencies. We assume the developer isn't completely stupid. * - * Each field must be named `service_XXXX' where `XXX' corresponds to - * the correct FT_SERVICE_ID_XXXX macro. See the definition of + * Each field must be named `service_XXXX' where `XXX' corresponds to the + * correct FT_SERVICE_ID_XXXX macro. See the definition of * FT_FACE_LOOKUP_SERVICE below how this is implemented. * */ diff --git a/include/freetype/internal/ftstream.h b/include/freetype/internal/ftstream.h index aaf8e0b34..7d44e4bf7 100644 --- a/include/freetype/internal/ftstream.h +++ b/include/freetype/internal/ftstream.h @@ -149,8 +149,8 @@ FT_BEGIN_HEADER /************************************************************************** * - * Integer extraction macros -- the `buffer' parameter must ALWAYS be of - * type `char*' or equivalent (1-byte elements). + * Integer extraction macros -- the 'buffer' parameter must ALWAYS be of + * type 'char*' or equivalent (1-byte elements). */ #define FT_BYTE_( p, i ) ( ((const FT_Byte*)(p))[(i)] ) @@ -166,8 +166,8 @@ FT_BEGIN_HEADER /* - * `FT_PEEK_XXX' are generic macros to get data from a buffer position. - * No safety checks are performed. + * `FT_PEEK_XXX' are generic macros to get data from a buffer position. No + * safety checks are performed. */ #define FT_PEEK_SHORT( p ) FT_INT16( FT_BYTE_U16( p, 0, 8 ) | \ FT_BYTE_U16( p, 1, 0 ) ) @@ -267,11 +267,11 @@ FT_BEGIN_HEADER /************************************************************************** * - * The `FT_GET_XXX' macros use an implicit `stream' variable. + * The `FT_GET_XXX` macros use an implicit 'stream' variable. * - * Note that a call to `FT_STREAM_SEEK' or `FT_STREAM_POS' has *no* effect - * on `FT_GET_XXX'! They operate on `stream->pos', while `FT_GET_XXX' use - * `stream->cursor'. + * Note that a call to `FT_STREAM_SEEK` or `FT_STREAM_POS` has **no** + * effect on `FT_GET_XXX`! They operate on `stream->pos`, while + * `FT_GET_XXX` use `stream->cursor`. */ #if 0 #define FT_GET_MACRO( type ) FT_NEXT_ ## type ( stream->cursor ) @@ -319,8 +319,8 @@ FT_BEGIN_HEADER * The `FT_READ_XXX' macros use implicit `stream' and `error' variables. * * `FT_READ_XXX' can be controlled with `FT_STREAM_SEEK' and - * `FT_STREAM_POS'. They use the full machinery to check whether a read - * is valid. + * `FT_STREAM_POS'. They use the full machinery to check whether a read is + * valid. */ #define FT_READ_BYTE( var ) FT_READ_MACRO( FT_Stream_ReadChar, FT_Byte, var ) #define FT_READ_CHAR( var ) FT_READ_MACRO( FT_Stream_ReadChar, FT_Char, var ) diff --git a/include/freetype/internal/ftvalid.h b/include/freetype/internal/ftvalid.h index 265d79ba9..6450c4c8c 100644 --- a/include/freetype/internal/ftvalid.h +++ b/include/freetype/internal/ftvalid.h @@ -54,17 +54,17 @@ FT_BEGIN_HEADER * FT_VALIDATE_TIGHT :: * A table that passes this validation level can be used reliably and * doesn't contain invalid data. For example, a charmap table that - * returns invalid glyph indices will not pass, even though it can - * be used with FreeType in default mode (the library will simply - * return an error later when trying to load the glyph). + * returns invalid glyph indices will not pass, even though it can be + * used with FreeType in default mode (the library will simply return an + * error later when trying to load the glyph). * * It also checks that fields which must be a multiple of 2, 4, or 8, * don't have incorrect values, etc. * * FT_VALIDATE_PARANOID :: * Only for font debugging. Checks that a table follows the - * specification by 100%. Very few fonts will be able to pass this - * level anyway but it can be useful for certain tools like font + * specification by 100%. Very few fonts will be able to pass this level + * anyway but it can be useful for certain tools like font * editors/converters. */ typedef enum FT_ValidationLevel_ diff --git a/include/freetype/internal/internal.h b/include/freetype/internal/internal.h index 826104336..33cceac3d 100644 --- a/include/freetype/internal/internal.h +++ b/include/freetype/internal/internal.h @@ -18,8 +18,8 @@ /************************************************************************** * - * This file is automatically included by `ft2build.h'. - * Do not include it manually! + * This file is automatically included by `ft2build.h`. Do not include it + * manually! * */ diff --git a/include/freetype/internal/psaux.h b/include/freetype/internal/psaux.h index 2c5a6d291..2e5478f9b 100644 --- a/include/freetype/internal/psaux.h +++ b/include/freetype/internal/psaux.h @@ -113,25 +113,22 @@ FT_BEGIN_HEADER * PS_TableRec * * @description: - * A PS_Table is a simple object used to store an array of objects in - * a single memory block. + * A PS_Table is a simple object used to store an array of objects in a + * single memory block. * * @fields: * block :: - * The address in memory of the growheap's block. This - * can change between two object adds, due to - * reallocation. + * The address in memory of the growheap's block. This can change + * between two object adds, due to reallocation. * * cursor :: * The current top of the grow heap within its block. * * capacity :: - * The current size of the heap block. Increments by - * 1kByte chunks. + * The current size of the heap block. Increments by 1kByte chunks. * * init :: - * Set to 0xDEADBEEF if `elements' and `lengths' have - * been allocated. + * Set to 0xDEADBEEF if 'elements' and 'lengths' have been allocated. * * max_elems :: * The maximum number of elements in table. @@ -146,8 +143,7 @@ FT_BEGIN_HEADER * A table of element sizes within the block. * * memory :: - * The object used for memory operations - * (alloc/realloc). + * The object used for memory operations (alloc/realloc). * * funcs :: * A table of method pointers for this object. @@ -556,9 +552,8 @@ FT_BEGIN_HEADER * Set but not used. * * metrics_only :: - * A boolean indicating that we only want to compute - * the metrics of a given glyph, not load all of its - * points. + * A boolean indicating that we only want to compute the metrics of a + * given glyph, not load all of its points. * * is_t1 :: * Set if current font type is Type 1. @@ -815,8 +810,7 @@ FT_BEGIN_HEADER * Unused. * * parse_state :: - * An enumeration which controls the charstring - * parsing state. + * An enumeration which controls the charstring parsing state. * * load_points :: * If this flag is not set, no points are loaded. @@ -825,9 +819,8 @@ FT_BEGIN_HEADER * Set but not used. * * metrics_only :: - * A boolean indicating that we only want to compute - * the metrics of a given glyph, not load all of its - * points. + * A boolean indicating that we only want to compute the metrics of a + * given glyph, not load all of its points. * * funcs :: * An array of function pointers for the builder. @@ -1100,9 +1093,8 @@ FT_BEGIN_HEADER * Set but not used. * * metrics_only :: - * A boolean indicating that we only want to compute - * the metrics of a given glyph, not load all of its - * points. + * A boolean indicating that we only want to compute the metrics of a + * given glyph, not load all of its points. * * hints_funcs :: * Auxiliary pointer for hinting. @@ -1294,8 +1286,7 @@ FT_BEGIN_HEADER * * @fields: * memory :: - * The object used for memory operations (alloc and - * realloc). + * The object used for memory operations (alloc and realloc). * * stream :: * This is an opaque object. @@ -1304,8 +1295,7 @@ FT_BEGIN_HEADER * The result will be stored here. * * get_index :: - * A user provided function to get a glyph index by its - * name. + * A user provided function to get a glyph index by its name. */ typedef struct AFM_ParserRec_ { diff --git a/include/freetype/internal/pshints.h b/include/freetype/internal/pshints.h index 90a28ac49..368ecdfa5 100644 --- a/include/freetype/internal/pshints.h +++ b/include/freetype/internal/pshints.h @@ -4,7 +4,7 @@ * * Interface to Postscript-specific (Type 1 and Type 2) hints * recorders (specification only). These are used to support native - * T1/T2 hints in the `type1', `cid', and `cff' font drivers. + * T1/T2 hints in the 'type1', 'cid', and 'cff' font drivers. * * Copyright 2001-2018 by * David Turner, Robert Wilhelm, and Werner Lemberg. @@ -86,16 +86,16 @@ FT_BEGIN_HEADER * @T1_Hints_FuncsRec structure. Recording glyph hints is normally * achieved through the following scheme: * - * - Open a new hint recording session by calling the `open' method. + * - Open a new hint recording session by calling the 'open' method. * This rewinds the recorder and prepare it for new input. * * - For each hint found in the glyph charstring, call the corresponding - * method (`stem', `stem3', or `reset'). Note that these functions do + * method ('stem', 'stem3', or 'reset'). Note that these functions do * not return an error code. * - * - Close the recording session by calling the `close' method. It - * returns an error code if the hints were invalid or something - * strange happened (e.g., memory shortage). + * - Close the recording session by calling the 'close' method. It + * returns an error code if the hints were invalid or something strange + * happened (e.g., memory shortage). * * The hints accumulated in the object can later be used by the * PostScript hinter. @@ -146,7 +146,7 @@ FT_BEGIN_HEADER * * @description: * A method of the @T1_Hints class used to record a new horizontal or - * vertical stem. This corresponds to the Type 1 `hstem' and `vstem' + * vertical stem. This corresponds to the Type 1 'hstem' and 'vstem' * operators. * * @input: @@ -164,15 +164,15 @@ FT_BEGIN_HEADER * Use vertical coordinates (y) for horizontal stems (dim=0). Use * horizontal coordinates (x) for vertical stems (dim=1). * - * `coords[0]' is the absolute stem position (lowest coordinate); - * `coords[1]' is the length. + * 'coords[0]' is the absolute stem position (lowest coordinate); + * 'coords[1]' is the length. * * The length can be negative, in which case it must be either -20 or - * -21. It is interpreted as a `ghost' stem, according to the Type 1 + * -21. It is interpreted as a 'ghost' stem, according to the Type 1 * specification. * - * If the length is -21 (corresponding to a bottom ghost stem), then - * the real stem position is `coords[0]+coords[1]'. + * If the length is -21 (corresponding to a bottom ghost stem), then the + * real stem position is 'coords[0]+coords[1]'. * */ typedef void @@ -297,7 +297,7 @@ FT_BEGIN_HEADER * On input, all points within the outline are in font coordinates. On * output, they are in 1/64th of pixels. * - * The scaling transformation is taken from the `globals' object which + * The scaling transformation is taken from the 'globals' object which * must correspond to the same font as the glyph. * */ @@ -373,16 +373,16 @@ FT_BEGIN_HEADER * @T2_Hints_FuncsRec structure. Recording glyph hints is normally * achieved through the following scheme: * - * - Open a new hint recording session by calling the `open' method. + * - Open a new hint recording session by calling the 'open' method. * This rewinds the recorder and prepare it for new input. * * - For each hint found in the glyph charstring, call the corresponding - * method (`stems', `hintmask', `counters'). Note that these - * functions do not return an error code. + * method ('stems', 'hintmask', 'counters'). Note that these functions + * do not return an error code. * - * - Close the recording session by calling the `close' method. It - * returns an error code if the hints were invalid or something - * strange happened (e.g., memory shortage). + * - Close the recording session by calling the 'close' method. It + * returns an error code if the hints were invalid or something strange + * happened (e.g., memory shortage). * * The hints accumulated in the object can later be used by the * Postscript hinter. @@ -434,7 +434,7 @@ FT_BEGIN_HEADER * @description: * A method of the @T2_Hints class used to set the table of stems in * either the vertical or horizontal dimension. Equivalent to the - * `hstem', `vstem', `hstemhm', and `vstemhm' Type 2 operators. + * 'hstem', 'vstem', 'hstemhm', and 'vstemhm' Type 2 operators. * * @input: * hints :: @@ -447,18 +447,18 @@ FT_BEGIN_HEADER * The number of stems. * * coords :: - * An array of `count' (position,length) pairs in 16.16 format. + * An array of 'count' (position,length) pairs in 16.16 format. * * @note: * Use vertical coordinates (y) for horizontal stems (dim=0). Use * horizontal coordinates (x) for vertical stems (dim=1). * - * There are `2*count' elements in the `coords' array. Each even - * element is an absolute position in font units, each odd element is a - * length in font units. + * There are '2*count' elements in the 'coords' array. Each even element + * is an absolute position in font units, each odd element is a length in + * font units. * - * A length can be negative, in which case it must be either -20 or - * -21. It is interpreted as a `ghost' stem, according to the Type 1 + * A length can be negative, in which case it must be either -20 or -21. + * It is interpreted as a 'ghost' stem, according to the Type 1 * specification. * */ @@ -476,15 +476,15 @@ FT_BEGIN_HEADER * * @description: * A method of the @T2_Hints class used to set a given hintmask (this - * corresponds to the `hintmask' Type 2 operator). + * corresponds to the 'hintmask' Type 2 operator). * * @input: * hints :: * A handle to the Type 2 hints recorder. * * end_point :: - * The glyph index of the last point to which the previously defined - * or activated hints apply. + * The glyph index of the last point to which the previously defined or + * activated hints apply. * * bit_count :: * The number of bits in the hint mask. @@ -494,13 +494,13 @@ FT_BEGIN_HEADER * * @note: * If the hintmask starts the charstring (before any glyph point - * definition), the value of `end_point' should be 0. + * definition), the value of `end_point` should be 0. * - * `bit_count' is the number of meaningful bits in the `bytes' array; it + * `bit_count` is the number of meaningful bits in the 'bytes' array; it * must be equal to the total number of hints defined so far (i.e., * horizontal+verticals). * - * The `bytes' array can come directly from the Type 2 charstring and + * The 'bytes' array can come directly from the Type 2 charstring and * respects the same format. * */ @@ -517,8 +517,8 @@ FT_BEGIN_HEADER * T2_Hints_CounterFunc * * @description: - * A method of the @T2_Hints class used to set a given counter mask - * (this corresponds to the `hintmask' Type 2 operator). + * A method of the @T2_Hints class used to set a given counter mask (this + * corresponds to the 'hintmask' Type 2 operator). * * @input: * hints :: @@ -536,13 +536,13 @@ FT_BEGIN_HEADER * * @note: * If the hintmask starts the charstring (before any glyph point - * definition), the value of `end_point' should be 0. + * definition), the value of `end_point` should be 0. * - * `bit_count' is the number of meaningful bits in the `bytes' array; it + * `bit_count` is the number of meaningful bits in the 'bytes' array; it * must be equal to the total number of hints defined so far (i.e., * horizontal+verticals). * - * The `bytes' array can come directly from the Type 2 charstring and + * The 'bytes' array can come directly from the Type 2 charstring and * respects the same format. * */ @@ -588,8 +588,7 @@ FT_BEGIN_HEADER * * @description: * A method of the @T2_Hints class used to apply hints to the - * corresponding glyph outline. Must be called after the `close' - * method. + * corresponding glyph outline. Must be called after the 'close' method. * * @input: * hints :: @@ -611,7 +610,7 @@ FT_BEGIN_HEADER * On input, all points within the outline are in font coordinates. On * output, they are in 1/64th of pixels. * - * The scaling transformation is taken from the `globals' object which + * The scaling transformation is taken from the 'globals' object which * must correspond to the same font than the glyph. * */ diff --git a/include/freetype/internal/services/svfntfmt.h b/include/freetype/internal/services/svfntfmt.h index 618236261..e7b75a550 100644 --- a/include/freetype/internal/services/svfntfmt.h +++ b/include/freetype/internal/services/svfntfmt.h @@ -27,8 +27,8 @@ FT_BEGIN_HEADER /* * A trivial service used to return the name of a face's font driver, - * according to the XFree86 nomenclature. Note that the service data - * is a simple constant string pointer. + * according to the XFree86 nomenclature. Note that the service data is a + * simple constant string pointer. */ #define FT_SERVICE_ID_FONT_FORMAT "font-format" diff --git a/include/freetype/internal/services/svgldict.h b/include/freetype/internal/services/svgldict.h index 0840b584a..582d4aebe 100644 --- a/include/freetype/internal/services/svgldict.h +++ b/include/freetype/internal/services/svgldict.h @@ -26,8 +26,8 @@ FT_BEGIN_HEADER /* - * A service used to retrieve glyph names, as well as to find the - * index of a given glyph name in a font. + * A service used to retrieve glyph names, as well as to find the index of + * a given glyph name in a font. * */ diff --git a/include/freetype/internal/services/svpostnm.h b/include/freetype/internal/services/svpostnm.h index 1e39dce79..bfa1db58b 100644 --- a/include/freetype/internal/services/svpostnm.h +++ b/include/freetype/internal/services/svpostnm.h @@ -25,8 +25,8 @@ FT_BEGIN_HEADER /* - * A trivial service used to retrieve the PostScript name of a given - * font when available. The `get_name' field should never be NULL. + * A trivial service used to retrieve the PostScript name of a given font + * when available. The `get_name' field should never be NULL. * * The corresponding function can return NULL to indicate that the * PostScript name is not available. diff --git a/include/freetype/internal/services/svpscmap.h b/include/freetype/internal/services/svpscmap.h index 136879d64..7c6e16d7e 100644 --- a/include/freetype/internal/services/svpscmap.h +++ b/include/freetype/internal/services/svpscmap.h @@ -48,8 +48,7 @@ FT_BEGIN_HEADER /* - * Simple unicode -> glyph index charmap built from font glyph names - * table. + * Simple unicode -> glyph index charmap built from font glyph names table. */ typedef struct PS_UniMap_ { @@ -71,8 +70,8 @@ FT_BEGIN_HEADER /* - * A function which returns a glyph name for a given index. Returns - * NULL if invalid index. + * A function which returns a glyph name for a given index. Returns NULL + * if invalid index. */ typedef const char* (*PS_GetGlyphNameFunc)( FT_Pointer data, diff --git a/include/freetype/internal/services/svttcmap.h b/include/freetype/internal/services/svttcmap.h index cc4328f69..bc415abe1 100644 --- a/include/freetype/internal/services/svttcmap.h +++ b/include/freetype/internal/services/svttcmap.h @@ -45,15 +45,14 @@ FT_BEGIN_HEADER * @fields: * language :: * The language ID used in Mac fonts. Definitions of values are in - * `ttnameid.h'. + * `ttnameid.h`. * * format :: - * The cmap format. OpenType 1.6 defines the formats 0 (byte - * encoding table), 2~(high-byte mapping through table), 4~(segment - * mapping to delta values), 6~(trimmed table mapping), 8~(mixed - * 16-bit and 32-bit coverage), 10~(trimmed array), 12~(segmented - * coverage), 13~(last resort font), and 14 (Unicode Variation - * Sequences). + * The cmap format. OpenType 1.6 defines the formats 0 (byte encoding + * table), 2~(high-byte mapping through table), 4~(segment mapping to + * delta values), 6~(trimmed table mapping), 8~(mixed 16-bit and 32-bit + * coverage), 10~(trimmed array), 12~(segmented coverage), 13~(last + * resort font), and 14 (Unicode Variation Sequences). */ typedef struct TT_CMapInfo_ { diff --git a/include/freetype/internal/sfnt.h b/include/freetype/internal/sfnt.h index 178d892d3..f189e7bad 100644 --- a/include/freetype/internal/sfnt.h +++ b/include/freetype/internal/sfnt.h @@ -2,7 +2,7 @@ * * sfnt.h * - * High-level `sfnt' driver interface (specification). + * High-level 'sfnt' driver interface (specification). * * Copyright 1996-2018 by * David Turner, Robert Wilhelm, and Werner Lemberg. @@ -34,8 +34,8 @@ FT_BEGIN_HEADER * TT_Init_Face_Func * * @description: - * First part of the SFNT face object initialization. This finds - * the face in a SFNT file or collection, and load its format tag in + * First part of the SFNT face object initialization. This finds the + * face in a SFNT file or collection, and load its format tag in * face->format_tag. * * @input: @@ -46,10 +46,9 @@ FT_BEGIN_HEADER * A handle to the target face object. * * face_index :: - * The index of the TrueType font, if we are opening a - * collection, in bits 0-15. The numbered instance - * index~+~1 of a GX (sub)font, if applicable, in bits - * 16-30. + * The index of the TrueType font, if we are opening a collection, in + * bits 0-15. The numbered instance index~+~1 of a GX (sub)font, if + * applicable, in bits 16-30. * * num_params :: * The number of additional parameters. @@ -63,12 +62,11 @@ FT_BEGIN_HEADER * @note: * The stream cursor must be at the font file's origin. * - * This function recognizes fonts embedded in a `TrueType - * collection'. + * This function recognizes fonts embedded in a 'TrueType collection'. * - * Once the format tag has been validated by the font driver, it - * should then call the TT_Load_Face_Func() callback to read the rest - * of the SFNT tables in the object. + * Once the format tag has been validated by the font driver, it should + * then call the TT_Load_Face_Func() callback to read the rest of the + * SFNT tables in the object. */ typedef FT_Error (*TT_Init_Face_Func)( FT_Stream stream, @@ -84,9 +82,9 @@ FT_BEGIN_HEADER * TT_Load_Face_Func * * @description: - * Second part of the SFNT face object initialization. This loads - * the common SFNT tables (head, OS/2, maxp, metrics, etc.) in the - * face object. + * Second part of the SFNT face object initialization. This loads the + * common SFNT tables (head, OS/2, maxp, metrics, etc.) in the face + * object. * * @input: * stream :: @@ -96,10 +94,9 @@ FT_BEGIN_HEADER * A handle to the target face object. * * face_index :: - * The index of the TrueType font, if we are opening a - * collection, in bits 0-15. The numbered instance - * index~+~1 of a GX (sub)font, if applicable, in bits - * 16-30. + * The index of the TrueType font, if we are opening a collection, in + * bits 0-15. The numbered instance index~+~1 of a GX (sub)font, if + * applicable, in bits 16-30. * * num_params :: * The number of additional parameters. @@ -153,30 +150,24 @@ FT_BEGIN_HEADER * The face object to look for. * * tag :: - * The tag of table to load. Use the value 0 if you want - * to access the whole font file, else set this parameter - * to a valid TrueType table tag that you can forge with - * the MAKE_TT_TAG macro. + * The tag of table to load. Use the value 0 if you want to access the + * whole font file, else set this parameter to a valid TrueType table + * tag that you can forge with the MAKE_TT_TAG macro. * * offset :: - * The starting offset in the table (or the file if - * tag == 0). + * The starting offset in the table (or the file if tag == 0). * * length :: * The address of the decision variable: * - * If length == NULL: - * Loads the whole table. Returns an error if - * `offset' == 0! + * If length == NULL: Loads the whole table. Returns an error if + * 'offset' == 0! * - * If *length == 0: - * Exits immediately; returning the length of the given - * table or of the font file, depending on the value of - * `tag'. + * If *length == 0: Exits immediately; returning the length of the + * given table or of the font file, depending on the value of 'tag'. * - * If *length != 0: - * Loads the next `length' bytes of table or font, - * starting at offset `offset' (in table or font too). + * If *length != 0: Loads the next 'length' bytes of table or font, + * starting at offset 'offset' (in table or font too). * * @output: * buffer :: @@ -199,8 +190,8 @@ FT_BEGIN_HEADER * TT_Find_SBit_Image_Func * * @description: - * Check whether an embedded bitmap (an `sbit') exists for a given - * glyph, at a given strike. + * Check whether an embedded bitmap (an 'sbit') exists for a given glyph, + * at a given strike. * * @input: * face :: @@ -220,12 +211,11 @@ FT_BEGIN_HEADER * The SBit strike containing the glyph index. * * aglyph_offset :: - * The offset of the glyph data in `EBDT' table. + * The offset of the glyph data in 'EBDT' table. * * @return: * FreeType error code. 0 means success. Returns - * SFNT_Err_Invalid_Argument if no sbit exists for the requested - * glyph. + * SFNT_Err_Invalid_Argument if no sbit exists for the requested glyph. */ typedef FT_Error (*TT_Find_SBit_Image_Func)( TT_Face face, @@ -259,11 +249,11 @@ FT_BEGIN_HEADER * FreeType error code. 0 means success. * * @note: - * The stream cursor must be positioned at the glyph's offset within - * the `EBDT' table before the call. + * The stream cursor must be positioned at the glyph's offset within the + * 'EBDT' table before the call. * * If the image format uses variable metrics, the stream cursor is - * positioned just after the metrics header in the `EBDT' table on + * positioned just after the metrics header in the 'EBDT' table on * function exit. */ typedef FT_Error @@ -305,11 +295,11 @@ FT_BEGIN_HEADER * A big sbit metrics structure for the glyph image. * * @return: - * FreeType error code. 0 means success. Returns an error if no - * glyph sbit exists for the index. + * FreeType error code. 0 means success. Returns an error if no glyph + * sbit exists for the index. * * @note: - * The `map.buffer' field is always freed before the glyph is loaded. + * The `map.buffer` field is always freed before the glyph is loaded. */ typedef FT_Error (*TT_Load_SBit_Image_Func)( TT_Face face, @@ -341,8 +331,8 @@ FT_BEGIN_HEADER * The index of the sbit strike. * * @return: - * FreeType error code. 0 means success. Returns an error if no - * sbit strike exists for the selected ppem values. + * FreeType error code. 0 means success. Returns an error if no sbit + * strike exists for the selected ppem values. */ typedef FT_Error (*TT_Set_SBit_Strike_Func)( TT_Face face, @@ -370,8 +360,8 @@ FT_BEGIN_HEADER * the metrics of the strike. * * @return: - * FreeType error code. 0 means success. Returns an error if no - * such sbit strike exists. + * FreeType error code. 0 means success. Returns an error if no such + * sbit strike exists. */ typedef FT_Error (*TT_Load_Strike_Metrics_Func)( TT_Face face, @@ -392,8 +382,8 @@ FT_BEGIN_HEADER * The glyph index. * * PSname :: - * The address of a string pointer. Will be NULL in case - * of error, otherwise it is a pointer to the glyph name. + * The address of a string pointer. Will be NULL in case of error, + * otherwise it is a pointer to the glyph name. * * You must not modify the returned string! * @@ -454,12 +444,10 @@ FT_BEGIN_HEADER * * @output: * abearing :: - * The horizontal (or vertical) bearing. Set to zero in - * case of error. + * The horizontal (or vertical) bearing. Set to zero in case of error. * * aadvance :: - * The horizontal (or vertical) advance. Set to zero in - * case of error. + * The horizontal (or vertical) advance. Set to zero in case of error. */ typedef void (*TT_Get_Metrics_Func)( TT_Face face, @@ -475,7 +463,7 @@ FT_BEGIN_HEADER * TT_Set_Palette_Func * * @description: - * Load the colors into `face->palette' for a given palette index. + * Load the colors into `face->palette` for a given palette index. * * @input: * face :: @@ -510,8 +498,8 @@ FT_BEGIN_HEADER * @inout: * iterator :: * An @FT_LayerIterator object. For the first call you should set - * `iterator->p' to NULL. For all following calls, simply use the - * same object again. + * `iterator->p` to NULL. For all following calls, simply use the same + * object again. * * @output: * aglyph_index :: @@ -524,9 +512,9 @@ FT_BEGIN_HEADER * instead (to be set up by the application outside of FreeType). * * @return: - * Value~1 if everything is OK. If there are no more layers (or if - * there are no layers at all), value~0 gets returned. In case of an - * error, value~0 is returned also. + * Value~1 if everything is OK. If there are no more layers (or if there + * are no layers at all), value~0 gets returned. In case of an error, + * value~0 is returned also. */ typedef FT_Bool (*TT_Get_Colr_Layer_Func)( TT_Face face, @@ -542,10 +530,10 @@ FT_BEGIN_HEADER * TT_Blend_Colr_Func * * @description: - * Blend the bitmap in `new_glyph' into `base_glyph' using the color - * specified by `color_index'. If `color_index' is 0xFFFF, use - * `face->foreground_color' if `face->have_foreground_color' is set. - * Otherwise check `face->palette_data.palette_flags': If present and + * Blend the bitmap in `new_glyph` into `base_glyph` using the color + * specified by `color_index`. If `color_index` is 0xFFFF, use + * `face->foreground_color` if `face->have_foreground_color` is set. + * Otherwise check `face->palette_data.palette_flags`: If present and * @FT_PALETTE_FOR_DARK_BACKGROUND is set, use BGRA value 0xFFFFFFFF * (white opaque). Otherwise use BGRA value 0x000000FF (black opaque). * @@ -557,11 +545,11 @@ FT_BEGIN_HEADER * Color index from the COLR table. * * base_glyph :: - * Slot for bitmap to be merged into. The underlying - * bitmap may get reallocated. + * Slot for bitmap to be merged into. The underlying bitmap may get + * reallocated. * * new_glyph :: - * Slot to be incooperated into `base_glyph'. + * Slot to be incooperated into `base_glyph`. * * @return: * FreeType error code. 0 means success. Returns an error if @@ -580,8 +568,7 @@ FT_BEGIN_HEADER * TT_Get_Name_Func * * @description: - * From the `name' table, return a given ENGLISH name record in - * ASCII. + * From the 'name' table, return a given ENGLISH name record in ASCII. * * @input: * face :: @@ -592,8 +579,8 @@ FT_BEGIN_HEADER * * @inout: * name :: - * The address of an allocated string pointer. NULL if - * no name is present. + * The address of an allocated string pointer. NULL if no name is + * present. * * @return: * FreeType error code. 0 means success. @@ -610,8 +597,8 @@ FT_BEGIN_HEADER * TT_Get_Name_ID_Func * * @description: - * Search whether an ENGLISH version for a given name ID is in the - * `name' table. + * Search whether an ENGLISH version for a given name ID is in the 'name' + * table. * * @input: * face :: @@ -622,12 +609,12 @@ FT_BEGIN_HEADER * * @output: * win :: - * If non-negative, an index into the `name' table with - * the corresponding (3,1) or (3,0) Windows entry. + * If non-negative, an index into the 'name' table with the + * corresponding (3,1) or (3,0) Windows entry. * * apple :: - * If non-negative, an index into the `name' table with - * the corresponding (1,0) Apple entry. + * If non-negative, an index into the 'name' table with the + * corresponding (1,0) Apple entry. * * @return: * 1 if there is either a win or apple entry (or both), 0 otheriwse. @@ -658,8 +645,8 @@ FT_BEGIN_HEADER * FreeType error code. 0 means success. * * @note: - * The function uses `face->goto_table' to seek the stream to the - * start of the table, except while loading the font directory. + * The function uses `face->goto_table` to seek the stream to the start + * of the table, except while loading the font directory. */ typedef FT_Error (*TT_Load_Table_Func)( TT_Face face, @@ -690,8 +677,8 @@ FT_BEGIN_HEADER * Return the horizontal kerning value between two glyphs. * * @input: - * face :: A handle to the source face object. - * left_glyph :: The left glyph index. + * face :: A handle to the source face object. left_glyph :: The left + * glyph index. * right_glyph :: The right glyph index. * * @return: @@ -709,8 +696,8 @@ FT_BEGIN_HEADER * SFNT_Interface * * @description: - * This structure holds pointers to the functions used to load and - * free the basic tables that are required in a `sfnt' font file. + * This structure holds pointers to the functions used to load and free + * the basic tables that are required in a 'sfnt' font file. * * @fields: * Check the various xxx_Func() descriptions for details. diff --git a/include/freetype/internal/t1types.h b/include/freetype/internal/t1types.h index 67c385784..3d9d05862 100644 --- a/include/freetype/internal/t1types.h +++ b/include/freetype/internal/t1types.h @@ -55,16 +55,14 @@ FT_BEGIN_HEADER * * @fields: * num_chars :: - * The number of character codes in the encoding. - * Usually 256. + * The number of character codes in the encoding. Usually 256. * * code_first :: * The lowest valid character code in the encoding. * * code_last :: - * The highest valid character code in the encoding - * + 1. When equal to code_first there are no valid - * character codes. + * The highest valid character code in the encoding + 1. When equal to + * code_first there are no valid character codes. * * char_index :: * An array of corresponding glyph indices. diff --git a/include/freetype/internal/tttypes.h b/include/freetype/internal/tttypes.h index 4df6b298f..4cfdf8b79 100644 --- a/include/freetype/internal/tttypes.h +++ b/include/freetype/internal/tttypes.h @@ -53,21 +53,20 @@ FT_BEGIN_HEADER * TTC_HeaderRec * * @description: - * TrueType collection header. This table contains the offsets of - * the font headers of each distinct TrueType face in the file. + * TrueType collection header. This table contains the offsets of the + * font headers of each distinct TrueType face in the file. * * @fields: * tag :: - * Must be `ttc ' to indicate a TrueType collection. + * Must be 'ttc ' to indicate a TrueType collection. * * version :: * The version number. * * count :: - * The number of faces in the collection. The - * specification says this should be an unsigned long, but - * we use a signed long since we need the value -1 for - * specific purposes. + * The number of faces in the collection. The specification says this + * should be an unsigned long, but we use a signed long since we need + * the value -1 for specific purposes. * * offsets :: * The offsets of the font headers, one per face. @@ -98,13 +97,13 @@ FT_BEGIN_HEADER * The number of tables in file. * * search_range :: - * Must be `16 * (max power of 2 <= num_tables)'. + * Must be '16 * (max power of 2 <= num_tables)'. * * entry_selector :: - * Must be log2 of `search_range / 16'. + * Must be log2 of 'search_range / 16'. * * range_shift :: - * Must be `num_tables * 16 - search_range'. + * Must be 'num_tables * 16 - search_range'. */ typedef struct SFNT_HeaderRec_ { @@ -135,8 +134,8 @@ FT_BEGIN_HEADER * The table checksum. This value can be ignored. * * Offset :: - * The offset of the table from the start of the TrueType - * font in its resource. + * The offset of the table from the start of the TrueType font in its + * resource. * * Length :: * The table length (in bytes). @@ -196,8 +195,8 @@ FT_BEGIN_HEADER * A four-bytes tag describing the table. * * Offset :: - * The offset of the table from the start of the WOFF - * font in its resource. + * The offset of the table from the start of the WOFF font in its + * resource. * * CompLength :: * Compressed table length (in bytes). @@ -209,9 +208,9 @@ FT_BEGIN_HEADER * The table checksum. This value can be ignored. * * OrigOffset :: - * The uncompressed table file offset. This value gets - * computed while constructing the (uncompressed) SFNT - * header. It is not contained in the WOFF file. + * The uncompressed table file offset. This value gets computed while + * constructing the (uncompressed) SFNT header. It is not contained in + * the WOFF file. */ typedef struct WOFF_TableRec_ { @@ -232,7 +231,7 @@ FT_BEGIN_HEADER * TT_LongMetricsRec * * @description: - * A structure modeling the long metrics of the `hmtx' and `vmtx' + * A structure modeling the long metrics of the 'hmtx' and 'vmtx' * TrueType tables. The values are expressed in font units. * * @fields: @@ -256,7 +255,7 @@ FT_BEGIN_HEADER * TT_ShortMetrics * * @description: - * A simple type to model the short metrics of the `hmtx' and `vmtx' + * A simple type to model the short metrics of the 'hmtx' and 'vmtx' * tables. */ typedef FT_Short TT_ShortMetrics; @@ -268,10 +267,9 @@ FT_BEGIN_HEADER * TT_NameRec * * @description: - * A structure modeling TrueType name records. Name records are used - * to store important strings like family name, style name, - * copyright, etc. in _localized_ versions (i.e., language, encoding, - * etc). + * A structure modeling TrueType name records. Name records are used to + * store important strings like family name, style name, copyright, + * etc. in _localized_ versions (i.e., language, encoding, etc). * * @fields: * platformID :: @@ -290,11 +288,11 @@ FT_BEGIN_HEADER * The length of the string in bytes. * * stringOffset :: - * The offset to the string in the `name' table. + * The offset to the string in the 'name' table. * * string :: - * A pointer to the string's bytes. Note that these - * are usually UTF-16 encoded characters. + * A pointer to the string's bytes. Note that these are usually UTF-16 + * encoded characters. */ typedef struct TT_NameRec_ { @@ -319,7 +317,7 @@ FT_BEGIN_HEADER * TT_LangTagRec * * @description: - * A structure modeling language tag records in SFNT `name' tables, + * A structure modeling language tag records in SFNT 'name' tables, * introduced in OpenType version 1.6. * * @fields: @@ -327,11 +325,11 @@ FT_BEGIN_HEADER * The length of the string in bytes. * * stringOffset :: - * The offset to the string in the `name' table. + * The offset to the string in the 'name' table. * * string :: - * A pointer to the string's bytes. Note that these - * are UTF-16BE encoded characters. + * A pointer to the string's bytes. Note that these are UTF-16BE + * encoded characters. */ typedef struct TT_LangTagRec_ { @@ -362,8 +360,7 @@ FT_BEGIN_HEADER * The number of names in table. * * storageOffset :: - * The offset of the name table in the `name' - * TrueType table. + * The offset of the name table in the 'name' TrueType table. * * names :: * An array of name records. @@ -409,16 +406,16 @@ FT_BEGIN_HEADER * TT_GaspRangeRec * * @description: - * A tiny structure used to model a gasp range according to the - * TrueType specification. + * A tiny structure used to model a gasp range according to the TrueType + * specification. * * @fields: * maxPPEM :: - * The maximum ppem value to which `gaspFlag' applies. + * The maximum ppem value to which `gaspFlag` applies. * * gaspFlag :: - * A flag describing the grid-fitting and anti-aliasing - * modes to be used. + * A flag describing the grid-fitting and anti-aliasing modes to be + * used. */ typedef struct TT_GaspRangeRec_ { @@ -438,7 +435,7 @@ FT_BEGIN_HEADER * TT_GaspRec * * @description: - * A structure modeling the TrueType `gasp' table used to specify + * A structure modeling the TrueType 'gasp' table used to specify * grid-fitting and anti-aliasing behaviour. * * @fields: @@ -479,9 +476,9 @@ FT_BEGIN_HEADER * TT_SBit_MetricsRec * * @description: - * A structure used to hold the big metrics of a given glyph bitmap - * in a TrueType or OpenType font. These are usually found in the - * `EBDT' (Microsoft) or `bloc' (Apple) table. + * A structure used to hold the big metrics of a given glyph bitmap in a + * TrueType or OpenType font. These are usually found in the 'EBDT' + * (Microsoft) or 'bloc' (Apple) table. * * @fields: * height :: @@ -530,9 +527,9 @@ FT_BEGIN_HEADER * TT_SBit_SmallMetricsRec * * @description: - * A structure used to hold the small metrics of a given glyph bitmap - * in a TrueType or OpenType font. These are usually found in the - * `EBDT' (Microsoft) or the `bdat' (Apple) table. + * A structure used to hold the small metrics of a given glyph bitmap in + * a TrueType or OpenType font. These are usually found in the 'EBDT' + * (Microsoft) or the 'bdat' (Apple) table. * * @fields: * height :: @@ -568,8 +565,8 @@ FT_BEGIN_HEADER * TT_SBit_LineMetricsRec * * @description: - * A structure used to describe the text line metrics of a given - * bitmap strike, for either a horizontal or vertical layout. + * A structure used to describe the text line metrics of a given bitmap + * strike, for either a horizontal or vertical layout. * * @fields: * ascender :: @@ -582,34 +579,27 @@ FT_BEGIN_HEADER * The maximum glyph width in pixels. * * caret_slope_enumerator :: - * Rise of the caret slope, typically set - * to 1 for non-italic fonts. + * Rise of the caret slope, typically set to 1 for non-italic fonts. * * caret_slope_denominator :: - * Rise of the caret slope, typically set - * to 0 for non-italic fonts. + * Rise of the caret slope, typically set to 0 for non-italic fonts. * * caret_offset :: - * Offset in pixels to move the caret for - * proper positioning. + * Offset in pixels to move the caret for proper positioning. * * min_origin_SB :: - * Minimum of horiBearingX (resp. - * vertBearingY). + * Minimum of horiBearingX (resp. vertBearingY). * min_advance_SB :: * Minimum of * - * horizontal advance - - * ( horiBearingX + width ) + * horizontal advance - ( horiBearingX + width ) * * resp. * - * vertical advance - - * ( vertBearingY + height ) + * vertical advance - ( vertBearingY + height ) * * max_before_BL :: - * Maximum of horiBearingY (resp. - * vertBearingY). + * Maximum of horiBearingY (resp. vertBearingY). * * min_after_BL :: * Minimum of @@ -621,8 +611,7 @@ FT_BEGIN_HEADER * vertBearingX - width * * pads :: - * Unused (to make the size of the record - * a multiple of 32 bits. + * Unused (to make the size of the record a multiple of 32 bits. */ typedef struct TT_SBit_LineMetricsRec_ { @@ -647,8 +636,8 @@ FT_BEGIN_HEADER * TT_SBit_RangeRec * * @description: - * A TrueType/OpenType subIndexTable as defined in the `EBLC' - * (Microsoft) or `bloc' (Apple) tables. + * A TrueType/OpenType subIndexTable as defined in the 'EBLC' (Microsoft) + * or 'bloc' (Apple) tables. * * @fields: * first_glyph :: @@ -658,26 +647,25 @@ FT_BEGIN_HEADER * The last glyph index in the range. * * index_format :: - * The format of index table. Valid values are 1 - * to 5. + * The format of index table. Valid values are 1 to 5. * * image_format :: - * The format of `EBDT' image data. + * The format of 'EBDT' image data. * * image_offset :: - * The offset to image data in `EBDT'. + * The offset to image data in 'EBDT'. * * image_size :: - * For index formats 2 and 5. This is the size in - * bytes of each glyph bitmap. + * For index formats 2 and 5. This is the size in bytes of each glyph + * bitmap. * * big_metrics :: - * For index formats 2 and 5. This is the big - * metrics for each glyph bitmap. + * For index formats 2 and 5. This is the big metrics for each glyph + * bitmap. * * num_glyphs :: - * For index formats 4 and 5. This is the number of - * glyphs in the code array. + * For index formats 4 and 5. This is the number of glyphs in the code + * array. * * glyph_offsets :: * For index formats 1 and 3. @@ -686,8 +674,8 @@ FT_BEGIN_HEADER * For index formats 4 and 5. * * table_offset :: - * The offset of the index table in the `EBLC' - * table. Only used during strike loading. + * The offset of the index table in the 'EBLC' table. Only used during + * strike loading. */ typedef struct TT_SBit_RangeRec_ { @@ -716,8 +704,8 @@ FT_BEGIN_HEADER * TT_SBit_StrikeRec * * @description: - * A structure used describe a given bitmap strike in the `EBLC' - * (Microsoft) or `bloc' (Apple) tables. + * A structure used describe a given bitmap strike in the 'EBLC' + * (Microsoft) or 'bloc' (Apple) tables. * * @fields: * num_index_ranges :: @@ -727,10 +715,9 @@ FT_BEGIN_HEADER * An array of glyph index ranges. * * color_ref :: - * Unused. `color_ref' is put in for future - * enhancements, but these fields are already - * in use by other platforms (e.g. Newton). - * For details, please see + * Unused. `color_ref` is put in for future enhancements, but these + * fields are already in use by other platforms (e.g. Newton). For + * details, please see * * https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6bloc.html * @@ -753,12 +740,10 @@ FT_BEGIN_HEADER * The number of vertical pixels per EM. * * bit_depth :: - * The bit depth. Valid values are 1, 2, 4, - * and 8. + * The bit depth. Valid values are 1, 2, 4, and 8. * * flags :: - * Is this a vertical or horizontal strike? For - * details, please see + * Is this a vertical or horizontal strike? For details, please see * * https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6bloc.html */ @@ -818,8 +803,8 @@ FT_BEGIN_HEADER * TT_SBit_ScaleRec * * @description: - * A structure used describe a given bitmap scaling table, as defined - * in the `EBSC' table. + * A structure used describe a given bitmap scaling table, as defined in + * the 'EBSC' table. * * @fields: * hori :: @@ -873,8 +858,8 @@ FT_BEGIN_HEADER * TT_Post_20Rec * * @description: - * Postscript names sub-table, format 2.0. Stores the PS name of - * each glyph in the font face. + * Postscript names sub-table, format 2.0. Stores the PS name of each + * glyph in the font face. * * @fields: * num_glyphs :: @@ -905,16 +890,15 @@ FT_BEGIN_HEADER * TT_Post_25Rec * * @description: - * Postscript names sub-table, format 2.5. Stores the PS name of - * each glyph in the font face. + * Postscript names sub-table, format 2.5. Stores the PS name of each + * glyph in the font face. * * @fields: * num_glyphs :: * The number of glyphs in the table. * * offsets :: - * An array of signed offsets in a normal Mac - * Postscript name encoding. + * An array of signed offsets in a normal Mac Postscript name encoding. */ typedef struct TT_Post_25_ { @@ -987,25 +971,25 @@ FT_BEGIN_HEADER /* * These types are used to support a `BDF ' table that isn't part of the - * official TrueType specification. It is mainly used in SFNT-based - * bitmap fonts that were generated from a set of BDF fonts. + * official TrueType specification. It is mainly used in SFNT-based bitmap + * fonts that were generated from a set of BDF fonts. * * The format of the table is as follows. * - * USHORT version `BDF ' table version number, should be 0x0001. - * USHORT strikeCount Number of strikes (bitmap sizes) in this table. - * ULONG stringTable Offset (from start of BDF table) to string + * USHORT version `BDF ' table version number, should be 0x0001. USHORT + * strikeCount Number of strikes (bitmap sizes) in this table. ULONG + * stringTable Offset (from start of BDF table) to string * table. * * This is followed by an array of `strikeCount' descriptors, having the * following format. * - * USHORT ppem Vertical pixels per EM for this strike. - * USHORT numItems Number of items for this strike (properties and + * USHORT ppem Vertical pixels per EM for this strike. USHORT numItems + * Number of items for this strike (properties and * atoms). Maximum is 255. * - * This array in turn is followed by `strikeCount' value sets. Each - * `value set' is an array of `numItems' items with the following format. + * This array in turn is followed by `strikeCount' value sets. Each `value + * set' is an array of `numItems' items with the following format. * * ULONG item_name Offset in string table to item name. * USHORT item_type The item type. Possible values are @@ -1058,8 +1042,8 @@ FT_BEGIN_HEADER * This structure/class is defined here because it is common to the * following formats: TTF, OpenType-TT, and OpenType-CFF. * - * Note, however, that the classes TT_Size and TT_GlyphSlot are not - * shared between font drivers, and are thus defined in `ttobjs.h'. + * Note, however, that the classes TT_Size and TT_GlyphSlot are not shared + * between font drivers, and are thus defined in `ttobjs.h`. * */ @@ -1070,12 +1054,11 @@ FT_BEGIN_HEADER * TT_Face * * @description: - * A handle to a TrueType face/font object. A TT_Face encapsulates - * the resolution and scaling independent parts of a TrueType font - * resource. + * A handle to a TrueType face/font object. A TT_Face encapsulates the + * resolution and scaling independent parts of a TrueType font resource. * * @note: - * The TT_Face structure is also used as a `parent class' for the + * The TT_Face structure is also used as a 'parent class' for the * OpenType-CFF class (T2_Face). */ typedef struct TT_FaceRec_* TT_Face; @@ -1109,8 +1092,7 @@ FT_BEGIN_HEADER * * @output: * length :: - * The length of the table in bytes. Set to 0 if not - * needed. + * The length of the table in bytes. Set to 0 if not needed. * * @return: * FreeType error code. 0 means success. @@ -1141,8 +1123,7 @@ FT_BEGIN_HEADER * glyph index :: The index of the glyph to access. * * offset :: - * The offset of the glyph according to the - * `locations' table. + * The offset of the glyph according to the 'locations' table. * * byte_count :: * The size of the frame in bytes. @@ -1152,8 +1133,8 @@ FT_BEGIN_HEADER * * @note: * This function is normally equivalent to FT_STREAM_SEEK(offset) - * followed by FT_FRAME_ENTER(byte_count) with the loader's stream, - * but alternative formats (e.g. compressed ones) might use something + * followed by FT_FRAME_ENTER(byte_count) with the loader's stream, but + * alternative formats (e.g. compressed ones) might use something * different. */ typedef FT_Error @@ -1169,8 +1150,8 @@ FT_BEGIN_HEADER * TT_Loader_ReadGlyphFunc * * @description: - * Reads one glyph element (its header, a simple glyph, or a - * composite) from the loader's current stream frame. + * Reads one glyph element (its header, a simple glyph, or a composite) + * from the loader's current stream frame. * * @input: * loader :: @@ -1254,111 +1235,90 @@ FT_BEGIN_HEADER * * @fields: * root :: - * The base FT_Face structure, managed by the - * base layer. + * The base FT_Face structure, managed by the base layer. * * ttc_header :: - * The TrueType collection header, used when - * the file is a `ttc' rather than a `ttf'. - * For ordinary font files, the field - * `ttc_header.count' is set to 0. + * The TrueType collection header, used when the file is a 'ttc' rather + * than a 'ttf'. For ordinary font files, the field `ttc_header.count` + * is set to 0. * * format_tag :: * The font format tag. * * num_tables :: - * The number of TrueType tables in this font - * file. + * The number of TrueType tables in this font file. * * dir_tables :: - * The directory of TrueType tables for this - * font file. + * The directory of TrueType tables for this font file. * * header :: - * The font's font header (`head' table). - * Read on font opening. + * The font's font header ('head' table). Read on font opening. * * horizontal :: - * The font's horizontal header (`hhea' - * table). This field also contains the - * associated horizontal metrics table - * (`hmtx'). + * The font's horizontal header ('hhea' table). This field also + * contains the associated horizontal metrics table ('hmtx'). * * max_profile :: - * The font's maximum profile table. Read on - * font opening. Note that some maximum - * values cannot be taken directly from this - * table. We thus define additional fields - * below to hold the computed maxima. + * The font's maximum profile table. Read on font opening. Note that + * some maximum values cannot be taken directly from this table. We + * thus define additional fields below to hold the computed maxima. * * vertical_info :: - * A boolean which is set when the font file - * contains vertical metrics. If not, the - * value of the `vertical' field is - * undefined. + * A boolean which is set when the font file contains vertical metrics. + * If not, the value of the 'vertical' field is undefined. * * vertical :: - * The font's vertical header (`vhea' table). - * This field also contains the associated - * vertical metrics table (`vmtx'), if found. - * IMPORTANT: The contents of this field is - * undefined if the `vertical_info' field is - * unset. + * The font's vertical header ('vhea' table). This field also contains + * the associated vertical metrics table ('vmtx'), if found. + * IMPORTANT: The contents of this field is undefined if the + * `vertical_info` field is unset. * * num_names :: - * The number of name records within this - * TrueType font. + * The number of name records within this TrueType font. * * name_table :: - * The table of name records (`name'). + * The table of name records ('name'). * * os2 :: - * The font's OS/2 table (`OS/2'). + * The font's OS/2 table ('OS/2'). * * postscript :: - * The font's PostScript table (`post' - * table). The PostScript glyph names are - * not loaded by the driver on face opening. - * See the `ttpost' module for more details. + * The font's PostScript table ('post' table). The PostScript glyph + * names are not loaded by the driver on face opening. See the + * 'ttpost' module for more details. * * cmap_table :: - * Address of the face's `cmap' SFNT table - * in memory (it's an extracted frame). + * Address of the face's 'cmap' SFNT table in memory (it's an extracted + * frame). * * cmap_size :: - * The size in bytes of the `cmap_table' - * described above. + * The size in bytes of the `cmap_table` described above. * * goto_table :: - * A function called by each TrueType table - * loader to position a stream's cursor to - * the start of a given table according to - * its tag. It defaults to TT_Goto_Face but - * can be different for strange formats (e.g. - * Type 42). + * A function called by each TrueType table loader to position a + * stream's cursor to the start of a given table according to its tag. + * It defaults to TT_Goto_Face but can be different for strange formats + * (e.g. Type 42). * * access_glyph_frame :: - * A function used to access the frame of a - * given glyph within the face's font file. + * A function used to access the frame of a given glyph within the + * face's font file. * * forget_glyph_frame :: - * A function used to forget the frame of a - * given glyph when all data has been loaded. + * A function used to forget the frame of a given glyph when all data + * has been loaded. * * read_glyph_header :: - * A function used to read a glyph header. - * It must be called between an `access' and - * `forget'. + * A function used to read a glyph header. It must be called between + * an 'access' and 'forget'. * * read_simple_glyph :: - * A function used to read a simple glyph. - * It must be called after the header was - * read, and before the `forget'. + * A function used to read a simple glyph. It must be called after the + * header was read, and before the 'forget'. * * read_composite_glyph :: - * A function used to read a composite glyph. - * It must be called after the header was - * read, and before the `forget'. + * A function used to read a composite glyph. It must be called after + * the header was read, and before the 'forget'. * * sfnt :: * A pointer to the SFNT service. @@ -1370,38 +1330,33 @@ FT_BEGIN_HEADER * A pointer to the Multiple Masters service. * * var :: - * A pointer to the Metrics Variations - * service. + * A pointer to the Metrics Variations service. * * hdmx :: - * The face's horizontal device metrics - * (`hdmx' table). This table is optional in - * TrueType/OpenType fonts. + * The face's horizontal device metrics ('hdmx' table). This table is + * optional in TrueType/OpenType fonts. * * gasp :: - * The grid-fitting and scaling properties - * table (`gasp'). This table is optional in - * TrueType/OpenType fonts. + * The grid-fitting and scaling properties table ('gasp'). This table + * is optional in TrueType/OpenType fonts. * * pclt :: - * The `pclt' SFNT table. + * The 'pclt' SFNT table. * * num_sbit_scales :: * The number of sbit scales for this font. * * sbit_scales :: - * Array of sbit scales embedded in this - * font. This table is optional in a - * TrueType/OpenType font. + * Array of sbit scales embedded in this font. This table is optional + * in a TrueType/OpenType font. * * postscript_names :: - * A table used to store the Postscript names - * of the glyphs for this font. See the - * file `ttconfig.h' for comments on the + * A table used to store the Postscript names of the glyphs for this + * font. See the file `ttconfig.h` for comments on the * TT_CONFIG_OPTION_POSTSCRIPT_NAMES option. * * palette_data :: - * Some fields from the `CPAL' table that are directly indexed. + * Some fields from the 'CPAL' table that are directly indexed. * * palette_index :: * The current palette index, as set by @FT_Palette_Select. @@ -1413,109 +1368,95 @@ FT_BEGIN_HEADER * There was a call to @FT_Palette_Set_Foreground_Color. * * foreground_color :: - * The current foreground color corresponding to `CPAL' color index - * 0xFFFF. Only valid if `have_foreground_color' is set. + * The current foreground color corresponding to 'CPAL' color index + * 0xFFFF. Only valid if `have_foreground_color` is set. * * font_program_size :: - * Size in bytecodes of the face's font - * program. 0 if none defined. Ignored for - * Type 2 fonts. + * Size in bytecodes of the face's font program. 0 if none defined. + * Ignored for Type 2 fonts. * * font_program :: - * The face's font program (bytecode stream) - * executed at load time, also used during - * glyph rendering. Comes from the `fpgm' - * table. Ignored for Type 2 font fonts. + * The face's font program (bytecode stream) executed at load time, + * also used during glyph rendering. Comes from the 'fpgm' table. + * Ignored for Type 2 font fonts. * * cvt_program_size :: - * The size in bytecodes of the face's cvt - * program. Ignored for Type 2 fonts. + * The size in bytecodes of the face's cvt program. Ignored for Type 2 + * fonts. * * cvt_program :: - * The face's cvt program (bytecode stream) - * executed each time an instance/size is - * changed/reset. Comes from the `prep' - * table. Ignored for Type 2 fonts. + * The face's cvt program (bytecode stream) executed each time an + * instance/size is changed/reset. Comes from the 'prep' table. + * Ignored for Type 2 fonts. * * cvt_size :: - * Size of the control value table (in - * entries). Ignored for Type 2 fonts. + * Size of the control value table (in entries). Ignored for Type 2 + * fonts. * * cvt :: - * The face's original control value table. - * Coordinates are expressed in unscaled font - * units. Comes from the `cvt ' table. - * Ignored for Type 2 fonts. + * The face's original control value table. Coordinates are expressed + * in unscaled font units. Comes from the 'cvt ' table. Ignored for + * Type 2 fonts. * * interpreter :: - * A pointer to the TrueType bytecode - * interpreters field is also used to hook - * the debugger in `ttdebug'. + * A pointer to the TrueType bytecode interpreters field is also used + * to hook the debugger in 'ttdebug'. * * extra :: * Reserved for third-party font drivers. * * postscript_name :: - * The PS name of the font. Used by the - * postscript name service. + * The PS name of the font. Used by the postscript name service. * * glyf_len :: - * The length of the `glyf' table. Needed - * for malformed `loca' tables. + * The length of the 'glyf' table. Needed for malformed 'loca' tables. * * glyf_offset :: - * The file offset of the `glyf' table. + * The file offset of the 'glyf' table. * * is_cff2 :: * Set if the font format is CFF2. * * doblend :: - * A boolean which is set if the font should - * be blended (this is for GX var). + * A boolean which is set if the font should be blended (this is for GX + * var). * * blend :: - * Contains the data needed to control GX - * variation tables (rather like Multiple - * Master data). + * Contains the data needed to control GX variation tables (rather like + * Multiple Master data). * * variation_support :: - * Flags that indicate which OpenType - * functionality related to font variation - * support is present, valid, and usable. - * For example, TT_FACE_FLAG_VAR_FVAR is only - * set if we have at least one design axis. + * Flags that indicate which OpenType functionality related to font + * variation support is present, valid, and usable. For example, + * TT_FACE_FLAG_VAR_FVAR is only set if we have at least one design + * axis. * * var_postscript_prefix :: - * The PostScript name prefix needed for - * constructing a variation font instance's - * PS name . + * The PostScript name prefix needed for constructing a variation font + * instance's PS name . * * var_postscript_prefix_len :: - * The length of the `var_postscript_prefix' - * string. + * The length of the `var_postscript_prefix` string. * * horz_metrics_size :: - * The size of the `hmtx' table. + * The size of the 'hmtx' table. * * vert_metrics_size :: - * The size of the `vmtx' table. + * The size of the 'vmtx' table. * * num_locations :: - * The number of glyph locations in this - * TrueType file. This should be - * identical to the number of glyphs. - * Ignored for Type 2 fonts. + * The number of glyph locations in this TrueType file. This should be + * identical to the number of glyphs. Ignored for Type 2 fonts. * * glyph_locations :: - * An array of longs. These are offsets to - * glyph data within the `glyf' table. - * Ignored for Type 2 font faces. + * An array of longs. These are offsets to glyph data within the + * 'glyf' table. Ignored for Type 2 font faces. * * hdmx_table :: - * A pointer to the `hdmx' table. + * A pointer to the 'hdmx' table. * * hdmx_table_size :: - * The size of the `hdmx' table. + * The size of the 'hdmx' table. * * hdmx_record_count :: * The number of hdmx records. @@ -1524,79 +1465,70 @@ FT_BEGIN_HEADER * The size of a single hdmx record. * * hdmx_record_sizes :: - * An array holding the ppem sizes available - * in the `hdmx' table. + * An array holding the ppem sizes available in the 'hdmx' table. * * sbit_table :: - * A pointer to the font's embedded bitmap - * location table. + * A pointer to the font's embedded bitmap location table. * * sbit_table_size :: - * The size of `sbit_table'. + * The size of `sbit_table`. * * sbit_table_type :: * The sbit table type (CBLC, sbix, etc.). * * sbit_num_strikes :: - * The number of sbit strikes exposed by - * FreeType's API, omitting invalid strikes. + * The number of sbit strikes exposed by FreeType's API, omitting + * invalid strikes. * * sbit_strike_map :: - * A mapping between the strike indices - * exposed by the API and the indices used in - * the font's sbit table. + * A mapping between the strike indices exposed by the API and the + * indices used in the font's sbit table. * * cpal :: - * A pointer to data related to the `CPAL' table. NULL if the table - * is not available. + * A pointer to data related to the 'CPAL' table. NULL if the table is + * not available. * * colr :: - * A pointer to data related to the `COLR' table. NULL if the table - * is not available. + * A pointer to data related to the 'COLR' table. NULL if the table is + * not available. * * kern_table :: - * A pointer to the `kern' table. + * A pointer to the 'kern' table. * * kern_table_size :: - * The size of the `kern' table. + * The size of the 'kern' table. * * num_kern_tables :: - * The number of supported kern subtables - * (up to 32; FreeType recognizes only - * horizontal ones with format 0). + * The number of supported kern subtables (up to 32; FreeType + * recognizes only horizontal ones with format 0). * * kern_avail_bits :: - * The availability status of kern subtables; - * if bit n is set, table n is available. + * The availability status of kern subtables; if bit n is set, table n + * is available. * * kern_order_bits :: - * The sortedness status of kern subtables; - * if bit n is set, table n is sorted. + * The sortedness status of kern subtables; if bit n is set, table n is + * sorted. * * bdf :: - * Data related to an SFNT font's `bdf' - * table; see `tttypes.h'. + * Data related to an SFNT font's 'bdf' table; see `tttypes.h`. * * horz_metrics_offset :: - * The file offset of the `hmtx' table. + * The file offset of the 'hmtx' table. * * vert_metrics_offset :: - * The file offset of the `vmtx' table. + * The file offset of the 'vmtx' table. * * sph_found_func_flags :: - * Flags identifying special bytecode - * functions (used by the v38 implementation - * of the bytecode interpreter). + * Flags identifying special bytecode functions (used by the v38 + * implementation of the bytecode interpreter). * * sph_compatibility_mode :: - * This flag is set if we are in ClearType - * backward compatibility mode (used by the - * v38 implementation of the bytecode - * interpreter). + * This flag is set if we are in ClearType backward compatibility mode + * (used by the v38 implementation of the bytecode interpreter). * * ebdt_start :: - * The file offset of the sbit data table - * (CBDT, bdat, etc.). + * The file offset of the sbit data table (CBDT, bdat, etc.). * * ebdt_size :: * The size of the sbit data table. @@ -1815,8 +1747,7 @@ FT_BEGIN_HEADER * The current number of contours in the zone. * * org :: - * The original glyph coordinates (font - * units/scaled). + * The original glyph coordinates (font units/scaled). * * cur :: * The current glyph coordinates (scaled/hinted). diff --git a/include/freetype/t1tables.h b/include/freetype/t1tables.h index 784f1b90a..29e619d37 100644 --- a/include/freetype/t1tables.h +++ b/include/freetype/t1tables.h @@ -118,9 +118,8 @@ FT_BEGIN_HEADER * T1_FontInfo * * @description: - * This type is equivalent to @PS_FontInfoRec. It is deprecated but - * kept to maintain source compatibility between various versions of - * FreeType. + * This type is equivalent to @PS_FontInfoRec. It is deprecated but kept + * to maintain source compatibility between various versions of FreeType. */ typedef PS_FontInfoRec T1_FontInfo; @@ -131,9 +130,9 @@ FT_BEGIN_HEADER * PS_PrivateRec * * @description: - * A structure used to model a Type~1 or Type~2 private dictionary. - * Note that for Multiple Master fonts, each instance has its own - * Private dictionary. + * A structure used to model a Type~1 or Type~2 private dictionary. Note + * that for Multiple Master fonts, each instance has its own Private + * dictionary. */ typedef struct PS_PrivateRec_ { @@ -193,9 +192,8 @@ FT_BEGIN_HEADER * T1_Private * * @description: - * This type is equivalent to @PS_PrivateRec. It is deprecated but - * kept to maintain source compatibility between various versions of - * FreeType. + * This type is equivalent to @PS_PrivateRec. It is deprecated but kept + * to maintain source compatibility between various versions of FreeType. */ typedef PS_PrivateRec T1_Private; @@ -206,9 +204,9 @@ FT_BEGIN_HEADER * T1_Blend_Flags * * @description: - * A set of flags used to indicate which fields are present in a - * given blend dictionary (font info or private). Used to support - * Multiple Masters fonts. + * A set of flags used to indicate which fields are present in a given + * blend dictionary (font info or private). Used to support Multiple + * Masters fonts. * * @values: * T1_BLEND_UNDERLINE_POSITION :: @@ -337,14 +335,14 @@ FT_BEGIN_HEADER * * @description: * A structure used to represent data in a CID top-level dictionary. In - * most cases, they are part of the font's `/FDArray' array. Within a + * most cases, they are part of the font's '/FDArray' array. Within a * CID font file, such (internal) subfont dictionaries are enclosed by - * `%ADOBeginFontDict' and `%ADOEndFontDict' comments. + * '%ADOBeginFontDict' and '%ADOEndFontDict' comments. * - * Note that `CID_FaceDictRec' misses a field for the `/FontName' + * Note that `CID_FaceDictRec` misses a field for the '/FontName' * keyword, specifying the subfont's name (the top-level font name is - * given by the `/CIDFontName' keyword). This is an oversight, but it - * doesn't limit the `cid' font module's functionality because FreeType + * given by the '/CIDFontName' keyword). This is an oversight, but it + * doesn't limit the 'cid' font module's functionality because FreeType * neither needs this entry nor gives access to CID subfonts. */ typedef struct CID_FaceDictRec_ @@ -447,9 +445,8 @@ FT_BEGIN_HEADER * CID_Info * * @description: - * This type is equivalent to @CID_FaceInfoRec. It is deprecated but - * kept to maintain source compatibility between various versions of - * FreeType. + * This type is equivalent to @CID_FaceInfoRec. It is deprecated but kept + * to maintain source compatibility between various versions of FreeType. */ typedef CID_FaceInfoRec CID_Info; @@ -460,10 +457,9 @@ FT_BEGIN_HEADER * FT_Has_PS_Glyph_Names * * @description: - * Return true if a given face provides reliable PostScript glyph - * names. This is similar to using the @FT_HAS_GLYPH_NAMES macro, - * except that certain fonts (mostly TrueType) contain incorrect - * glyph name tables. + * Return true if a given face provides reliable PostScript glyph names. + * This is similar to using the @FT_HAS_GLYPH_NAMES macro, except that + * certain fonts (mostly TrueType) contain incorrect glyph name tables. * * When this function returns true, the caller is sure that the glyph * names returned by @FT_Get_Glyph_Name are reliable. @@ -501,12 +497,12 @@ FT_BEGIN_HEADER * FreeType error code. 0~means success. * * @note: - * String pointers within the @PS_FontInfoRec structure are owned by - * the face and don't need to be freed by the caller. Missing entries - * in the font's FontInfo dictionary are represented by NULL pointers. + * String pointers within the @PS_FontInfoRec structure are owned by the + * face and don't need to be freed by the caller. Missing entries in + * the font's FontInfo dictionary are represented by NULL pointers. * * If the font's format is not PostScript-based, this function will - * return the `FT_Err_Invalid_Argument' error code. + * return the `FT_Err_Invalid_Argument` error code. * */ FT_EXPORT( FT_Error ) @@ -539,7 +535,7 @@ FT_BEGIN_HEADER * the face and don't need to be freed by the caller. * * If the font's format is not PostScript-based, this function returns - * the `FT_Err_Invalid_Argument' error code. + * the `FT_Err_Invalid_Argument` error code. * */ FT_EXPORT( FT_Error ) @@ -553,8 +549,7 @@ FT_BEGIN_HEADER * T1_EncodingType * * @description: - * An enumeration describing the `Encoding' entry in a Type 1 - * dictionary. + * An enumeration describing the 'Encoding' entry in a Type 1 dictionary. * * @values: * T1_ENCODING_TYPE_NONE :: @@ -583,8 +578,8 @@ FT_BEGIN_HEADER * PS_Dict_Keys * * @description: - * An enumeration used in calls to @FT_Get_PS_Font_Value to identify - * the Type~1 dictionary entry to retrieve. + * An enumeration used in calls to @FT_Get_PS_Font_Value to identify the + * Type~1 dictionary entry to retrieve. * * @values: * PS_DICT_FONT_TYPE :: @@ -725,38 +720,38 @@ FT_BEGIN_HEADER * The value matching the above key, if it exists. * * @return: - * The amount of memory (in bytes) required to hold the requested - * value (if it exists, -1 otherwise). + * The amount of memory (in bytes) required to hold the requested value + * (if it exists, -1 otherwise). * * @note: * The values returned are not pointers into the internal structures of - * the face, but are `fresh' copies, so that the memory containing them + * the face, but are 'fresh' copies, so that the memory containing them * belongs to the calling application. This also enforces the - * `read-only' nature of these values, i.e., this function cannot be + * 'read-only' nature of these values, i.e., this function cannot be * used to manipulate the face. * - * `value' is a void pointer because the values returned can be of + * 'value' is a void pointer because the values returned can be of * various types. * - * If either `value' is NULL or `value_len' is too small, just the + * If either 'value' is NULL or `value_len` is too small, just the * required memory size for the requested entry is returned. * - * The `idx' parameter is used, not only to retrieve elements of, for + * The 'idx' parameter is used, not only to retrieve elements of, for * example, the FontMatrix or FontBBox, but also to retrieve name keys * from the CharStrings dictionary, and the charstrings themselves. It * is ignored for atomic values. * - * PS_DICT_BLUE_SCALE returns a value that is scaled up by 1000. To - * get the value as in the font stream, you need to divide by - * 65536000.0 (to remove the FT_Fixed scale, and the x1000 scale). + * PS_DICT_BLUE_SCALE returns a value that is scaled up by 1000. To get + * the value as in the font stream, you need to divide by 65536000.0 (to + * remove the FT_Fixed scale, and the x1000 scale). * * IMPORTANT: Only key/value pairs read by the FreeType interpreter can - * be retrieved. So, for example, PostScript procedures such as NP, - * ND, and RD are not available. Arbitrary keys are, obviously, not be + * be retrieved. So, for example, PostScript procedures such as NP, ND, + * and RD are not available. Arbitrary keys are, obviously, not be * available either. * * If the font's format is not PostScript-based, this function returns - * the `FT_Err_Invalid_Argument' error code. + * the `FT_Err_Invalid_Argument` error code. * * @since: * 2.4.8 diff --git a/include/freetype/ttnameid.h b/include/freetype/ttnameid.h index f71516c2c..f86ecee72 100644 --- a/include/freetype/ttnameid.h +++ b/include/freetype/ttnameid.h @@ -35,8 +35,8 @@ FT_BEGIN_HEADER /************************************************************************** * - * Possible values for the `platform' identifier code in the name - * records of an SFNT `name' table. + * Possible values for the 'platform' identifier code in the name records + * of an SFNT 'name' table. * */ @@ -47,30 +47,31 @@ FT_BEGIN_HEADER * TT_PLATFORM_XXX * * @description: - * A list of valid values for the `platform_id' identifier code in + * A list of valid values for the `platform_id` identifier code in * @FT_CharMapRec and @FT_SfntName structures. * * @values: * TT_PLATFORM_APPLE_UNICODE :: * Used by Apple to indicate a Unicode character map and/or name entry. - * See @TT_APPLE_ID_XXX for corresponding `encoding_id' values. Note + * See @TT_APPLE_ID_XXX for corresponding `encoding_id` values. Note * that name entries in this format are coded as big-endian UCS-2 * character codes _only_. * * TT_PLATFORM_MACINTOSH :: - * Used by Apple to indicate a MacOS-specific charmap and/or name entry. - * See @TT_MAC_ID_XXX for corresponding `encoding_id' values. Note that - * most TrueType fonts contain an Apple roman charmap to be usable on - * MacOS systems (even if they contain a Microsoft charmap as well). + * Used by Apple to indicate a MacOS-specific charmap and/or name + * entry. See @TT_MAC_ID_XXX for corresponding `encoding_id` values. + * Note that most TrueType fonts contain an Apple roman charmap to be + * usable on MacOS systems (even if they contain a Microsoft charmap as + * well). * * TT_PLATFORM_ISO :: - * This value was used to specify ISO/IEC 10646 charmaps. It is however - * now deprecated. See @TT_ISO_ID_XXX for a list of corresponding - * `encoding_id' values. + * This value was used to specify ISO/IEC 10646 charmaps. It is + * however now deprecated. See @TT_ISO_ID_XXX for a list of + * corresponding `encoding_id` values. * * TT_PLATFORM_MICROSOFT :: * Used by Microsoft to indicate Windows-specific charmaps. See - * @TT_MS_ID_XXX for a list of corresponding `encoding_id' values. + * @TT_MS_ID_XXX for a list of corresponding `encoding_id` values. * Note that most fonts contain a Unicode charmap using * (TT_PLATFORM_MICROSOFT, @TT_MS_ID_UNICODE_CS). * @@ -97,7 +98,7 @@ FT_BEGIN_HEADER * TT_APPLE_ID_XXX * * @description: - * A list of valid values for the `encoding_id' for + * A list of valid values for the `encoding_id` for * @TT_PLATFORM_APPLE_UNICODE charmaps and name entries. * * @values: @@ -117,8 +118,8 @@ FT_BEGIN_HEADER * Unicode 3.1 and beyond, using UTF-32. * * TT_APPLE_ID_VARIANT_SELECTOR :: - * From Adobe, not Apple. Not a normal cmap. Specifies variations - * on a real cmap. + * From Adobe, not Apple. Not a normal cmap. Specifies variations on + * a real cmap. * * TT_APPLE_ID_FULL_UNICODE :: * Used for fallback fonts that provide complete Unicode coverage with @@ -140,7 +141,7 @@ FT_BEGIN_HEADER * TT_MAC_ID_XXX * * @description: - * A list of valid values for the `encoding_id' for + * A list of valid values for the `encoding_id` for * @TT_PLATFORM_MACINTOSH charmaps and name entries. */ @@ -186,8 +187,8 @@ FT_BEGIN_HEADER * TT_ISO_ID_XXX * * @description: - * A list of valid values for the `encoding_id' for - * @TT_PLATFORM_ISO charmaps and name entries. + * A list of valid values for the `encoding_id` for @TT_PLATFORM_ISO + * charmaps and name entries. * * Their use is now deprecated. * @@ -211,7 +212,7 @@ FT_BEGIN_HEADER * TT_MS_ID_XXX * * @description: - * A list of valid values for the `encoding_id' for + * A list of valid values for the `encoding_id` for * @TT_PLATFORM_MICROSOFT charmaps and name entries. * * @values: @@ -219,16 +220,15 @@ FT_BEGIN_HEADER * Microsoft symbol encoding. See @FT_ENCODING_MS_SYMBOL. * * TT_MS_ID_UNICODE_CS :: - * Microsoft WGL4 charmap, matching Unicode. See - * @FT_ENCODING_UNICODE. + * Microsoft WGL4 charmap, matching Unicode. See @FT_ENCODING_UNICODE. * * TT_MS_ID_SJIS :: * Shift JIS Japanese encoding. See @FT_ENCODING_SJIS. * * TT_MS_ID_PRC :: * Chinese encodings as used in the People's Republic of China (PRC). - * This means the encodings GB~2312 and its supersets GBK and - * GB~18030. See @FT_ENCODING_PRC. + * This means the encodings GB~2312 and its supersets GBK and GB~18030. + * See @FT_ENCODING_PRC. * * TT_MS_ID_BIG_5 :: * Traditional Chinese as used in Taiwan and Hong Kong. See @@ -264,8 +264,8 @@ FT_BEGIN_HEADER * TT_ADOBE_ID_XXX * * @description: - * A list of valid values for the `encoding_id' for - * @TT_PLATFORM_ADOBE charmaps. This is a FreeType-specific extension! + * A list of valid values for the `encoding_id` for @TT_PLATFORM_ADOBE + * charmaps. This is a FreeType-specific extension! * * @values: * TT_ADOBE_ID_STANDARD :: @@ -291,7 +291,7 @@ FT_BEGIN_HEADER * * @description: * Possible values of the language identifier field in the name records - * of the SFNT `name' table if the `platform' identifier code is + * of the SFNT 'name' table if the 'platform' identifier code is * @TT_PLATFORM_MACINTOSH. These values are also used as return values * for function @FT_Get_CMap_Language_ID. * @@ -431,7 +431,7 @@ FT_BEGIN_HEADER * * @description: * Possible values of the language identifier field in the name records - * of the SFNT `name' table if the `platform' identifier code is + * of the SFNT 'name' table if the 'platform' identifier code is * @TT_PLATFORM_MICROSOFT. These values are also used as return values * for function @FT_Get_CMap_Language_ID. * @@ -441,7 +441,7 @@ FT_BEGIN_HEADER * * however, we only provide macros for language identifiers present in * the OpenType specification: Microsoft has abandoned the concept of - * LCIDs (language code identifiers), and format~1 of the `name' table + * LCIDs (language code identifiers), and format~1 of the 'name' table * provides a better mechanism for languages not covered here. * * More legacy values not listed in the reference can be found in the @@ -786,8 +786,8 @@ FT_BEGIN_HEADER * TT_NAME_ID_XXX * * @description: - * Possible values of the `name' identifier field in the name records of - * an SFNT `name' table. These values are platform independent. + * Possible values of the 'name' identifier field in the name records of + * an SFNT 'name' table. These values are platform independent. */ #define TT_NAME_ID_COPYRIGHT 0 @@ -840,8 +840,8 @@ FT_BEGIN_HEADER * TT_UCR_XXX * * @description: - * Possible bit mask values for the `ulUnicodeRangeX' fields in an SFNT - * `OS/2' table. + * Possible bit mask values for the `ulUnicodeRangeX` fields in an SFNT + * 'OS/2' table. */ /* ulUnicodeRange1 */ diff --git a/include/freetype/tttables.h b/include/freetype/tttables.h index 8ecc8e274..cbb17def7 100644 --- a/include/freetype/tttables.h +++ b/include/freetype/tttables.h @@ -77,8 +77,8 @@ FT_BEGIN_HEADER * TT_Header * * @description: - * A structure to model a TrueType font header table. All fields - * follow the OpenType specification. + * A structure to model a TrueType font header table. All fields follow + * the OpenType specification. */ typedef struct TT_Header_ { @@ -115,76 +115,61 @@ FT_BEGIN_HEADER * TT_HoriHeader * * @description: - * A structure to model a TrueType horizontal header, the `hhea' - * table, as well as the corresponding horizontal metrics table, - * `hmtx'. + * A structure to model a TrueType horizontal header, the 'hhea' table, + * as well as the corresponding horizontal metrics table, 'hmtx'. * * @fields: * Version :: * The table version. * * Ascender :: - * The font's ascender, i.e., the distance - * from the baseline to the top-most of all - * glyph points found in the font. + * The font's ascender, i.e., the distance from the baseline to the + * top-most of all glyph points found in the font. * - * This value is invalid in many fonts, as - * it is usually set by the font designer, - * and often reflects only a portion of the - * glyphs found in the font (maybe ASCII). + * This value is invalid in many fonts, as it is usually set by the + * font designer, and often reflects only a portion of the glyphs found + * in the font (maybe ASCII). * - * You should use the `sTypoAscender' field - * of the `OS/2' table instead if you want - * the correct one. + * You should use the `sTypoAscender` field of the 'OS/2' table instead + * if you want the correct one. * * Descender :: - * The font's descender, i.e., the distance - * from the baseline to the bottom-most of - * all glyph points found in the font. It - * is negative. + * The font's descender, i.e., the distance from the baseline to the + * bottom-most of all glyph points found in the font. It is negative. * - * This value is invalid in many fonts, as - * it is usually set by the font designer, - * and often reflects only a portion of the - * glyphs found in the font (maybe ASCII). + * This value is invalid in many fonts, as it is usually set by the + * font designer, and often reflects only a portion of the glyphs found + * in the font (maybe ASCII). * - * You should use the `sTypoDescender' - * field of the `OS/2' table instead if you - * want the correct one. + * You should use the `sTypoDescender` field of the 'OS/2' table + * instead if you want the correct one. * * Line_Gap :: - * The font's line gap, i.e., the distance - * to add to the ascender and descender to - * get the BTB, i.e., the - * baseline-to-baseline distance for the - * font. + * The font's line gap, i.e., the distance to add to the ascender and + * descender to get the BTB, i.e., the baseline-to-baseline distance + * for the font. * * advance_Width_Max :: - * This field is the maximum of all advance - * widths found in the font. It can be - * used to compute the maximum width of an - * arbitrary string of text. + * This field is the maximum of all advance widths found in the font. + * It can be used to compute the maximum width of an arbitrary string + * of text. * * min_Left_Side_Bearing :: - * The minimum left side bearing of all - * glyphs within the font. + * The minimum left side bearing of all glyphs within the font. * * min_Right_Side_Bearing :: - * The minimum right side bearing of all - * glyphs within the font. + * The minimum right side bearing of all glyphs within the font. * * xMax_Extent :: - * The maximum horizontal extent (i.e., the - * `width' of a glyph's bounding box) for - * all glyphs in the font. + * The maximum horizontal extent (i.e., the 'width' of a glyph's + * bounding box) for all glyphs in the font. * * caret_Slope_Rise :: - * The rise coefficient of the cursor's - * slope of the cursor (slope=rise/run). + * The rise coefficient of the cursor's slope of the cursor + * (slope=rise/run). * * caret_Slope_Run :: - * The run coefficient of the cursor's - * slope. + * The run coefficient of the cursor's slope. * * caret_Offset :: * The cursor's offset for slanted fonts. @@ -196,21 +181,20 @@ FT_BEGIN_HEADER * Always~0. * * number_Of_HMetrics :: - * Number of HMetrics entries in the `hmtx' - * table -- this value can be smaller than - * the total number of glyphs in the font. + * Number of HMetrics entries in the 'hmtx' table -- this value can be + * smaller than the total number of glyphs in the font. * * long_metrics :: - * A pointer into the `hmtx' table. + * A pointer into the 'hmtx' table. * * short_metrics :: - * A pointer into the `hmtx' table. + * A pointer into the 'hmtx' table. * * @note: - * For an OpenType variation font, the values of the following fields - * can change after a call to @FT_Set_Var_Design_Coordinates (and - * friends) if the font contains an `MVAR' table: `caret_Slope_Rise', - * `caret_Slope_Run', and `caret_Offset'. + * For an OpenType variation font, the values of the following fields can + * change after a call to @FT_Set_Var_Design_Coordinates (and friends) if + * the font contains an 'MVAR' table: `caret_Slope_Rise`, + * `caret_Slope_Run`, and `caret_Offset`. */ typedef struct TT_HoriHeader_ { @@ -249,78 +233,61 @@ FT_BEGIN_HEADER * TT_VertHeader * * @description: - * A structure used to model a TrueType vertical header, the `vhea' - * table, as well as the corresponding vertical metrics table, - * `vmtx'. + * A structure used to model a TrueType vertical header, the 'vhea' + * table, as well as the corresponding vertical metrics table, 'vmtx'. * * @fields: * Version :: * The table version. * * Ascender :: - * The font's ascender, i.e., the distance - * from the baseline to the top-most of - * all glyph points found in the font. + * The font's ascender, i.e., the distance from the baseline to the + * top-most of all glyph points found in the font. * - * This value is invalid in many fonts, as - * it is usually set by the font designer, - * and often reflects only a portion of - * the glyphs found in the font (maybe - * ASCII). + * This value is invalid in many fonts, as it is usually set by the + * font designer, and often reflects only a portion of the glyphs found + * in the font (maybe ASCII). * - * You should use the `sTypoAscender' - * field of the `OS/2' table instead if - * you want the correct one. + * You should use the `sTypoAscender` field of the 'OS/2' table instead + * if you want the correct one. * * Descender :: - * The font's descender, i.e., the - * distance from the baseline to the - * bottom-most of all glyph points found - * in the font. It is negative. + * The font's descender, i.e., the distance from the baseline to the + * bottom-most of all glyph points found in the font. It is negative. * - * This value is invalid in many fonts, as - * it is usually set by the font designer, - * and often reflects only a portion of - * the glyphs found in the font (maybe - * ASCII). + * This value is invalid in many fonts, as it is usually set by the + * font designer, and often reflects only a portion of the glyphs found + * in the font (maybe ASCII). * - * You should use the `sTypoDescender' - * field of the `OS/2' table instead if - * you want the correct one. + * You should use the `sTypoDescender` field of the 'OS/2' table + * instead if you want the correct one. * * Line_Gap :: - * The font's line gap, i.e., the distance - * to add to the ascender and descender to - * get the BTB, i.e., the - * baseline-to-baseline distance for the - * font. + * The font's line gap, i.e., the distance to add to the ascender and + * descender to get the BTB, i.e., the baseline-to-baseline distance + * for the font. * * advance_Height_Max :: - * This field is the maximum of all - * advance heights found in the font. It - * can be used to compute the maximum - * height of an arbitrary string of text. + * This field is the maximum of all advance heights found in the font. + * It can be used to compute the maximum height of an arbitrary string + * of text. * * min_Top_Side_Bearing :: - * The minimum top side bearing of all - * glyphs within the font. + * The minimum top side bearing of all glyphs within the font. * * min_Bottom_Side_Bearing :: - * The minimum bottom side bearing of all - * glyphs within the font. + * The minimum bottom side bearing of all glyphs within the font. * * yMax_Extent :: - * The maximum vertical extent (i.e., the - * `height' of a glyph's bounding box) for - * all glyphs in the font. + * The maximum vertical extent (i.e., the 'height' of a glyph's + * bounding box) for all glyphs in the font. * * caret_Slope_Rise :: - * The rise coefficient of the cursor's - * slope of the cursor (slope=rise/run). + * The rise coefficient of the cursor's slope of the cursor + * (slope=rise/run). * * caret_Slope_Run :: - * The run coefficient of the cursor's - * slope. + * The run coefficient of the cursor's slope. * * caret_Offset :: * The cursor's offset for slanted fonts. @@ -332,23 +299,20 @@ FT_BEGIN_HEADER * Always~0. * * number_Of_VMetrics :: - * Number of VMetrics entries in the - * `vmtx' table -- this value can be - * smaller than the total number of glyphs - * in the font. + * Number of VMetrics entries in the 'vmtx' table -- this value can be + * smaller than the total number of glyphs in the font. * * long_metrics :: - * A pointer into the `vmtx' table. + * A pointer into the 'vmtx' table. * * short_metrics :: - * A pointer into the `vmtx' table. + * A pointer into the 'vmtx' table. * * @note: - * For an OpenType variation font, the values of the following fields - * can change after a call to @FT_Set_Var_Design_Coordinates (and - * friends) if the font contains an `MVAR' table: `Ascender', - * `Descender', `Line_Gap', `caret_Slope_Rise', `caret_Slope_Run', - * and `caret_Offset'. + * For an OpenType variation font, the values of the following fields can + * change after a call to @FT_Set_Var_Design_Coordinates (and friends) if + * the font contains an 'MVAR' table: 'Ascender', 'Descender', + * `Line_Gap`, `caret_Slope_Rise`, `caret_Slope_Run`, and `caret_Offset`. */ typedef struct TT_VertHeader_ { @@ -387,26 +351,24 @@ FT_BEGIN_HEADER * TT_OS2 * * @description: - * A structure to model a TrueType `OS/2' table. All fields comply - * to the OpenType specification. + * A structure to model a TrueType 'OS/2' table. All fields comply to + * the OpenType specification. * - * Note that we now support old Mac fonts that do not include an - * `OS/2' table. In this case, the `version' field is always set to - * 0xFFFF. + * Note that we now support old Mac fonts that do not include an 'OS/2' + * table. In this case, the 'version' field is always set to 0xFFFF. * * @note: - * For an OpenType variation font, the values of the following fields - * can change after a call to @FT_Set_Var_Design_Coordinates (and - * friends) if the font contains an `MVAR' table: `sCapHeight', - * `sTypoAscender', `sTypoDescender', `sTypoLineGap', `sxHeight', - * `usWinAscent', `usWinDescent', `yStrikeoutPosition', - * `yStrikeoutSize', `ySubscriptXOffset', `ySubScriptXSize', - * `ySubscriptYOffset', `ySubscriptYSize', `ySuperscriptXOffset', - * `ySuperscriptXSize', `ySuperscriptYOffset', and - * `ySuperscriptYSize'. - * - * Possible values for bits in the `ulUnicodeRangeX' fields are given - * by the @TT_UCR_XXX macros. + * For an OpenType variation font, the values of the following fields can + * change after a call to @FT_Set_Var_Design_Coordinates (and friends) if + * the font contains an 'MVAR' table: `sCapHeight`, `sTypoAscender`, + * `sTypoDescender`, `sTypoLineGap`, `sxHeight`, `usWinAscent`, + * `usWinDescent`, `yStrikeoutPosition`, `yStrikeoutSize`, + * `ySubscriptXOffset`, `ySubScriptXSize`, `ySubscriptYOffset`, + * `ySubscriptYSize`, `ySuperscriptXOffset`, `ySuperscriptXSize`, + * `ySuperscriptYOffset`, and `ySuperscriptYSize`. + * + * Possible values for bits in the `ulUnicodeRangeX` fields are given by + * the @TT_UCR_XXX macros. */ typedef struct TT_OS2_ @@ -473,16 +435,16 @@ FT_BEGIN_HEADER * TT_Postscript * * @description: - * A structure to model a TrueType `post' table. All fields comply - * to the OpenType specification. This structure does not reference - * a font's PostScript glyph names; use @FT_Get_Glyph_Name to - * retrieve them. + * A structure to model a TrueType 'post' table. All fields comply to + * the OpenType specification. This structure does not reference a + * font's PostScript glyph names; use @FT_Get_Glyph_Name to retrieve + * them. * * @note: - * For an OpenType variation font, the values of the following fields - * can change after a call to @FT_Set_Var_Design_Coordinates (and - * friends) if the font contains an `MVAR' table: `underlinePosition' - * and `underlineThickness'. + * For an OpenType variation font, the values of the following fields can + * change after a call to @FT_Set_Var_Design_Coordinates (and friends) if + * the font contains an 'MVAR' table: `underlinePosition` and + * `underlineThickness`. */ typedef struct TT_Postscript_ { @@ -508,8 +470,8 @@ FT_BEGIN_HEADER * TT_PCLT * * @description: - * A structure to model a TrueType `PCLT' table. All fields comply - * to the OpenType specification. + * A structure to model a TrueType 'PCLT' table. All fields comply to + * the OpenType specification. */ typedef struct TT_PCLT_ { @@ -538,75 +500,65 @@ FT_BEGIN_HEADER * TT_MaxProfile * * @description: - * The maximum profile (`maxp') table contains many max values, which - * can be used to pre-allocate arrays for speeding up glyph loading - * and hinting. + * The maximum profile ('maxp') table contains many max values, which can + * be used to pre-allocate arrays for speeding up glyph loading and + * hinting. * * @fields: * version :: * The version number. * * numGlyphs :: - * The number of glyphs in this TrueType - * font. + * The number of glyphs in this TrueType font. * * maxPoints :: - * The maximum number of points in a - * non-composite TrueType glyph. See also - * `maxCompositePoints'. + * The maximum number of points in a non-composite TrueType glyph. See + * also `maxCompositePoints`. * * maxContours :: - * The maximum number of contours in a - * non-composite TrueType glyph. See also - * `maxCompositeContours'. + * The maximum number of contours in a non-composite TrueType glyph. + * See also `maxCompositeContours`. * * maxCompositePoints :: - * The maximum number of points in a - * composite TrueType glyph. See also - * `maxPoints'. + * The maximum number of points in a composite TrueType glyph. See + * also `maxPoints`. * * maxCompositeContours :: - * The maximum number of contours in a - * composite TrueType glyph. See also - * `maxContours'. + * The maximum number of contours in a composite TrueType glyph. See + * also `maxContours`. * * maxZones :: - * The maximum number of zones used for - * glyph hinting. + * The maximum number of zones used for glyph hinting. * * maxTwilightPoints :: - * The maximum number of points in the - * twilight zone used for glyph hinting. + * The maximum number of points in the twilight zone used for glyph + * hinting. * * maxStorage :: - * The maximum number of elements in the - * storage area used for glyph hinting. + * The maximum number of elements in the storage area used for glyph + * hinting. * * maxFunctionDefs :: - * The maximum number of function - * definitions in the TrueType bytecode for - * this font. + * The maximum number of function definitions in the TrueType bytecode + * for this font. * * maxInstructionDefs :: - * The maximum number of instruction - * definitions in the TrueType bytecode for - * this font. + * The maximum number of instruction definitions in the TrueType + * bytecode for this font. * * maxStackElements :: - * The maximum number of stack elements used - * during bytecode interpretation. + * The maximum number of stack elements used during bytecode + * interpretation. * * maxSizeOfInstructions :: - * The maximum number of TrueType opcodes - * used for glyph hinting. + * The maximum number of TrueType opcodes used for glyph hinting. * * maxComponentElements :: - * The maximum number of simple (i.e., - * non-composite) glyphs in a composite glyph. + * The maximum number of simple (i.e., non-composite) glyphs in a + * composite glyph. * * maxComponentDepth :: - * The maximum nesting depth of composite - * glyphs. + * The maximum nesting depth of composite glyphs. * * @note: * This structure is only used during font loading. @@ -638,8 +590,8 @@ FT_BEGIN_HEADER * FT_Sfnt_Tag * * @description: - * An enumeration to specify indices of SFNT tables loaded and parsed - * by FreeType during initialization of an SFNT font. Used in the + * An enumeration to specify indices of SFNT tables loaded and parsed by + * FreeType during initialization of an SFNT font. Used in the * @FT_Get_Sfnt_Table API function. * * @values: @@ -705,30 +657,29 @@ FT_BEGIN_HEADER * The index of the SFNT table. * * @return: - * A type-less pointer to the table. This will be NULL in case of - * error, or if the corresponding table was not found *OR* loaded - * from the file. + * A type-less pointer to the table. This will be NULL in case of error, + * or if the corresponding table was not found **OR** loaded from the + * file. * - * Use a typecast according to `tag' to access the structure - * elements. + * Use a typecast according to 'tag' to access the structure elements. * * @note: * The table is owned by the face object and disappears with it. * - * This function is only useful to access SFNT tables that are loaded - * by the sfnt, truetype, and opentype drivers. See @FT_Sfnt_Tag for - * a list. + * This function is only useful to access SFNT tables that are loaded by + * the sfnt, truetype, and opentype drivers. See @FT_Sfnt_Tag for a + * list. * * @example: - * Here an example how to access the `vhea' table. + * Here an example how to access the 'vhea' table. * - * { + * ``` * TT_VertHeader* vert_header; * * * vert_header = * (TT_VertHeader*)FT_Get_Sfnt_Table( face, FT_SFNT_VHEA ); - * } + * ``` */ FT_EXPORT( void* ) FT_Get_Sfnt_Table( FT_Face face, @@ -748,8 +699,8 @@ FT_BEGIN_HEADER * A handle to the source face. * * tag :: - * The four-byte tag of the table to load. Use value~0 if you want - * to access the whole font file. Otherwise, you can use one of the + * The four-byte tag of the table to load. Use value~0 if you want to + * access the whole font file. Otherwise, you can use one of the * definitions found in the @FT_TRUETYPE_TAGS_H file, or forge a new * one with @FT_MAKE_TAG. * @@ -763,10 +714,10 @@ FT_BEGIN_HEADER * * @inout: * length :: - * If the `length' parameter is NULL, try to load the whole table. + * If the 'length' parameter is NULL, try to load the whole table. * Return an error code if it fails. * - * Else, if `*length' is~0, exit immediately while returning the + * Else, if '*length' is~0, exit immediately while returning the * table's (or file) full size in it. * * Else the number of bytes to read from the table or file, from the @@ -777,9 +728,9 @@ FT_BEGIN_HEADER * * @note: * If you need to determine the table's length you should first call this - * function with `*length' set to~0, as in the following example: + * function with '*length' set to~0, as in the following example: * - * { + * ``` * FT_ULong length = 0; * * @@ -791,7 +742,7 @@ FT_BEGIN_HEADER * * error = FT_Load_Sfnt_Table( face, tag, 0, buffer, &length ); * if ( error ) { ... could not load table ... } - * } + * ``` * * Note that structures like @TT_Header or @TT_OS2 can't be used with * this function; they are limited to @FT_Get_Sfnt_Table. Reason is that @@ -825,14 +776,14 @@ FT_BEGIN_HEADER * * @inout: * tag :: - * The name tag of the SFNT table. If the value is NULL, `table_index' - * is ignored, and `length' returns the number of SFNT tables in the + * The name tag of the SFNT table. If the value is NULL, `table_index` + * is ignored, and 'length' returns the number of SFNT tables in the * font. * * @output: * length :: - * The length of the SFNT table (or the number of SFNT tables, depending - * on `tag'). + * The length of the SFNT table (or the number of SFNT tables, + * depending on 'tag'). * * @return: * FreeType error code. 0~means success. @@ -863,8 +814,8 @@ FT_BEGIN_HEADER * The target charmap. * * @return: - * The language ID of `charmap'. If `charmap' doesn't belong to an - * SFNT face, just return~0 as the default value. + * The language ID of 'charmap'. If 'charmap' doesn't belong to an SFNT + * face, just return~0 as the default value. * * For a format~14 cmap (to access Unicode IVS), the return value is * 0xFFFFFFFF. @@ -879,15 +830,15 @@ FT_BEGIN_HEADER * FT_Get_CMap_Format * * @description: - * Return the format of an SFNT `cmap' table. + * Return the format of an SFNT 'cmap' table. * * @input: * charmap :: * The target charmap. * * @return: - * The format of `charmap'. If `charmap' doesn't belong to an SFNT - * face, return -1. + * The format of 'charmap'. If 'charmap' doesn't belong to an SFNT face, + * return -1. */ FT_EXPORT( FT_Long ) FT_Get_CMap_Format( FT_CharMap charmap ); diff --git a/include/ft2build.h b/include/ft2build.h index 97dbd3c6a..b30282bc7 100644 --- a/include/ft2build.h +++ b/include/ft2build.h @@ -18,17 +18,17 @@ /************************************************************************** * - * This is the `entry point' for FreeType header file inclusions. It is + * This is the 'entry point' for FreeType header file inclusions. It is * the only header file which should be included directly; all other * FreeType header files should be accessed with macro names (after - * including `ft2build.h'). + * including `ft2build.h`). * * A typical example is * - * { + * ``` * #include <ft2build.h> * #include FT_FREETYPE_H - * } + * ``` * */ |