diff options
| author | Werner Lemberg <wl@gnu.org> | 2018-06-03 22:00:42 +0200 |
|---|---|---|
| committer | Werner Lemberg <wl@gnu.org> | 2018-06-03 22:00:42 +0200 |
| commit | f999375a9a834666f82928f9ad6293d9b25213a5 (patch) | |
| tree | 2416528a574600ee96ea0ce9709143f5fc9d1d64 /include | |
| parent | dc170dea33545dbbbf18bb59b316117e73275889 (diff) | |
| download | freetype2-f999375a9a834666f82928f9ad6293d9b25213a5.tar.gz | |
[GSoC] include/*.*, devel/*.*: Convert block comments to `light' style.
This second and final monster commit was created by applying Nikhil's
scripts `docconverter.py' and `markify.py' to all C header and source files,
followed up by minor manual clean-up.
No change in functionality, of course.
I used commit f7419907bc6044b9b7057f9789866426c804ba82 from
https://github.com/nikramakrishnan/freetype-docs.git.
Diffstat (limited to 'include')
92 files changed, 15169 insertions, 14117 deletions
diff --git a/include/freetype/config/ftconfig.h b/include/freetype/config/ftconfig.h index 52c5e335a..c76816e19 100644 --- a/include/freetype/config/ftconfig.h +++ b/include/freetype/config/ftconfig.h @@ -1,39 +1,39 @@ -/***************************************************************************/ -/* */ -/* ftconfig.h */ -/* */ -/* ANSI-specific configuration file (specification only). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ - - - /*************************************************************************/ - /* */ - /* 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. */ - /* */ - /* 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/'. */ - /* */ - /*************************************************************************/ +/**************************************************************************** + * + * ftconfig.h + * + * ANSI-specific configuration file (specification only). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ + + + /************************************************************************** + * + * 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. + * + * 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/'. + * + */ #ifndef FTCONFIG_H_ #define FTCONFIG_H_ @@ -46,16 +46,16 @@ 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. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * 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. + * + */ /* There are systems (like the Texas Instruments 'C54x) where a `char' */ @@ -102,24 +102,24 @@ FT_BEGIN_HEADER #endif - /*************************************************************************/ - /* */ - /* AUTOMATIC CONFIGURATION MACROS */ - /* */ - /* These macros are computed from the ones defined above. Don't touch */ - /* their definition, unless you know precisely what you are doing. No */ - /* porter should need to mess with them. */ - /* */ - /*************************************************************************/ - - - /*************************************************************************/ - /* */ - /* Mac support */ - /* */ - /* This is the only necessary change, so it is defined here instead */ - /* providing a new configuration file. */ - /* */ + /************************************************************************** + * + * AUTOMATIC CONFIGURATION MACROS + * + * These macros are computed from the ones defined above. Don't touch + * their definition, unless you know precisely what you are doing. No + * porter should need to mess with them. + * + */ + + + /************************************************************************** + * + * Mac support + * + * This is the only necessary change, so it is defined here instead + * providing a new configuration file. + */ #if defined( __APPLE__ ) || ( defined( __MWERKS__ ) && defined( macintosh ) ) /* no Carbon frameworks for 64bit 10.4.x */ /* AvailabilityMacros.h is available since Mac OS X 10.2, */ @@ -151,33 +151,33 @@ FT_BEGIN_HEADER #endif - /*************************************************************************/ - /* */ - /* <Section> */ - /* basic_types */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * basic_types + * + */ - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_Int16 */ - /* */ - /* <Description> */ - /* A typedef for a 16bit signed integer type. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_Int16 + * + * @Description: + * A typedef for a 16bit signed integer type. + */ typedef signed short FT_Int16; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_UInt16 */ - /* */ - /* <Description> */ - /* A typedef for a 16bit unsigned integer type. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_UInt16 + * + * @Description: + * A typedef for a 16bit unsigned integer type. + */ typedef unsigned short FT_UInt16; /* */ @@ -186,50 +186,50 @@ FT_BEGIN_HEADER /* this #if 0 ... #endif clause is for documentation purposes */ #if 0 - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_Int32 */ - /* */ - /* <Description> */ - /* A typedef for a 32bit signed integer type. The size depends on */ - /* the configuration. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_Int32 + * + * @Description: + * A typedef for a 32bit signed integer type. The size depends on + * the configuration. + */ typedef signed XXX FT_Int32; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_UInt32 */ - /* */ - /* A typedef for a 32bit unsigned integer type. The size depends on */ - /* the configuration. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_UInt32 + * + * A typedef for a 32bit unsigned integer type. The size depends on + * the configuration. + */ typedef unsigned XXX FT_UInt32; - /*************************************************************************/ - /* */ - /* <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; */ - /* otherwise, it gets emulated with a structure (if necessary). */ - /* */ + /************************************************************************** + * + * @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; + * otherwise, it gets emulated with a structure (if necessary). + */ typedef signed XXX FT_Int64; - /*************************************************************************/ - /* */ - /* <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; */ - /* otherwise, it gets emulated with a structure (if necessary). */ - /* */ + /************************************************************************** + * + * @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; + * otherwise, it gets emulated with a structure (if necessary). + */ typedef unsigned XXX FT_UInt64; /* */ @@ -274,13 +274,13 @@ FT_BEGIN_HEADER #define FT_INT64 long #define FT_UINT64 unsigned long - /*************************************************************************/ - /* */ - /* 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 ) #if defined( __STDC_VERSION__ ) && __STDC_VERSION__ >= 199901L @@ -342,11 +342,11 @@ FT_BEGIN_HEADER #endif - /*************************************************************************/ - /* */ - /* miscellaneous */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * miscellaneous + * + */ #define FT_BEGIN_STMNT do { diff --git a/include/freetype/config/ftheader.h b/include/freetype/config/ftheader.h index 13e5de7d6..6a736850c 100644 --- a/include/freetype/config/ftheader.h +++ b/include/freetype/config/ftheader.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftheader.h */ -/* */ -/* Build macros of the FreeType 2 library. */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftheader.h + * + * Build macros of the FreeType 2 library. + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTHEADER_H_ #define FTHEADER_H_ @@ -55,43 +55,43 @@ #endif - /*************************************************************************/ - /* */ - /* Aliases for the FreeType 2 public and configuration files. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * Aliases for the FreeType 2 public and configuration files. + * + */ - /*************************************************************************/ - /* */ - /* <Section> */ - /* header_file_macros */ - /* */ - /* <Title> */ - /* Header File Macros */ - /* */ - /* <Abstract> */ - /* 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: */ - /* */ - /* { */ - /* #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'). */ - /* */ - /* The second reason is that it allows for more flexibility in the */ - /* way FreeType~2 is installed on a given system. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * header_file_macros + * + * @Title: + * Header File Macros + * + * @Abstract: + * 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: + * + * { + * #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'). + * + * The second reason is that it allows for more flexibility in the + * way FreeType~2 is installed on a given system. + * + */ /* configuration files */ diff --git a/include/freetype/config/ftmodule.h b/include/freetype/config/ftmodule.h index 76d271a74..820c11c3a 100644 --- a/include/freetype/config/ftmodule.h +++ b/include/freetype/config/ftmodule.h @@ -1,12 +1,12 @@ /* - * This file registers the FreeType modules compiled into the library. + * This file registers the FreeType modules compiled into the library. * - * If you use GNU make, this file IS NOT USED! Instead, it is created in - * the objects directory (normally `<topdir>/objs/') based on information - * from `<topdir>/modules.cfg'. + * If you use GNU make, this file IS NOT USED! Instead, it is created in + * the objects directory (normally `<topdir>/objs/') based on information + * from `<topdir>/modules.cfg'. * - * Please read `docs/INSTALL.ANY' and `docs/CUSTOMIZE' how to compile - * FreeType without GNU make. + * Please read `docs/INSTALL.ANY' and `docs/CUSTOMIZE' how to compile + * FreeType without GNU make. * */ diff --git a/include/freetype/config/ftoption.h b/include/freetype/config/ftoption.h index 3b6603b39..c030a88cd 100644 --- a/include/freetype/config/ftoption.h +++ b/include/freetype/config/ftoption.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftoption.h */ -/* */ -/* User-selectable configuration macros (specification only). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftoption.h + * + * User-selectable configuration macros (specification only). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTOPTION_H_ @@ -25,45 +25,45 @@ 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: */ - /* */ - /* - 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. */ - /* */ - /* - 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. */ - /* */ - /* 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, */ - /* */ - /* #define FT_CONFIG_OPTIONS_H <myftoptions.h> */ - /* #include <freetype/config/ftheader.h> */ - /* */ - /* will use `$BUILD/myftoptions.h' instead of this file for macro */ - /* definitions. */ - /* */ - /* Note also that you can similarly pre-define the macro */ - /* FT_CONFIG_MODULES_H used to locate the file listing of the modules */ - /* that are statically linked to the library at compile time. By */ - /* default, this file is <freetype/config/ftmodule.h>. */ - /* */ - /* We highly recommend using the third method whenever possible. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * 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: + * + * - 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. + * + * - 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. + * + * 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, + * + * #define FT_CONFIG_OPTIONS_H <myftoptions.h> + * #include <freetype/config/ftheader.h> + * + * will use `$BUILD/myftoptions.h' instead of this file for macro + * definitions. + * + * Note also that you can similarly pre-define the macro + * FT_CONFIG_MODULES_H used to locate the file listing of the modules + * that are statically linked to the library at compile time. By + * default, this file is <freetype/config/ftmodule.h>. + * + * We highly recommend using the third method whenever possible. + * + */ /*************************************************************************/ @@ -108,381 +108,381 @@ FT_BEGIN_HEADER #define FT_CONFIG_OPTION_ENVIRONMENT_PROPERTIES - /*************************************************************************/ - /* */ - /* 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. */ - /* */ - /* 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 */ + /************************************************************************** + * + * 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. + * + * 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. + * + */ - /*************************************************************************/ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * 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. + * + * 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. + */ #undef FT_CONFIG_OPTION_FORCE_INT64 - /*************************************************************************/ - /* */ - /* 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. */ -/* #define FT_CONFIG_OPTION_NO_ASSEMBLER */ + /************************************************************************** + * + * 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. + */ - /*************************************************************************/ - /* */ - /* 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'. */ - /* */ + /************************************************************************** + * + * 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'. + */ #define FT_CONFIG_OPTION_INLINE_MULFIX - /*************************************************************************/ - /* */ - /* 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 */ - /* 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). */ - /* */ - /* Define this macro if you want to enable this `feature'. */ - /* */ + /************************************************************************** + * + * 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 + * 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). + * + * Define this macro if you want to enable this `feature'. + */ #define FT_CONFIG_OPTION_USE_LZW - /*************************************************************************/ - /* */ - /* 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). */ - /* */ - /* Define this macro if you want to enable this `feature'. See also */ - /* the macro FT_CONFIG_OPTION_SYSTEM_ZLIB below. */ - /* */ + /************************************************************************** + * + * 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). + * + * 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 - /*************************************************************************/ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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 */ + /************************************************************************** + * + * 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. + * + * 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. + * + * 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. + * + */ - /*************************************************************************/ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ -/* #define FT_CONFIG_OPTION_USE_BZIP2 */ + /************************************************************************** + * + * 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. + * + * 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. + * + */ - /*************************************************************************/ - /* */ - /* 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. */ - /* */ -/* #define FT_CONFIG_OPTION_DISABLE_STREAM_SUPPORT */ + /************************************************************************** + * + * 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. + * + */ - /*************************************************************************/ - /* */ - /* PNG bitmap support. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ -/* #define FT_CONFIG_OPTION_USE_PNG */ + /************************************************************************** + * + * PNG bitmap support. + * + * 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. + * + * 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. + * + */ - /*************************************************************************/ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ -/* #define FT_CONFIG_OPTION_USE_HARFBUZZ */ + /************************************************************************** + * + * 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. + * + * 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. + * + */ - /*************************************************************************/ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* - 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. */ - /* */ + /************************************************************************** + * + * 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. + * + * 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. + * + * - 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. + */ #define FT_CONFIG_OPTION_POSTSCRIPT_NAMES - /*************************************************************************/ - /* */ - /* 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). */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * 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). + * + * 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 - /*************************************************************************/ - /* */ - /* 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. */ - /* */ - /* Note that the `FOND' resource isn't checked. */ - /* */ + /************************************************************************** + * + * 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. + * + * Note that the `FOND' resource isn't checked. + */ #define FT_CONFIG_OPTION_MAC_FONTS - /*************************************************************************/ - /* */ - /* Guessing methods to access embedded resource forks */ - /* */ - /* Enable extra Mac fonts support on non-Mac platforms (e.g. */ - /* GNU/Linux). */ - /* */ - /* 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. */ - /* */ - /* Note that normal, direct access of resource forks is controlled via */ - /* the FT_CONFIG_OPTION_MAC_FONTS option. */ - /* */ + /************************************************************************** + * + * Guessing methods to access embedded resource forks + * + * Enable extra Mac fonts support on non-Mac platforms (e.g. + * GNU/Linux). + * + * 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. + * + * Note that normal, direct access of resource forks is controlled via + * the FT_CONFIG_OPTION_MAC_FONTS option. + */ #ifdef FT_CONFIG_OPTION_MAC_FONTS #define FT_CONFIG_OPTION_GUESSING_EMBEDDED_RFORK #endif - /*************************************************************************/ - /* */ - /* 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 - /*************************************************************************/ - /* */ - /* FT_MAX_MODULES */ - /* */ - /* The maximum number of modules that can be registered in a single */ - /* FreeType library object. 32 is the default. */ - /* */ + /************************************************************************** + * + * FT_MAX_MODULES + * + * The maximum number of modules that can be registered in a single + * FreeType library object. 32 is the default. + */ #define FT_MAX_MODULES 32 - /*************************************************************************/ - /* */ - /* 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. */ - /* */ - /* 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! */ - /* */ - /* Do not #undef these macros here since the build system might define */ - /* them for certain configurations only. */ - /* */ -/* #define FT_DEBUG_LEVEL_ERROR */ -/* #define FT_DEBUG_LEVEL_TRACE */ + /************************************************************************** + * + * 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. + * + * 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! + * + * Do not #undef these macros here since the build system might define + * them for certain configurations only. + * + * #define FT_DEBUG_LEVEL_ERROR + */ - /*************************************************************************/ - /* */ - /* Autofitter debugging */ - /* */ - /* 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): */ - /* */ - /* _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'): */ - /* */ - /* 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 */ - /* variables and macros should be used. */ - /* */ - /* Do not #undef these macros here since the build system might define */ - /* them for certain configurations only. */ - /* */ -/* #define FT_DEBUG_AUTOFIT */ + /************************************************************************** + * + * Autofitter debugging + * + * 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): + * + * _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'): + * + * 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 + * variables and macros should be used. + * + * Do not #undef these macros here since the build system might define + * them for certain configurations only. + * + */ - /*************************************************************************/ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ -/* #define FT_DEBUG_MEMORY */ + /************************************************************************** + * + * 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. + * + * 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. + * + */ - /*************************************************************************/ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * 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. + * + * 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. + */ #undef FT_CONFIG_OPTION_USE_MODULE_ERRORS @@ -495,59 +495,59 @@ 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 - /*************************************************************************/ - /* */ - /* Define TT_CONFIG_OPTION_COLOR_LAYERS if you want to support coloured */ - /* outlines (from the COLR/CPAL tables) in all formats using the SFNT */ - /* module (namely TrueType & OpenType). */ - /* */ + /************************************************************************** + * + * Define TT_CONFIG_OPTION_COLOR_LAYERS if you want to support coloured + * outlines (from the COLR/CPAL tables) in all formats using the SFNT + * module (namely TrueType & OpenType). + */ #define TT_CONFIG_OPTION_COLOR_LAYERS - /*************************************************************************/ - /* */ - /* 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. */ - /* */ - /* (By default, the module uses `PSNames' to extract glyph names.) */ - /* */ + /************************************************************************** + * + * 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. + * + * (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. */ - /* */ - /* Accessing SFNT names is done through the functions declared in */ - /* `ftsnames.h'. */ - /* */ + /************************************************************************** + * + * 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'. + */ #define TT_CONFIG_OPTION_SFNT_NAMES - /*************************************************************************/ - /* */ - /* TrueType CMap support */ - /* */ - /* Here you can fine-tune which TrueType CMap table format shall be */ - /* supported. */ + /************************************************************************** + * + * TrueType CMap support + * + * Here you can fine-tune which TrueType CMap table format shall be + */ #define TT_CONFIG_CMAP_FORMAT_0 #define TT_CONFIG_CMAP_FORMAT_2 #define TT_CONFIG_CMAP_FORMAT_4 @@ -567,131 +567,131 @@ FT_BEGIN_HEADER /*************************************************************************/ /*************************************************************************/ - /*************************************************************************/ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * 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. + */ #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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* The corresponding interpreter version is v40. */ - /* */ - /* Value 3: */ - /* 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'). */ - /* */ - /* This option requires TT_CONFIG_OPTION_BYTECODE_INTERPRETER to be */ - /* defined. */ - /* */ - /* [1] https://www.microsoft.com/typography/cleartype/truetypecleartype.aspx */ - /* */ -/* #define TT_CONFIG_OPTION_SUBPIXEL_HINTING 1 */ + /************************************************************************** + * + * 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. + * + * 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. + * + * 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. + * + * The corresponding interpreter version is v40. + * + * Value 3: + * 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'). + * + * This option requires TT_CONFIG_OPTION_BYTECODE_INTERPRETER to be + * defined. + * + * [1] https://www.microsoft.com/typography/cleartype/truetypecleartype.aspx + * + */ #define TT_CONFIG_OPTION_SUBPIXEL_HINTING 2 /* #define TT_CONFIG_OPTION_SUBPIXEL_HINTING ( 1 | 2 ) */ - /*************************************************************************/ - /* */ - /* 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. */ - /* */ - /* https://www.microsoft.com/typography/otspec/glyf.htm */ - /* https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6glyf.html */ - /* */ + /************************************************************************** + * + * 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. + * + * https://www.microsoft.com/typography/otspec/glyf.htm + * https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6glyf.html + */ #undef TT_CONFIG_OPTION_COMPONENT_OFFSET_SCALED - /*************************************************************************/ - /* */ - /* 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). */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * 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. + */ #ifndef TT_CONFIG_OPTION_MAX_RUNNABLE_OPCODES #define TT_CONFIG_OPTION_MAX_RUNNABLE_OPCODES 1000000L #endif @@ -706,60 +706,60 @@ 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 - /*************************************************************************/ - /* */ - /* T1_MAX_SUBRS_CALLS details the maximum number of nested sub-routine */ - /* calls during glyph loading. */ - /* */ + /************************************************************************** + * + * T1_MAX_SUBRS_CALLS details the maximum number of nested sub-routine + * calls during glyph loading. + */ #define T1_MAX_SUBRS_CALLS 16 - /*************************************************************************/ - /* */ - /* T1_MAX_CHARSTRING_OPERANDS is the charstring stack's capacity. A */ - /* minimum of 16 is required. */ - /* */ - /* The Chinese font MingTiEG-Medium (CNS 11643 character set) needs 256. */ - /* */ + /************************************************************************** + * + * T1_MAX_CHARSTRING_OPERANDS is the charstring stack's capacity. A + * minimum of 16 is required. + * + * The Chinese font MingTiEG-Medium (CNS 11643 character set) needs 256. + */ #define T1_MAX_CHARSTRINGS_OPERANDS 256 - /*************************************************************************/ - /* */ - /* 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. */ - /* */ -/* #define T1_CONFIG_OPTION_OLD_ENGINE */ + /************************************************************************** + * + * 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. + * + */ /*************************************************************************/ @@ -771,17 +771,17 @@ 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. */ - /* */ - /* Do *not* undefine these macros! */ - /* */ + /************************************************************************** + * + * 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. + * + * Do *not* undefine these macros! + */ #define CFF_CONFIG_OPTION_DARKENING_PARAMETER_X1 500 #define CFF_CONFIG_OPTION_DARKENING_PARAMETER_Y1 400 @@ -795,14 +795,14 @@ FT_BEGIN_HEADER #define CFF_CONFIG_OPTION_DARKENING_PARAMETER_Y4 0 - /*************************************************************************/ - /* */ - /* 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 */ + /************************************************************************** + * + * 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. + * + */ /*************************************************************************/ @@ -814,22 +814,22 @@ 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. */ - /* */ - /* 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. */ - /* */ -/* #define PCF_CONFIG_OPTION_LONG_FAMILY_NAMES */ + /************************************************************************** + * + * 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'. + * + * If this option is activated, it can be controlled with the + * `no-long-family-names' property of the pcf driver module. + * + */ /*************************************************************************/ @@ -841,55 +841,55 @@ FT_BEGIN_HEADER /*************************************************************************/ - /*************************************************************************/ - /* */ - /* Compile autofit module with CJK (Chinese, Japanese, Korean) script */ - /* support. */ - /* */ + /************************************************************************** + * + * Compile autofit module with CJK (Chinese, Japanese, Korean) script + * support. + */ #define AF_CONFIG_OPTION_CJK - /*************************************************************************/ - /* */ - /* 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. */ - /* */ - /* 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 */ - /* information; by default it is switched off). */ - /* */ + /************************************************************************** + * + * 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 + * information; by default it is switched off). + */ #define AF_CONFIG_OPTION_USE_WARPER - /*************************************************************************/ - /* */ - /* 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. */ - /* */ - /* 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). */ - /* */ -/* #define AF_CONFIG_OPTION_TT_SIZE_METRICS */ + /************************************************************************** + * + * 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. + * + * 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). + * + */ /* */ diff --git a/include/freetype/config/ftstdlib.h b/include/freetype/config/ftstdlib.h index 42f9a06e4..a744d0d05 100644 --- a/include/freetype/config/ftstdlib.h +++ b/include/freetype/config/ftstdlib.h @@ -1,31 +1,31 @@ -/***************************************************************************/ -/* */ -/* ftstdlib.h */ -/* */ -/* ANSI-specific library and header configuration file (specification */ -/* only). */ -/* */ -/* Copyright 2002-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ - - - /*************************************************************************/ - /* */ - /* This file is used to group all #includes to the ANSI C library that */ - /* FreeType normally requires. It also defines macros to rename the */ - /* standard functions within the FreeType source code. */ - /* */ - /* Load a file which defines FTSTDLIB_H_ before this one to override it. */ - /* */ - /*************************************************************************/ +/**************************************************************************** + * + * ftstdlib.h + * + * ANSI-specific library and header configuration file (specification + * only). + * + * Copyright 2002-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ + + + /************************************************************************** + * + * This file is used to group all #includes to the ANSI C library that + * FreeType normally requires. It also defines macros to rename the + * standard functions within the FreeType source code. + * + * Load a file which defines FTSTDLIB_H_ before this one to override it. + * + */ #ifndef FTSTDLIB_H_ @@ -37,23 +37,23 @@ #define ft_ptrdiff_t ptrdiff_t - /**********************************************************************/ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /**********************************************************************/ + /*********************************************************************** + * + * 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. + * + * 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. + * + */ #include <limits.h> @@ -68,11 +68,11 @@ #define FT_ULONG_MAX ULONG_MAX - /**********************************************************************/ - /* */ - /* character and string processing */ - /* */ - /**********************************************************************/ + /*********************************************************************** + * + * character and string processing + * + */ #include <string.h> @@ -92,11 +92,11 @@ #define ft_strstr strstr - /**********************************************************************/ - /* */ - /* file handling */ - /* */ - /**********************************************************************/ + /*********************************************************************** + * + * file handling + * + */ #include <stdio.h> @@ -110,11 +110,11 @@ #define ft_sprintf sprintf - /**********************************************************************/ - /* */ - /* sorting */ - /* */ - /**********************************************************************/ + /*********************************************************************** + * + * sorting + * + */ #include <stdlib.h> @@ -122,11 +122,11 @@ #define ft_qsort qsort - /**********************************************************************/ - /* */ - /* memory allocation */ - /* */ - /**********************************************************************/ + /*********************************************************************** + * + * memory allocation + * + */ #define ft_scalloc calloc @@ -135,22 +135,22 @@ #define ft_srealloc realloc - /**********************************************************************/ - /* */ - /* miscellaneous */ - /* */ - /**********************************************************************/ + /*********************************************************************** + * + * miscellaneous + * + */ #define ft_strtol strtol #define ft_getenv getenv - /**********************************************************************/ - /* */ - /* execution control */ - /* */ - /**********************************************************************/ + /*********************************************************************** + * + * execution control + * + */ #include <setjmp.h> diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h index a6f0d8070..736c251bd 100644 --- a/include/freetype/freetype.h +++ b/include/freetype/freetype.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* freetype.h */ -/* */ -/* FreeType high-level API and common types (specification only). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * freetype.h + * + * FreeType high-level API and common types (specification only). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FREETYPE_H_ @@ -39,56 +39,56 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* header_inclusion */ - /* */ - /* <Title> */ - /* FreeType's header inclusion scheme */ - /* */ - /* <Abstract> */ - /* 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 */ - /* */ - /* { */ - /* #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 preprocessor macro names, */ - /* loaded by `ft2build.h'. The API documentation always gives the */ - /* header macro name needed for a particular function. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * header_inclusion + * + * @Title: + * FreeType's header inclusion scheme + * + * @Abstract: + * 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 + * + * { + * #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 preprocessor macro names, + * loaded by `ft2build.h'. The API documentation always gives the + * header macro name needed for a particular function. + * + */ - /*************************************************************************/ - /* */ - /* <Section> */ - /* user_allocation */ - /* */ - /* <Title> */ - /* User allocation */ - /* */ - /* <Abstract> */ - /* 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. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * user_allocation + * + * @Title: + * User allocation + * + * @Abstract: + * 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. + * + */ @@ -101,219 +101,219 @@ FT_BEGIN_HEADER /*************************************************************************/ - /*************************************************************************/ - /* */ - /* <Section> */ - /* base_interface */ - /* */ - /* <Title> */ - /* Base Interface */ - /* */ - /* <Abstract> */ - /* The FreeType~2 base font interface. */ - /* */ - /* <Description> */ - /* This section describes the most important public high-level API */ - /* functions of FreeType~2. */ - /* */ - /* <Order> */ - /* FT_Library */ - /* FT_Face */ - /* FT_Size */ - /* FT_GlyphSlot */ - /* FT_CharMap */ - /* FT_Encoding */ - /* FT_ENC_TAG */ - /* */ - /* FT_FaceRec */ - /* */ - /* FT_FACE_FLAG_SCALABLE */ - /* FT_FACE_FLAG_FIXED_SIZES */ - /* FT_FACE_FLAG_FIXED_WIDTH */ - /* FT_FACE_FLAG_HORIZONTAL */ - /* FT_FACE_FLAG_VERTICAL */ - /* FT_FACE_FLAG_COLOR */ - /* FT_FACE_FLAG_SFNT */ - /* FT_FACE_FLAG_CID_KEYED */ - /* FT_FACE_FLAG_TRICKY */ - /* FT_FACE_FLAG_KERNING */ - /* FT_FACE_FLAG_MULTIPLE_MASTERS */ - /* FT_FACE_FLAG_VARIATION */ - /* FT_FACE_FLAG_GLYPH_NAMES */ - /* FT_FACE_FLAG_EXTERNAL_STREAM */ - /* FT_FACE_FLAG_HINTER */ - /* */ - /* FT_HAS_HORIZONTAL */ - /* FT_HAS_VERTICAL */ - /* FT_HAS_KERNING */ - /* FT_HAS_FIXED_SIZES */ - /* FT_HAS_GLYPH_NAMES */ - /* FT_HAS_COLOR */ - /* FT_HAS_MULTIPLE_MASTERS */ - /* */ - /* FT_IS_SFNT */ - /* FT_IS_SCALABLE */ - /* FT_IS_FIXED_WIDTH */ - /* FT_IS_CID_KEYED */ - /* FT_IS_TRICKY */ - /* FT_IS_NAMED_INSTANCE */ - /* FT_IS_VARIATION */ - /* */ - /* FT_STYLE_FLAG_BOLD */ - /* FT_STYLE_FLAG_ITALIC */ - /* */ - /* FT_SizeRec */ - /* FT_Size_Metrics */ - /* */ - /* FT_GlyphSlotRec */ - /* FT_Glyph_Metrics */ - /* FT_SubGlyph */ - /* */ - /* FT_Bitmap_Size */ - /* */ - /* FT_Init_FreeType */ - /* FT_Done_FreeType */ - /* */ - /* FT_New_Face */ - /* FT_Done_Face */ - /* FT_Reference_Face */ - /* FT_New_Memory_Face */ - /* FT_Face_Properties */ - /* FT_Open_Face */ - /* FT_Open_Args */ - /* FT_Parameter */ - /* FT_Attach_File */ - /* FT_Attach_Stream */ - /* */ - /* FT_Set_Char_Size */ - /* FT_Set_Pixel_Sizes */ - /* FT_Request_Size */ - /* FT_Select_Size */ - /* FT_Size_Request_Type */ - /* FT_Size_RequestRec */ - /* FT_Size_Request */ - /* FT_Set_Transform */ - /* FT_Load_Glyph */ - /* FT_Get_Char_Index */ - /* FT_Get_First_Char */ - /* FT_Get_Next_Char */ - /* FT_Get_Name_Index */ - /* FT_Load_Char */ - /* */ - /* FT_OPEN_MEMORY */ - /* FT_OPEN_STREAM */ - /* FT_OPEN_PATHNAME */ - /* FT_OPEN_DRIVER */ - /* FT_OPEN_PARAMS */ - /* */ - /* FT_LOAD_DEFAULT */ - /* FT_LOAD_RENDER */ - /* FT_LOAD_MONOCHROME */ - /* FT_LOAD_LINEAR_DESIGN */ - /* FT_LOAD_NO_SCALE */ - /* FT_LOAD_NO_HINTING */ - /* FT_LOAD_NO_BITMAP */ - /* FT_LOAD_NO_AUTOHINT */ - /* FT_LOAD_COLOR */ - /* */ - /* FT_LOAD_VERTICAL_LAYOUT */ - /* FT_LOAD_IGNORE_TRANSFORM */ - /* FT_LOAD_FORCE_AUTOHINT */ - /* FT_LOAD_NO_RECURSE */ - /* FT_LOAD_PEDANTIC */ - /* */ - /* FT_LOAD_TARGET_NORMAL */ - /* FT_LOAD_TARGET_LIGHT */ - /* FT_LOAD_TARGET_MONO */ - /* FT_LOAD_TARGET_LCD */ - /* FT_LOAD_TARGET_LCD_V */ - /* */ - /* FT_LOAD_TARGET_MODE */ - /* */ - /* FT_Render_Glyph */ - /* FT_Render_Mode */ - /* FT_Get_Kerning */ - /* FT_Kerning_Mode */ - /* FT_Get_Track_Kerning */ - /* FT_Get_Glyph_Name */ - /* FT_Get_Postscript_Name */ - /* */ - /* FT_CharMapRec */ - /* FT_Select_Charmap */ - /* FT_Set_Charmap */ - /* FT_Get_Charmap_Index */ - /* */ - /* FT_Get_FSType_Flags */ - /* FT_Get_SubGlyph_Info */ - /* */ - /* FT_Face_Internal */ - /* FT_Size_Internal */ - /* FT_Slot_Internal */ - /* */ - /* FT_FACE_FLAG_XXX */ - /* FT_STYLE_FLAG_XXX */ - /* FT_OPEN_XXX */ - /* FT_LOAD_XXX */ - /* FT_LOAD_TARGET_XXX */ - /* FT_SUBGLYPH_FLAG_XXX */ - /* FT_FSTYPE_XXX */ - /* */ - /* FT_HAS_FAST_GLYPHS */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * base_interface + * + * @Title: + * Base Interface + * + * @Abstract: + * The FreeType~2 base font interface. + * + * @Description: + * This section describes the most important public high-level API + * functions of FreeType~2. + * + * @Order: + * FT_Library + * FT_Face + * FT_Size + * FT_GlyphSlot + * FT_CharMap + * FT_Encoding + * FT_ENC_TAG + * + * FT_FaceRec + * + * FT_FACE_FLAG_SCALABLE + * FT_FACE_FLAG_FIXED_SIZES + * FT_FACE_FLAG_FIXED_WIDTH + * FT_FACE_FLAG_HORIZONTAL + * FT_FACE_FLAG_VERTICAL + * FT_FACE_FLAG_COLOR + * FT_FACE_FLAG_SFNT + * FT_FACE_FLAG_CID_KEYED + * FT_FACE_FLAG_TRICKY + * FT_FACE_FLAG_KERNING + * FT_FACE_FLAG_MULTIPLE_MASTERS + * FT_FACE_FLAG_VARIATION + * FT_FACE_FLAG_GLYPH_NAMES + * FT_FACE_FLAG_EXTERNAL_STREAM + * FT_FACE_FLAG_HINTER + * + * FT_HAS_HORIZONTAL + * FT_HAS_VERTICAL + * FT_HAS_KERNING + * FT_HAS_FIXED_SIZES + * FT_HAS_GLYPH_NAMES + * FT_HAS_COLOR + * FT_HAS_MULTIPLE_MASTERS + * + * FT_IS_SFNT + * FT_IS_SCALABLE + * FT_IS_FIXED_WIDTH + * FT_IS_CID_KEYED + * FT_IS_TRICKY + * FT_IS_NAMED_INSTANCE + * FT_IS_VARIATION + * + * FT_STYLE_FLAG_BOLD + * FT_STYLE_FLAG_ITALIC + * + * FT_SizeRec + * FT_Size_Metrics + * + * FT_GlyphSlotRec + * FT_Glyph_Metrics + * FT_SubGlyph + * + * FT_Bitmap_Size + * + * FT_Init_FreeType + * FT_Done_FreeType + * + * FT_New_Face + * FT_Done_Face + * FT_Reference_Face + * FT_New_Memory_Face + * FT_Face_Properties + * FT_Open_Face + * FT_Open_Args + * FT_Parameter + * FT_Attach_File + * FT_Attach_Stream + * + * FT_Set_Char_Size + * FT_Set_Pixel_Sizes + * FT_Request_Size + * FT_Select_Size + * FT_Size_Request_Type + * FT_Size_RequestRec + * FT_Size_Request + * FT_Set_Transform + * FT_Load_Glyph + * FT_Get_Char_Index + * FT_Get_First_Char + * FT_Get_Next_Char + * FT_Get_Name_Index + * FT_Load_Char + * + * FT_OPEN_MEMORY + * FT_OPEN_STREAM + * FT_OPEN_PATHNAME + * FT_OPEN_DRIVER + * FT_OPEN_PARAMS + * + * FT_LOAD_DEFAULT + * FT_LOAD_RENDER + * FT_LOAD_MONOCHROME + * FT_LOAD_LINEAR_DESIGN + * FT_LOAD_NO_SCALE + * FT_LOAD_NO_HINTING + * FT_LOAD_NO_BITMAP + * FT_LOAD_NO_AUTOHINT + * FT_LOAD_COLOR + * + * FT_LOAD_VERTICAL_LAYOUT + * FT_LOAD_IGNORE_TRANSFORM + * FT_LOAD_FORCE_AUTOHINT + * FT_LOAD_NO_RECURSE + * FT_LOAD_PEDANTIC + * + * FT_LOAD_TARGET_NORMAL + * FT_LOAD_TARGET_LIGHT + * FT_LOAD_TARGET_MONO + * FT_LOAD_TARGET_LCD + * FT_LOAD_TARGET_LCD_V + * + * FT_LOAD_TARGET_MODE + * + * FT_Render_Glyph + * FT_Render_Mode + * FT_Get_Kerning + * FT_Kerning_Mode + * FT_Get_Track_Kerning + * FT_Get_Glyph_Name + * FT_Get_Postscript_Name + * + * FT_CharMapRec + * FT_Select_Charmap + * FT_Set_Charmap + * FT_Get_Charmap_Index + * + * FT_Get_FSType_Flags + * FT_Get_SubGlyph_Info + * + * FT_Face_Internal + * FT_Size_Internal + * FT_Slot_Internal + * + * FT_FACE_FLAG_XXX + * FT_STYLE_FLAG_XXX + * FT_OPEN_XXX + * FT_LOAD_XXX + * FT_LOAD_TARGET_XXX + * FT_SUBGLYPH_FLAG_XXX + * FT_FSTYPE_XXX + * + * FT_HAS_FAST_GLYPHS + * + */ - /*************************************************************************/ - /* */ - /* <Struct> */ - /* 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. */ - /* */ - /* <Fields> */ - /* width :: */ - /* The glyph's width. */ - /* */ - /* height :: */ - /* The glyph's height. */ - /* */ - /* horiBearingX :: */ - /* Left side bearing for horizontal layout. */ - /* */ - /* horiBearingY :: */ - /* Top side bearing for horizontal layout. */ - /* */ - /* horiAdvance :: */ - /* Advance width for horizontal layout. */ - /* */ - /* vertBearingX :: */ - /* Left side bearing for vertical layout. */ - /* */ - /* vertBearingY :: */ - /* 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. */ - /* */ - /* <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 */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Struct: + * 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. + * + * @Fields: + * width :: + * The glyph's width. + * + * height :: + * The glyph's height. + * + * horiBearingX :: + * Left side bearing for horizontal layout. + * + * horiBearingY :: + * Top side bearing for horizontal layout. + * + * horiAdvance :: + * Advance width for horizontal layout. + * + * vertBearingX :: + * Left side bearing for vertical layout. + * + * vertBearingY :: + * 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. + * + * @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 + * 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. + */ typedef struct FT_Glyph_Metrics_ { FT_Pos width; @@ -330,44 +330,49 @@ FT_BEGIN_HEADER } FT_Glyph_Metrics; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* 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. */ - /* */ - /* <Fields> */ - /* height :: 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. */ - /* */ - /* size :: 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. */ - /* */ - /* y_ppem :: 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. */ - /* */ - /* TrueType embedded bitmaps: */ - /* `size', `width', and `height' values are not contained in the */ - /* bitmap strike itself. They are computed from the global font */ - /* parameters. */ - /* */ + /************************************************************************** + * + * @Struct: + * 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. + * + * @Fields: + * height :: + * 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. + * + * size :: + * 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. + * + * y_ppem :: + * 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. + * + * TrueType embedded bitmaps: + * `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_ { FT_Short height; @@ -389,225 +394,225 @@ FT_BEGIN_HEADER /*************************************************************************/ /*************************************************************************/ - /*************************************************************************/ - /* */ - /* <Type> */ - /* 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. */ - /* */ - /* It also embeds a memory manager (see @FT_Memory), as well as a */ - /* scan-line converter object (see @FT_Raster). */ - /* */ - /* 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 */ - /* (since FreeType version 2.5.6), 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. */ - /* */ + /************************************************************************** + * + * @Type: + * 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. + * + * It also embeds a memory manager (see @FT_Memory), as well as a + * scan-line converter object (see @FT_Raster). + * + * 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 + * (since FreeType version 2.5.6), 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. + */ typedef struct FT_LibraryRec_ *FT_Library; - /*************************************************************************/ - /* */ - /* <Section> */ - /* module_management */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * module_management + * + */ - /*************************************************************************/ - /* */ - /* <Type> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Type: + * 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. + */ typedef struct FT_ModuleRec_* FT_Module; - /*************************************************************************/ - /* */ - /* <Type> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Type: + * 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. + */ typedef struct FT_DriverRec_* FT_Driver; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_Renderer */ - /* */ - /* <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. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_Renderer + * + * @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. + */ typedef struct FT_RendererRec_* FT_Renderer; - /*************************************************************************/ - /* */ - /* <Section> */ - /* base_interface */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * base_interface + * + */ - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_Face */ - /* */ - /* <Description> */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* <Also> */ - /* See @FT_FaceRec for the publicly accessible fields of a given face */ - /* object. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_Face + * + * @Description: + * 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. + * + * 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. + * + * @Also: + * See @FT_FaceRec for the publicly accessible fields of a given face + * object. + */ typedef struct FT_FaceRec_* FT_Face; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_Size */ - /* */ - /* <Description> */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* <Also> */ - /* See @FT_SizeRec for the publicly accessible fields of a given size */ - /* object. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_Size + * + * @Description: + * 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. + * + * 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. + * + * @Also: + * See @FT_SizeRec for the publicly accessible fields of a given size + * object. + */ typedef struct FT_SizeRec_* FT_Size; - /*************************************************************************/ - /* */ - /* <Type> */ - /* 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. */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Type: + * 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. + * + * 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. + */ typedef struct FT_GlyphSlotRec_* FT_GlyphSlot; - /*************************************************************************/ - /* */ - /* <Type> */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* <Also> */ - /* See @FT_CharMapRec for the publicly accessible fields of a given */ - /* character map. */ - /* */ + /************************************************************************** + * + * @Type: + * 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. + * + * 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. + * + * 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. + * + * @Also: + * See @FT_CharMapRec for the publicly accessible fields of a given + * character map. + */ typedef struct FT_CharMapRec_* FT_CharMap; - /*************************************************************************/ - /* */ - /* <Macro> */ - /* FT_ENC_TAG */ - /* */ - /* <Description> */ - /* This macro converts four-letter tags into an unsigned long. It is */ - /* 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: */ - /* */ - /* { */ - /* #define FT_ENC_TAG( value, a, b, c, d ) value */ - /* } */ - /* */ - /* to get a simple enumeration without assigning special numbers. */ - /* */ + /************************************************************************** + * + * @Macro: + * FT_ENC_TAG + * + * @Description: + * This macro converts four-letter tags into an unsigned long. It is + * 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: + * + * { + * #define FT_ENC_TAG( value, a, b, c, d ) value + * } + * + * to get a simple enumeration without assigning special numbers. + */ #ifndef FT_ENC_TAG #define FT_ENC_TAG( value, a, b, c, d ) \ @@ -619,150 +624,150 @@ FT_BEGIN_HEADER #endif /* FT_ENC_TAG */ - /*************************************************************************/ - /* */ - /* <Enum> */ - /* FT_Encoding */ - /* */ - /* <Description> */ - /* 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 */ - /* repertories (i.e., charsets), and not text encoding methods (e.g., */ - /* UTF-8, UTF-16, etc.). */ - /* */ - /* Other encodings might be defined in the future. */ - /* */ - /* <Values> */ - /* FT_ENCODING_NONE :: */ - /* The encoding value~0 is reserved. */ - /* */ - /* 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. */ - /* */ - /* 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'. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* FT_ENCODING_BIG5 :: */ - /* 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'. */ - /* */ - /* FT_ENCODING_JOHAB :: */ - /* The Korean standard character set (KS~C 5601-1992), which */ - /* corresponds to MS Windows code page 1361. This character set */ - /* 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. */ - /* */ - /* FT_ENCODING_ADOBE_STANDARD :: */ - /* 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 */ - /* fonts. It is limited to 256 character codes. */ - /* */ - /* FT_ENCODING_ADOBE_CUSTOM :: */ - /* Corresponds to a custom encoding, as found in Type~1, CFF, and */ - /* 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. */ - /* */ - /* FT_ENCODING_OLD_LATIN_2 :: */ - /* This value is deprecated and was neither used nor reported by */ - /* FreeType. Don't use or test for it. */ - /* */ - /* FT_ENCODING_MS_SJIS :: */ - /* Same as FT_ENCODING_SJIS. Deprecated. */ - /* */ - /* FT_ENCODING_MS_GB2312 :: */ - /* Same as FT_ENCODING_PRC. Deprecated. */ - /* */ - /* FT_ENCODING_MS_BIG5 :: */ - /* Same as FT_ENCODING_BIG5. Deprecated. */ - /* */ - /* FT_ENCODING_MS_WANSUNG :: */ - /* Same as FT_ENCODING_WANSUNG. Deprecated. */ - /* */ - /* FT_ENCODING_MS_JOHAB :: */ - /* Same as FT_ENCODING_JOHAB. Deprecated. */ - /* */ - /* <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. */ - /* */ - /* 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 */ - /* 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 */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Enum: + * FT_Encoding + * + * @Description: + * 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 + * repertories (i.e., charsets), and not text encoding methods (e.g., + * UTF-8, UTF-16, etc.). + * + * Other encodings might be defined in the future. + * + * @Values: + * FT_ENCODING_NONE :: + * The encoding value~0 is reserved. + * + * 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. + * + * 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'. + * + * 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. + * + * 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. + * + * FT_ENCODING_BIG5 :: + * 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'. + * + * FT_ENCODING_JOHAB :: + * The Korean standard character set (KS~C 5601-1992), which + * corresponds to MS Windows code page 1361. This character set + * 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. + * + * FT_ENCODING_ADOBE_STANDARD :: + * 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 + * fonts. It is limited to 256 character codes. + * + * FT_ENCODING_ADOBE_CUSTOM :: + * Corresponds to a custom encoding, as found in Type~1, CFF, and + * 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. + * + * FT_ENCODING_OLD_LATIN_2 :: + * This value is deprecated and was neither used nor reported by + * FreeType. Don't use or test for it. + * + * FT_ENCODING_MS_SJIS :: + * Same as FT_ENCODING_SJIS. Deprecated. + * + * FT_ENCODING_MS_GB2312 :: + * Same as FT_ENCODING_PRC. Deprecated. + * + * FT_ENCODING_MS_BIG5 :: + * Same as FT_ENCODING_BIG5. Deprecated. + * + * FT_ENCODING_MS_WANSUNG :: + * Same as FT_ENCODING_WANSUNG. Deprecated. + * + * FT_ENCODING_MS_JOHAB :: + * Same as FT_ENCODING_JOHAB. Deprecated. + * + * @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. + * + * 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 + * 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 + * + * 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. + */ typedef enum FT_Encoding_ { FT_ENC_TAG( FT_ENCODING_NONE, 0, 0, 0, 0 ), @@ -815,29 +820,33 @@ FT_BEGIN_HEADER #define ft_encoding_apple_roman FT_ENCODING_APPLE_ROMAN - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_CharMapRec */ - /* */ - /* <Description> */ - /* The base charmap structure. */ - /* */ - /* <Fields> */ - /* face :: A handle to the parent face object. */ - /* */ - /* encoding :: 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. */ - /* */ - /* encoding_id :: A platform specific encoding number. This also */ - /* comes from the TrueType specification and gets */ - /* emulated similarly. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_CharMapRec + * + * @Description: + * The base charmap structure. + * + * @Fields: + * face :: + * A handle to the parent face object. + * + * encoding :: + * 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. + * + * encoding_id :: + * A platform specific encoding number. This also + * comes from the TrueType specification and gets + * emulated similarly. + */ typedef struct FT_CharMapRec_ { FT_Face face; @@ -857,215 +866,239 @@ FT_BEGIN_HEADER /*************************************************************************/ - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_Face_Internal */ - /* */ - /* <Description> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_Face_Internal + * + * @Description: + * 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. + */ typedef struct FT_Face_InternalRec_* FT_Face_Internal; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_FaceRec */ - /* */ - /* <Description> */ - /* 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. */ - /* */ - /* 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). */ - /* */ - /* face_flags :: 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. */ - /* */ - /* 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. */ - /* */ - /* 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 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). */ - /* */ - /* 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 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* charmaps :: An array of the charmaps of the face. */ - /* */ - /* generic :: 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* underline_thickness :: The thickness, in font units, of the */ - /* underline for this face. Only relevant for */ - /* scalable formats. */ - /* */ - /* glyph :: The face's associated glyph slot(s). */ - /* */ - /* size :: The current active size for this face. */ - /* */ - /* charmap :: The current active charmap for this face. */ - /* */ - /* <Note> */ - /* 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'. */ - /* */ - /* Especially for TrueType fonts see also the documentation for */ - /* @FT_Size_Metrics. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_FaceRec + * + * @Description: + * 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. + * + * 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). + * + * face_flags :: + * 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. + * + * 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. + * + * 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 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). + * + * 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 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. + * + * 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. + * + * 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. + * + * charmaps :: + * An array of the charmaps of the face. + * + * generic :: + * 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. + * + * 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. + * + * 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. + * + * 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. + * 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. + * + * 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. + * + * 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. + * + * 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. + * + * underline_thickness :: + * The thickness, in font units, of the + * underline for this face. Only relevant for + * scalable formats. + * + * glyph :: + * The face's associated glyph slot(s). + * + * size :: + * The current active size for this face. + * + * charmap :: + * The current active charmap for this face. + * + * @Note: + * 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'. + * + * Especially for TrueType fonts see also the documentation for + * @FT_Size_Metrics. + */ typedef struct FT_FaceRec_ { FT_Long num_faces; @@ -1125,117 +1158,117 @@ FT_BEGIN_HEADER } FT_FaceRec; - /*************************************************************************/ - /* */ - /* <Enum> */ - /* 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. */ - /* */ - /* <Values> */ - /* FT_FACE_FLAG_SCALABLE :: */ - /* The face contains outline glyphs. Note that a face can contain */ - /* bitmap strikes also, i.e., a face can have both this flag and */ - /* @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. */ - /* */ - /* 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. */ - /* */ - /* FT_FACE_FLAG_HORIZONTAL :: */ - /* 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. */ - /* */ - /* 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). */ - /* */ - /* 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. */ - /* */ - /* 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_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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* Currently, there are about a dozen TrueType fonts in the list of */ - /* 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. */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Enum: + * 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. + * + * @Values: + * FT_FACE_FLAG_SCALABLE :: + * The face contains outline glyphs. Note that a face can contain + * bitmap strikes also, i.e., a face can have both this flag and + * @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. + * + * 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. + * + * FT_FACE_FLAG_HORIZONTAL :: + * 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. + * + * 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). + * + * 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. + * + * 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_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. + * + * 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. + * + * 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. + * + * 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. + * + * 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. + * + * Currently, there are about a dozen TrueType fonts in the list of + * 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. + * + * 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. + */ #define FT_FACE_FLAG_SCALABLE ( 1L << 0 ) #define FT_FACE_FLAG_FIXED_SIZES ( 1L << 1 ) #define FT_FACE_FLAG_FIXED_WIDTH ( 1L << 2 ) @@ -1493,149 +1526,157 @@ FT_BEGIN_HEADER ( (face)->face_flags & FT_FACE_FLAG_COLOR ) - /*************************************************************************/ - /* */ - /* <Const> */ - /* 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. */ - /* */ - /* <Values> */ - /* FT_STYLE_FLAG_ITALIC :: */ - /* The face style is italic or oblique. */ - /* */ - /* FT_STYLE_FLAG_BOLD :: */ - /* The face is bold. */ - /* */ - /* <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). */ - /* */ + /************************************************************************** + * + * @Const: + * 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. + * + * @Values: + * FT_STYLE_FLAG_ITALIC :: + * The face style is italic or oblique. + * + * FT_STYLE_FLAG_BOLD :: + * The face is bold. + * + * @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). + */ #define FT_STYLE_FLAG_ITALIC ( 1 << 0 ) #define FT_STYLE_FLAG_BOLD ( 1 << 1 ) - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_Size_Internal */ - /* */ - /* <Description> */ - /* An opaque handle to an `FT_Size_InternalRec' structure, used to */ - /* model private data of a given @FT_Size object. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_Size_Internal + * + * @Description: + * 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; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_Size_Metrics */ - /* */ - /* <Description> */ - /* The size metrics structure gives the metrics of a size object. */ - /* */ - /* <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'. */ - /* */ - /* 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'. */ - /* */ - /* x_scale :: 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 */ - /* font formats. */ - /* */ - /* ascender :: 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. */ - /* */ - /* height :: 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. */ - /* */ - /* <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. */ - /* */ - /* { */ - /* 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! */ - /* */ - /* 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. */ - /* */ - /* */ - /* *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). */ - /* */ - /* 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" ) && */ - /* do_native_bytecode_hinting ) */ - /* { */ - /* ascender = ROUND( FT_MulFix( face->ascender, */ - /* size_metrics->y_scale ) ); */ - /* descender = ROUND( FT_MulFix( face->descender, */ - /* size_metrics->y_scale ) ); */ - /* } */ - /* else */ - /* { */ - /* ascender = size_metrics->ascender; */ - /* descender = size_metrics->descender; */ - /* } */ - /* */ - /* height = size_metrics->height; */ - /* max_advance = size_metrics->max_advance; */ - /* } */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_Size_Metrics + * + * @Description: + * The size metrics structure gives the metrics of a size object. + * + * @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'. + * + * 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'. + * + * x_scale :: + * 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 + * font formats. + * + * ascender :: + * 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. + * + * height :: + * 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. + * + * @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. + * + * { + * 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! + * + * 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. + * + * + * *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). + * + * 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" ) && + * do_native_bytecode_hinting ) + * { + * ascender = ROUND( FT_MulFix( face->ascender, + * size_metrics->y_scale ) ); + * descender = ROUND( FT_MulFix( face->descender, + * size_metrics->y_scale ) ); + * } + * else + * { + * ascender = size_metrics->ascender; + * descender = size_metrics->descender; + * } + * + * height = size_metrics->height; + * max_advance = size_metrics->max_advance; + * } + */ typedef struct FT_Size_Metrics_ { FT_UShort x_ppem; /* horizontal pixels per EM */ @@ -1652,25 +1693,28 @@ FT_BEGIN_HEADER } FT_Size_Metrics; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_SizeRec */ - /* */ - /* <Description> */ - /* FreeType root size class structure. A size object models a face */ - /* object at a given size. */ - /* */ - /* <Fields> */ - /* face :: 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. */ - /* */ - /* metrics :: Metrics for this size object. This field is read-only. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_SizeRec + * + * @Description: + * FreeType root size class structure. A size object models a face + * object at a given size. + * + * @Fields: + * face :: + * 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. + * + * metrics :: + * Metrics for this size object. This field is read-only. + */ typedef struct FT_SizeRec_ { FT_Face face; /* parent face object */ @@ -1681,231 +1725,251 @@ FT_BEGIN_HEADER } FT_SizeRec; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_SubGlyph */ - /* */ - /* <Description> */ - /* The subglyph structure is an internal object used to describe */ - /* 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. */ - /* */ - /* You can however retrieve subglyph information with */ - /* @FT_Get_SubGlyph_Info. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_SubGlyph + * + * @Description: + * The subglyph structure is an internal object used to describe + * 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. + * + * You can however retrieve subglyph information with + * @FT_Get_SubGlyph_Info. + */ typedef struct FT_SubGlyphRec_* FT_SubGlyph; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_Slot_Internal */ - /* */ - /* <Description> */ - /* An opaque handle to an `FT_Slot_InternalRec' structure, used to */ - /* model private data of a given @FT_GlyphSlot object. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_Slot_Internal + * + * @Description: + * 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; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* 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. */ - /* */ - /* <Fields> */ - /* library :: 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. */ - /* */ - /* 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 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* bitmap :: 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. */ - /* */ - /* 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*. */ - /* */ - /* 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. */ - /* */ - /* 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 */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* control_len :: 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. */ - /* */ - /* rsb_delta :: 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. */ - /* */ - /* 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. */ - /* */ - /* 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 */ - /* position (e.g., coordinates (0,0) on the baseline). Of course, */ - /* `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: */ - /* */ - /* { */ - /* FT_GlyphSlot slot = face->glyph; */ - /* FT_Pos origin_x = 0; */ - /* */ - /* */ - /* for all glyphs do */ - /* <load glyph with `FT_Load_Glyph'> */ - /* */ - /* FT_Outline_Translate( slot->outline, origin_x & 63, 0 ); */ - /* */ - /* <save glyph image, or render glyph, or ...> */ - /* */ - /* <compute kern between current and next glyph */ - /* and add it to `origin_x'> */ - /* */ - /* 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: */ - /* */ - /* { */ - /* FT_GlyphSlot slot = face->glyph; */ - /* FT_Pos origin_x = 0; */ - /* FT_Pos prev_rsb_delta = 0; */ - /* */ - /* */ - /* for all glyphs do */ - /* <compute kern between current and previous glyph */ - /* and add it to `origin_x'> */ - /* */ - /* <load glyph with `FT_Load_Glyph'> */ - /* */ - /* if ( prev_rsb_delta - slot->lsb_delta > 32 ) */ - /* origin_x -= 64; */ - /* else if ( prev_rsb_delta - slot->lsb_delta < -31 ) */ - /* origin_x += 64; */ - /* */ - /* prev_rsb_delta = slot->rsb_delta; */ - /* */ - /* <save glyph image, or render glyph, or ...> */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Struct: + * 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. + * + * @Fields: + * library :: + * 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. + * + * 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 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. + * + * 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. + * + * 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. + * + * 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. + * + * 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. + * + * bitmap :: + * 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. + * + * 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*. + * + * 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. + * + * 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 + * 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. + * + * 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. + * + * control_len :: + * 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. + * + * rsb_delta :: + * 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. + * + * 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. + * + * 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 + * position (e.g., coordinates (0,0) on the baseline). Of course, + * `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: + * + * { + * FT_GlyphSlot slot = face->glyph; + * FT_Pos origin_x = 0; + * + * + * for all glyphs do + * <load glyph with `FT_Load_Glyph'> + * + * FT_Outline_Translate( slot->outline, origin_x & 63, 0 ); + * + * <save glyph image, or render glyph, or ...> + * + * <compute kern between current and next glyph + * and add it to `origin_x'> + * + * 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: + * + * { + * FT_GlyphSlot slot = face->glyph; + * FT_Pos origin_x = 0; + * FT_Pos prev_rsb_delta = 0; + * + * + * for all glyphs do + * <compute kern between current and previous glyph + * and add it to `origin_x'> + * + * <load glyph with `FT_Load_Glyph'> + * + * if ( prev_rsb_delta - slot->lsb_delta > 32 ) + * origin_x -= 64; + * else if ( prev_rsb_delta - slot->lsb_delta < -31 ) + * origin_x += 64; + * + * prev_rsb_delta = slot->rsb_delta; + * + * <save glyph image, or render glyph, or ...> + * + * 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. + */ typedef struct FT_GlyphSlotRec_ { FT_Library library; @@ -1952,86 +2016,93 @@ FT_BEGIN_HEADER /*************************************************************************/ - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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. */ - /* */ - /* <Output> */ - /* alibrary :: A handle to a new library object. */ - /* */ - /* <Return> */ - /* 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. */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Function: + * 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. + * + * @Output: + * alibrary :: + * A handle to a new library object. + * + * @Return: + * 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. + * + * 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. + */ FT_EXPORT( FT_Error ) FT_Init_FreeType( FT_Library *alibrary ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Done_FreeType */ - /* */ - /* <Description> */ - /* Destroy a given FreeType library object and all of its children, */ - /* including resources, drivers, faces, sizes, etc. */ - /* */ - /* <Input> */ - /* library :: A handle to the target library object. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Done_FreeType + * + * @Description: + * Destroy a given FreeType library object and all of its children, + * including resources, drivers, faces, sizes, etc. + * + * @Input: + * library :: + * A handle to the target library object. + * + * @Return: + * FreeType error code. 0~means success. + */ FT_EXPORT( FT_Error ) FT_Done_FreeType( FT_Library library ); - /*************************************************************************/ - /* */ - /* <Enum> */ - /* FT_OPEN_XXX */ - /* */ - /* <Description> */ - /* A list of bit field constants used within the `flags' field of the */ - /* @FT_Open_Args structure. */ - /* */ - /* <Values> */ - /* FT_OPEN_MEMORY :: This is a memory-based stream. */ - /* */ - /* FT_OPEN_STREAM :: Copy the stream from the `stream' field. */ - /* */ - /* FT_OPEN_PATHNAME :: Create a new input stream from a C~path */ - /* name. */ - /* */ - /* FT_OPEN_DRIVER :: Use the `driver' field. */ - /* */ - /* FT_OPEN_PARAMS :: Use the `num_params' and `params' fields. */ - /* */ - /* <Note> */ - /* The `FT_OPEN_MEMORY', `FT_OPEN_STREAM', and `FT_OPEN_PATHNAME' */ - /* flags are mutually exclusive. */ - /* */ + /************************************************************************** + * + * @Enum: + * FT_OPEN_XXX + * + * @Description: + * A list of bit field constants used within the `flags' field of the + * @FT_Open_Args structure. + * + * @Values: + * FT_OPEN_MEMORY :: + * This is a memory-based stream. + * + * FT_OPEN_STREAM :: + * Copy the stream from the `stream' field. + * + * FT_OPEN_PATHNAME :: + * Create a new input stream from a C~path + * name. + * + * FT_OPEN_DRIVER :: + * Use the `driver' field. + * + * FT_OPEN_PARAMS :: + * Use the `num_params' and `params' fields. + * + * @Note: + * 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 #define FT_OPEN_PATHNAME 0x4 @@ -2048,24 +2119,26 @@ FT_BEGIN_HEADER #define ft_open_params FT_OPEN_PARAMS - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_Parameter */ - /* */ - /* <Description> */ - /* A simple structure to pass more or less generic parameters to */ - /* @FT_Open_Face and @FT_Face_Properties. */ - /* */ - /* <Fields> */ - /* tag :: A four-byte identification tag. */ - /* */ - /* data :: A pointer to the parameter data. */ - /* */ - /* <Note> */ - /* The ID and function of parameters are driver-specific. See */ - /* section @parameter_tags for more information. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_Parameter + * + * @Description: + * A simple structure to pass more or less generic parameters to + * @FT_Open_Face and @FT_Face_Properties. + * + * @Fields: + * tag :: + * A four-byte identification tag. + * + * data :: + * A pointer to the parameter data. + * + * @Note: + * The ID and function of parameters are driver-specific. See + * section @parameter_tags for more information. + */ typedef struct FT_Parameter_ { FT_ULong tag; @@ -2074,65 +2147,73 @@ FT_BEGIN_HEADER } FT_Parameter; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_Open_Args */ - /* */ - /* <Description> */ - /* A structure to indicate how to open a new font file or stream. A */ - /* pointer to such a structure can be used as a parameter for the */ - /* functions @FT_Open_Face and @FT_Attach_Stream. */ - /* */ - /* <Fields> */ - /* flags :: A set of bit flags indicating how to use the */ - /* structure. */ - /* */ - /* memory_base :: The first byte of the file in memory. */ - /* */ - /* memory_size :: The size in bytes of the file in memory. */ - /* */ - /* pathname :: A pointer to an 8-bit file pathname. */ - /* */ - /* stream :: 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. */ - /* */ - /* num_params :: The number of extra parameters. */ - /* */ - /* params :: Extra parameters passed to the font driver when */ - /* opening a new face. */ - /* */ - /* <Note> */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_Open_Args + * + * @Description: + * A structure to indicate how to open a new font file or stream. A + * pointer to such a structure can be used as a parameter for the + * functions @FT_Open_Face and @FT_Attach_Stream. + * + * @Fields: + * flags :: + * A set of bit flags indicating how to use the + * structure. + * + * memory_base :: + * The first byte of the file in memory. + * + * memory_size :: + * The size in bytes of the file in memory. + * + * pathname :: + * A pointer to an 8-bit file pathname. + * + * stream :: + * 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. + * + * num_params :: + * The number of extra parameters. + * + * params :: + * Extra parameters passed to the font driver when + * opening a new face. + * + * @Note: + * 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. + * + * 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. + * + * 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. + * + * 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_ { FT_UInt flags; @@ -2147,34 +2228,38 @@ FT_BEGIN_HEADER } FT_Open_Args; - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_New_Face */ - /* */ - /* <Description> */ - /* Call @FT_Open_Face to open a font by its pathname. */ - /* */ - /* <InOut> */ - /* library :: A handle to the library resource. */ - /* */ - /* <Input> */ - /* pathname :: A path to the font file. */ - /* */ - /* face_index :: 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. */ - /* */ - /* <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). */ - /* */ + /************************************************************************** + * + * @Function: + * FT_New_Face + * + * @Description: + * Call @FT_Open_Face to open a font by its pathname. + * + * @InOut: + * library :: + * A handle to the library resource. + * + * @Input: + * pathname :: + * A path to the font file. + * + * face_index :: + * 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. + * + * @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). + */ FT_EXPORT( FT_Error ) FT_New_Face( FT_Library library, const char* filepathname, @@ -2182,36 +2267,41 @@ FT_BEGIN_HEADER FT_Face *aface ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_New_Memory_Face */ - /* */ - /* <Description> */ - /* Call @FT_Open_Face to open a font that has been loaded into */ - /* memory. */ - /* */ - /* <InOut> */ - /* library :: A handle to the library resource. */ - /* */ - /* <Input> */ - /* file_base :: A pointer to the beginning of the font data. */ - /* */ - /* file_size :: The size of the memory chunk used by the font data. */ - /* */ - /* face_index :: 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. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ - /* <Note> */ - /* You must not deallocate the memory before calling @FT_Done_Face. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_New_Memory_Face + * + * @Description: + * Call @FT_Open_Face to open a font that has been loaded into + * memory. + * + * @InOut: + * library :: + * A handle to the library resource. + * + * @Input: + * file_base :: + * A pointer to the beginning of the font data. + * + * file_size :: + * The size of the memory chunk used by the font data. + * + * face_index :: + * 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. + * + * @Return: + * FreeType error code. 0~means success. + * + * @Note: + * You must not deallocate the memory before calling @FT_Done_Face. + */ FT_EXPORT( FT_Error ) FT_New_Memory_Face( FT_Library library, const FT_Byte* file_base, @@ -2220,147 +2310,151 @@ FT_BEGIN_HEADER FT_Face *aface ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Open_Face */ - /* */ - /* <Description> */ - /* Create a face object from a given resource described by */ - /* @FT_Open_Args. */ - /* */ - /* <InOut> */ - /* library :: A handle to the library resource. */ - /* */ - /* <Input> */ - /* args :: 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 */ - /* 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. */ - /* */ - /* <Output> */ - /* aface :: 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'. */ - /* */ - /* 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. */ - /* */ - /* See the discussion of reference counters in the description of */ - /* @FT_Reference_Face. */ - /* */ - /* To loop over all faces, use code similar to the following snippet */ - /* (omitting the error handling). */ - /* */ - /* { */ - /* ... */ - /* FT_Face face; */ - /* FT_Long i, num_faces; */ - /* */ - /* */ - /* error = FT_Open_Face( library, args, -1, &face ); */ - /* if ( error ) { ... } */ - /* */ - /* num_faces = face->num_faces; */ - /* FT_Done_Face( face ); */ - /* */ - /* for ( i = 0; i < num_faces; i++ ) */ - /* { */ - /* ... */ - /* error = FT_Open_Face( library, args, i, &face ); */ - /* ... */ - /* 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. */ - /* */ - /* { */ - /* ... */ - /* FT_Face face; */ - /* */ - /* FT_Long num_faces = 0; */ - /* FT_Long num_instances = 0; */ - /* */ - /* FT_Long face_idx = 0; */ - /* FT_Long instance_idx = 0; */ - /* */ - /* */ - /* do */ - /* { */ - /* FT_Long id = ( instance_idx << 16 ) + face_idx; */ - /* */ - /* */ - /* error = FT_Open_Face( library, args, id, &face ); */ - /* if ( error ) { ... } */ - /* */ - /* num_faces = face->num_faces; */ - /* num_instances = face->style_flags >> 16; */ - /* */ - /* ... */ - /* */ - /* FT_Done_Face( face ); */ - /* */ - /* if ( instance_idx < num_instances ) */ - /* instance_idx++; */ - /* else */ - /* { */ - /* face_idx++; */ - /* instance_idx = 0; */ - /* } */ - /* */ - /* } while ( face_idx < num_faces ) */ - /* } */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Open_Face + * + * @Description: + * Create a face object from a given resource described by + * @FT_Open_Args. + * + * @InOut: + * library :: + * A handle to the library resource. + * + * @Input: + * args :: + * 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 + * 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. + * + * @Output: + * aface :: + * 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'. + * + * 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. + * + * See the discussion of reference counters in the description of + * @FT_Reference_Face. + * + * To loop over all faces, use code similar to the following snippet + * (omitting the error handling). + * + * { + * ... + * FT_Face face; + * FT_Long i, num_faces; + * + * + * error = FT_Open_Face( library, args, -1, &face ); + * if ( error ) { ... } + * + * num_faces = face->num_faces; + * FT_Done_Face( face ); + * + * for ( i = 0; i < num_faces; i++ ) + * { + * ... + * error = FT_Open_Face( library, args, i, &face ); + * ... + * 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. + * + * { + * ... + * FT_Face face; + * + * FT_Long num_faces = 0; + * FT_Long num_instances = 0; + * + * FT_Long face_idx = 0; + * FT_Long instance_idx = 0; + * + * + * do + * { + * FT_Long id = ( instance_idx << 16 ) + face_idx; + * + * + * error = FT_Open_Face( library, args, id, &face ); + * if ( error ) { ... } + * + * num_faces = face->num_faces; + * num_instances = face->style_flags >> 16; + * + * ... + * + * FT_Done_Face( face ); + * + * if ( instance_idx < num_instances ) + * instance_idx++; + * else + * { + * face_idx++; + * instance_idx = 0; + * } + * + * } while ( face_idx < num_faces ) + * } + */ FT_EXPORT( FT_Error ) FT_Open_Face( FT_Library library, const FT_Open_Args* args, @@ -2368,204 +2462,212 @@ FT_BEGIN_HEADER FT_Face *aface ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Attach_File */ - /* */ - /* <Description> */ - /* Call @FT_Attach_Stream to attach a file. */ - /* */ - /* <InOut> */ - /* face :: The target face object. */ - /* */ - /* <Input> */ - /* filepathname :: The pathname. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Attach_File + * + * @Description: + * Call @FT_Attach_Stream to attach a file. + * + * @InOut: + * face :: + * The target face object. + * + * @Input: + * filepathname :: + * The pathname. + * + * @Return: + * FreeType error code. 0~means success. + */ FT_EXPORT( FT_Error ) FT_Attach_File( FT_Face face, const char* filepathname ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Attach_Stream */ - /* */ - /* <Description> */ - /* `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. */ - /* */ - /* <InOut> */ - /* face :: The target face object. */ - /* */ - /* <Input> */ - /* parameters :: 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). */ - /* */ - /* Client applications are expected to know what they are doing */ - /* when invoking this function. Most drivers simply do not implement */ - /* file or stream attachments. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Attach_Stream + * + * @Description: + * `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. + * + * @InOut: + * face :: + * The target face object. + * + * @Input: + * parameters :: + * 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). + * + * 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, FT_Open_Args* parameters ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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 */ - /* decrements the counter. */ - /* */ - /* This function helps in managing life-cycles of structures that */ - /* reference @FT_Face objects. */ - /* */ - /* <Input> */ - /* face :: A handle to a target face object. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ - /* <Since> */ - /* 2.4.2 */ - /* */ + /************************************************************************** + * + * @Function: + * 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 + * decrements the counter. + * + * This function helps in managing life-cycles of structures that + * reference @FT_Face objects. + * + * @Input: + * face :: + * A handle to a target face object. + * + * @Return: + * FreeType error code. 0~means success. + * + * @Since: + * 2.4.2 + */ FT_EXPORT( FT_Error ) FT_Reference_Face( FT_Face face ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Done_Face */ - /* */ - /* <Description> */ - /* Discard a given face object, as well as all of its child slots and */ - /* sizes. */ - /* */ - /* <Input> */ - /* face :: A handle to a target face object. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ - /* <Note> */ - /* See the discussion of reference counters in the description of */ - /* @FT_Reference_Face. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Done_Face + * + * @Description: + * Discard a given face object, as well as all of its child slots and + * sizes. + * + * @Input: + * face :: + * A handle to a target face object. + * + * @Return: + * FreeType error code. 0~means success. + * + * @Note: + * See the discussion of reference counters in the description of + * @FT_Reference_Face. + */ FT_EXPORT( FT_Error ) FT_Done_Face( FT_Face face ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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. */ - /* */ - /* <InOut> */ - /* face :: A handle to a target face object. */ - /* */ - /* <Input> */ - /* strike_index :: 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 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. */ - /* */ + /************************************************************************** + * + * @Function: + * 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. + * + * @InOut: + * face :: + * A handle to a target face object. + * + * @Input: + * strike_index :: + * 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 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. + */ FT_EXPORT( FT_Error ) FT_Select_Size( FT_Face face, FT_Int strike_index ); - /*************************************************************************/ - /* */ - /* <Enum> */ - /* 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). */ - /* */ - /* <Values> */ - /* FT_SIZE_REQUEST_TYPE_NOMINAL :: */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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 */ - /* 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. */ - /* */ - /* FT_SIZE_REQUEST_TYPE_SCALES :: */ - /* Specify the scaling values directly. */ - /* */ - /* <Note> */ - /* The above descriptions only apply to scalable formats. For bitmap */ - /* formats, the behaviour is up to the driver. */ - /* */ - /* See the note section of @FT_Size_Metrics if you wonder how size */ - /* requesting relates to scaling values. */ - /* */ + /************************************************************************** + * + * @Enum: + * 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). + * + * @Values: + * FT_SIZE_REQUEST_TYPE_NOMINAL :: + * 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. + * + * 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. + * + * 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 + * 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. + * + * FT_SIZE_REQUEST_TYPE_SCALES :: + * Specify the scaling values directly. + * + * @Note: + * The above descriptions only apply to scalable formats. For bitmap + * formats, the behaviour is up to the driver. + * + * See the note section of @FT_Size_Metrics if you wonder how size + * requesting relates to scaling values. + */ typedef enum FT_Size_Request_Type_ { FT_SIZE_REQUEST_TYPE_NOMINAL, @@ -2579,42 +2681,47 @@ FT_BEGIN_HEADER } FT_Size_Request_Type; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_Size_RequestRec */ - /* */ - /* <Description> */ - /* A structure to model a size request. */ - /* */ - /* <Fields> */ - /* type :: See @FT_Size_Request_Type. */ - /* */ - /* width :: 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). */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* <Note> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_Size_RequestRec + * + * @Description: + * A structure to model a size request. + * + * @Fields: + * type :: + * See @FT_Size_Request_Type. + * + * width :: + * 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). + * + * 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. + * + * 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. + * + * @Note: + * 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. + */ typedef struct FT_Size_RequestRec_ { FT_Size_Request_Type type; @@ -2626,96 +2733,103 @@ FT_BEGIN_HEADER } FT_Size_RequestRec; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_Size_Request */ - /* */ - /* <Description> */ - /* A handle to a size request structure. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_Size_Request + * + * @Description: + * A handle to a size request structure. + */ typedef struct FT_Size_RequestRec_ *FT_Size_Request; - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Request_Size */ - /* */ - /* <Description> */ - /* Resize the scale of the active @FT_Size object in a face. */ - /* */ - /* <InOut> */ - /* face :: A handle to a target face object. */ - /* */ - /* <Input> */ - /* req :: A pointer to a @FT_Size_RequestRec. */ - /* */ - /* <Return> */ - /* 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. */ - /* */ - /* 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). */ - /* */ - /* Don't use this function if you are using the FreeType cache API. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Request_Size + * + * @Description: + * Resize the scale of the active @FT_Size object in a face. + * + * @InOut: + * face :: + * A handle to a target face object. + * + * @Input: + * req :: + * A pointer to a @FT_Size_RequestRec. + * + * @Return: + * 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. + * + * 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). + * + * Don't use this function if you are using the FreeType cache API. + */ FT_EXPORT( FT_Error ) FT_Request_Size( FT_Face face, FT_Size_Request req ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Set_Char_Size */ - /* */ - /* <Description> */ - /* Call @FT_Request_Size to request the nominal size (in points). */ - /* */ - /* <InOut> */ - /* face :: A handle to a target face object. */ - /* */ - /* <Input> */ - /* char_width :: The nominal width, in 26.6 fractional points. */ - /* */ - /* char_height :: The nominal height, in 26.6 fractional points. */ - /* */ - /* horz_resolution :: The horizontal resolution in dpi. */ - /* */ - /* vert_resolution :: The vertical resolution in dpi. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ - /* <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. */ - /* */ - /* 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. */ - /* */ - /* Don't use this function if you are using the FreeType cache API. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Set_Char_Size + * + * @Description: + * Call @FT_Request_Size to request the nominal size (in points). + * + * @InOut: + * face :: + * A handle to a target face object. + * + * @Input: + * char_width :: + * The nominal width, in 26.6 fractional points. + * + * char_height :: + * The nominal height, in 26.6 fractional points. + * + * horz_resolution :: + * The horizontal resolution in dpi. + * + * vert_resolution :: + * The vertical resolution in dpi. + * + * @Return: + * FreeType error code. 0~means success. + * + * @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. + * + * 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. + * + * Don't use this function if you are using the FreeType cache API. + */ FT_EXPORT( FT_Error ) FT_Set_Char_Size( FT_Face face, FT_F26Dot6 char_width, @@ -2724,120 +2838,129 @@ FT_BEGIN_HEADER FT_UInt vert_resolution ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Set_Pixel_Sizes */ - /* */ - /* <Description> */ - /* Call @FT_Request_Size to request the nominal size (in pixels). */ - /* */ - /* <InOut> */ - /* face :: A handle to the target face object. */ - /* */ - /* <Input> */ - /* pixel_width :: The nominal width, in pixels. */ - /* */ - /* pixel_height :: The nominal height, in pixels. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ - /* <Note> */ - /* You should not rely on the resulting glyphs matching or being */ - /* constrained to this pixel size. Refer to @FT_Request_Size to */ - /* understand how requested sizes relate to actual sizes. */ - /* */ - /* Don't use this function if you are using the FreeType cache API. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Set_Pixel_Sizes + * + * @Description: + * Call @FT_Request_Size to request the nominal size (in pixels). + * + * @InOut: + * face :: + * A handle to the target face object. + * + * @Input: + * pixel_width :: + * The nominal width, in pixels. + * + * pixel_height :: + * The nominal height, in pixels. + * + * @Return: + * FreeType error code. 0~means success. + * + * @Note: + * You should not rely on the resulting glyphs matching or being + * constrained to this pixel size. Refer to @FT_Request_Size to + * understand how requested sizes relate to actual sizes. + * + * Don't use this function if you are using the FreeType cache API. + */ FT_EXPORT( FT_Error ) FT_Set_Pixel_Sizes( FT_Face face, FT_UInt pixel_width, FT_UInt pixel_height ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Load_Glyph */ - /* */ - /* <Description> */ - /* Load a glyph into the glyph slot of a face object. */ - /* */ - /* <InOut> */ - /* face :: 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. */ - /* */ - /* 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). */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ - /* <Note> */ - /* 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. */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Load_Glyph + * + * @Description: + * Load a glyph into the glyph slot of a face object. + * + * @InOut: + * face :: + * 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. + * + * 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). + * + * @Return: + * FreeType error code. 0~means success. + * + * @Note: + * 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. + * + * 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, FT_UInt glyph_index, FT_Int32 load_flags ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Load_Char */ - /* */ - /* <Description> */ - /* Load a glyph into the glyph slot of a face object, accessed by its */ - /* character code. */ - /* */ - /* <InOut> */ - /* face :: 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. */ - /* */ - /* 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). */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ - /* <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. */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Load_Char + * + * @Description: + * Load a glyph into the glyph slot of a face object, accessed by its + * character code. + * + * @InOut: + * face :: + * 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. + * + * 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). + * + * @Return: + * FreeType error code. 0~means success. + * + * @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. + * + * 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, FT_ULong char_code, @@ -2859,15 +2982,15 @@ 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 @@ -3155,98 +3278,101 @@ FT_BEGIN_HEADER #define FT_LOAD_TARGET_MODE( x ) ( (FT_Render_Mode)( ( (x) >> 16 ) & 15 ) ) - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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. */ - /* */ - /* <InOut> */ - /* face :: A handle to the source face object. */ - /* */ - /* <Input> */ - /* 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. */ - /* */ - /* <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. */ - /* */ - /* Note that this also transforms the `face.glyph.advance' field, but */ - /* *not* the values in `face.glyph.metrics'. */ - /* */ + /************************************************************************** + * + * @Function: + * 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. + * + * @InOut: + * face :: + * A handle to the source face object. + * + * @Input: + * 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. + * + * @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. + * + * 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, FT_Matrix* matrix, FT_Vector* delta ); - /*************************************************************************/ - /* */ - /* <Enum> */ - /* FT_Render_Mode */ - /* */ - /* <Description> */ - /* 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. */ - /* */ - /* All modes except @FT_RENDER_MODE_MONO use 256 levels of opacity, */ - /* indicating pixel coverage. Use linear alpha blending and gamma */ - /* correction to correctly render non-monochrome glyph bitmaps onto a */ - /* surface; see @FT_Render_Glyph. */ - /* */ - /* <Values> */ - /* FT_RENDER_MODE_NORMAL :: */ - /* 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. */ - /* */ - /* FT_RENDER_MODE_MONO :: */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* <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. */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Enum: + * FT_Render_Mode + * + * @Description: + * 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. + * + * All modes except @FT_RENDER_MODE_MONO use 256 levels of opacity, + * indicating pixel coverage. Use linear alpha blending and gamma + * correction to correctly render non-monochrome glyph bitmaps onto a + * surface; see @FT_Render_Glyph. + * + * @Values: + * FT_RENDER_MODE_NORMAL :: + * 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. + * + * FT_RENDER_MODE_MONO :: + * 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. + * + * 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. + * + * @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. + * + * 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. + */ typedef enum FT_Render_Mode_ { FT_RENDER_MODE_NORMAL = 0, @@ -3266,150 +3392,155 @@ FT_BEGIN_HEADER #define ft_render_mode_mono FT_RENDER_MODE_MONO - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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. */ - /* */ - /* <InOut> */ - /* slot :: 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. */ - /* */ - /* <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 */ - /* 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. */ - /* */ - /* 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, */ - /* */ - /* 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 */ - /* */ - /* 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. */ - /* */ - /* 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 */ - /* 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_filtering. 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. */ - /* */ + /************************************************************************** + * + * @Function: + * 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. + * + * @InOut: + * slot :: + * 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. + * + * @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 + * 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. + * + * 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, + * + * 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 + * + * 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. + * + * 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 + * 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_filtering. 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, FT_Render_Mode render_mode ); - /*************************************************************************/ - /* */ - /* <Enum> */ - /* FT_Kerning_Mode */ - /* */ - /* <Description> */ - /* An enumeration to specify the format of kerning values returned by */ - /* @FT_Get_Kerning. */ - /* */ - /* <Values> */ - /* FT_KERNING_DEFAULT :: Return grid-fitted kerning distances in */ - /* 26.6 fractional pixels. */ - /* */ - /* FT_KERNING_UNFITTED :: Return un-grid-fitted kerning distances in */ - /* 26.6 fractional pixels. */ - /* */ - /* FT_KERNING_UNSCALED :: 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. */ - /* */ - /* Both FT_KERNING_DEFAULT and FT_KERNING_UNFITTED use the current */ - /* horizontal scaling factor (as set e.g. with @FT_Set_Char_Size) to */ - /* convert font units to pixels. */ - /* */ + /************************************************************************** + * + * @Enum: + * FT_Kerning_Mode + * + * @Description: + * An enumeration to specify the format of kerning values returned by + * @FT_Get_Kerning. + * + * @Values: + * FT_KERNING_DEFAULT :: + * Return grid-fitted kerning distances in + * 26.6 fractional pixels. + * + * FT_KERNING_UNFITTED :: + * Return un-grid-fitted kerning distances in + * 26.6 fractional pixels. + * + * FT_KERNING_UNSCALED :: + * 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. + * + * Both FT_KERNING_DEFAULT and FT_KERNING_UNFITTED use the current + * horizontal scaling factor (as set e.g. with @FT_Set_Char_Size) to + * convert font units to pixels. + */ typedef enum FT_Kerning_Mode_ { FT_KERNING_DEFAULT = 0, @@ -3426,44 +3557,49 @@ FT_BEGIN_HEADER #define ft_kerning_unscaled FT_KERNING_UNSCALED - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Get_Kerning */ - /* */ - /* <Description> */ - /* Return the kerning vector between two glyphs of the same face. */ - /* */ - /* <Input> */ - /* face :: A handle to a source face object. */ - /* */ - /* left_glyph :: The index of the left glyph in the kern pair. */ - /* */ - /* right_glyph :: 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. */ - /* */ - /* <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. */ - /* */ - /* <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. */ - /* */ - /* 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'. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Get_Kerning + * + * @Description: + * Return the kerning vector between two glyphs of the same face. + * + * @Input: + * face :: + * A handle to a source face object. + * + * left_glyph :: + * The index of the left glyph in the kern pair. + * + * right_glyph :: + * 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. + * + * @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. + * + * @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. + * + * 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'. + */ FT_EXPORT( FT_Error ) FT_Get_Kerning( FT_Face face, FT_UInt left_glyph, @@ -3472,39 +3608,43 @@ FT_BEGIN_HEADER FT_Vector *akerning ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Get_Track_Kerning */ - /* */ - /* <Description> */ - /* Return the track kerning for a given face object at a given size. */ - /* */ - /* <Input> */ - /* face :: A handle to a source face object. */ - /* */ - /* point_size :: 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. */ - /* */ - /* <Output> */ - /* akerning :: 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 */ - /* @FT_Attach_Stream). */ - /* */ - /* Only very few AFM files come with track kerning data; please refer */ - /* to Adobe's AFM specification for more details. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Get_Track_Kerning + * + * @Description: + * Return the track kerning for a given face object at a given size. + * + * @Input: + * face :: + * A handle to a source face object. + * + * point_size :: + * 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. + * + * @Output: + * akerning :: + * 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 + * @FT_Attach_Stream). + * + * 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, FT_Fixed point_size, @@ -3512,45 +3652,49 @@ FT_BEGIN_HEADER FT_Fixed* akerning ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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. */ - /* */ - /* <Input> */ - /* face :: A handle to a source face object. */ - /* */ - /* glyph_index :: The glyph index. */ - /* */ - /* buffer_max :: The maximum number of bytes available in the */ - /* buffer. */ - /* */ - /* <Output> */ - /* buffer :: 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. */ - /* */ - /* 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'). */ - /* */ - /* This function always returns an error if the config macro */ - /* `FT_CONFIG_OPTION_NO_GLYPH_NAMES' is not defined in `ftoption.h'. */ - /* */ + /************************************************************************** + * + * @Function: + * 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. + * + * @Input: + * face :: + * A handle to a source face object. + * + * glyph_index :: + * The glyph index. + * + * buffer_max :: + * The maximum number of bytes available in the + * buffer. + * + * @Output: + * buffer :: + * 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. + * + * 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'). + * + * This function always returns an error if the config macro + * `FT_CONFIG_OPTION_NO_GLYPH_NAMES' is not defined in `ftoption.h'. + */ FT_EXPORT( FT_Error ) FT_Get_Glyph_Name( FT_Face face, FT_UInt glyph_index, @@ -3558,101 +3702,106 @@ FT_BEGIN_HEADER FT_UInt buffer_max ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Get_Postscript_Name */ - /* */ - /* <Description> */ - /* Retrieve the ASCII PostScript name of a given face, if available. */ - /* This only works with PostScript, TrueType, and OpenType fonts. */ - /* */ - /* <Input> */ - /* face :: A handle to the source face object. */ - /* */ - /* <Return> */ - /* 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. */ - /* */ - /* 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 */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Get_Postscript_Name + * + * @Description: + * Retrieve the ASCII PostScript name of a given face, if available. + * This only works with PostScript, TrueType, and OpenType fonts. + * + * @Input: + * face :: + * A handle to the source face object. + * + * @Return: + * 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. + * + * 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 + * 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. + */ FT_EXPORT( const char* ) FT_Get_Postscript_Name( FT_Face face ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Select_Charmap */ - /* */ - /* <Description> */ - /* Select a given charmap by its encoding tag (as listed in */ - /* `freetype.h'). */ - /* */ - /* <InOut> */ - /* face :: A handle to the source face object. */ - /* */ - /* <Input> */ - /* encoding :: A handle to the selected encoding. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ - /* <Note> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Select_Charmap + * + * @Description: + * Select a given charmap by its encoding tag (as listed in + * `freetype.h'). + * + * @InOut: + * face :: + * A handle to the source face object. + * + * @Input: + * encoding :: + * A handle to the selected encoding. + * + * @Return: + * FreeType error code. 0~means success. + * + * @Note: + * 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. + */ FT_EXPORT( FT_Error ) FT_Select_Charmap( FT_Face face, FT_Encoding encoding ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Set_Charmap */ - /* */ - /* <Description> */ - /* Select a given charmap for character code to glyph index mapping. */ - /* */ - /* <InOut> */ - /* face :: A handle to the source face object. */ - /* */ - /* <Input> */ - /* charmap :: A handle to the selected charmap. */ - /* */ - /* <Return> */ - /* 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). */ - /* */ - /* It also fails if an OpenType type~14 charmap is selected (which */ - /* doesn't map character codes to glyph indices at all). */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Set_Charmap + * + * @Description: + * Select a given charmap for character code to glyph index mapping. + * + * @InOut: + * face :: + * A handle to the source face object. + * + * @Input: + * charmap :: + * A handle to the selected charmap. + * + * @Return: + * 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). + * + * It also fails if an OpenType type~14 charmap is selected (which + * doesn't map character codes to glyph indices at all). + */ FT_EXPORT( FT_Error ) FT_Set_Charmap( FT_Face face, FT_CharMap charmap ); @@ -3679,125 +3828,132 @@ FT_BEGIN_HEADER FT_Get_Charmap_Index( FT_CharMap charmap ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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. */ - /* */ - /* <Input> */ - /* face :: A handle to the source face object. */ - /* */ - /* charcode :: The character code. */ - /* */ - /* <Return> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Function: + * 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. + * + * @Input: + * face :: + * A handle to the source face object. + * + * charcode :: + * The character code. + * + * @Return: + * 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. + */ FT_EXPORT( FT_UInt ) FT_Get_Char_Index( FT_Face face, FT_ULong charcode ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Get_First_Char */ - /* */ - /* <Description> */ - /* Return the first character code in the current charmap of a given */ - /* face, together with its corresponding glyph index. */ - /* */ - /* <Input> */ - /* face :: A handle to the source face object. */ - /* */ - /* <Output> */ - /* agindex :: 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: */ - /* */ - /* { */ - /* FT_ULong charcode; */ - /* FT_UInt gindex; */ - /* */ - /* */ - /* charcode = FT_Get_First_Char( face, &gindex ); */ - /* while ( gindex != 0 ) */ - /* { */ - /* ... do something with (charcode,gindex) pair ... */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Get_First_Char + * + * @Description: + * Return the first character code in the current charmap of a given + * face, together with its corresponding glyph index. + * + * @Input: + * face :: + * A handle to the source face object. + * + * @Output: + * agindex :: + * 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: + * + * { + * FT_ULong charcode; + * FT_UInt gindex; + * + * + * charcode = FT_Get_First_Char( face, &gindex ); + * while ( gindex != 0 ) + * { + * ... do something with (charcode,gindex) pair ... + * + * 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. + */ FT_EXPORT( FT_ULong ) FT_Get_First_Char( FT_Face face, FT_UInt *agindex ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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. */ - /* */ - /* <Input> */ - /* face :: A handle to the source face object. */ - /* */ - /* char_code :: The starting character code. */ - /* */ - /* <Output> */ - /* agindex :: 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. */ - /* */ - /* Note that `*agindex' is set to~0 when there are no more codes in */ - /* the charmap. */ - /* */ + /************************************************************************** + * + * @Function: + * 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. + * + * @Input: + * face :: + * A handle to the source face object. + * + * char_code :: + * The starting character code. + * + * @Output: + * agindex :: + * 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. + * + * 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, FT_ULong char_code, @@ -3903,22 +4059,24 @@ FT_BEGIN_HEADER FT_Parameter* properties ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Get_Name_Index */ - /* */ - /* <Description> */ - /* Return the glyph index of a given glyph name. */ - /* */ - /* <Input> */ - /* face :: A handle to the source face object. */ - /* */ - /* glyph_name :: The glyph name. */ - /* */ - /* <Return> */ - /* The glyph index. 0~means `undefined character code'. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Get_Name_Index + * + * @Description: + * Return the glyph index of a given glyph name. + * + * @Input: + * face :: + * A handle to the source face object. + * + * glyph_name :: + * The glyph name. + * + * @Return: + * The glyph index. 0~means `undefined character code'. + */ FT_EXPORT( FT_UInt ) FT_Get_Name_Index( FT_Face face, FT_String* glyph_name ); @@ -4102,59 +4260,59 @@ FT_BEGIN_HEADER FT_Glyph_Layer *alayers ); - /*************************************************************************/ - /* */ - /* <Enum> */ - /* 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. */ - /* */ - /* See */ - /* https://www.adobe.com/content/dam/Adobe/en/devnet/acrobat/pdfs/FontPolicies.pdf */ - /* for more details. */ - /* */ - /* <Values> */ - /* FT_FSTYPE_INSTALLABLE_EMBEDDING :: */ - /* Fonts with no fsType bit set may be embedded and permanently */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* <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. */ - /* */ + /************************************************************************** + * + * @Enum: + * 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. + * + * See + * https://www.adobe.com/content/dam/Adobe/en/devnet/acrobat/pdfs/FontPolicies.pdf + * for more details. + * + * @Values: + * FT_FSTYPE_INSTALLABLE_EMBEDDING :: + * Fonts with no fsType bit set may be embedded and permanently + * 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. + * + * 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. + * + * 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. + * + * 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. + * + * @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. + */ #define FT_FSTYPE_INSTALLABLE_EMBEDDING 0x0000 #define FT_FSTYPE_RESTRICTED_LICENSE_EMBEDDING 0x0002 #define FT_FSTYPE_PREVIEW_AND_PRINT_EMBEDDING 0x0004 @@ -4163,492 +4321,505 @@ FT_BEGIN_HEADER #define FT_FSTYPE_BITMAP_EMBEDDING_ONLY 0x0200 - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Get_FSType_Flags */ - /* */ - /* <Description> */ - /* Return the `fsType' flags for a font. */ - /* */ - /* <Input> */ - /* face :: A handle to the source face object. */ - /* */ - /* <Return> */ - /* 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. */ - /* */ - /* <Since> */ - /* 2.3.8 */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Get_FSType_Flags + * + * @Description: + * Return the `fsType' flags for a font. + * + * @Input: + * face :: + * A handle to the source face object. + * + * @Return: + * 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. + * + * @Since: + * 2.3.8 + */ FT_EXPORT( FT_UShort ) FT_Get_FSType_Flags( FT_Face face ); - /*************************************************************************/ - /* */ - /* <Section> */ - /* glyph_variants */ - /* */ - /* <Title> */ - /* Unicode Variation Sequences */ - /* */ - /* <Abstract> */ - /* 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). */ - /* */ - /* https://unicode.org/Public/UCD/latest/ucd/StandardizedVariants.txt */ - /* 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. */ - /* */ - /* 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'. */ - /* */ - /* 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. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * glyph_variants + * + * @Title: + * Unicode Variation Sequences + * + * @Abstract: + * 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). + * + * https://unicode.org/Public/UCD/latest/ucd/StandardizedVariants.txt + * 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. + * + * 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'. + * + * 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. + * + */ - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Face_GetCharVariantIndex */ - /* */ - /* <Description> */ - /* Return the glyph index of a given character code as modified by */ - /* the variation selector. */ - /* */ - /* <Input> */ - /* face :: */ - /* A handle to the source face object. */ - /* */ - /* charcode :: */ - /* The character code point in Unicode. */ - /* */ - /* variantSelector :: */ - /* 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'. */ - /* */ - /* <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'. */ - /* */ - /* This function is only meaningful if */ - /* a) the font has a variation selector cmap sub table, */ - /* and */ - /* b) the current charmap has a Unicode encoding. */ - /* */ - /* <Since> */ - /* 2.3.6 */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Face_GetCharVariantIndex + * + * @Description: + * Return the glyph index of a given character code as modified by + * the variation selector. + * + * @Input: + * face :: + * A handle to the source face object. + * + * charcode :: + * The character code point in Unicode. + * + * variantSelector :: + * 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'. + * + * @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'. + * + * This function is only meaningful if + * a) the font has a variation selector cmap sub table, + * and + * b) the current charmap has a Unicode encoding. + * + * @Since: + * 2.3.6 + */ FT_EXPORT( FT_UInt ) FT_Face_GetCharVariantIndex( FT_Face face, FT_ULong charcode, FT_ULong variantSelector ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Face_GetCharVariantIsDefault */ - /* */ - /* <Description> */ - /* Check whether this variation of this Unicode character is the one */ - /* to be found in the `cmap'. */ - /* */ - /* <Input> */ - /* face :: */ - /* A handle to the source face object. */ - /* */ - /* charcode :: */ - /* The character codepoint in Unicode. */ - /* */ - /* variantSelector :: */ - /* 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. */ - /* */ - /* <Note> */ - /* This function is only meaningful if the font has a variation */ - /* selector cmap subtable. */ - /* */ - /* <Since> */ - /* 2.3.6 */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Face_GetCharVariantIsDefault + * + * @Description: + * Check whether this variation of this Unicode character is the one + * to be found in the `cmap'. + * + * @Input: + * face :: + * A handle to the source face object. + * + * charcode :: + * The character codepoint in Unicode. + * + * variantSelector :: + * 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. + * + * @Note: + * This function is only meaningful if the font has a variation + * selector cmap subtable. + * + * @Since: + * 2.3.6 + */ FT_EXPORT( FT_Int ) FT_Face_GetCharVariantIsDefault( FT_Face face, FT_ULong charcode, FT_ULong variantSelector ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Face_GetVariantSelectors */ - /* */ - /* <Description> */ - /* 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. */ - /* */ - /* <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. */ - /* */ - /* <Since> */ - /* 2.3.6 */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Face_GetVariantSelectors + * + * @Description: + * 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. + * + * @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. + * + * @Since: + * 2.3.6 + */ FT_EXPORT( FT_UInt32* ) FT_Face_GetVariantSelectors( FT_Face face ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Face_GetVariantsOfChar */ - /* */ - /* <Description> */ - /* Return a zero-terminated list of Unicode variation selectors found */ - /* for the specified character code. */ - /* */ - /* <Input> */ - /* face :: */ - /* A handle to the source face object. */ - /* */ - /* charcode :: */ - /* The character codepoint in Unicode. */ - /* */ - /* <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. */ - /* */ - /* <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. */ - /* */ - /* <Since> */ - /* 2.3.6 */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Face_GetVariantsOfChar + * + * @Description: + * Return a zero-terminated list of Unicode variation selectors found + * for the specified character code. + * + * @Input: + * face :: + * A handle to the source face object. + * + * charcode :: + * The character codepoint in Unicode. + * + * @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. + * + * @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. + * + * @Since: + * 2.3.6 + */ FT_EXPORT( FT_UInt32* ) FT_Face_GetVariantsOfChar( FT_Face face, FT_ULong charcode ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Face_GetCharsOfVariant */ - /* */ - /* <Description> */ - /* Return a zero-terminated list of Unicode character codes found for */ - /* the specified variation selector. */ - /* */ - /* <Input> */ - /* face :: */ - /* A handle to the source face object. */ - /* */ - /* variantSelector :: */ - /* The variation selector code point in Unicode. */ - /* */ - /* <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. */ - /* */ - /* <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. */ - /* */ - /* <Since> */ - /* 2.3.6 */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Face_GetCharsOfVariant + * + * @Description: + * Return a zero-terminated list of Unicode character codes found for + * the specified variation selector. + * + * @Input: + * face :: + * A handle to the source face object. + * + * variantSelector :: + * The variation selector code point in Unicode. + * + * @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. + * + * @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. + * + * @Since: + * 2.3.6 + */ FT_EXPORT( FT_UInt32* ) FT_Face_GetCharsOfVariant( FT_Face face, FT_ULong variantSelector ); - /*************************************************************************/ - /* */ - /* <Section> */ - /* computations */ - /* */ - /* <Title> */ - /* Computations */ - /* */ - /* <Abstract> */ - /* Crunching fixed numbers and vectors. */ - /* */ - /* <Description> */ - /* This section contains various functions used to perform */ - /* computations on 16.16 fixed-float numbers or 2d vectors. */ - /* */ - /* <Order> */ - /* FT_MulDiv */ - /* FT_MulFix */ - /* FT_DivFix */ - /* FT_RoundFix */ - /* FT_CeilFix */ - /* FT_FloorFix */ - /* FT_Vector_Transform */ - /* FT_Matrix_Multiply */ - /* FT_Matrix_Invert */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * computations + * + * @Title: + * Computations + * + * @Abstract: + * Crunching fixed numbers and vectors. + * + * @Description: + * This section contains various functions used to perform + * computations on 16.16 fixed-float numbers or 2d vectors. + * + * @Order: + * FT_MulDiv + * FT_MulFix + * FT_DivFix + * FT_RoundFix + * FT_CeilFix + * FT_FloorFix + * FT_Vector_Transform + * FT_Matrix_Multiply + * FT_Matrix_Invert + * + */ - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_MulDiv */ - /* */ - /* <Description> */ - /* 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. */ - /* */ - /* <Input> */ - /* a :: The first multiplier. */ - /* */ - /* b :: The second multiplier. */ - /* */ - /* c :: 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'. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_MulDiv + * + * @Description: + * 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. + * + * @Input: + * a :: + * The first multiplier. + * + * b :: + * The second multiplier. + * + * c :: + * 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'. + */ FT_EXPORT( FT_Long ) FT_MulDiv( FT_Long a, FT_Long b, FT_Long c ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_MulFix */ - /* */ - /* <Description> */ - /* Compute `(a*b)/0x10000' with maximum accuracy. Its main use is to */ - /* multiply a given value by a 16.16 fixed-point factor. */ - /* */ - /* <Input> */ - /* a :: The first multiplier. */ - /* */ - /* b :: The second multiplier. Use a 16.16 factor here whenever */ - /* possible (see note below). */ - /* */ - /* <Return> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_MulFix + * + * @Description: + * Compute `(a*b)/0x10000' with maximum accuracy. Its main use is to + * multiply a given value by a 16.16 fixed-point factor. + * + * @Input: + * a :: + * The first multiplier. + * + * b :: + * The second multiplier. Use a 16.16 factor here whenever + * possible (see note below). + * + * @Return: + * 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. + */ FT_EXPORT( FT_Long ) FT_MulFix( FT_Long a, FT_Long b ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_DivFix */ - /* */ - /* <Description> */ - /* Compute `(a*0x10000)/b' with maximum accuracy. Its main use is to */ - /* divide a given value by a 16.16 fixed-point factor. */ - /* */ - /* <Input> */ - /* a :: The numerator. */ - /* */ - /* b :: The denominator. Use a 16.16 factor here. */ - /* */ - /* <Return> */ - /* The result of `(a*0x10000)/b'. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_DivFix + * + * @Description: + * Compute `(a*0x10000)/b' with maximum accuracy. Its main use is to + * divide a given value by a 16.16 fixed-point factor. + * + * @Input: + * a :: + * The numerator. + * + * b :: + * The denominator. Use a 16.16 factor here. + * + * @Return: + * The result of `(a*0x10000)/b'. + */ FT_EXPORT( FT_Long ) FT_DivFix( FT_Long a, FT_Long b ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_RoundFix */ - /* */ - /* <Description> */ - /* Round a 16.16 fixed number. */ - /* */ - /* <Input> */ - /* a :: The number to be rounded. */ - /* */ - /* <Return> */ - /* `a' rounded to the nearest 16.16 fixed integer, halfway cases away */ - /* from zero. */ - /* */ - /* <Note> */ - /* The function uses wrap-around arithmetic. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_RoundFix + * + * @Description: + * Round a 16.16 fixed number. + * + * @Input: + * a :: + * The number to be rounded. + * + * @Return: + * `a' rounded to the nearest 16.16 fixed integer, halfway cases away + * from zero. + * + * @Note: + * The function uses wrap-around arithmetic. + */ FT_EXPORT( FT_Fixed ) FT_RoundFix( FT_Fixed a ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_CeilFix */ - /* */ - /* <Description> */ - /* Compute the smallest following integer of a 16.16 fixed number. */ - /* */ - /* <Input> */ - /* a :: The number for which the ceiling function is to be computed. */ - /* */ - /* <Return> */ - /* `a' rounded towards plus infinity. */ - /* */ - /* <Note> */ - /* The function uses wrap-around arithmetic. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_CeilFix + * + * @Description: + * Compute the smallest following integer of a 16.16 fixed number. + * + * @Input: + * a :: + * The number for which the ceiling function is to be computed. + * + * @Return: + * `a' rounded towards plus infinity. + * + * @Note: + * The function uses wrap-around arithmetic. + */ FT_EXPORT( FT_Fixed ) FT_CeilFix( FT_Fixed a ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_FloorFix */ - /* */ - /* <Description> */ - /* Compute the largest previous integer of a 16.16 fixed number. */ - /* */ - /* <Input> */ - /* a :: The number for which the floor function is to be computed. */ - /* */ - /* <Return> */ - /* `a' rounded towards minus infinity. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_FloorFix + * + * @Description: + * Compute the largest previous integer of a 16.16 fixed number. + * + * @Input: + * a :: + * The number for which the floor function is to be computed. + * + * @Return: + * `a' rounded towards minus infinity. + */ FT_EXPORT( FT_Fixed ) FT_FloorFix( FT_Fixed a ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Vector_Transform */ - /* */ - /* <Description> */ - /* Transform a single vector through a 2x2 matrix. */ - /* */ - /* <InOut> */ - /* vector :: The target vector to transform. */ - /* */ - /* <Input> */ - /* matrix :: A pointer to the source 2x2 matrix. */ - /* */ - /* <Note> */ - /* The result is undefined if either `vector' or `matrix' is invalid. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Vector_Transform + * + * @Description: + * Transform a single vector through a 2x2 matrix. + * + * @InOut: + * vector :: + * The target vector to transform. + * + * @Input: + * matrix :: + * A pointer to the source 2x2 matrix. + * + * @Note: + * The result is undefined if either `vector' or `matrix' is invalid. + */ FT_EXPORT( void ) FT_Vector_Transform( FT_Vector* vec, const FT_Matrix* matrix ); - /*************************************************************************/ - /* */ - /* <Section> */ - /* version */ - /* */ - /* <Title> */ - /* FreeType Version */ - /* */ - /* <Abstract> */ - /* Functions and macros related to FreeType versions. */ - /* */ - /* <Description> */ - /* Note that those functions and macros are of limited use because */ - /* even a new release of FreeType with only documentation changes */ - /* increases the version number. */ - /* */ - /* <Order> */ - /* FT_Library_Version */ - /* */ - /* FREETYPE_MAJOR */ - /* FREETYPE_MINOR */ - /* FREETYPE_PATCH */ - /* */ - /* FT_Face_CheckTrueTypePatents */ - /* FT_Face_SetUnpatentedHinting */ - /* */ - /* FREETYPE_XXX */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * version + * + * @Title: + * FreeType Version + * + * @Abstract: + * Functions and macros related to FreeType versions. + * + * @Description: + * Note that those functions and macros are of limited use because + * even a new release of FreeType with only documentation changes + * increases the version number. + * + * @Order: + * FT_Library_Version + * + * FREETYPE_MAJOR + * FREETYPE_MINOR + * FREETYPE_PATCH + * + * FT_Face_CheckTrueTypePatents + * FT_Face_SetUnpatentedHinting + * + * FREETYPE_XXX + * + */ /************************************************************************* @@ -4661,9 +4832,12 @@ FT_BEGIN_HEADER * Use @FT_Library_Version to access them at runtime. * * @values: - * FREETYPE_MAJOR :: The major version number. - * FREETYPE_MINOR :: The minor version number. - * FREETYPE_PATCH :: The patch level. + * FREETYPE_MAJOR :: + * The major version number. + * FREETYPE_MINOR :: + * The minor version number. + * FREETYPE_PATCH :: + * The patch level. * * @note: * The version number of FreeType if built as a dynamic link library @@ -4676,35 +4850,39 @@ FT_BEGIN_HEADER #define FREETYPE_PATCH 1 - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Library_Version */ - /* */ - /* <Description> */ - /* Return the version of the FreeType library being used. This is */ - /* useful when dynamically linking to the library, since one cannot */ - /* use the macros @FREETYPE_MAJOR, @FREETYPE_MINOR, and */ - /* @FREETYPE_PATCH. */ - /* */ - /* <Input> */ - /* library :: A source library handle. */ - /* */ - /* <Output> */ - /* amajor :: The major version number. */ - /* */ - /* aminor :: The minor version number. */ - /* */ - /* apatch :: The patch version number. */ - /* */ - /* <Note> */ - /* The reason why this function takes a `library' argument is because */ - /* certain programs implement library initialization in a custom way */ - /* that doesn't use @FT_Init_FreeType. */ - /* */ - /* In such cases, the library version might not be available before */ - /* the library object has been created. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Library_Version + * + * @Description: + * Return the version of the FreeType library being used. This is + * useful when dynamically linking to the library, since one cannot + * use the macros @FREETYPE_MAJOR, @FREETYPE_MINOR, and + * @FREETYPE_PATCH. + * + * @Input: + * library :: + * A source library handle. + * + * @Output: + * amajor :: + * The major version number. + * + * aminor :: + * The minor version number. + * + * apatch :: + * The patch version number. + * + * @Note: + * The reason why this function takes a `library' argument is because + * certain programs implement library initialization in a custom way + * that doesn't use @FT_Init_FreeType. + * + * In such cases, the library version might not be available before + * the library object has been created. + */ FT_EXPORT( void ) FT_Library_Version( FT_Library library, FT_Int *amajor, @@ -4712,52 +4890,55 @@ FT_BEGIN_HEADER FT_Int *apatch ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Face_CheckTrueTypePatents */ - /* */ - /* <Description> */ - /* Deprecated, does nothing. */ - /* */ - /* <Input> */ - /* face :: A face handle. */ - /* */ - /* <Return> */ - /* Always returns false. */ - /* */ - /* <Note> */ - /* Since May 2010, TrueType hinting is no longer patented. */ - /* */ - /* <Since> */ - /* 2.3.5 */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Face_CheckTrueTypePatents + * + * @Description: + * Deprecated, does nothing. + * + * @Input: + * face :: + * A face handle. + * + * @Return: + * Always returns false. + * + * @Note: + * Since May 2010, TrueType hinting is no longer patented. + * + * @Since: + * 2.3.5 + */ FT_EXPORT( FT_Bool ) FT_Face_CheckTrueTypePatents( FT_Face face ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Face_SetUnpatentedHinting */ - /* */ - /* <Description> */ - /* Deprecated, does nothing. */ - /* */ - /* <Input> */ - /* face :: A face handle. */ - /* */ - /* value :: New boolean setting. */ - /* */ - /* <Return> */ - /* Always returns false. */ - /* */ - /* <Note> */ - /* Since May 2010, TrueType hinting is no longer patented. */ - /* */ - /* <Since> */ - /* 2.3.5 */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Face_SetUnpatentedHinting + * + * @Description: + * Deprecated, does nothing. + * + * @Input: + * face :: + * A face handle. + * + * value :: + * New boolean setting. + * + * @Return: + * Always returns false. + * + * @Note: + * Since May 2010, TrueType hinting is no longer patented. + * + * @Since: + * 2.3.5 + */ FT_EXPORT( FT_Bool ) FT_Face_SetUnpatentedHinting( FT_Face face, FT_Bool value ); diff --git a/include/freetype/ftadvanc.h b/include/freetype/ftadvanc.h index f78e8b1a9..61980065e 100644 --- a/include/freetype/ftadvanc.h +++ b/include/freetype/ftadvanc.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftadvanc.h */ -/* */ -/* Quick computation of advance widths (specification only). */ -/* */ -/* Copyright 2008-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftadvanc.h + * + * Quick computation of advance widths (specification only). + * + * Copyright 2008-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTADVANC_H_ @@ -56,68 +56,72 @@ FT_BEGIN_HEADER */ - /*************************************************************************/ - /* */ - /* <Const> */ - /* FT_ADVANCE_FLAG_FAST_ONLY */ - /* */ - /* <Description> */ - /* 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. */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Const: + * FT_ADVANCE_FLAG_FAST_ONLY + * + * @Description: + * 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. + * + * 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. + */ #define FT_ADVANCE_FLAG_FAST_ONLY 0x20000000L - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Get_Advance */ - /* */ - /* <Description> */ - /* Retrieve the advance value of a given glyph outline in an */ - /* @FT_Face. */ - /* */ - /* <Input> */ - /* face :: The source @FT_Face handle. */ - /* */ - /* gindex :: 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. */ - /* <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. */ - /* */ - /* 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. */ - /* */ - /* A scaled advance is returned in 16.16 format but isn't transformed */ - /* by the affine transformation specified by @FT_Set_Transform. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Get_Advance + * + * @Description: + * Retrieve the advance value of a given glyph outline in an + * @FT_Face. + * + * @Input: + * face :: + * The source @FT_Face handle. + * + * gindex :: + * 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. + * @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. + * + * 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. + * + * 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, FT_UInt gindex, @@ -125,50 +129,55 @@ FT_BEGIN_HEADER FT_Fixed *padvance ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Get_Advances */ - /* */ - /* <Description> */ - /* Retrieve the advance values of several glyph outlines in an */ - /* @FT_Face. */ - /* */ - /* <Input> */ - /* face :: The source @FT_Face handle. */ - /* */ - /* start :: The first glyph index. */ - /* */ - /* count :: 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. */ - /* */ - /* <Output> */ - /* padvance :: 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 @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. */ - /* */ - /* Scaled advances are returned in 16.16 format but aren't */ - /* transformed by the affine transformation specified by */ - /* @FT_Set_Transform. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Get_Advances + * + * @Description: + * Retrieve the advance values of several glyph outlines in an + * @FT_Face. + * + * @Input: + * face :: + * The source @FT_Face handle. + * + * start :: + * The first glyph index. + * + * count :: + * 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. + * + * @Output: + * padvance :: + * 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 @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. + * + * 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, FT_UInt start, diff --git a/include/freetype/ftbbox.h b/include/freetype/ftbbox.h index f9eb70b13..08095ea13 100644 --- a/include/freetype/ftbbox.h +++ b/include/freetype/ftbbox.h @@ -1,30 +1,30 @@ -/***************************************************************************/ -/* */ -/* ftbbox.h */ -/* */ -/* FreeType exact bbox computation (specification). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ - - - /*************************************************************************/ - /* */ - /* This component has a _single_ role: to compute exact outline bounding */ - /* boxes. */ - /* */ - /* It is separated from the rest of the engine for various technical */ - /* reasons. It may well be integrated in `ftoutln' later. */ - /* */ - /*************************************************************************/ +/**************************************************************************** + * + * ftbbox.h + * + * FreeType exact bbox computation (specification). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ + + + /************************************************************************** + * + * This component has a _single_ role: to compute exact outline bounding + * boxes. + * + * It is separated from the rest of the engine for various technical + * reasons. It may well be integrated in `ftoutln' later. + * + */ #ifndef FTBBOX_H_ @@ -44,43 +44,45 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* outline_processing */ - /* */ - /*************************************************************************/ - - - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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. */ - /* */ - /* <Input> */ - /* outline :: A pointer to the source outline. */ - /* */ - /* <Output> */ - /* abbox :: The outline's exact bounding box. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ - /* <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. */ - /* */ + /************************************************************************** + * + * @Section: + * outline_processing + * + */ + + + /************************************************************************** + * + * @Function: + * 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. + * + * @Input: + * outline :: + * A pointer to the source outline. + * + * @Output: + * abbox :: + * The outline's exact bounding box. + * + * @Return: + * FreeType error code. 0~means success. + * + * @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. + */ FT_EXPORT( FT_Error ) FT_Outline_Get_BBox( FT_Outline* outline, FT_BBox *abbox ); diff --git a/include/freetype/ftbdf.h b/include/freetype/ftbdf.h index 1b6dea658..f10b0c257 100644 --- a/include/freetype/ftbdf.h +++ b/include/freetype/ftbdf.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftbdf.h */ -/* */ -/* FreeType API for accessing BDF-specific strings (specification). */ -/* */ -/* Copyright 2002-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftbdf.h + * + * FreeType API for accessing BDF-specific strings (specification). + * + * Copyright 2002-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTBDF_H_ @@ -32,22 +32,22 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* bdf_fonts */ - /* */ - /* <Title> */ - /* BDF and PCF Files */ - /* */ - /* <Abstract> */ - /* BDF and PCF specific API. */ - /* */ - /* <Description> */ - /* This section contains the declaration of functions specific to BDF */ - /* and PCF fonts. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * bdf_fonts + * + * @Title: + * BDF and PCF Files + * + * @Abstract: + * BDF and PCF specific API. + * + * @Description: + * This section contains the declaration of functions specific to BDF + * and PCF fonts. + * + */ /********************************************************************** @@ -139,14 +139,14 @@ FT_BEGIN_HEADER * * @input: * face :: - * A handle to the input face. + * A handle to the input face. * * @output: * acharset_encoding :: - * Charset encoding, as a C~string, owned by the face. + * Charset encoding, as a C~string, owned by the face. * * acharset_registry :: - * Charset registry, as a C~string, owned by the face. + * Charset registry, as a C~string, owned by the face. * * @return: * FreeType error code. 0~means success. @@ -169,12 +169,15 @@ FT_BEGIN_HEADER * Retrieve a BDF property from a BDF or PCF font file. * * @input: - * face :: A handle to the input face. + * face :: + * A handle to the input face. * - * name :: The property name. + * name :: + * The property name. * * @output: - * aproperty :: The property. + * aproperty :: + * The property. * * @return: * FreeType error code. 0~means success. diff --git a/include/freetype/ftbitmap.h b/include/freetype/ftbitmap.h index cbdccc208..809e3bd11 100644 --- a/include/freetype/ftbitmap.h +++ b/include/freetype/ftbitmap.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftbitmap.h */ -/* */ -/* FreeType utility functions for bitmaps (specification). */ -/* */ -/* Copyright 2004-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftbitmap.h + * + * FreeType utility functions for bitmaps (specification). + * + * Copyright 2004-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTBITMAP_H_ @@ -33,39 +33,40 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* bitmap_handling */ - /* */ - /* <Title> */ - /* Bitmap Handling */ - /* */ - /* <Abstract> */ - /* Handling FT_Bitmap objects. */ - /* */ - /* <Description> */ - /* This section contains functions for handling @FT_Bitmap objects. */ - /* Note that none of the functions changes the bitmap's `flow' (as */ - /* indicated by the sign of the `pitch' field in `FT_Bitmap'). */ - /* */ - /*************************************************************************/ - - - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Bitmap_Init */ - /* */ - /* <Description> */ - /* Initialize a pointer to an @FT_Bitmap structure. */ - /* */ - /* <InOut> */ - /* abitmap :: A pointer to the bitmap structure. */ - /* */ - /* <Note> */ - /* A deprecated name for the same function is `FT_Bitmap_New'. */ - /* */ + /************************************************************************** + * + * @Section: + * bitmap_handling + * + * @Title: + * Bitmap Handling + * + * @Abstract: + * Handling FT_Bitmap objects. + * + * @Description: + * This section contains functions for handling @FT_Bitmap objects. + * Note that none of the functions changes the bitmap's `flow' (as + * indicated by the sign of the `pitch' field in `FT_Bitmap'). + * + */ + + + /************************************************************************** + * + * @Function: + * FT_Bitmap_Init + * + * @Description: + * Initialize a pointer to an @FT_Bitmap structure. + * + * @InOut: + * abitmap :: + * A pointer to the bitmap structure. + * + * @Note: + * A deprecated name for the same function is `FT_Bitmap_New'. + */ FT_EXPORT( void ) FT_Bitmap_Init( FT_Bitmap *abitmap ); @@ -75,66 +76,73 @@ FT_BEGIN_HEADER FT_Bitmap_New( FT_Bitmap *abitmap ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Bitmap_Copy */ - /* */ - /* <Description> */ - /* Copy a bitmap into another one. */ - /* */ - /* <Input> */ - /* library :: A handle to a library object. */ - /* */ - /* source :: A handle to the source bitmap. */ - /* */ - /* <Output> */ - /* target :: A handle to the target bitmap. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Bitmap_Copy + * + * @Description: + * Copy a bitmap into another one. + * + * @Input: + * library :: + * A handle to a library object. + * + * source :: + * A handle to the source bitmap. + * + * @Output: + * target :: + * A handle to the target bitmap. + * + * @Return: + * FreeType error code. 0~means success. + */ FT_EXPORT( FT_Error ) FT_Bitmap_Copy( FT_Library library, const FT_Bitmap *source, FT_Bitmap *target ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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. */ - /* */ - /* <Input> */ - /* library :: A handle to a library object. */ - /* */ - /* xStrength :: 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. */ - /* */ - /* <InOut> */ - /* bitmap :: A handle to the target bitmap. */ - /* */ - /* <Return> */ - /* 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. */ - /* */ - /* 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). */ - /* */ + /************************************************************************** + * + * @Function: + * 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. + * + * @Input: + * library :: + * A handle to a library object. + * + * xStrength :: + * 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. + * + * @InOut: + * bitmap :: + * A handle to the target bitmap. + * + * @Return: + * 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. + * + * 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). + */ FT_EXPORT( FT_Error ) FT_Bitmap_Embolden( FT_Library library, FT_Bitmap* bitmap, @@ -142,39 +150,43 @@ FT_BEGIN_HEADER FT_Pos yStrength ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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'. */ - /* */ - /* <Input> */ - /* library :: A handle to a library object. */ - /* */ - /* source :: The source bitmap. */ - /* */ - /* alignment :: The pitch of the bitmap is a multiple of this */ - /* argument. Common values are 1, 2, or 4. */ - /* */ - /* <Output> */ - /* target :: The target bitmap. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ - /* <Note> */ - /* It is possible to call @FT_Bitmap_Convert multiple times without */ - /* calling @FT_Bitmap_Done (the memory is simply reallocated). */ - /* */ - /* Use @FT_Bitmap_Done to finally remove the bitmap object. */ - /* */ - /* The `library' argument is taken to have access to FreeType's */ - /* memory handling functions. */ - /* */ + /************************************************************************** + * + * @Function: + * 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'. + * + * @Input: + * library :: + * A handle to a library object. + * + * source :: + * The source bitmap. + * + * alignment :: + * The pitch of the bitmap is a multiple of this + * argument. Common values are 1, 2, or 4. + * + * @Output: + * target :: + * The target bitmap. + * + * @Return: + * FreeType error code. 0~means success. + * + * @Note: + * It is possible to call @FT_Bitmap_Convert multiple times without + * calling @FT_Bitmap_Done (the memory is simply reallocated). + * + * Use @FT_Bitmap_Done to finally remove the bitmap object. + * + * The `library' argument is taken to have access to FreeType's + * memory handling functions. + */ FT_EXPORT( FT_Error ) FT_Bitmap_Convert( FT_Library library, const FT_Bitmap *source, @@ -182,48 +194,51 @@ FT_BEGIN_HEADER FT_Int alignment ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_GlyphSlot_Own_Bitmap */ - /* */ - /* <Description> */ - /* Make sure that a glyph slot owns `slot->bitmap'. */ - /* */ - /* <Input> */ - /* slot :: The glyph slot. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ - /* <Note> */ - /* This function is to be used in combination with */ - /* @FT_Bitmap_Embolden. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_GlyphSlot_Own_Bitmap + * + * @Description: + * Make sure that a glyph slot owns `slot->bitmap'. + * + * @Input: + * slot :: + * The glyph slot. + * + * @Return: + * FreeType error code. 0~means success. + * + * @Note: + * This function is to be used in combination with + * @FT_Bitmap_Embolden. + */ FT_EXPORT( FT_Error ) FT_GlyphSlot_Own_Bitmap( FT_GlyphSlot slot ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Bitmap_Done */ - /* */ - /* <Description> */ - /* Destroy a bitmap object initialized with @FT_Bitmap_Init. */ - /* */ - /* <Input> */ - /* library :: A handle to a library object. */ - /* */ - /* bitmap :: The bitmap object to be freed. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ - /* <Note> */ - /* The `library' argument is taken to have access to FreeType's */ - /* memory handling functions. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Bitmap_Done + * + * @Description: + * Destroy a bitmap object initialized with @FT_Bitmap_Init. + * + * @Input: + * library :: + * A handle to a library object. + * + * bitmap :: + * The bitmap object to be freed. + * + * @Return: + * FreeType error code. 0~means success. + * + * @Note: + * The `library' argument is taken to have access to FreeType's + * memory handling functions. + */ FT_EXPORT( FT_Error ) FT_Bitmap_Done( FT_Library library, FT_Bitmap *bitmap ); diff --git a/include/freetype/ftbzip2.h b/include/freetype/ftbzip2.h index 6edfa031b..7450f1437 100644 --- a/include/freetype/ftbzip2.h +++ b/include/freetype/ftbzip2.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftbzip2.h */ -/* */ -/* Bzip2-compressed stream support. */ -/* */ -/* Copyright 2010-2018 by */ -/* Joel Klinghed. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftbzip2.h + * + * Bzip2-compressed stream support. + * + * Copyright 2010-2018 by + * Joel Klinghed. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTBZIP2_H_ @@ -31,21 +31,21 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* bzip2 */ - /* */ - /* <Title> */ - /* BZIP2 Streams */ - /* */ - /* <Abstract> */ - /* Using bzip2-compressed font files. */ - /* */ - /* <Description> */ - /* This section contains the declaration of Bzip2-specific functions. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * bzip2 + * + * @Title: + * BZIP2 Streams + * + * @Abstract: + * Using bzip2-compressed font files. + * + * @Description: + * This section contains the declaration of Bzip2-specific functions. + * + */ /************************************************************************ diff --git a/include/freetype/ftcache.h b/include/freetype/ftcache.h index 52d5f00e0..08d33165c 100644 --- a/include/freetype/ftcache.h +++ b/include/freetype/ftcache.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftcache.h */ -/* */ -/* FreeType Cache subsystem (specification). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftcache.h + * + * FreeType Cache subsystem (specification). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTCACHE_H_ @@ -29,16 +29,16 @@ FT_BEGIN_HEADER /************************************************************************* * - * <Section> + * @Section: * cache_subsystem * - * <Title> + * @Title: * Cache Sub-System * - * <Abstract> + * @Abstract: * How to cache face, size, and glyph data with FreeType~2. * - * <Description> + * @Description: * This section describes the FreeType~2 cache sub-system, which is used * to limit the number of concurrently opened @FT_Face and @FT_Size * objects, as well as caching information like character maps and glyph @@ -100,7 +100,7 @@ FT_BEGIN_HEADER * We hope to also provide a kerning cache in the near future. * * - * <Order> + * @Order: * FTC_Manager * FTC_FaceID * FTC_Face_Requester @@ -181,7 +181,7 @@ FT_BEGIN_HEADER * the cache manager to translate a given @FTC_FaceID into a new valid * @FT_Face object, on demand. * - * <Input> + * @Input: * face_id :: * The face ID to resolve. * @@ -191,14 +191,14 @@ FT_BEGIN_HEADER * req_data :: * Application-provided request data (see note below). * - * <Output> + * @Output: * aface :: * A new @FT_Face handle. * - * <Return> + * @Return: * FreeType error code. 0~means success. * - * <Note> + * @Note: * The third parameter `req_data' is the same as the one passed by the * client when @FTC_Manager_New is called. * @@ -226,84 +226,91 @@ FT_BEGIN_HEADER /*************************************************************************/ - /*************************************************************************/ - /* */ - /* <Type> */ - /* 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. */ - /* */ - /* The manager intentionally limits the total number of opened */ - /* @FT_Face and @FT_Size objects to control memory usage. See the */ - /* `max_faces' and `max_sizes' parameters of @FTC_Manager_New. */ - /* */ - /* The manager is also used to cache `nodes' of various types while */ - /* limiting their total memory usage. */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Type: + * 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. + * + * The manager intentionally limits the total number of opened + * @FT_Face and @FT_Size objects to control memory usage. See the + * `max_faces' and `max_sizes' parameters of @FTC_Manager_New. + * + * The manager is also used to cache `nodes' of various types while + * limiting their total memory usage. + * + * 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; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FTC_Node */ - /* */ - /* <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. */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Type: + * FTC_Node + * + * @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. + * + * 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. + */ typedef struct FTC_NodeRec_* FTC_Node; - /*************************************************************************/ - /* */ - /* <Function> */ - /* FTC_Manager_New */ - /* */ - /* <Description> */ - /* Create a new cache manager. */ - /* */ - /* <Input> */ - /* library :: 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. */ - /* */ - /* max_sizes :: 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. */ - /* */ - /* requester :: An application-provided callback used to translate */ - /* face IDs into real @FT_Face objects. */ - /* */ - /* req_data :: A generic pointer that is passed to the requester */ - /* each time it is called (see @FTC_Face_Requester). */ - /* */ - /* <Output> */ - /* amanager :: A handle to a new manager object. 0~in case of */ - /* failure. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ + /************************************************************************** + * + * @Function: + * FTC_Manager_New + * + * @Description: + * Create a new cache manager. + * + * @Input: + * library :: + * 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. + * + * max_sizes :: + * 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. + * + * requester :: + * An application-provided callback used to translate + * face IDs into real @FT_Face objects. + * + * req_data :: + * A generic pointer that is passed to the requester + * each time it is called (see @FTC_Face_Requester). + * + * @Output: + * amanager :: + * A handle to a new manager object. 0~in case of + * failure. + * + * @Return: + * FreeType error code. 0~means success. + */ FT_EXPORT( FT_Error ) FTC_Manager_New( FT_Library library, FT_UInt max_faces, @@ -314,114 +321,125 @@ FT_BEGIN_HEADER FTC_Manager *amanager ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FTC_Manager_Reset */ - /* */ - /* <Description> */ - /* Empty a given cache manager. This simply gets rid of all the */ - /* currently cached @FT_Face and @FT_Size objects within the manager. */ - /* */ - /* <InOut> */ - /* manager :: A handle to the manager. */ - /* */ + /************************************************************************** + * + * @Function: + * FTC_Manager_Reset + * + * @Description: + * Empty a given cache manager. This simply gets rid of all the + * currently cached @FT_Face and @FT_Size objects within the manager. + * + * @InOut: + * manager :: + * A handle to the manager. + */ FT_EXPORT( void ) FTC_Manager_Reset( FTC_Manager manager ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FTC_Manager_Done */ - /* */ - /* <Description> */ - /* Destroy a given manager after emptying it. */ - /* */ - /* <Input> */ - /* manager :: A handle to the target cache manager object. */ - /* */ + /************************************************************************** + * + * @Function: + * FTC_Manager_Done + * + * @Description: + * Destroy a given manager after emptying it. + * + * @Input: + * manager :: + * A handle to the target cache manager object. + */ FT_EXPORT( void ) FTC_Manager_Done( FTC_Manager manager ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FTC_Manager_LookupFace */ - /* */ - /* <Description> */ - /* Retrieve the @FT_Face object that corresponds to a given face ID */ - /* through a cache manager. */ - /* */ - /* <Input> */ - /* manager :: A handle to the cache manager. */ - /* */ - /* face_id :: The ID of the face object. */ - /* */ - /* <Output> */ - /* aface :: A handle to the face object. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ - /* <Note> */ - /* The returned @FT_Face object is always owned by the manager. You */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Function: + * FTC_Manager_LookupFace + * + * @Description: + * Retrieve the @FT_Face object that corresponds to a given face ID + * through a cache manager. + * + * @Input: + * manager :: + * A handle to the cache manager. + * + * face_id :: + * The ID of the face object. + * + * @Output: + * aface :: + * A handle to the face object. + * + * @Return: + * FreeType error code. 0~means success. + * + * @Note: + * The returned @FT_Face object is always owned by the manager. You + * 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. + * + * 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. + * + * 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, FTC_FaceID face_id, FT_Face *aface ); - /*************************************************************************/ - /* */ - /* <Struct> */ - /* 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. */ - /* */ - /* <Fields> */ - /* face_id :: The source face ID. */ - /* */ - /* width :: The character width. */ - /* */ - /* height :: 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. */ - /* */ - /* x_res :: 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. */ - /* */ - /* <Note> */ - /* This type is mainly used to retrieve @FT_Size objects through the */ - /* cache manager. */ - /* */ + /************************************************************************** + * + * @Struct: + * 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. + * + * @Fields: + * face_id :: + * The source face ID. + * + * width :: + * The character width. + * + * height :: + * 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. + * + * x_res :: + * 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. + * + * @Note: + * This type is mainly used to retrieve @FT_Size objects through the + * cache manager. + */ typedef struct FTC_ScalerRec_ { FTC_FaceID face_id; @@ -434,75 +452,80 @@ FT_BEGIN_HEADER } FTC_ScalerRec; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FTC_Scaler */ - /* */ - /* <Description> */ - /* A handle to an @FTC_ScalerRec structure. */ - /* */ + /************************************************************************** + * + * @Struct: + * FTC_Scaler + * + * @Description: + * A handle to an @FTC_ScalerRec structure. + */ typedef struct FTC_ScalerRec_* FTC_Scaler; - /*************************************************************************/ - /* */ - /* <Function> */ - /* FTC_Manager_LookupSize */ - /* */ - /* <Description> */ - /* Retrieve the @FT_Size object that corresponds to a given */ - /* @FTC_ScalerRec pointer through a cache manager. */ - /* */ - /* <Input> */ - /* manager :: A handle to the cache manager. */ - /* */ - /* scaler :: A scaler handle. */ - /* */ - /* <Output> */ - /* asize :: A handle to the size object. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ - /* <Note> */ - /* 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. */ - /* */ - /* <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. */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Function: + * FTC_Manager_LookupSize + * + * @Description: + * Retrieve the @FT_Size object that corresponds to a given + * @FTC_ScalerRec pointer through a cache manager. + * + * @Input: + * manager :: + * A handle to the cache manager. + * + * scaler :: + * A scaler handle. + * + * @Output: + * asize :: + * A handle to the size object. + * + * @Return: + * FreeType error code. 0~means success. + * + * @Note: + * 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. + * + * @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. + * + * 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, FTC_Scaler scaler, FT_Size *asize ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FTC_Node_Unref */ - /* */ - /* <Description> */ - /* Decrement a cache node's internal reference count. When the count */ - /* reaches 0, it is not destroyed but becomes eligible for subsequent */ - /* cache flushes. */ - /* */ - /* <Input> */ - /* node :: The cache node handle. */ - /* */ - /* manager :: The cache manager handle. */ - /* */ + /************************************************************************** + * + * @Function: + * FTC_Node_Unref + * + * @Description: + * Decrement a cache node's internal reference count. When the count + * reaches 0, it is not destroyed but becomes eligible for subsequent + * cache flushes. + * + * @Input: + * node :: + * The cache node handle. + * + * manager :: + * The cache manager handle. + */ FT_EXPORT( void ) FTC_Node_Unref( FTC_Node node, FTC_Manager manager ); @@ -680,83 +703,90 @@ FT_BEGIN_HEADER (d1)->flags == (d2)->flags ) - /*************************************************************************/ - /* */ - /* <Type> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Type: + * 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. + */ typedef struct FTC_ImageCacheRec_* FTC_ImageCache; - /*************************************************************************/ - /* */ - /* <Function> */ - /* FTC_ImageCache_New */ - /* */ - /* <Description> */ - /* Create a new glyph image cache. */ - /* */ - /* <Input> */ - /* manager :: The parent manager for the image cache. */ - /* */ - /* <Output> */ - /* acache :: A handle to the new glyph image cache object. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ + /************************************************************************** + * + * @Function: + * FTC_ImageCache_New + * + * @Description: + * Create a new glyph image cache. + * + * @Input: + * manager :: + * The parent manager for the image cache. + * + * @Output: + * acache :: + * A handle to the new glyph image cache object. + * + * @Return: + * FreeType error code. 0~means success. + */ FT_EXPORT( FT_Error ) FTC_ImageCache_New( FTC_Manager manager, FTC_ImageCache *acache ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FTC_ImageCache_Lookup */ - /* */ - /* <Description> */ - /* Retrieve a given glyph image from a glyph image cache. */ - /* */ - /* <Input> */ - /* cache :: A handle to the source glyph image cache. */ - /* */ - /* type :: A pointer to a glyph image type descriptor. */ - /* */ - /* gindex :: The glyph index to retrieve. */ - /* */ - /* <Output> */ - /* aglyph :: 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). */ - /* */ - /* <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! */ - /* */ + /************************************************************************** + * + * @Function: + * FTC_ImageCache_Lookup + * + * @Description: + * Retrieve a given glyph image from a glyph image cache. + * + * @Input: + * cache :: + * A handle to the source glyph image cache. + * + * type :: + * A pointer to a glyph image type descriptor. + * + * gindex :: + * The glyph index to retrieve. + * + * @Output: + * aglyph :: + * 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). + * + * @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! + */ FT_EXPORT( FT_Error ) FTC_ImageCache_Lookup( FTC_ImageCache cache, FTC_ImageType type, @@ -765,54 +795,60 @@ FT_BEGIN_HEADER FTC_Node *anode ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FTC_ImageCache_LookupScaler */ - /* */ - /* <Description> */ - /* A variant of @FTC_ImageCache_Lookup that uses an @FTC_ScalerRec */ - /* to specify the face ID and its size. */ - /* */ - /* <Input> */ - /* cache :: A handle to the source glyph image cache. */ - /* */ - /* scaler :: A pointer to a scaler descriptor. */ - /* */ - /* load_flags :: The corresponding load flags. */ - /* */ - /* gindex :: The glyph index to retrieve. */ - /* */ - /* <Output> */ - /* aglyph :: 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). */ - /* */ - /* <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! */ - /* */ - /* Calls to @FT_Set_Char_Size and friends have no effect on cached */ - /* glyphs; you should always use the FreeType cache API instead. */ - /* */ + /************************************************************************** + * + * @Function: + * FTC_ImageCache_LookupScaler + * + * @Description: + * A variant of @FTC_ImageCache_Lookup that uses an @FTC_ScalerRec + * to specify the face ID and its size. + * + * @Input: + * cache :: + * A handle to the source glyph image cache. + * + * scaler :: + * A pointer to a scaler descriptor. + * + * load_flags :: + * The corresponding load flags. + * + * gindex :: + * The glyph index to retrieve. + * + * @Output: + * aglyph :: + * 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). + * + * @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! + * + * Calls to @FT_Set_Char_Size and friends have no effect on cached + * glyphs; you should always use the FreeType cache API instead. + */ FT_EXPORT( FT_Error ) FTC_ImageCache_LookupScaler( FTC_ImageCache cache, FTC_Scaler scaler, @@ -822,53 +858,63 @@ FT_BEGIN_HEADER FTC_Node *anode ); - /*************************************************************************/ - /* */ - /* <Type> */ - /* FTC_SBit */ - /* */ - /* <Description> */ - /* A handle to a small bitmap descriptor. See the @FTC_SBitRec */ - /* structure for details. */ - /* */ + /************************************************************************** + * + * @Type: + * FTC_SBit + * + * @Description: + * A handle to a small bitmap descriptor. See the @FTC_SBitRec + * structure for details. + */ typedef struct FTC_SBitRec_* FTC_SBit; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FTC_SBitRec */ - /* */ - /* <Description> */ - /* A very compact structure used to describe a small glyph bitmap. */ - /* */ - /* <Fields> */ - /* width :: The bitmap width in pixels. */ - /* */ - /* height :: 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'). */ - /* */ - /* 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. */ - /* */ - /* format :: The format of the glyph bitmap (monochrome or gray). */ - /* */ - /* max_grays :: Maximum gray level value (in the range 1 to~255). */ - /* */ - /* pitch :: The number of bytes per bitmap line. May be positive */ - /* or negative. */ - /* */ - /* xadvance :: The horizontal advance width in pixels. */ - /* */ - /* yadvance :: The vertical advance height in pixels. */ - /* */ - /* buffer :: A pointer to the bitmap pixels. */ - /* */ + /************************************************************************** + * + * @Struct: + * FTC_SBitRec + * + * @Description: + * A very compact structure used to describe a small glyph bitmap. + * + * @Fields: + * width :: + * The bitmap width in pixels. + * + * height :: + * 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'). + * + * 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. + * + * format :: + * The format of the glyph bitmap (monochrome or gray). + * + * max_grays :: + * Maximum gray level value (in the range 1 to~255). + * + * pitch :: + * The number of bytes per bitmap line. May be positive + * or negative. + * + * xadvance :: + * The horizontal advance width in pixels. + * + * yadvance :: + * The vertical advance height in pixels. + * + * buffer :: + * A pointer to the bitmap pixels. + */ typedef struct FTC_SBitRec_ { FT_Byte width; @@ -887,87 +933,94 @@ FT_BEGIN_HEADER } FTC_SBitRec; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FTC_SBitCache */ - /* */ - /* <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. */ - /* */ + /************************************************************************** + * + * @Type: + * FTC_SBitCache + * + * @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. + */ typedef struct FTC_SBitCacheRec_* FTC_SBitCache; - /*************************************************************************/ - /* */ - /* <Function> */ - /* FTC_SBitCache_New */ - /* */ - /* <Description> */ - /* Create a new cache to store small glyph bitmaps. */ - /* */ - /* <Input> */ - /* manager :: A handle to the source cache manager. */ - /* */ - /* <Output> */ - /* acache :: A handle to the new sbit cache. NULL in case of error. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ + /************************************************************************** + * + * @Function: + * FTC_SBitCache_New + * + * @Description: + * Create a new cache to store small glyph bitmaps. + * + * @Input: + * manager :: + * A handle to the source cache manager. + * + * @Output: + * acache :: + * A handle to the new sbit cache. NULL in case of error. + * + * @Return: + * FreeType error code. 0~means success. + */ FT_EXPORT( FT_Error ) FTC_SBitCache_New( FTC_Manager manager, FTC_SBitCache *acache ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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. */ - /* */ - /* <Input> */ - /* cache :: A handle to the source sbit cache. */ - /* */ - /* type :: A pointer to the glyph image type descriptor. */ - /* */ - /* gindex :: The glyph index. */ - /* */ - /* <Output> */ - /* sbit :: 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). */ - /* */ - /* <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 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 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! */ - /* */ + /************************************************************************** + * + * @Function: + * 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. + * + * @Input: + * cache :: + * A handle to the source sbit cache. + * + * type :: + * A pointer to the glyph image type descriptor. + * + * gindex :: + * The glyph index. + * + * @Output: + * sbit :: + * 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). + * + * @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 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 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, FTC_ImageType type, @@ -976,53 +1029,59 @@ FT_BEGIN_HEADER FTC_Node *anode ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FTC_SBitCache_LookupScaler */ - /* */ - /* <Description> */ - /* A variant of @FTC_SBitCache_Lookup that uses an @FTC_ScalerRec */ - /* to specify the face ID and its size. */ - /* */ - /* <Input> */ - /* cache :: A handle to the source sbit cache. */ - /* */ - /* scaler :: A pointer to the scaler descriptor. */ - /* */ - /* load_flags :: The corresponding load flags. */ - /* */ - /* gindex :: The glyph index. */ - /* */ - /* <Output> */ - /* sbit :: 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). */ - /* */ - /* <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 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 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! */ - /* */ + /************************************************************************** + * + * @Function: + * FTC_SBitCache_LookupScaler + * + * @Description: + * A variant of @FTC_SBitCache_Lookup that uses an @FTC_ScalerRec + * to specify the face ID and its size. + * + * @Input: + * cache :: + * A handle to the source sbit cache. + * + * scaler :: + * A pointer to the scaler descriptor. + * + * load_flags :: + * The corresponding load flags. + * + * gindex :: + * The glyph index. + * + * @Output: + * sbit :: + * 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). + * + * @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 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 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, FTC_Scaler scaler, diff --git a/include/freetype/ftchapters.h b/include/freetype/ftchapters.h index 51257bb7c..0bb822912 100644 --- a/include/freetype/ftchapters.h +++ b/include/freetype/ftchapters.h @@ -1,139 +1,139 @@ -/***************************************************************************/ -/* */ -/* This file defines the structure of the FreeType reference. */ -/* It is used by the python script that generates the HTML files. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * This file defines the structure of the FreeType reference. + * It is used by the python script that generates the HTML files. + * + */ -/***************************************************************************/ -/* */ -/* <Chapter> */ -/* general_remarks */ -/* */ -/* <Title> */ -/* General Remarks */ -/* */ -/* <Sections> */ -/* header_inclusion */ -/* user_allocation */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * @Chapter: + * general_remarks + * + * @Title: + * General Remarks + * + * @Sections: + * header_inclusion + * user_allocation + * + */ -/***************************************************************************/ -/* */ -/* <Chapter> */ -/* core_api */ -/* */ -/* <Title> */ -/* Core API */ -/* */ -/* <Sections> */ -/* version */ -/* basic_types */ -/* base_interface */ -/* glyph_variants */ -/* glyph_management */ -/* mac_specific */ -/* sizes_management */ -/* header_file_macros */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * @Chapter: + * core_api + * + * @Title: + * Core API + * + * @Sections: + * version + * basic_types + * base_interface + * glyph_variants + * glyph_management + * mac_specific + * sizes_management + * header_file_macros + * + */ -/***************************************************************************/ -/* */ -/* <Chapter> */ -/* format_specific */ -/* */ -/* <Title> */ -/* Format-Specific API */ -/* */ -/* <Sections> */ -/* multiple_masters */ -/* truetype_tables */ -/* type1_tables */ -/* sfnt_names */ -/* bdf_fonts */ -/* cid_fonts */ -/* pfr_fonts */ -/* winfnt_fonts */ -/* font_formats */ -/* gasp_table */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * @Chapter: + * format_specific + * + * @Title: + * Format-Specific API + * + * @Sections: + * multiple_masters + * truetype_tables + * type1_tables + * sfnt_names + * bdf_fonts + * cid_fonts + * pfr_fonts + * winfnt_fonts + * font_formats + * gasp_table + * + */ -/***************************************************************************/ -/* */ -/* <Chapter> */ -/* module_specific */ -/* */ -/* <Title> */ -/* Controlling FreeType Modules */ -/* */ -/* <Sections> */ -/* auto_hinter */ -/* cff_driver */ -/* t1_cid_driver */ -/* tt_driver */ -/* pcf_driver */ -/* properties */ -/* parameter_tags */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * @Chapter: + * module_specific + * + * @Title: + * Controlling FreeType Modules + * + * @Sections: + * auto_hinter + * cff_driver + * t1_cid_driver + * tt_driver + * pcf_driver + * properties + * parameter_tags + * + */ -/***************************************************************************/ -/* */ -/* <Chapter> */ -/* cache_subsystem */ -/* */ -/* <Title> */ -/* Cache Sub-System */ -/* */ -/* <Sections> */ -/* cache_subsystem */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * @Chapter: + * cache_subsystem + * + * @Title: + * Cache Sub-System + * + * @Sections: + * cache_subsystem + * + */ -/***************************************************************************/ -/* */ -/* <Chapter> */ -/* support_api */ -/* */ -/* <Title> */ -/* Support API */ -/* */ -/* <Sections> */ -/* computations */ -/* list_processing */ -/* outline_processing */ -/* quick_advance */ -/* bitmap_handling */ -/* raster */ -/* glyph_stroker */ -/* system_interface */ -/* module_management */ -/* gzip */ -/* lzw */ -/* bzip2 */ -/* lcd_filtering */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * @Chapter: + * support_api + * + * @Title: + * Support API + * + * @Sections: + * computations + * list_processing + * outline_processing + * quick_advance + * bitmap_handling + * raster + * glyph_stroker + * system_interface + * module_management + * gzip + * lzw + * bzip2 + * lcd_filtering + * + */ -/***************************************************************************/ -/* */ -/* <Chapter> */ -/* error_codes */ -/* */ -/* <Title> */ -/* Error Codes */ -/* */ -/* <Sections> */ -/* error_enumerations */ -/* error_code_values */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * @Chapter: + * error_codes + * + * @Title: + * Error Codes + * + * @Sections: + * error_enumerations + * error_code_values + * + */ diff --git a/include/freetype/ftcid.h b/include/freetype/ftcid.h index 5e9100a67..209577351 100644 --- a/include/freetype/ftcid.h +++ b/include/freetype/ftcid.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftcid.h */ -/* */ -/* FreeType API for accessing CID font information (specification). */ -/* */ -/* Copyright 2007-2018 by */ -/* Dereg Clegg and Michael Toftdal. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftcid.h + * + * FreeType API for accessing CID font information (specification). + * + * Copyright 2007-2018 by + * Dereg Clegg and Michael Toftdal. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTCID_H_ @@ -32,22 +32,22 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* cid_fonts */ - /* */ - /* <Title> */ - /* CID Fonts */ - /* */ - /* <Abstract> */ - /* CID-keyed font specific API. */ - /* */ - /* <Description> */ - /* This section contains the declaration of CID-keyed font specific */ - /* functions. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * cid_fonts + * + * @Title: + * CID Fonts + * + * @Abstract: + * CID-keyed font specific API. + * + * @Description: + * This section contains the declaration of CID-keyed font specific + * functions. + * + */ /********************************************************************** @@ -61,17 +61,17 @@ FT_BEGIN_HEADER * * @input: * face :: - * A handle to the input face. + * A handle to the input face. * * @output: * registry :: - * The registry, as a C~string, owned by the face. + * The registry, as a C~string, owned by the face. * * ordering :: - * The ordering, as a C~string, owned by the face. + * The ordering, as a C~string, owned by the face. * * supplement :: - * The supplement. + * The supplement. * * @return: * FreeType error code. 0~means success. @@ -102,11 +102,11 @@ FT_BEGIN_HEADER * * @input: * face :: - * A handle to the input face. + * A handle to the input face. * * @output: * is_cid :: - * The type of the face as an @FT_Bool. + * The type of the face as an @FT_Bool. * * @return: * FreeType error code. 0~means success. @@ -133,14 +133,14 @@ FT_BEGIN_HEADER * * @input: * face :: - * A handle to the input face. + * A handle to the input face. * * glyph_index :: - * The input glyph index. + * The input glyph index. * * @output: * cid :: - * The CID as an @FT_UInt. + * The CID as an @FT_UInt. * * @return: * FreeType error code. 0~means success. diff --git a/include/freetype/ftcolor.h b/include/freetype/ftcolor.h index 3065fdebd..4c326c394 100644 --- a/include/freetype/ftcolor.h +++ b/include/freetype/ftcolor.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftcolor.h */ -/* */ -/* FreeType's glyph color management (specification). */ -/* */ -/* Copyright 2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftcolor.h + * + * FreeType's glyph color management (specification). + * + * Copyright 2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTCOLOR_H_ diff --git a/include/freetype/ftdriver.h b/include/freetype/ftdriver.h index e90475b2a..510f0c03e 100644 --- a/include/freetype/ftdriver.h +++ b/include/freetype/ftdriver.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftdriver.h */ -/* */ -/* FreeType API for controlling driver modules (specification only). */ -/* */ -/* Copyright 2017-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftdriver.h + * + * FreeType API for controlling driver modules (specification only). + * + * Copyright 2017-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTDRIVER_H_ @@ -428,7 +428,7 @@ FT_BEGIN_HEADER * 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. + * 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 diff --git a/include/freetype/fterrdef.h b/include/freetype/fterrdef.h index 8ffd346ca..1179fa9a7 100644 --- a/include/freetype/fterrdef.h +++ b/include/freetype/fterrdef.h @@ -1,58 +1,58 @@ -/***************************************************************************/ -/* */ -/* fterrdef.h */ -/* */ -/* FreeType error codes (specification). */ -/* */ -/* Copyright 2002-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * fterrdef.h + * + * FreeType error codes (specification). + * + * Copyright 2002-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ - /*************************************************************************/ - /* */ - /* <Section> */ - /* error_code_values */ - /* */ - /* <Title> */ - /* Error Code Values */ - /* */ - /* <Abstract> */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * error_code_values + * + * @Title: + * Error Code Values + * + * @Abstract: + * 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. + * + * 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. + * + */ - /*************************************************************************/ - /* */ - /* <Enum> */ - /* FT_Err_XXX */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Enum: + * FT_Err_XXX + * + */ /* generic errors */ diff --git a/include/freetype/fterrors.h b/include/freetype/fterrors.h index f6ee5c24e..e9bcf4d31 100644 --- a/include/freetype/fterrors.h +++ b/include/freetype/fterrors.h @@ -1,101 +1,101 @@ -/***************************************************************************/ -/* */ -/* fterrors.h */ -/* */ -/* FreeType error code handling (specification). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ - - - /*************************************************************************/ - /* */ - /* <Section> */ - /* error_enumerations */ - /* */ - /* <Title> */ - /* Error Enumerations */ - /* */ - /* <Abstract> */ - /* 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. */ - /* */ - /* *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. */ - /* */ - /* *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). */ - /* */ - /* 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. */ - /* */ - /* { */ - /* 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. */ - /* */ - /* { */ - /* FT_ERROR_END_LIST */ - /* } */ - /* */ - /* This macro ends the list. */ - /* */ - /* 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 { */ - /* #define FT_ERROR_END_LIST { 0, NULL } }; */ - /* */ - /* const struct */ - /* { */ - /* int err_code; */ - /* const char* err_msg; */ - /* } 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. */ - /* */ - /*************************************************************************/ +/**************************************************************************** + * + * fterrors.h + * + * FreeType error code handling (specification). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ + + + /************************************************************************** + * + * @Section: + * error_enumerations + * + * @Title: + * Error Enumerations + * + * @Abstract: + * 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. + * + * *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. + * + * *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). + * + * 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. + * + * { + * 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. + * + * { + * FT_ERROR_END_LIST + * } + * + * This macro ends the list. + * + * 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 { + * #define FT_ERROR_END_LIST { 0, NULL } }; + * + * const struct + * { + * int err_code; + * const char* err_msg; + * } 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. + * + */ /* */ diff --git a/include/freetype/ftfntfmt.h b/include/freetype/ftfntfmt.h index cc86efac2..c073e3708 100644 --- a/include/freetype/ftfntfmt.h +++ b/include/freetype/ftfntfmt.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftfntfmt.h */ -/* */ -/* Support functions for font formats. */ -/* */ -/* Copyright 2002-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftfntfmt.h + * + * Support functions for font formats. + * + * Copyright 2002-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTFNTFMT_H_ @@ -32,49 +32,49 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* font_formats */ - /* */ - /* <Title> */ - /* Font Formats */ - /* */ - /* <Abstract> */ - /* 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. */ - /* */ - /*************************************************************************/ - - - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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'. */ - /* */ - /* The return value is suitable to be used as an X11 FONT_PROPERTY. */ - /* */ - /* <Input> */ - /* face :: */ - /* Input face handle. */ - /* */ - /* <Return> */ - /* Font format string. NULL in case of error. */ - /* */ - /* <Note> */ - /* A deprecated name for the same function is */ - /* `FT_Get_X11_Font_Format'. */ - /* */ + /************************************************************************** + * + * @Section: + * font_formats + * + * @Title: + * Font Formats + * + * @Abstract: + * 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. + * + */ + + + /************************************************************************** + * + * @Function: + * 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'. + * + * The return value is suitable to be used as an X11 FONT_PROPERTY. + * + * @Input: + * face :: + * Input face handle. + * + * @Return: + * Font format string. NULL in case of error. + * + * @Note: + * 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 fc1248ff4..4e512beb8 100644 --- a/include/freetype/ftgasp.h +++ b/include/freetype/ftgasp.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftgasp.h */ -/* */ -/* Access of TrueType's `gasp' table (specification). */ -/* */ -/* Copyright 2007-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftgasp.h + * + * Access of TrueType's `gasp' table (specification). + * + * Copyright 2007-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTGASP_H_ @@ -110,9 +110,11 @@ FT_BEGIN_HEADER * character pixel size. * * @input: - * face :: The source face handle. + * face :: + * The source face handle. * - * ppem :: The vertical character pixel size. + * ppem :: + * The vertical character pixel size. * * @return: * Bit flags (see @FT_GASP_XXX), or @FT_GASP_NO_TABLE if there is no diff --git a/include/freetype/ftglyph.h b/include/freetype/ftglyph.h index 08cf585a0..626a0d598 100644 --- a/include/freetype/ftglyph.h +++ b/include/freetype/ftglyph.h @@ -1,32 +1,32 @@ -/***************************************************************************/ -/* */ -/* ftglyph.h */ -/* */ -/* FreeType convenience functions to handle glyphs (specification). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ - - - /*************************************************************************/ - /* */ - /* 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. */ - /* */ - /*************************************************************************/ +/**************************************************************************** + * + * ftglyph.h + * + * FreeType convenience functions to handle glyphs (specification). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ + + + /************************************************************************** + * + * 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. + * + */ #ifndef FTGLYPH_H_ @@ -46,65 +46,69 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* glyph_management */ - /* */ - /* <Title> */ - /* Glyph Management */ - /* */ - /* <Abstract> */ - /* 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. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * glyph_management + * + * @Title: + * Glyph Management + * + * @Abstract: + * 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. + * + */ /* forward declaration to a private type */ typedef struct FT_Glyph_Class_ FT_Glyph_Class; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_Glyph */ - /* */ - /* <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. */ - /* */ - /* <Note> */ - /* Glyph objects are not owned by the library. You must thus release */ - /* them manually (through @FT_Done_Glyph) _before_ calling */ - /* @FT_Done_FreeType. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_Glyph + * + * @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. + * + * @Note: + * Glyph objects are not owned by the library. You must thus release + * them manually (through @FT_Done_Glyph) _before_ calling + * @FT_Done_FreeType. + */ typedef struct FT_GlyphRec_* FT_Glyph; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_GlyphRec */ - /* */ - /* <Description> */ - /* The root glyph structure contains a given glyph image plus its */ - /* advance width in 16.16 fixed-point format. */ - /* */ - /* <Fields> */ - /* library :: A handle to the FreeType library object. */ - /* */ - /* clazz :: A pointer to the glyph's class. Private. */ - /* */ - /* format :: The format of the glyph's image. */ - /* */ - /* advance :: A 16.16 vector that gives the glyph's advance width. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_GlyphRec + * + * @Description: + * The root glyph structure contains a given glyph image plus its + * advance width in 16.16 fixed-point format. + * + * @Fields: + * library :: + * A handle to the FreeType library object. + * + * clazz :: + * A pointer to the glyph's class. Private. + * + * format :: + * The format of the glyph's image. + * + * advance :: + * A 16.16 vector that gives the glyph's advance width. + */ typedef struct FT_GlyphRec_ { FT_Library library; @@ -115,48 +119,52 @@ FT_BEGIN_HEADER } FT_GlyphRec; - /*************************************************************************/ - /* */ - /* <Type> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Type: + * 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. + */ typedef struct FT_BitmapGlyphRec_* FT_BitmapGlyph; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_BitmapGlyphRec */ - /* */ - /* <Description> */ - /* A structure used for bitmap glyph images. This really is a */ - /* `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. */ - /* */ - /* 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! */ - /* */ - /* 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. */ - /* */ - /* The corresponding pixel buffer is always owned by @FT_BitmapGlyph */ - /* and is thus created and destroyed with it. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_BitmapGlyphRec + * + * @Description: + * A structure used for bitmap glyph images. This really is a + * `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. + * + * 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! + * + * 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. + * + * The corresponding pixel buffer is always owned by @FT_BitmapGlyph + * and is thus created and destroyed with it. + */ typedef struct FT_BitmapGlyphRec_ { FT_GlyphRec root; @@ -167,44 +175,46 @@ FT_BEGIN_HEADER } FT_BitmapGlyphRec; - /*************************************************************************/ - /* */ - /* <Type> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Type: + * 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. + */ typedef struct FT_OutlineGlyphRec_* FT_OutlineGlyph; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_OutlineGlyphRec */ - /* */ - /* <Description> */ - /* A structure used for outline (vectorial) glyph images. This */ - /* really is a `sub-class' of @FT_GlyphRec. */ - /* */ - /* <Fields> */ - /* root :: The root @FT_Glyph fields. */ - /* */ - /* outline :: A descriptor for the outline. */ - /* */ - /* <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. */ - /* */ - /* 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(). */ - /* */ - /* The outline's tables are always owned by the object and are */ - /* destroyed with it. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_OutlineGlyphRec + * + * @Description: + * A structure used for outline (vectorial) glyph images. This + * really is a `sub-class' of @FT_GlyphRec. + * + * @Fields: + * root :: + * The root @FT_Glyph fields. + * + * outline :: + * A descriptor for the outline. + * + * @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. + * + * 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(). + * + * The outline's tables are always owned by the object and are + * destroyed with it. + */ typedef struct FT_OutlineGlyphRec_ { FT_GlyphRec root; @@ -213,113 +223,120 @@ FT_BEGIN_HEADER } FT_OutlineGlyphRec; - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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. */ - /* */ - /* <Input> */ - /* slot :: A handle to the source glyph slot. */ - /* */ - /* <Output> */ - /* aglyph :: A handle to the glyph object. */ - /* */ - /* <Return> */ - /* 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[. */ - /* */ + /************************************************************************** + * + * @Function: + * 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. + * + * @Input: + * slot :: + * A handle to the source glyph slot. + * + * @Output: + * aglyph :: + * A handle to the glyph object. + * + * @Return: + * 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[. + */ FT_EXPORT( FT_Error ) FT_Get_Glyph( FT_GlyphSlot slot, FT_Glyph *aglyph ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Glyph_Copy */ - /* */ - /* <Description> */ - /* A function used to copy a glyph image. Note that the created */ - /* @FT_Glyph object must be released with @FT_Done_Glyph. */ - /* */ - /* <Input> */ - /* source :: A handle to the source glyph object. */ - /* */ - /* <Output> */ - /* target :: A handle to the target glyph object. 0~in case of */ - /* error. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Glyph_Copy + * + * @Description: + * A function used to copy a glyph image. Note that the created + * @FT_Glyph object must be released with @FT_Done_Glyph. + * + * @Input: + * source :: + * A handle to the source glyph object. + * + * @Output: + * target :: + * A handle to the target glyph object. 0~in case of + * error. + * + * @Return: + * FreeType error code. 0~means success. + */ FT_EXPORT( FT_Error ) FT_Glyph_Copy( FT_Glyph source, FT_Glyph *target ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Glyph_Transform */ - /* */ - /* <Description> */ - /* Transform a glyph image if its format is scalable. */ - /* */ - /* <InOut> */ - /* glyph :: A handle to the target glyph object. */ - /* */ - /* <Input> */ - /* matrix :: 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. */ - /* */ - /* <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. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Glyph_Transform + * + * @Description: + * Transform a glyph image if its format is scalable. + * + * @InOut: + * glyph :: + * A handle to the target glyph object. + * + * @Input: + * matrix :: + * 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. + * + * @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. + */ FT_EXPORT( FT_Error ) FT_Glyph_Transform( FT_Glyph glyph, FT_Matrix* matrix, FT_Vector* delta ); - /*************************************************************************/ - /* */ - /* <Enum> */ - /* FT_Glyph_BBox_Mode */ - /* */ - /* <Description> */ - /* The mode how the values of @FT_Glyph_Get_CBox are returned. */ - /* */ - /* <Values> */ - /* FT_GLYPH_BBOX_UNSCALED :: */ - /* Return unscaled font units. */ - /* */ - /* FT_GLYPH_BBOX_SUBPIXELS :: */ - /* Return unfitted 26.6 coordinates. */ - /* */ - /* FT_GLYPH_BBOX_GRIDFIT :: */ - /* Return grid-fitted 26.6 coordinates. */ - /* */ - /* FT_GLYPH_BBOX_TRUNCATE :: */ - /* Return coordinates in integer pixels. */ - /* */ - /* FT_GLYPH_BBOX_PIXELS :: */ - /* Return grid-fitted pixel coordinates. */ - /* */ + /************************************************************************** + * + * @Enum: + * FT_Glyph_BBox_Mode + * + * @Description: + * The mode how the values of @FT_Glyph_Get_CBox are returned. + * + * @Values: + * FT_GLYPH_BBOX_UNSCALED :: + * Return unscaled font units. + * + * FT_GLYPH_BBOX_SUBPIXELS :: + * Return unfitted 26.6 coordinates. + * + * FT_GLYPH_BBOX_GRIDFIT :: + * Return grid-fitted 26.6 coordinates. + * + * FT_GLYPH_BBOX_TRUNCATE :: + * Return coordinates in integer pixels. + * + * FT_GLYPH_BBOX_PIXELS :: + * Return grid-fitted pixel coordinates. + */ typedef enum FT_Glyph_BBox_Mode_ { FT_GLYPH_BBOX_UNSCALED = 0, @@ -340,187 +357,194 @@ FT_BEGIN_HEADER #define ft_glyph_bbox_pixels FT_GLYPH_BBOX_PIXELS - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Glyph_Get_CBox */ - /* */ - /* <Description> */ - /* 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). */ - /* */ - /* 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. */ - /* */ - /* <Output> */ - /* acbox :: 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 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. */ - /* */ - /* 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 */ - /* @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 */ - /* @FT_GLYPH_BBOX_TRUNCATE. */ - /* */ - /* To get the bbox in grid-fitted pixel coordinates, set `bbox_mode' */ - /* to @FT_GLYPH_BBOX_PIXELS. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Glyph_Get_CBox + * + * @Description: + * 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). + * + * 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. + * + * @Output: + * acbox :: + * 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 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. + * + * 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 + * @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 + * @FT_GLYPH_BBOX_TRUNCATE. + * + * 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, FT_UInt bbox_mode, FT_BBox *acbox ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Glyph_To_Bitmap */ - /* */ - /* <Description> */ - /* Convert a given glyph object to a bitmap glyph object. */ - /* */ - /* <InOut> */ - /* the_glyph :: A pointer to a handle to the target glyph. */ - /* */ - /* <Input> */ - /* render_mode :: 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. */ - /* */ - /* destroy :: 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. */ - /* */ - /* <Note> */ - /* This function does nothing if the glyph format isn't scalable. */ - /* */ - /* 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): */ - /* */ - /* */ - /* { */ - /* FT_Glyph glyph; */ - /* FT_BitmapGlyph glyph_bitmap; */ - /* */ - /* */ - /* // load glyph */ - /* error = FT_Load_Char( face, glyph_index, FT_LOAD_DEFAULT ); */ - /* */ - /* // extract glyph image */ - /* error = FT_Get_Glyph( face->glyph, &glyph ); */ - /* */ - /* // convert to a bitmap (default render mode + destroying old) */ - /* if ( glyph->format != FT_GLYPH_FORMAT_BITMAP ) */ - /* { */ - /* error = FT_Glyph_To_Bitmap( &glyph, FT_RENDER_MODE_NORMAL, */ - /* 0, 1 ); */ - /* if ( error ) // `glyph' unchanged */ - /* ... */ - /* } */ - /* */ - /* // access bitmap content by typecasting */ - /* glyph_bitmap = (FT_BitmapGlyph)glyph; */ - /* */ - /* // do funny stuff with it, like blitting/drawing */ - /* ... */ - /* */ - /* // discard glyph image (bitmap or not) */ - /* FT_Done_Glyph( glyph ); */ - /* } */ - /* */ - /* */ - /* Here another example, again without error handling: */ - /* */ - /* */ - /* { */ - /* FT_Glyph glyphs[MAX_GLYPHS] */ - /* */ - /* */ - /* ... */ - /* */ - /* for ( idx = 0; i < MAX_GLYPHS; i++ ) */ - /* error = FT_Load_Glyph( face, idx, FT_LOAD_DEFAULT ) || */ - /* FT_Get_Glyph ( face->glyph, &glyphs[idx] ); */ - /* */ - /* ... */ - /* */ - /* for ( idx = 0; i < MAX_GLYPHS; i++ ) */ - /* { */ - /* FT_Glyph bitmap = glyphs[idx]; */ - /* */ - /* */ - /* ... */ - /* */ - /* // after this call, `bitmap' no longer points into */ - /* // the `glyphs' array (and the old value isn't destroyed) */ - /* FT_Glyph_To_Bitmap( &bitmap, FT_RENDER_MODE_MONO, 0, 0 ); */ - /* */ - /* ... */ - /* */ - /* FT_Done_Glyph( bitmap ); */ - /* } */ - /* */ - /* ... */ - /* */ - /* for ( idx = 0; i < MAX_GLYPHS; i++ ) */ - /* FT_Done_Glyph( glyphs[idx] ); */ - /* } */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Glyph_To_Bitmap + * + * @Description: + * Convert a given glyph object to a bitmap glyph object. + * + * @InOut: + * the_glyph :: + * A pointer to a handle to the target glyph. + * + * @Input: + * render_mode :: + * 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. + * + * destroy :: + * 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. + * + * @Note: + * This function does nothing if the glyph format isn't scalable. + * + * 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): + * + * + * { + * FT_Glyph glyph; + * FT_BitmapGlyph glyph_bitmap; + * + * + * // load glyph + * error = FT_Load_Char( face, glyph_index, FT_LOAD_DEFAULT ); + * + * // extract glyph image + * error = FT_Get_Glyph( face->glyph, &glyph ); + * + * // convert to a bitmap (default render mode + destroying old) + * if ( glyph->format != FT_GLYPH_FORMAT_BITMAP ) + * { + * error = FT_Glyph_To_Bitmap( &glyph, FT_RENDER_MODE_NORMAL, + * 0, 1 ); + * if ( error ) // `glyph' unchanged + * ... + * } + * + * // access bitmap content by typecasting + * glyph_bitmap = (FT_BitmapGlyph)glyph; + * + * // do funny stuff with it, like blitting/drawing + * ... + * + * // discard glyph image (bitmap or not) + * FT_Done_Glyph( glyph ); + * } + * + * + * Here another example, again without error handling: + * + * + * { + * FT_Glyph glyphs[MAX_GLYPHS] + * + * + * ... + * + * for ( idx = 0; i < MAX_GLYPHS; i++ ) + * error = FT_Load_Glyph( face, idx, FT_LOAD_DEFAULT ) || + * FT_Get_Glyph ( face->glyph, &glyphs[idx] ); + * + * ... + * + * for ( idx = 0; i < MAX_GLYPHS; i++ ) + * { + * FT_Glyph bitmap = glyphs[idx]; + * + * + * ... + * + * // after this call, `bitmap' no longer points into + * // the `glyphs' array (and the old value isn't destroyed) + * FT_Glyph_To_Bitmap( &bitmap, FT_RENDER_MODE_MONO, 0, 0 ); + * + * ... + * + * FT_Done_Glyph( bitmap ); + * } + * + * ... + * + * for ( idx = 0; i < MAX_GLYPHS; i++ ) + * FT_Done_Glyph( glyphs[idx] ); + * } + */ FT_EXPORT( FT_Error ) FT_Glyph_To_Bitmap( FT_Glyph* the_glyph, FT_Render_Mode render_mode, @@ -528,17 +552,18 @@ FT_BEGIN_HEADER FT_Bool destroy ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Done_Glyph */ - /* */ - /* <Description> */ - /* Destroy a given glyph. */ - /* */ - /* <Input> */ - /* glyph :: A handle to the target glyph object. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Done_Glyph + * + * @Description: + * Destroy a given glyph. + * + * @Input: + * glyph :: + * A handle to the target glyph object. + */ FT_EXPORT( void ) FT_Done_Glyph( FT_Glyph glyph ); @@ -547,54 +572,57 @@ FT_BEGIN_HEADER /* other helpful functions */ - /*************************************************************************/ - /* */ - /* <Section> */ - /* computations */ - /* */ - /*************************************************************************/ - - - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Matrix_Multiply */ - /* */ - /* <Description> */ - /* Perform the matrix operation `b = a*b'. */ - /* */ - /* <Input> */ - /* a :: A pointer to matrix `a'. */ - /* */ - /* <InOut> */ - /* b :: A pointer to matrix `b'. */ - /* */ - /* <Note> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Section: + * computations + * + */ + + + /************************************************************************** + * + * @Function: + * FT_Matrix_Multiply + * + * @Description: + * Perform the matrix operation `b = a*b'. + * + * @Input: + * a :: + * A pointer to matrix `a'. + * + * @InOut: + * b :: + * A pointer to matrix `b'. + * + * @Note: + * 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. + */ FT_EXPORT( void ) FT_Matrix_Multiply( const FT_Matrix* a, FT_Matrix* b ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Matrix_Invert */ - /* */ - /* <Description> */ - /* Invert a 2x2 matrix. Return an error if it can't be inverted. */ - /* */ - /* <InOut> */ - /* matrix :: A pointer to the target matrix. Remains untouched in */ - /* case of error. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Matrix_Invert + * + * @Description: + * Invert a 2x2 matrix. Return an error if it can't be inverted. + * + * @InOut: + * matrix :: + * A pointer to the target matrix. Remains untouched in + * case of error. + * + * @Return: + * FreeType error code. 0~means success. + */ FT_EXPORT( FT_Error ) FT_Matrix_Invert( FT_Matrix* matrix ); diff --git a/include/freetype/ftgxval.h b/include/freetype/ftgxval.h index 8382d5995..6cec81d08 100644 --- a/include/freetype/ftgxval.h +++ b/include/freetype/ftgxval.h @@ -1,28 +1,28 @@ -/***************************************************************************/ -/* */ -/* ftgxval.h */ -/* */ -/* FreeType API for validating TrueTypeGX/AAT tables (specification). */ -/* */ -/* Copyright 2004-2018 by */ -/* Masatake YAMATO, Redhat K.K, */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ - -/***************************************************************************/ -/* */ -/* gxvalid is derived from both gxlayout module and otvalid module. */ -/* Development of gxlayout is supported by the Information-technology */ -/* Promotion Agency(IPA), Japan. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftgxval.h + * + * FreeType API for validating TrueTypeGX/AAT tables (specification). + * + * Copyright 2004-2018 by + * Masatake YAMATO, Redhat K.K, + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ + +/**************************************************************************** + * + * gxvalid is derived from both gxlayout module and otvalid module. + * Development of gxlayout is supported by the Information-technology + * Promotion Agency(IPA), Japan. + * + */ #ifndef FTGXVAL_H_ @@ -41,43 +41,43 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* gx_validation */ - /* */ - /* <Title> */ - /* TrueTypeGX/AAT Validation */ - /* */ - /* <Abstract> */ - /* 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). */ - /* */ - /* <Order> */ - /* FT_TrueTypeGX_Validate */ - /* FT_TrueTypeGX_Free */ - /* */ - /* FT_ClassicKern_Validate */ - /* FT_ClassicKern_Free */ - /* */ - /* FT_VALIDATE_GX_LENGTH */ - /* FT_VALIDATE_GXXXX */ - /* FT_VALIDATE_CKERNXXX */ - /* */ - /*************************************************************************/ - - /*************************************************************************/ - /* */ - /* */ - /* Warning: Use FT_VALIDATE_XXX to validate a table. */ - /* Following definitions are for gxvalid developers. */ - /* */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * gx_validation + * + * @Title: + * TrueTypeGX/AAT Validation + * + * @Abstract: + * 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). + * + * @Order: + * FT_TrueTypeGX_Validate + * FT_TrueTypeGX_Free + * + * FT_ClassicKern_Validate + * FT_ClassicKern_Free + * + * FT_VALIDATE_GX_LENGTH + * FT_VALIDATE_GXXXX + * FT_VALIDATE_CKERNXXX + * + */ + + /************************************************************************** + * + * + * Warning: Use FT_VALIDATE_XXX to validate a table. + * Following definitions are for gxvalid developers. + * + * + */ #define FT_VALIDATE_feat_INDEX 0 #define FT_VALIDATE_mort_INDEX 1 @@ -194,20 +194,20 @@ FT_BEGIN_HEADER * * @input: * face :: - * A handle to the input face. + * A handle to the input face. * * validation_flags :: - * A bit field that specifies the tables to be validated. See - * @FT_VALIDATE_GXXXX for possible values. + * A bit field that specifies the tables to be validated. See + * @FT_VALIDATE_GXXXX for possible values. * * table_length :: - * The size of the `tables' array. Normally, @FT_VALIDATE_GX_LENGTH - * should be passed. + * 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. @@ -239,11 +239,11 @@ FT_BEGIN_HEADER * * @input: * face :: - * A handle to the input face. + * 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 @@ -298,15 +298,15 @@ FT_BEGIN_HEADER * * @input: * face :: - * A handle to the input face. + * A handle to the input face. * * validation_flags :: - * A bit field that specifies the dialect to be validated. See - * @FT_VALIDATE_CKERNXXX for possible values. + * A bit field that specifies the dialect to be validated. See + * @FT_VALIDATE_CKERNXXX for possible values. * * @output: * ckern_table :: - * A pointer to the kern table. + * A pointer to the kern table. * * @return: * FreeType error code. 0~means success. @@ -332,11 +332,11 @@ FT_BEGIN_HEADER * * @input: * face :: - * A handle to the input face. + * A handle to the input face. * * table :: - * The pointer to the buffer that is allocated by - * @FT_ClassicKern_Validate. + * The pointer to the buffer that is allocated by + * @FT_ClassicKern_Validate. * * @note: * This function must be used to free the buffer allocated by diff --git a/include/freetype/ftgzip.h b/include/freetype/ftgzip.h index db033da0e..f0f6d87d3 100644 --- a/include/freetype/ftgzip.h +++ b/include/freetype/ftgzip.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftgzip.h */ -/* */ -/* Gzip-compressed stream support. */ -/* */ -/* Copyright 2002-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftgzip.h + * + * Gzip-compressed stream support. + * + * Copyright 2002-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTGZIP_H_ @@ -31,21 +31,21 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* gzip */ - /* */ - /* <Title> */ - /* GZIP Streams */ - /* */ - /* <Abstract> */ - /* Using gzip-compressed font files. */ - /* */ - /* <Description> */ - /* This section contains the declaration of Gzip-specific functions. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * gzip + * + * @Title: + * GZIP Streams + * + * @Abstract: + * Using gzip-compressed font files. + * + * @Description: + * This section contains the declaration of Gzip-specific functions. + * + */ /************************************************************************ @@ -112,7 +112,7 @@ FT_BEGIN_HEADER * The length of the input buffer. * * @output: - * output:: + * output :: * The output buffer. * * @inout: diff --git a/include/freetype/ftimage.h b/include/freetype/ftimage.h index 79ede1959..dad6ca9f8 100644 --- a/include/freetype/ftimage.h +++ b/include/freetype/ftimage.h @@ -1,27 +1,27 @@ -/***************************************************************************/ -/* */ -/* ftimage.h */ -/* */ -/* FreeType glyph image formats and default raster interface */ -/* (specification). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ - - /*************************************************************************/ - /* */ - /* Note: A `raster' is simply a scan-line converter, used to render */ - /* FT_Outlines into FT_Bitmaps. */ - /* */ - /*************************************************************************/ +/**************************************************************************** + * + * ftimage.h + * + * FreeType glyph image formats and default raster interface + * (specification). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ + + /************************************************************************** + * + * Note: A `raster' is simply a scan-line converter, used to render + * FT_Outlines into FT_Bitmaps. + * + */ #ifndef FTIMAGE_H_ @@ -37,40 +37,42 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* basic_types */ - /* */ - /*************************************************************************/ - - - /*************************************************************************/ - /* */ - /* <Type> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Section: + * basic_types + * + */ + + + /************************************************************************** + * + * @Type: + * 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. + */ typedef signed long FT_Pos; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_Vector */ - /* */ - /* <Description> */ - /* A simple structure used to store a 2D vector; coordinates are of */ - /* the FT_Pos type. */ - /* */ - /* <Fields> */ - /* x :: The horizontal coordinate. */ - /* y :: The vertical coordinate. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_Vector + * + * @Description: + * A simple structure used to store a 2D vector; coordinates are of + * the FT_Pos type. + * + * @Fields: + * x :: + * The horizontal coordinate. + * y :: + * The vertical coordinate. + */ typedef struct FT_Vector_ { FT_Pos x; @@ -79,39 +81,43 @@ FT_BEGIN_HEADER } FT_Vector; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_BBox */ - /* */ - /* <Description> */ - /* A structure used to hold an outline's bounding box, i.e., the */ - /* coordinates of its extrema in the horizontal and vertical */ - /* directions. */ - /* */ - /* <Fields> */ - /* xMin :: The horizontal minimum (left-most). */ - /* */ - /* yMin :: The vertical minimum (bottom-most). */ - /* */ - /* xMax :: The horizontal maximum (right-most). */ - /* */ - /* yMax :: 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. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_BBox + * + * @Description: + * A structure used to hold an outline's bounding box, i.e., the + * coordinates of its extrema in the horizontal and vertical + * directions. + * + * @Fields: + * xMin :: + * The horizontal minimum (left-most). + * + * yMin :: + * The vertical minimum (bottom-most). + * + * xMax :: + * The horizontal maximum (right-most). + * + * yMax :: + * 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. + */ typedef struct FT_BBox_ { FT_Pos xMin, yMin; @@ -120,63 +126,63 @@ FT_BEGIN_HEADER } FT_BBox; - /*************************************************************************/ - /* */ - /* <Enum> */ - /* 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. */ - /* */ - /* <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. */ - /* */ - /* 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). */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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 */ - /* @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. */ - /* */ + /************************************************************************** + * + * @Enum: + * 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. + * + * @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. + * + * 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). + * + * 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. + * + * 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. + * + * 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. + * + * 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 + * @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. + */ typedef enum FT_Pixel_Mode_ { FT_PIXEL_MODE_NONE = 0, @@ -202,62 +208,70 @@ FT_BEGIN_HEADER #define ft_pixel_mode_pal4 FT_PIXEL_MODE_GRAY4 - /*************************************************************************/ - /* */ - /* <Struct> */ - /* 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. */ - /* */ - /* <Fields> */ - /* rows :: The number of bitmap rows. */ - /* */ - /* width :: 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. */ - /* */ - /* buffer :: 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. */ - /* */ - /* pixel_mode :: 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. */ - /* */ - /* palette :: A typeless pointer to the bitmap palette; this */ - /* field is intended for paletted pixel modes. Not */ - /* used currently. */ - /* */ + /************************************************************************** + * + * @Struct: + * 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. + * + * @Fields: + * rows :: + * The number of bitmap rows. + * + * width :: + * 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. + * + * buffer :: + * 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. + * + * pixel_mode :: + * 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. + * + * palette :: + * A typeless pointer to the bitmap palette; this + * field is intended for paletted pixel modes. Not + * used currently. + */ typedef struct FT_Bitmap_ { unsigned int rows; @@ -272,65 +286,71 @@ FT_BEGIN_HEADER } FT_Bitmap; - /*************************************************************************/ - /* */ - /* <Section> */ - /* outline_processing */ - /* */ - /*************************************************************************/ - - - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_Outline */ - /* */ - /* <Description> */ - /* This structure is used to describe an outline to the scan-line */ - /* converter. */ - /* */ - /* <Fields> */ - /* n_contours :: The number of contours in the outline. */ - /* */ - /* n_points :: 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. */ - /* */ - /* tags :: 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. */ - /* */ - /* 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). */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* <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 */ - /* @FT_OUTLINE_IGNORE_DROPOUTS, @FT_OUTLINE_SMART_DROPOUTS, and */ - /* @FT_OUTLINE_INCLUDE_STUBS in `flags' is then overridden. */ - /* */ + /************************************************************************** + * + * @Section: + * outline_processing + * + */ + + + /************************************************************************** + * + * @Struct: + * FT_Outline + * + * @Description: + * This structure is used to describe an outline to the scan-line + * converter. + * + * @Fields: + * n_contours :: + * The number of contours in the outline. + * + * n_points :: + * 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. + * + * tags :: + * 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. + * + * 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). + * + * 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. + * + * 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. + * + * @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 + * @FT_OUTLINE_IGNORE_DROPOUTS, @FT_OUTLINE_SMART_DROPOUTS, and + * @FT_OUTLINE_INCLUDE_STUBS in `flags' is then overridden. + */ typedef struct FT_Outline_ { short n_contours; /* number of contours in glyph */ @@ -352,78 +372,78 @@ FT_BEGIN_HEADER #define FT_OUTLINE_POINTS_MAX SHRT_MAX - /*************************************************************************/ - /* */ - /* <Enum> */ - /* FT_OUTLINE_XXX */ - /* */ - /* <Description> */ - /* A list of bit-field constants use for the flags in an outline's */ - /* `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. */ - /* */ - /* 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). */ - /* */ - /* FT_OUTLINE_REVERSE_FILL :: */ - /* By default, outside contours of an outline are oriented in */ - /* clock-wise direction, as defined in the TrueType specification. */ - /* This flag is set if the outline uses the opposite direction */ - /* (typically for Type~1 fonts). This flag is ignored by the scan */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* <Note> */ - /* 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. */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Enum: + * FT_OUTLINE_XXX + * + * @Description: + * A list of bit-field constants use for the flags in an outline's + * `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. + * + * 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). + * + * FT_OUTLINE_REVERSE_FILL :: + * By default, outside contours of an outline are oriented in + * clock-wise direction, as defined in the TrueType specification. + * This flag is set if the outline uses the opposite direction + * (typically for Type~1 fonts). This flag is ignored by the scan + * 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. + * + * 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. + * + * 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. + * + * 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. + * + * 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. + * + * @Note: + * 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. + * + * 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 #define FT_OUTLINE_EVEN_ODD_FILL 0x2 @@ -469,26 +489,28 @@ FT_BEGIN_HEADER #define FT_Curve_Tag_Touch_Y FT_CURVE_TAG_TOUCH_Y - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* FT_Outline_MoveToFunc */ - /* */ - /* <Description> */ - /* 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. */ - /* */ - /* <Input> */ - /* to :: A pointer to the target point of the `move to'. */ - /* */ - /* user :: A typeless pointer, which is passed from the caller of the */ - /* decomposition function. */ - /* */ - /* <Return> */ - /* Error code. 0~means success. */ - /* */ + /************************************************************************** + * + * @FuncType: + * FT_Outline_MoveToFunc + * + * @Description: + * 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. + * + * @Input: + * to :: + * A pointer to the target point of the `move to'. + * + * user :: + * A typeless pointer, which is passed from the caller of the + * decomposition function. + * + * @Return: + * Error code. 0~means success. + */ typedef int (*FT_Outline_MoveToFunc)( const FT_Vector* to, void* user ); @@ -496,26 +518,28 @@ FT_BEGIN_HEADER #define FT_Outline_MoveTo_Func FT_Outline_MoveToFunc - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* FT_Outline_LineToFunc */ - /* */ - /* <Description> */ - /* 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. */ - /* */ - /* <Input> */ - /* to :: A pointer to the target point of the `line to'. */ - /* */ - /* user :: A typeless pointer, which is passed from the caller of the */ - /* decomposition function. */ - /* */ - /* <Return> */ - /* Error code. 0~means success. */ - /* */ + /************************************************************************** + * + * @FuncType: + * FT_Outline_LineToFunc + * + * @Description: + * 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. + * + * @Input: + * to :: + * A pointer to the target point of the `line to'. + * + * user :: + * A typeless pointer, which is passed from the caller of the + * decomposition function. + * + * @Return: + * Error code. 0~means success. + */ typedef int (*FT_Outline_LineToFunc)( const FT_Vector* to, void* user ); @@ -523,30 +547,33 @@ FT_BEGIN_HEADER #define FT_Outline_LineTo_Func FT_Outline_LineToFunc - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* FT_Outline_ConicToFunc */ - /* */ - /* <Description> */ - /* 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. */ - /* */ - /* <Input> */ - /* control :: 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. */ - /* */ - /* <Return> */ - /* Error code. 0~means success. */ - /* */ + /************************************************************************** + * + * @FuncType: + * FT_Outline_ConicToFunc + * + * @Description: + * 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. + * + * @Input: + * control :: + * 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. + * + * @Return: + * Error code. 0~means success. + */ typedef int (*FT_Outline_ConicToFunc)( const FT_Vector* control, const FT_Vector* to, @@ -555,30 +582,34 @@ FT_BEGIN_HEADER #define FT_Outline_ConicTo_Func FT_Outline_ConicToFunc - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* FT_Outline_CubicToFunc */ - /* */ - /* <Description> */ - /* 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. */ - /* */ - /* <Input> */ - /* control1 :: A pointer to the first Bezier control point. */ - /* */ - /* control2 :: A pointer to the second Bezier control point. */ - /* */ - /* to :: A pointer to the target end point. */ - /* */ - /* user :: A typeless pointer, which is passed from the caller of */ - /* the decomposition function. */ - /* */ - /* <Return> */ - /* Error code. 0~means success. */ - /* */ + /************************************************************************** + * + * @FuncType: + * FT_Outline_CubicToFunc + * + * @Description: + * 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. + * + * @Input: + * control1 :: + * A pointer to the first Bezier control point. + * + * control2 :: + * A pointer to the second Bezier control point. + * + * to :: + * A pointer to the target end point. + * + * user :: + * A typeless pointer, which is passed from the caller of + * the decomposition function. + * + * @Return: + * Error code. 0~means success. + */ typedef int (*FT_Outline_CubicToFunc)( const FT_Vector* control1, const FT_Vector* control2, @@ -588,43 +619,49 @@ FT_BEGIN_HEADER #define FT_Outline_CubicTo_Func FT_Outline_CubicToFunc - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_Outline_Funcs */ - /* */ - /* <Description> */ - /* A structure to hold various function pointers used during outline */ - /* decomposition in order to emit segments, conic, and cubic Beziers. */ - /* */ - /* <Fields> */ - /* move_to :: The `move to' emitter. */ - /* */ - /* line_to :: The segment emitter. */ - /* */ - /* conic_to :: The second-order Bezier arc emitter. */ - /* */ - /* cubic_to :: The third-order Bezier arc emitter. */ - /* */ - /* shift :: 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. */ - /* */ - /* <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: */ - /* */ - /* { */ - /* x' = (x << shift) - delta */ - /* y' = (y << shift) - delta */ - /* } */ - /* */ - /* Set the values of `shift' and `delta' to~0 to get the original */ - /* point coordinates. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_Outline_Funcs + * + * @Description: + * A structure to hold various function pointers used during outline + * decomposition in order to emit segments, conic, and cubic Beziers. + * + * @Fields: + * move_to :: + * The `move to' emitter. + * + * line_to :: + * The segment emitter. + * + * conic_to :: + * The second-order Bezier arc emitter. + * + * cubic_to :: + * The third-order Bezier arc emitter. + * + * shift :: + * 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. + * + * @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: + * + * { + * x' = (x << shift) - delta + * y' = (y << shift) - delta + * } + * + * Set the values of `shift' and `delta' to~0 to get the original + * point coordinates. + */ typedef struct FT_Outline_Funcs_ { FT_Outline_MoveToFunc move_to; @@ -638,33 +675,33 @@ FT_BEGIN_HEADER } FT_Outline_Funcs; - /*************************************************************************/ - /* */ - /* <Section> */ - /* basic_types */ - /* */ - /*************************************************************************/ - - - /*************************************************************************/ - /* */ - /* <Macro> */ - /* FT_IMAGE_TAG */ - /* */ - /* <Description> */ - /* 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: */ - /* */ - /* { */ - /* #define FT_IMAGE_TAG( value, _x1, _x2, _x3, _x4 ) value */ - /* } */ - /* */ - /* to get a simple enumeration without assigning special numbers. */ - /* */ + /************************************************************************** + * + * @Section: + * basic_types + * + */ + + + /************************************************************************** + * + * @Macro: + * FT_IMAGE_TAG + * + * @Description: + * 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: + * + * { + * #define FT_IMAGE_TAG( value, _x1, _x2, _x3, _x4 ) value + * } + * + * to get a simple enumeration without assigning special numbers. + */ #ifndef FT_IMAGE_TAG #define FT_IMAGE_TAG( value, _x1, _x2, _x3, _x4 ) \ value = ( ( (unsigned long)_x1 << 24 ) | \ @@ -674,44 +711,44 @@ FT_BEGIN_HEADER #endif /* FT_IMAGE_TAG */ - /*************************************************************************/ - /* */ - /* <Enum> */ - /* FT_Glyph_Format */ - /* */ - /* <Description> */ - /* An enumeration type used to describe the format of a given glyph */ - /* image. Note that this version of FreeType only supports two image */ - /* formats, even though future font drivers will be able to register */ - /* their own format. */ - /* */ - /* <Values> */ - /* FT_GLYPH_FORMAT_NONE :: */ - /* 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). */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Enum: + * FT_Glyph_Format + * + * @Description: + * An enumeration type used to describe the format of a given glyph + * image. Note that this version of FreeType only supports two image + * formats, even though future font drivers will be able to register + * their own format. + * + * @Values: + * FT_GLYPH_FORMAT_NONE :: + * 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). + * + * 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. + * + * 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. + * + * 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. + */ typedef enum FT_Glyph_Format_ { FT_IMAGE_TAG( FT_GLYPH_FORMAT_NONE, 0, 0, 0, 0 ), @@ -744,87 +781,90 @@ 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. */ - /* */ - /* Note that in FreeType 2, all rasters are now encapsulated within */ - /* specific modules called `renderers'. See `ftrender.h' for more */ - /* details on renderers. */ - /* */ - /*************************************************************************/ - - - /*************************************************************************/ - /* */ - /* <Section> */ - /* raster */ - /* */ - /* <Title> */ - /* Scanline Converter */ - /* */ - /* <Abstract> */ - /* How vectorial outlines are converted into bitmaps and pixmaps. */ - /* */ - /* <Description> */ - /* This section contains technical definitions. */ - /* */ - /* <Order> */ - /* FT_Raster */ - /* FT_Span */ - /* FT_SpanFunc */ - /* */ - /* FT_Raster_Params */ - /* FT_RASTER_FLAG_XXX */ - /* */ - /* FT_Raster_NewFunc */ - /* FT_Raster_DoneFunc */ - /* FT_Raster_ResetFunc */ - /* FT_Raster_SetModeFunc */ - /* FT_Raster_RenderFunc */ - /* FT_Raster_Funcs */ - /* */ - /*************************************************************************/ - - - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_Raster */ - /* */ - /* <Description> */ - /* An opaque handle (pointer) to a raster object. Each object can be */ - /* used independently to convert an outline into a bitmap or pixmap. */ - /* */ + /************************************************************************** + * + * 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. + * + */ + + + /************************************************************************** + * + * @Section: + * raster + * + * @Title: + * Scanline Converter + * + * @Abstract: + * How vectorial outlines are converted into bitmaps and pixmaps. + * + * @Description: + * This section contains technical definitions. + * + * @Order: + * FT_Raster + * FT_Span + * FT_SpanFunc + * + * FT_Raster_Params + * FT_RASTER_FLAG_XXX + * + * FT_Raster_NewFunc + * FT_Raster_DoneFunc + * FT_Raster_ResetFunc + * FT_Raster_SetModeFunc + * FT_Raster_RenderFunc + * FT_Raster_Funcs + * + */ + + + /************************************************************************** + * + * @Type: + * FT_Raster + * + * @Description: + * An opaque handle (pointer) to a raster object. Each object can be + * used independently to convert an outline into a bitmap or pixmap. + */ typedef struct FT_RasterRec_* FT_Raster; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_Span */ - /* */ - /* <Description> */ - /* A structure used to model a single span of gray pixels when */ - /* rendering an anti-aliased bitmap. */ - /* */ - /* <Fields> */ - /* x :: The span's horizontal start position. */ - /* */ - /* len :: The span's length in pixels. */ - /* */ - /* coverage :: 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. */ - /* */ - /* The coverage value is always between 0 and 255. If you want less */ - /* gray values, the callback function has to reduce them. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_Span + * + * @Description: + * A structure used to model a single span of gray pixels when + * rendering an anti-aliased bitmap. + * + * @Fields: + * x :: + * The span's horizontal start position. + * + * len :: + * The span's length in pixels. + * + * coverage :: + * 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. + * + * 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_ { short x; @@ -834,32 +874,36 @@ FT_BEGIN_HEADER } FT_Span; - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* 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. */ - /* */ - /* <Input> */ - /* y :: The scanline's y~coordinate. */ - /* */ - /* count :: The number of spans to draw on this scanline. */ - /* */ - /* spans :: 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 can be used to write anti-aliased outlines directly to a */ - /* given background bitmap, and even perform translucency. */ - /* */ + /************************************************************************** + * + * @FuncType: + * 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. + * + * @Input: + * y :: + * The scanline's y~coordinate. + * + * count :: + * The number of spans to draw on this scanline. + * + * spans :: + * 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 can be used to write anti-aliased outlines directly to a + * given background bitmap, and even perform translucency. + */ typedef void (*FT_SpanFunc)( int y, int count, @@ -869,74 +913,78 @@ FT_BEGIN_HEADER #define FT_Raster_Span_Func FT_SpanFunc - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* FT_Raster_BitTest_Func */ - /* */ - /* <Description> */ - /* Deprecated, unimplemented. */ - /* */ + /************************************************************************** + * + * @FuncType: + * FT_Raster_BitTest_Func + * + * @Description: + * Deprecated, unimplemented. + */ typedef int (*FT_Raster_BitTest_Func)( int y, int x, void* user ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* FT_Raster_BitSet_Func */ - /* */ - /* <Description> */ - /* Deprecated, unimplemented. */ - /* */ + /************************************************************************** + * + * @FuncType: + * FT_Raster_BitSet_Func + * + * @Description: + * Deprecated, unimplemented. + */ typedef void (*FT_Raster_BitSet_Func)( int y, int x, void* user ); - /*************************************************************************/ - /* */ - /* <Enum> */ - /* FT_RASTER_FLAG_XXX */ - /* */ - /* <Description> */ - /* A list of bit flag constants as used in the `flags' field of a */ - /* @FT_Raster_Params structure. */ - /* */ - /* <Values> */ - /* FT_RASTER_FLAG_DEFAULT :: 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). */ - /* */ - /* 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 */ - /* rendering. */ - /* */ - /* 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 */ - /* @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. */ - /* */ + /************************************************************************** + * + * @Enum: + * FT_RASTER_FLAG_XXX + * + * @Description: + * A list of bit flag constants as used in the `flags' field of a + * @FT_Raster_Params structure. + * + * @Values: + * FT_RASTER_FLAG_DEFAULT :: + * 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). + * + * 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 + * rendering. + * + * 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 + * @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. + */ #define FT_RASTER_FLAG_DEFAULT 0x0 #define FT_RASTER_FLAG_AA 0x1 #define FT_RASTER_FLAG_DIRECT 0x2 @@ -950,50 +998,59 @@ FT_BEGIN_HEADER #define ft_raster_flag_clip FT_RASTER_FLAG_CLIP - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_Raster_Params */ - /* */ - /* <Description> */ - /* 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). */ - /* */ - /* flags :: The rendering flags. */ - /* */ - /* gray_spans :: The gray span drawing callback. */ - /* */ - /* black_spans :: Unused. */ - /* */ - /* bit_test :: Unused. */ - /* */ - /* bit_set :: Unused. */ - /* */ - /* user :: 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). */ - /* */ - /* <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. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_Raster_Params + * + * @Description: + * 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). + * + * flags :: + * The rendering flags. + * + * gray_spans :: + * The gray span drawing callback. + * + * black_spans :: + * Unused. + * + * bit_test :: + * Unused. + * + * bit_set :: + * Unused. + * + * user :: + * 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). + * + * @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. + */ typedef struct FT_Raster_Params_ { const FT_Bitmap* target; @@ -1009,30 +1066,32 @@ FT_BEGIN_HEADER } FT_Raster_Params; - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* FT_Raster_NewFunc */ - /* */ - /* <Description> */ - /* A function used to create a new raster object. */ - /* */ - /* <Input> */ - /* memory :: A handle to the memory allocator. */ - /* */ - /* <Output> */ - /* raster :: A handle to the new raster object. */ - /* */ - /* <Return> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @FuncType: + * FT_Raster_NewFunc + * + * @Description: + * A function used to create a new raster object. + * + * @Input: + * memory :: + * A handle to the memory allocator. + * + * @Output: + * raster :: + * A handle to the new raster object. + * + * @Return: + * 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. + */ typedef int (*FT_Raster_NewFunc)( void* memory, FT_Raster* raster ); @@ -1040,49 +1099,53 @@ FT_BEGIN_HEADER #define FT_Raster_New_Func FT_Raster_NewFunc - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* FT_Raster_DoneFunc */ - /* */ - /* <Description> */ - /* A function used to destroy a given raster object. */ - /* */ - /* <Input> */ - /* raster :: A handle to the raster object. */ - /* */ + /************************************************************************** + * + * @FuncType: + * FT_Raster_DoneFunc + * + * @Description: + * A function used to destroy a given raster object. + * + * @Input: + * raster :: + * A handle to the raster object. + */ typedef void (*FT_Raster_DoneFunc)( FT_Raster raster ); #define FT_Raster_Done_Func FT_Raster_DoneFunc - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* 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. */ - /* */ - /* This function is called after a new raster object is created. */ - /* */ - /* <Input> */ - /* raster :: A handle to the new raster object. */ - /* */ - /* pool_base :: 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. */ - /* */ - /* <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). */ - /* */ + /************************************************************************** + * + * @FuncType: + * 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. + * + * This function is called after a new raster object is created. + * + * @Input: + * raster :: + * A handle to the new raster object. + * + * pool_base :: + * 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. + * + * @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). + */ typedef void (*FT_Raster_ResetFunc)( FT_Raster raster, unsigned char* pool_base, @@ -1091,24 +1154,27 @@ FT_BEGIN_HEADER #define FT_Raster_Reset_Func FT_Raster_ResetFunc - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* 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. */ - /* */ - /* <Input> */ - /* raster :: A handle to the new raster object. */ - /* */ - /* mode :: A 4-byte tag used to name the mode or property. */ - /* */ - /* args :: A pointer to the new mode/property to use. */ - /* */ + /************************************************************************** + * + * @FuncType: + * 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. + * + * @Input: + * raster :: + * A handle to the new raster object. + * + * mode :: + * A 4-byte tag used to name the mode or property. + * + * args :: + * A pointer to the new mode/property to use. + */ typedef int (*FT_Raster_SetModeFunc)( FT_Raster raster, unsigned long mode, @@ -1117,40 +1183,42 @@ FT_BEGIN_HEADER #define FT_Raster_Set_Mode_Func FT_Raster_SetModeFunc - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* FT_Raster_RenderFunc */ - /* */ - /* <Description> */ - /* Invoke a given raster to scan-convert a given glyph image into a */ - /* target bitmap. */ - /* */ - /* <Input> */ - /* raster :: A handle to the raster object. */ - /* */ - /* params :: A pointer to an @FT_Raster_Params structure used to */ - /* store the rendering parameters. */ - /* */ - /* <Return> */ - /* Error code. 0~means success. */ - /* */ - /* <Note> */ - /* The exact format of the source image depends on the raster's glyph */ - /* format defined in its @FT_Raster_Funcs structure. It can be an */ - /* @FT_Outline or anything else in order to support a large array of */ - /* 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. */ - /* */ - /* 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). */ - /* */ + /************************************************************************** + * + * @FuncType: + * FT_Raster_RenderFunc + * + * @Description: + * Invoke a given raster to scan-convert a given glyph image into a + * target bitmap. + * + * @Input: + * raster :: + * A handle to the raster object. + * + * params :: + * A pointer to an @FT_Raster_Params structure used to + * store the rendering parameters. + * + * @Return: + * Error code. 0~means success. + * + * @Note: + * The exact format of the source image depends on the raster's glyph + * format defined in its @FT_Raster_Funcs structure. It can be an + * @FT_Outline or anything else in order to support a large array of + * 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. + * + * 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). + */ typedef int (*FT_Raster_RenderFunc)( FT_Raster raster, const FT_Raster_Params* params ); @@ -1158,25 +1226,30 @@ FT_BEGIN_HEADER #define FT_Raster_Render_Func FT_Raster_RenderFunc - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_Raster_Funcs */ - /* */ - /* <Description> */ - /* A structure used to describe a given raster class to the library. */ - /* */ - /* <Fields> */ - /* glyph_format :: The supported glyph format for this raster. */ - /* */ - /* raster_new :: The raster constructor. */ - /* */ - /* raster_reset :: Used to reset the render pool within the raster. */ - /* */ - /* raster_render :: A function to render a glyph into a given bitmap. */ - /* */ - /* raster_done :: The raster destructor. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_Raster_Funcs + * + * @Description: + * A structure used to describe a given raster class to the library. + * + * @Fields: + * glyph_format :: + * The supported glyph format for this raster. + * + * raster_new :: + * The raster constructor. + * + * raster_reset :: + * Used to reset the render pool within the raster. + * + * raster_render :: + * A function to render a glyph into a given bitmap. + * + * raster_done :: + * The raster destructor. + */ typedef struct FT_Raster_Funcs_ { FT_Glyph_Format glyph_format; diff --git a/include/freetype/ftincrem.h b/include/freetype/ftincrem.h index 44619f941..08bba7329 100644 --- a/include/freetype/ftincrem.h +++ b/include/freetype/ftincrem.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftincrem.h */ -/* */ -/* FreeType incremental loading (specification). */ -/* */ -/* Copyright 2002-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftincrem.h + * + * FreeType incremental loading (specification). + * + * Copyright 2002-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTINCREM_H_ diff --git a/include/freetype/ftlcdfil.h b/include/freetype/ftlcdfil.h index a71113e43..ce5ea3587 100644 --- a/include/freetype/ftlcdfil.h +++ b/include/freetype/ftlcdfil.h @@ -1,20 +1,20 @@ -/***************************************************************************/ -/* */ -/* ftlcdfil.h */ -/* */ -/* FreeType API for color filtering of subpixel bitmap glyphs */ -/* (specification). */ -/* */ -/* Copyright 2006-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftlcdfil.h + * + * FreeType API for color filtering of subpixel bitmap glyphs + * (specification). + * + * Copyright 2006-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTLCDFIL_H_ @@ -229,7 +229,8 @@ FT_BEGIN_HEADER unsigned char *weights ); - /* + /************************************************************************** + * * @type: * FT_LcdFiveTapFilter * diff --git a/include/freetype/ftlist.h b/include/freetype/ftlist.h index 117473b96..d130989e9 100644 --- a/include/freetype/ftlist.h +++ b/include/freetype/ftlist.h @@ -1,27 +1,27 @@ -/***************************************************************************/ -/* */ -/* ftlist.h */ -/* */ -/* Generic list support for FreeType (specification). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ - - - /*************************************************************************/ - /* */ - /* This file implements functions relative to list processing. Its */ - /* data structures are defined in `freetype.h'. */ - /* */ - /*************************************************************************/ +/**************************************************************************** + * + * ftlist.h + * + * Generic list support for FreeType (specification). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ + + + /************************************************************************** + * + * This file implements functions relative to list processing. Its + * data structures are defined in `freetype.h'. + * + */ #ifndef FTLIST_H_ @@ -41,224 +41,246 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* list_processing */ - /* */ - /* <Title> */ - /* List Processing */ - /* */ - /* <Abstract> */ - /* Simple management of lists. */ - /* */ - /* <Description> */ - /* This section contains various definitions related to list */ - /* processing using doubly-linked nodes. */ - /* */ - /* <Order> */ - /* FT_List */ - /* FT_ListNode */ - /* FT_ListRec */ - /* FT_ListNodeRec */ - /* */ - /* FT_List_Add */ - /* FT_List_Insert */ - /* FT_List_Find */ - /* FT_List_Remove */ - /* FT_List_Up */ - /* FT_List_Iterate */ - /* FT_List_Iterator */ - /* FT_List_Finalize */ - /* FT_List_Destructor */ - /* */ - /*************************************************************************/ - - - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_List_Find */ - /* */ - /* <Description> */ - /* Find the list node for a given listed object. */ - /* */ - /* <Input> */ - /* list :: A pointer to the parent list. */ - /* data :: The address of the listed object. */ - /* */ - /* <Return> */ - /* List node. NULL if it wasn't found. */ - /* */ + /************************************************************************** + * + * @Section: + * list_processing + * + * @Title: + * List Processing + * + * @Abstract: + * Simple management of lists. + * + * @Description: + * This section contains various definitions related to list + * processing using doubly-linked nodes. + * + * @Order: + * FT_List + * FT_ListNode + * FT_ListRec + * FT_ListNodeRec + * + * FT_List_Add + * FT_List_Insert + * FT_List_Find + * FT_List_Remove + * FT_List_Up + * FT_List_Iterate + * FT_List_Iterator + * FT_List_Finalize + * FT_List_Destructor + * + */ + + + /************************************************************************** + * + * @Function: + * FT_List_Find + * + * @Description: + * Find the list node for a given listed object. + * + * @Input: + * list :: + * A pointer to the parent list. + * data :: + * The address of the listed object. + * + * @Return: + * List node. NULL if it wasn't found. + */ FT_EXPORT( FT_ListNode ) FT_List_Find( FT_List list, void* data ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_List_Add */ - /* */ - /* <Description> */ - /* Append an element to the end of a list. */ - /* */ - /* <InOut> */ - /* list :: A pointer to the parent list. */ - /* node :: The node to append. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_List_Add + * + * @Description: + * Append an element to the end of a list. + * + * @InOut: + * list :: + * A pointer to the parent list. + * node :: + * The node to append. + */ FT_EXPORT( void ) FT_List_Add( FT_List list, FT_ListNode node ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_List_Insert */ - /* */ - /* <Description> */ - /* Insert an element at the head of a list. */ - /* */ - /* <InOut> */ - /* list :: A pointer to parent list. */ - /* node :: The node to insert. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_List_Insert + * + * @Description: + * Insert an element at the head of a list. + * + * @InOut: + * list :: + * A pointer to parent list. + * node :: + * The node to insert. + */ FT_EXPORT( void ) FT_List_Insert( FT_List list, FT_ListNode node ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_List_Remove */ - /* */ - /* <Description> */ - /* Remove a node from a list. This function doesn't check whether */ - /* the node is in the list! */ - /* */ - /* <Input> */ - /* node :: The node to remove. */ - /* */ - /* <InOut> */ - /* list :: A pointer to the parent list. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_List_Remove + * + * @Description: + * Remove a node from a list. This function doesn't check whether + * the node is in the list! + * + * @Input: + * node :: + * The node to remove. + * + * @InOut: + * list :: + * A pointer to the parent list. + */ FT_EXPORT( void ) FT_List_Remove( FT_List list, FT_ListNode node ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_List_Up */ - /* */ - /* <Description> */ - /* Move a node to the head/top of a list. Used to maintain LRU */ - /* lists. */ - /* */ - /* <InOut> */ - /* list :: A pointer to the parent list. */ - /* node :: The node to move. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_List_Up + * + * @Description: + * Move a node to the head/top of a list. Used to maintain LRU + * lists. + * + * @InOut: + * list :: + * A pointer to the parent list. + * node :: + * The node to move. + */ FT_EXPORT( void ) FT_List_Up( FT_List list, FT_ListNode node ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* FT_List_Iterator */ - /* */ - /* <Description> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @FuncType: + * FT_List_Iterator + * + * @Description: + * 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. + */ typedef FT_Error (*FT_List_Iterator)( FT_ListNode node, void* user ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_List_Iterate */ - /* */ - /* <Description> */ - /* Parse a list and calls a given iterator function on each element. */ - /* Note that parsing is stopped as soon as one of the iterator calls */ - /* returns a non-zero value. */ - /* */ - /* <Input> */ - /* list :: A handle to the list. */ - /* 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. */ - /* */ - /* <Return> */ - /* The result (a FreeType error code) of the last iterator call. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_List_Iterate + * + * @Description: + * Parse a list and calls a given iterator function on each element. + * Note that parsing is stopped as soon as one of the iterator calls + * returns a non-zero value. + * + * @Input: + * list :: + * A handle to the list. + * 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. + * + * @Return: + * The result (a FreeType error code) of the last iterator call. + */ FT_EXPORT( FT_Error ) FT_List_Iterate( FT_List list, FT_List_Iterator iterator, void* user ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* FT_List_Destructor */ - /* */ - /* <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. */ - /* */ - /* <Input> */ - /* system :: The current system object. */ - /* */ - /* data :: 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. */ - /* */ + /************************************************************************** + * + * @FuncType: + * FT_List_Destructor + * + * @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. + * + * @Input: + * system :: + * The current system object. + * + * data :: + * 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. + */ typedef void (*FT_List_Destructor)( FT_Memory memory, void* data, void* user ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_List_Finalize */ - /* */ - /* <Description> */ - /* Destroy all elements in the list as well as the list itself. */ - /* */ - /* <Input> */ - /* list :: 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. */ - /* */ - /* memory :: The current memory object that handles deallocation. */ - /* */ - /* user :: 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 */ - /* @FT_List_Insert have been dynamically allocated. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_List_Finalize + * + * @Description: + * Destroy all elements in the list as well as the list itself. + * + * @Input: + * list :: + * 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. + * + * memory :: + * The current memory object that handles deallocation. + * + * user :: + * 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 + * @FT_List_Insert have been dynamically allocated. + */ FT_EXPORT( void ) FT_List_Finalize( FT_List list, FT_List_Destructor destroy, diff --git a/include/freetype/ftlzw.h b/include/freetype/ftlzw.h index 1615912d6..d639eb1f7 100644 --- a/include/freetype/ftlzw.h +++ b/include/freetype/ftlzw.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftlzw.h */ -/* */ -/* LZW-compressed stream support. */ -/* */ -/* Copyright 2004-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftlzw.h + * + * LZW-compressed stream support. + * + * Copyright 2004-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTLZW_H_ @@ -31,21 +31,21 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* lzw */ - /* */ - /* <Title> */ - /* LZW Streams */ - /* */ - /* <Abstract> */ - /* Using LZW-compressed font files. */ - /* */ - /* <Description> */ - /* This section contains the declaration of LZW-specific functions. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * lzw + * + * @Title: + * LZW Streams + * + * @Abstract: + * Using LZW-compressed font files. + * + * @Description: + * This section contains the declaration of LZW-specific functions. + * + */ /************************************************************************ * @@ -58,9 +58,11 @@ FT_BEGIN_HEADER * with XFree86. * * @input: - * stream :: The target embedding stream. + * stream :: + * The target embedding stream. * - * source :: The source stream. + * source :: + * The source stream. * * @return: * FreeType error code. 0~means success. diff --git a/include/freetype/ftmac.h b/include/freetype/ftmac.h index c1e497ca2..56140b2fd 100644 --- a/include/freetype/ftmac.h +++ b/include/freetype/ftmac.h @@ -1,28 +1,28 @@ -/***************************************************************************/ -/* */ -/* ftmac.h */ -/* */ -/* Additional Mac-specific API. */ -/* */ -/* Copyright 1996-2018 by */ -/* Just van Rossum, David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftmac.h + * + * Additional Mac-specific API. + * + * Copyright 1996-2018 by + * Just van Rossum, David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ -/***************************************************************************/ -/* */ -/* NOTE: Include this file after FT_FREETYPE_H and after any */ -/* Mac-specific headers (because this header uses Mac types such as */ -/* Handle, FSSpec, FSRef, etc.) */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * NOTE: Include this file after FT_FREETYPE_H and after any + * Mac-specific headers (because this header uses Mac types such as + * Handle, FSSpec, FSRef, etc.) + * + */ #ifndef FTMAC_H_ @@ -47,56 +47,60 @@ FT_BEGIN_HEADER #endif - /*************************************************************************/ - /* */ - /* <Section> */ - /* mac_specific */ - /* */ - /* <Title> */ - /* Mac Specific Interface */ - /* */ - /* <Abstract> */ - /* Only available on the Macintosh. */ - /* */ - /* <Description> */ - /* The following definitions are only available if FreeType is */ - /* compiled on a Macintosh. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * mac_specific + * + * @Title: + * Mac Specific Interface + * + * @Abstract: + * Only available on the Macintosh. + * + * @Description: + * The following definitions are only available if FreeType is + * compiled on a Macintosh. + * + */ - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_New_Face_From_FOND */ - /* */ - /* <Description> */ - /* Create a new face object from a FOND resource. */ - /* */ - /* <InOut> */ - /* library :: A handle to the library resource. */ - /* */ - /* <Input> */ - /* fond :: A FOND resource. */ - /* */ - /* face_index :: Only supported for the -1 `sanity check' special */ - /* case. */ - /* */ - /* <Output> */ - /* aface :: A handle to a new face object. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ - /* <Notes> */ - /* 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 ); */ - /* } */ - /* */ + /************************************************************************** + * + * @Function: + * FT_New_Face_From_FOND + * + * @Description: + * Create a new face object from a FOND resource. + * + * @InOut: + * library :: + * A handle to the library resource. + * + * @Input: + * fond :: + * A FOND resource. + * + * face_index :: + * Only supported for the -1 `sanity check' special + * case. + * + * @Output: + * aface :: + * A handle to a new face object. + * + * @Return: + * FreeType error code. 0~means success. + * + * @Notes: + * 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, Handle fond, @@ -105,28 +109,31 @@ FT_BEGIN_HEADER FT_DEPRECATED_ATTRIBUTE; - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_GetFile_From_Mac_Name */ - /* */ - /* <Description> */ - /* Return an FSSpec for the disk file containing the named font. */ - /* */ - /* <Input> */ - /* fontName :: 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. */ - /* */ - /* face_index :: Index of the face. For passing to */ - /* @FT_New_Face_From_FSSpec. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_GetFile_From_Mac_Name + * + * @Description: + * Return an FSSpec for the disk file containing the named font. + * + * @Input: + * fontName :: + * 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. + * + * face_index :: + * Index of the face. For passing to + * @FT_New_Face_From_FSSpec. + * + * @Return: + * FreeType error code. 0~means success. + */ FT_EXPORT( FT_Error ) FT_GetFile_From_Mac_Name( const char* fontName, FSSpec* pathSpec, @@ -134,27 +141,30 @@ FT_BEGIN_HEADER FT_DEPRECATED_ATTRIBUTE; - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_GetFile_From_Mac_ATS_Name */ - /* */ - /* <Description> */ - /* Return an FSSpec for the disk file containing the named font. */ - /* */ - /* <Input> */ - /* fontName :: Mac OS name of the font in ATS framework. */ - /* */ - /* <Output> */ - /* pathSpec :: 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. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_GetFile_From_Mac_ATS_Name + * + * @Description: + * Return an FSSpec for the disk file containing the named font. + * + * @Input: + * fontName :: + * Mac OS name of the font in ATS framework. + * + * @Output: + * pathSpec :: + * 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. + * + * @Return: + * FreeType error code. 0~means success. + */ FT_EXPORT( FT_Error ) FT_GetFile_From_Mac_ATS_Name( const char* fontName, FSSpec* pathSpec, @@ -162,30 +172,34 @@ FT_BEGIN_HEADER FT_DEPRECATED_ATTRIBUTE; - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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. */ - /* */ - /* <Input> */ - /* fontName :: Mac OS name of the font in ATS framework. */ - /* */ - /* <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. */ - /* */ - /* maxPathSize :: Lengths of the buffer `path' that client allocated. */ - /* */ - /* face_index :: Index of the face. For passing to @FT_New_Face. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ + /************************************************************************** + * + * @Function: + * 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. + * + * @Input: + * fontName :: + * Mac OS name of the font in ATS framework. + * + * @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. + * + * maxPathSize :: + * Lengths of the buffer `path' that client allocated. + * + * face_index :: + * Index of the face. For passing to @FT_New_Face. + * + * @Return: + * FreeType error code. 0~means success. + */ FT_EXPORT( FT_Error ) FT_GetFilePath_From_Mac_ATS_Name( const char* fontName, UInt8* path, @@ -194,33 +208,37 @@ FT_BEGIN_HEADER FT_DEPRECATED_ATTRIBUTE; - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_New_Face_From_FSSpec */ - /* */ - /* <Description> */ - /* Create a new face object from a given resource and typeface index */ - /* using an FSSpec to the font file. */ - /* */ - /* <InOut> */ - /* library :: A handle to the library resource. */ - /* */ - /* <Input> */ - /* spec :: FSSpec to the font file. */ - /* */ - /* face_index :: The index of the face within the resource. The */ - /* first face has index~0. */ - /* <Output> */ - /* aface :: A handle to a new face object. */ - /* */ - /* <Return> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_New_Face_From_FSSpec + * + * @Description: + * Create a new face object from a given resource and typeface index + * using an FSSpec to the font file. + * + * @InOut: + * library :: + * A handle to the library resource. + * + * @Input: + * spec :: + * FSSpec to the font file. + * + * face_index :: + * The index of the face within the resource. The + * first face has index~0. + * @Output: + * aface :: + * A handle to a new face object. + * + * @Return: + * 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_EXPORT( FT_Error ) FT_New_Face_From_FSSpec( FT_Library library, const FSSpec *spec, @@ -229,33 +247,37 @@ FT_BEGIN_HEADER FT_DEPRECATED_ATTRIBUTE; - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_New_Face_From_FSRef */ - /* */ - /* <Description> */ - /* Create a new face object from a given resource and typeface index */ - /* using an FSRef to the font file. */ - /* */ - /* <InOut> */ - /* library :: A handle to the library resource. */ - /* */ - /* <Input> */ - /* spec :: FSRef to the font file. */ - /* */ - /* face_index :: The index of the face within the resource. The */ - /* first face has index~0. */ - /* <Output> */ - /* aface :: A handle to a new face object. */ - /* */ - /* <Return> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_New_Face_From_FSRef + * + * @Description: + * Create a new face object from a given resource and typeface index + * using an FSRef to the font file. + * + * @InOut: + * library :: + * A handle to the library resource. + * + * @Input: + * spec :: + * FSRef to the font file. + * + * face_index :: + * The index of the face within the resource. The + * first face has index~0. + * @Output: + * aface :: + * A handle to a new face object. + * + * @Return: + * 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_EXPORT( FT_Error ) FT_New_Face_From_FSRef( FT_Library library, const FSRef *ref, diff --git a/include/freetype/ftmm.h b/include/freetype/ftmm.h index 9948102c1..fdf2bed1b 100644 --- a/include/freetype/ftmm.h +++ b/include/freetype/ftmm.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftmm.h */ -/* */ -/* FreeType Multiple Master font interface (specification). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftmm.h + * + * FreeType Multiple Master font interface (specification). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTMM_H_ @@ -27,49 +27,52 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* multiple_masters */ - /* */ - /* <Title> */ - /* Multiple Masters */ - /* */ - /* <Abstract> */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /*************************************************************************/ - - - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_MM_Axis */ - /* */ - /* <Description> */ - /* 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. */ - /* */ - /* <Fields> */ - /* name :: The axis's name. */ - /* */ - /* minimum :: The axis's minimum design coordinate. */ - /* */ - /* maximum :: The axis's maximum design coordinate. */ - /* */ + /************************************************************************** + * + * @Section: + * multiple_masters + * + * @Title: + * Multiple Masters + * + * @Abstract: + * 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. + * + * 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. + * + */ + + + /************************************************************************** + * + * @Struct: + * FT_MM_Axis + * + * @Description: + * 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. + * + * @Fields: + * name :: + * The axis's name. + * + * minimum :: + * The axis's minimum design coordinate. + * + * maximum :: + * The axis's maximum design coordinate. + */ typedef struct FT_MM_Axis_ { FT_String* name; @@ -79,28 +82,31 @@ FT_BEGIN_HEADER } FT_MM_Axis; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_Multi_Master */ - /* */ - /* <Description> */ - /* 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. */ - /* */ - /* <Fields> */ - /* num_axis :: 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. */ - /* */ - /* axis :: A table of axis descriptors. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_Multi_Master + * + * @Description: + * 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. + * + * @Fields: + * num_axis :: + * 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. + * + * axis :: + * A table of axis descriptors. + */ typedef struct FT_Multi_Master_ { FT_UInt num_axis; @@ -110,42 +116,48 @@ FT_BEGIN_HEADER } FT_Multi_Master; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_Var_Axis */ - /* */ - /* <Description> */ - /* A structure to model a given axis in design space for Multiple */ - /* Masters, TrueType GX, and OpenType variation fonts. */ - /* */ - /* <Fields> */ - /* name :: 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* <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. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_Var_Axis + * + * @Description: + * A structure to model a given axis in design space for Multiple + * Masters, TrueType GX, and OpenType variation fonts. + * + * @Fields: + * name :: + * 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. + * + * 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. + * + * 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. + * + * @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. + */ typedef struct FT_Var_Axis_ { FT_String* name; @@ -160,27 +172,30 @@ FT_BEGIN_HEADER } FT_Var_Axis; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_Var_Named_Style */ - /* */ - /* <Description> */ - /* A structure to model a named instance in a TrueType GX or OpenType */ - /* variation font. */ - /* */ - /* This structure can't be used for Adobe MM fonts. */ - /* */ - /* <Fields> */ - /* coords :: 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. */ - /* */ - /* psid :: The entry in `name' table identifying a PostScript name */ - /* for this instance. Value 0xFFFF indicates a missing */ - /* entry. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_Var_Named_Style + * + * @Description: + * A structure to model a named instance in a TrueType GX or OpenType + * variation font. + * + * This structure can't be used for Adobe MM fonts. + * + * @Fields: + * coords :: + * 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. + * + * psid :: + * The entry in `name' table identifying a PostScript name + * for this instance. Value 0xFFFF indicates a missing + * entry. + */ typedef struct FT_Var_Named_Style_ { FT_Fixed* coords; @@ -190,50 +205,55 @@ FT_BEGIN_HEADER } FT_Var_Named_Style; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_MM_Var */ - /* */ - /* <Description> */ - /* 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. */ - /* */ - /* 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). */ - /* */ - /* 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'. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_MM_Var + * + * @Description: + * 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. + * + * 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). + * + * 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'. + * + * 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. + * + * 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. + */ typedef struct FT_MM_Var_ { FT_UInt num_axis; @@ -245,384 +265,409 @@ FT_BEGIN_HEADER } FT_MM_Var; - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Get_Multi_Master */ - /* */ - /* <Description> */ - /* Retrieve a variation descriptor of a given Adobe MM font. */ - /* */ - /* This function can't be used with TrueType GX or OpenType variation */ - /* fonts. */ - /* */ - /* <Input> */ - /* face :: A handle to the source face. */ - /* */ - /* <Output> */ - /* amaster :: The Multiple Masters descriptor. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Get_Multi_Master + * + * @Description: + * Retrieve a variation descriptor of a given Adobe MM font. + * + * This function can't be used with TrueType GX or OpenType variation + * fonts. + * + * @Input: + * face :: + * A handle to the source face. + * + * @Output: + * amaster :: + * The Multiple Masters descriptor. + * + * @Return: + * FreeType error code. 0~means success. + */ FT_EXPORT( FT_Error ) FT_Get_Multi_Master( FT_Face face, FT_Multi_Master *amaster ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Get_MM_Var */ - /* */ - /* <Description> */ - /* Retrieve a variation descriptor for a given font. */ - /* */ - /* This function works with all supported variation formats. */ - /* */ - /* <Input> */ - /* face :: A handle to the source face. */ - /* */ - /* <Output> */ - /* amaster :: 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. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Get_MM_Var + * + * @Description: + * Retrieve a variation descriptor for a given font. + * + * This function works with all supported variation formats. + * + * @Input: + * face :: + * A handle to the source face. + * + * @Output: + * amaster :: + * 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. + */ FT_EXPORT( FT_Error ) FT_Get_MM_Var( FT_Face face, FT_MM_Var* *amaster ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Done_MM_Var */ - /* */ - /* <Description> */ - /* Free the memory allocated by @FT_Get_MM_Var. */ - /* */ - /* <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'. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Done_MM_Var + * + * @Description: + * Free the memory allocated by @FT_Get_MM_Var. + * + * @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'. + * + * @Return: + * FreeType error code. 0~means success. + */ FT_EXPORT( FT_Error ) FT_Done_MM_Var( FT_Library library, FT_MM_Var *amaster ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Set_MM_Design_Coordinates */ - /* */ - /* <Description> */ - /* 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. */ - /* */ - /* <InOut> */ - /* face :: A handle to the source face. */ - /* */ - /* <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. */ - /* */ - /* coords :: An array of design coordinates. */ - /* */ - /* <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] 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. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Set_MM_Design_Coordinates + * + * @Description: + * 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. + * + * @InOut: + * face :: + * A handle to the source face. + * + * @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. + * + * coords :: + * An array of design coordinates. + * + * @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] 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, FT_UInt num_coords, FT_Long* coords ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Set_Var_Design_Coordinates */ - /* */ - /* <Description> */ - /* Choose an interpolated font design through design coordinates. */ - /* */ - /* This function works with all supported variation formats. */ - /* */ - /* <InOut> */ - /* face :: A handle to the source face. */ - /* */ - /* <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. */ - /* */ - /* coords :: An array of design coordinates. */ - /* */ - /* <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 */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Set_Var_Design_Coordinates + * + * @Description: + * Choose an interpolated font design through design coordinates. + * + * This function works with all supported variation formats. + * + * @InOut: + * face :: + * A handle to the source face. + * + * @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. + * + * coords :: + * An array of design coordinates. + * + * @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 + * 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. + */ FT_EXPORT( FT_Error ) FT_Set_Var_Design_Coordinates( FT_Face face, FT_UInt num_coords, FT_Fixed* coords ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Get_Var_Design_Coordinates */ - /* */ - /* <Description> */ - /* Get the design coordinates of the currently selected interpolated */ - /* font. */ - /* */ - /* This function works with all supported variation formats. */ - /* */ - /* <Input> */ - /* face :: 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. */ - /* */ - /* <Output> */ - /* coords :: The design coordinates array. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ - /* <Since> */ - /* 2.7.1 */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Get_Var_Design_Coordinates + * + * @Description: + * Get the design coordinates of the currently selected interpolated + * font. + * + * This function works with all supported variation formats. + * + * @Input: + * face :: + * 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. + * + * @Output: + * coords :: + * The design coordinates array. + * + * @Return: + * FreeType error code. 0~means success. + * + * @Since: + * 2.7.1 + */ FT_EXPORT( FT_Error ) FT_Get_Var_Design_Coordinates( FT_Face face, FT_UInt num_coords, FT_Fixed* coords ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Set_MM_Blend_Coordinates */ - /* */ - /* <Description> */ - /* Choose an interpolated font design through normalized blend */ - /* coordinates. */ - /* */ - /* This function works with all supported variation formats. */ - /* */ - /* <InOut> */ - /* face :: A handle to the source face. */ - /* */ - /* <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. */ - /* */ - /* 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). */ - /* */ - /* <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 */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Set_MM_Blend_Coordinates + * + * @Description: + * Choose an interpolated font design through normalized blend + * coordinates. + * + * This function works with all supported variation formats. + * + * @InOut: + * face :: + * A handle to the source face. + * + * @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. + * + * 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). + * + * @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 + * 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. + */ FT_EXPORT( FT_Error ) FT_Set_MM_Blend_Coordinates( FT_Face face, FT_UInt num_coords, FT_Fixed* coords ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Get_MM_Blend_Coordinates */ - /* */ - /* <Description> */ - /* Get the normalized blend coordinates of the currently selected */ - /* interpolated font. */ - /* */ - /* This function works with all supported variation formats. */ - /* */ - /* <Input> */ - /* face :: 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. */ - /* */ - /* <Output> */ - /* coords :: The normalized blend coordinates array. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ - /* <Since> */ - /* 2.7.1 */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Get_MM_Blend_Coordinates + * + * @Description: + * Get the normalized blend coordinates of the currently selected + * interpolated font. + * + * This function works with all supported variation formats. + * + * @Input: + * face :: + * 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. + * + * @Output: + * coords :: + * The normalized blend coordinates array. + * + * @Return: + * FreeType error code. 0~means success. + * + * @Since: + * 2.7.1 + */ FT_EXPORT( FT_Error ) FT_Get_MM_Blend_Coordinates( FT_Face face, FT_UInt num_coords, FT_Fixed* coords ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Set_Var_Blend_Coordinates */ - /* */ - /* <Description> */ - /* This is another name of @FT_Set_MM_Blend_Coordinates. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Set_Var_Blend_Coordinates + * + * @Description: + * This is another name of @FT_Set_MM_Blend_Coordinates. + */ FT_EXPORT( FT_Error ) FT_Set_Var_Blend_Coordinates( FT_Face face, FT_UInt num_coords, FT_Fixed* coords ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Get_Var_Blend_Coordinates */ - /* */ - /* <Description> */ - /* This is another name of @FT_Get_MM_Blend_Coordinates. */ - /* */ - /* <Since> */ - /* 2.7.1 */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Get_Var_Blend_Coordinates + * + * @Description: + * This is another name of @FT_Get_MM_Blend_Coordinates. + * + * @Since: + * 2.7.1 + */ FT_EXPORT( FT_Error ) FT_Get_Var_Blend_Coordinates( FT_Face face, FT_UInt num_coords, FT_Fixed* coords ); - /*************************************************************************/ - /* */ - /* <Enum> */ - /* FT_VAR_AXIS_FLAG_XXX */ - /* */ - /* <Description> */ - /* A list of bit flags used in the return value of */ - /* @FT_Get_Var_Axis_Flags. */ - /* */ - /* <Values> */ - /* FT_VAR_AXIS_FLAG_HIDDEN :: */ - /* The variation axis should not be exposed to user interfaces. */ - /* */ - /* <Since> */ - /* 2.8.1 */ - /* */ + /************************************************************************** + * + * @Enum: + * FT_VAR_AXIS_FLAG_XXX + * + * @Description: + * A list of bit flags used in the return value of + * @FT_Get_Var_Axis_Flags. + * + * @Values: + * FT_VAR_AXIS_FLAG_HIDDEN :: + * The variation axis should not be exposed to user interfaces. + * + * @Since: + * 2.8.1 + */ #define FT_VAR_AXIS_FLAG_HIDDEN 1 - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Get_Var_Axis_Flags */ - /* */ - /* <Description> */ - /* Get the `flags' field of an OpenType Variation Axis Record. */ - /* */ - /* Not meaningful for Adobe MM fonts (`*flags' is always zero). */ - /* */ - /* <Input> */ - /* master :: The variation descriptor. */ - /* */ - /* axis_index :: The index of the requested variation axis. */ - /* */ - /* <Output> */ - /* flags :: The `flags' field. See @FT_VAR_AXIS_FLAG_XXX for */ - /* possible values. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ - /* <Since> */ - /* 2.8.1 */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Get_Var_Axis_Flags + * + * @Description: + * Get the `flags' field of an OpenType Variation Axis Record. + * + * Not meaningful for Adobe MM fonts (`*flags' is always zero). + * + * @Input: + * master :: + * The variation descriptor. + * + * axis_index :: + * The index of the requested variation axis. + * + * @Output: + * flags :: + * The `flags' field. See @FT_VAR_AXIS_FLAG_XXX for + * possible values. + * + * @Return: + * FreeType error code. 0~means success. + * + * @Since: + * 2.8.1 + */ FT_EXPORT( FT_Error ) FT_Get_Var_Axis_Flags( FT_MM_Var* master, FT_UInt axis_index, FT_UInt* flags ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Set_Named_Instance */ - /* */ - /* <Description> */ - /* Set or change the current named instance. */ - /* */ - /* <Input> */ - /* face :: 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 */ - /* 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. */ - /* */ - /* <Since> */ - /* 2.9 */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Set_Named_Instance + * + * @Description: + * Set or change the current named instance. + * + * @Input: + * face :: + * 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 + * 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. + * + * @Since: + * 2.9 + */ FT_EXPORT( FT_Error ) FT_Set_Named_Instance( FT_Face face, FT_UInt instance_index ); diff --git a/include/freetype/ftmodapi.h b/include/freetype/ftmodapi.h index a6eb876eb..16934118f 100644 --- a/include/freetype/ftmodapi.h +++ b/include/freetype/ftmodapi.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftmodapi.h */ -/* */ -/* FreeType modules public interface (specification). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftmodapi.h + * + * FreeType modules public interface (specification). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTMODAPI_H_ @@ -33,77 +33,77 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* module_management */ - /* */ - /* <Title> */ - /* Module Management */ - /* */ - /* <Abstract> */ - /* How to add, upgrade, remove, and control modules from FreeType. */ - /* */ - /* <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. */ - /* */ - /* Here is a list of possible values of the `module_name' field in */ - /* the @FT_Module_Class structure. */ - /* */ - /* { */ - /* autofitter */ - /* bdf */ - /* cff */ - /* gxvalid */ - /* otvalid */ - /* pcf */ - /* pfr */ - /* psaux */ - /* pshinter */ - /* psnames */ - /* raster1 */ - /* sfnt */ - /* smooth, smooth-lcd, smooth-lcdv */ - /* truetype */ - /* type1 */ - /* type42 */ - /* t1cid */ - /* winfonts */ - /* } */ - /* */ - /* Note that the FreeType Cache sub-system is not a FreeType module. */ - /* */ - /* <Order> */ - /* FT_Module */ - /* FT_Module_Constructor */ - /* FT_Module_Destructor */ - /* FT_Module_Requester */ - /* FT_Module_Class */ - /* */ - /* FT_Add_Module */ - /* FT_Get_Module */ - /* FT_Remove_Module */ - /* FT_Add_Default_Modules */ - /* */ - /* FT_Property_Set */ - /* FT_Property_Get */ - /* FT_Set_Default_Properties */ - /* */ - /* FT_New_Library */ - /* FT_Done_Library */ - /* FT_Reference_Library */ - /* */ - /* FT_Renderer */ - /* FT_Renderer_Class */ - /* */ - /* FT_Get_Renderer */ - /* FT_Set_Renderer */ - /* */ - /* FT_Set_Debug_Hook */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * module_management + * + * @Title: + * Module Management + * + * @Abstract: + * How to add, upgrade, remove, and control modules from FreeType. + * + * @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. + * + * Here is a list of possible values of the `module_name' field in + * the @FT_Module_Class structure. + * + * { + * autofitter + * bdf + * cff + * gxvalid + * otvalid + * pcf + * pfr + * psaux + * pshinter + * psnames + * raster1 + * sfnt + * smooth, smooth-lcd, smooth-lcdv + * truetype + * type1 + * type42 + * t1cid + * winfonts + * } + * + * Note that the FreeType Cache sub-system is not a FreeType module. + * + * @Order: + * FT_Module + * FT_Module_Constructor + * FT_Module_Destructor + * FT_Module_Requester + * FT_Module_Class + * + * FT_Add_Module + * FT_Get_Module + * FT_Remove_Module + * FT_Add_Default_Modules + * + * FT_Property_Set + * FT_Property_Get + * FT_Set_Default_Properties + * + * FT_New_Library + * FT_Done_Library + * FT_Reference_Library + * + * FT_Renderer + * FT_Renderer_Class + * + * FT_Get_Renderer + * FT_Set_Renderer + * + * FT_Set_Debug_Hook + * + */ /* module bit flags */ @@ -137,83 +137,95 @@ FT_BEGIN_HEADER typedef FT_Pointer FT_Module_Interface; - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* FT_Module_Constructor */ - /* */ - /* <Description> */ - /* A function used to initialize (not create) a new module object. */ - /* */ - /* <Input> */ - /* module :: The module to initialize. */ - /* */ + /************************************************************************** + * + * @FuncType: + * FT_Module_Constructor + * + * @Description: + * A function used to initialize (not create) a new module object. + * + * @Input: + * module :: + * The module to initialize. + */ typedef FT_Error (*FT_Module_Constructor)( FT_Module module ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* FT_Module_Destructor */ - /* */ - /* <Description> */ - /* A function used to finalize (not destroy) a given module object. */ - /* */ - /* <Input> */ - /* module :: The module to finalize. */ - /* */ + /************************************************************************** + * + * @FuncType: + * FT_Module_Destructor + * + * @Description: + * A function used to finalize (not destroy) a given module object. + * + * @Input: + * module :: + * The module to finalize. + */ typedef void (*FT_Module_Destructor)( FT_Module module ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* FT_Module_Requester */ - /* */ - /* <Description> */ - /* A function used to query a given module for a specific interface. */ - /* */ - /* <Input> */ - /* module :: The module to be searched. */ - /* */ - /* name :: The name of the interface in the module. */ - /* */ + /************************************************************************** + * + * @FuncType: + * FT_Module_Requester + * + * @Description: + * A function used to query a given module for a specific interface. + * + * @Input: + * module :: + * The module to be searched. + * + * name :: + * The name of the interface in the module. + */ typedef FT_Module_Interface (*FT_Module_Requester)( FT_Module module, const char* name ); - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_Module_Class */ - /* */ - /* <Description> */ - /* The module class descriptor. */ - /* */ - /* <Fields> */ - /* module_flags :: Bit flags describing the module. */ - /* */ - /* module_size :: The size of one module object/instance in */ - /* bytes. */ - /* */ - /* module_name :: The name of the module. */ - /* */ - /* module_version :: The version, as a 16.16 fixed number */ - /* (major.minor). */ - /* */ - /* module_requires :: The version of FreeType this module requires, */ - /* as a 16.16 fixed number (major.minor). Starts */ - /* at version 2.0, i.e., 0x20000. */ - /* */ - /* module_init :: The initializing function. */ - /* */ - /* module_done :: The finalizing function. */ - /* */ - /* get_interface :: The interface requesting function. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_Module_Class + * + * @Description: + * The module class descriptor. + * + * @Fields: + * module_flags :: + * Bit flags describing the module. + * + * module_size :: + * The size of one module object/instance in + * bytes. + * + * module_name :: + * The name of the module. + * + * module_version :: + * The version, as a 16.16 fixed number + * (major.minor). + * + * module_requires :: + * The version of FreeType this module requires, + * as a 16.16 fixed number (major.minor). Starts + * at version 2.0, i.e., 0x20000. + * + * module_init :: + * The initializing function. + * + * module_done :: + * The finalizing function. + * + * get_interface :: + * The interface requesting function. + */ typedef struct FT_Module_Class_ { FT_ULong module_flags; @@ -231,77 +243,83 @@ FT_BEGIN_HEADER } FT_Module_Class; - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Add_Module */ - /* */ - /* <Description> */ - /* Add a new module to a given library instance. */ - /* */ - /* <InOut> */ - /* library :: A handle to the library object. */ - /* */ - /* <Input> */ - /* clazz :: A pointer to class descriptor for the module. */ - /* */ - /* <Return> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Add_Module + * + * @Description: + * Add a new module to a given library instance. + * + * @InOut: + * library :: + * A handle to the library object. + * + * @Input: + * clazz :: + * A pointer to class descriptor for the module. + * + * @Return: + * 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. + */ FT_EXPORT( FT_Error ) FT_Add_Module( FT_Library library, const FT_Module_Class* clazz ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Get_Module */ - /* */ - /* <Description> */ - /* Find a module by its name. */ - /* */ - /* <Input> */ - /* library :: A handle to the library object. */ - /* */ - /* module_name :: The module's name (as an ASCII string). */ - /* */ - /* <Return> */ - /* A module handle. 0~if none was found. */ - /* */ - /* <Note> */ - /* FreeType's internal modules aren't documented very well, and you */ - /* should look up the source code for details. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Get_Module + * + * @Description: + * Find a module by its name. + * + * @Input: + * library :: + * A handle to the library object. + * + * module_name :: + * The module's name (as an ASCII string). + * + * @Return: + * A module handle. 0~if none was found. + * + * @Note: + * FreeType's internal modules aren't documented very well, and you + * should look up the source code for details. + */ FT_EXPORT( FT_Module ) FT_Get_Module( FT_Library library, const char* module_name ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Remove_Module */ - /* */ - /* <Description> */ - /* Remove a given module from a library instance. */ - /* */ - /* <InOut> */ - /* library :: A handle to a library object. */ - /* */ - /* <Input> */ - /* module :: A handle to a module object. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ - /* <Note> */ - /* The module object is destroyed by the function in case of success. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Remove_Module + * + * @Description: + * Remove a given module from a library instance. + * + * @InOut: + * library :: + * A handle to a library object. + * + * @Input: + * module :: + * A handle to a module object. + * + * @Return: + * FreeType error code. 0~means success. + * + * @Note: + * The module object is destroyed by the function in case of success. + */ FT_EXPORT( FT_Error ) FT_Remove_Module( FT_Library library, FT_Module module ); @@ -317,21 +335,21 @@ FT_BEGIN_HEADER * * @input: * library :: - * A handle to the library the module is part of. + * A handle to the library the module is part of. * * module_name :: - * The module name. + * The module name. * * property_name :: - * The property name. Properties are described in section - * @properties. + * The property name. Properties are described in section + * @properties. * - * Note that only a few modules have properties. + * Note that only a few modules have properties. * * value :: - * A generic pointer to a variable or structure that gives the new - * 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 new + * value of the property. The exact definition of `value' is + * dependent on the property; see section @properties. * * @return: * FreeType error code. 0~means success. @@ -383,20 +401,20 @@ FT_BEGIN_HEADER * * @input: * library :: - * A handle to the library the module is part of. + * A handle to the library the module is part of. * * module_name :: - * The module name. + * The module name. * * property_name :: - * The property name. Properties are described in section - * @properties. + * The property name. Properties are described in section + * @properties. * * @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. @@ -436,134 +454,139 @@ FT_BEGIN_HEADER void* value ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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 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). */ - /* */ - /* { */ - /* <optional whitespace> */ - /* <module-name1> ':' */ - /* <property-name1> '=' <property-value1> */ - /* <whitespace> */ - /* <module-name2> ':' */ - /* <property-name2> '=' <property-value2> */ - /* ... */ - /* } */ - /* */ - /* Example: */ - /* */ - /* { */ - /* FREETYPE_PROPERTIES=truetype:interpreter-version=35 \ */ - /* cff:no-stem-darkening=1 \ */ - /* autofitter:warping=1 */ - /* } */ - /* */ - /* <InOut> */ - /* library :: A handle to a new library object. */ - /* */ - /* <Since> */ - /* 2.8 */ - /* */ + /************************************************************************** + * + * @Function: + * 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 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). + * + * { + * <optional whitespace> + * <module-name1> ':' + * <property-name1> '=' <property-value1> + * <whitespace> + * <module-name2> ':' + * <property-name2> '=' <property-value2> + * ... + * } + * + * Example: + * + * { + * FREETYPE_PROPERTIES=truetype:interpreter-version=35 \ + * cff:no-stem-darkening=1 \ + * autofitter:warping=1 + * } + * + * @InOut: + * library :: + * A handle to a new library object. + * + * @Since: + * 2.8 + */ FT_EXPORT( void ) FT_Set_Default_Properties( FT_Library library ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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. */ - /* */ - /* This function helps in managing life-cycles of structures that */ - /* reference @FT_Library objects. */ - /* */ - /* <Input> */ - /* library :: A handle to a target library object. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ - /* <Since> */ - /* 2.4.2 */ - /* */ + /************************************************************************** + * + * @Function: + * 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. + * + * This function helps in managing life-cycles of structures that + * reference @FT_Library objects. + * + * @Input: + * library :: + * A handle to a target library object. + * + * @Return: + * FreeType error code. 0~means success. + * + * @Since: + * 2.4.2 + */ FT_EXPORT( FT_Error ) FT_Reference_Library( FT_Library library ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* Don't use @FT_Done_FreeType but @FT_Done_Library to destroy a */ - /* library instance. */ - /* */ - /* <Input> */ - /* memory :: A handle to the original memory object. */ - /* */ - /* <Output> */ - /* alibrary :: A pointer to handle of a new library object. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ - /* <Note> */ - /* See the discussion of reference counters in the description of */ - /* @FT_Reference_Library. */ - /* */ + /************************************************************************** + * + * @Function: + * 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. + * + * 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. + * + * Don't use @FT_Done_FreeType but @FT_Done_Library to destroy a + * library instance. + * + * @Input: + * memory :: + * A handle to the original memory object. + * + * @Output: + * alibrary :: + * A pointer to handle of a new library object. + * + * @Return: + * FreeType error code. 0~means success. + * + * @Note: + * See the discussion of reference counters in the description of + * @FT_Reference_Library. + */ FT_EXPORT( FT_Error ) FT_New_Library( FT_Memory memory, FT_Library *alibrary ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Done_Library */ - /* */ - /* <Description> */ - /* Discard a given library object. This closes all drivers and */ - /* discards all resource objects. */ - /* */ - /* <Input> */ - /* library :: A handle to the target library. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ - /* <Note> */ - /* See the discussion of reference counters in the description of */ - /* @FT_Reference_Library. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Done_Library + * + * @Description: + * Discard a given library object. This closes all drivers and + * discards all resource objects. + * + * @Input: + * library :: + * A handle to the target library. + * + * @Return: + * FreeType error code. 0~means success. + * + * @Note: + * See the discussion of reference counters in the description of + * @FT_Reference_Library. + */ FT_EXPORT( FT_Error ) FT_Done_Library( FT_Library library ); @@ -573,52 +596,56 @@ FT_BEGIN_HEADER (*FT_DebugHook_Func)( void* arg ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Set_Debug_Hook */ - /* */ - /* <Description> */ - /* Set a debug hook function for debugging the interpreter of a font */ - /* format. */ - /* */ - /* <InOut> */ - /* library :: A handle to the library object. */ - /* */ - /* <Input> */ - /* hook_index :: 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. */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Set_Debug_Hook + * + * @Description: + * Set a debug hook function for debugging the interpreter of a font + * format. + * + * @InOut: + * library :: + * A handle to the library object. + * + * @Input: + * hook_index :: + * 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. + * + * Since the internal headers of FreeType are no longer installed, + * the symbol `FT_DEBUG_HOOK_TRUETYPE' isn't available publicly. + * This is a bug and will be fixed in a forthcoming release. + */ FT_EXPORT( void ) FT_Set_Debug_Hook( FT_Library library, FT_UInt hook_index, FT_DebugHook_Func debug_hook ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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). */ - /* */ - /* <InOut> */ - /* library :: A handle to a new library object. */ - /* */ + /************************************************************************** + * + * @Function: + * 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). + * + * @InOut: + * library :: + * A handle to a new library object. + */ FT_EXPORT( void ) FT_Add_Default_Modules( FT_Library library ); diff --git a/include/freetype/ftmoderr.h b/include/freetype/ftmoderr.h index e0fc1312b..1f71633c0 100644 --- a/include/freetype/ftmoderr.h +++ b/include/freetype/ftmoderr.h @@ -1,94 +1,94 @@ -/***************************************************************************/ -/* */ -/* ftmoderr.h */ -/* */ -/* FreeType module error offsets (specification). */ -/* */ -/* Copyright 2001-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ - - - /*************************************************************************/ - /* */ - /* 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, */ - /* 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. */ - /* */ - /* 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 */ - /* */ - /* error = FT_ERR( Invalid_Outline ); */ - /* */ - /* expands to */ - /* */ - /* error = BDF_Err_Invalid_Outline; */ - /* */ - /* 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: */ - /* */ - /* 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 */ - /* */ - /* if ( error == FT_Err_Invalid_Outline ) */ - /* ... */ - /* */ - /* 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 */ - /* */ - /* { */ - /* #undef FTMODERR_H_ */ - /* #define FT_MODERRDEF( e, v, s ) { FT_Mod_Err_ ## e, s }, */ - /* #define FT_MODERR_START_LIST { */ - /* #define FT_MODERR_END_LIST { 0, 0 } }; */ - /* */ - /* const struct */ - /* { */ - /* int mod_err_offset; */ - /* const char* mod_err_msg */ - /* } ft_mod_errors[] = */ - /* */ - /* #include FT_MODULE_ERRORS_H */ - /* } */ - /* */ - /*************************************************************************/ +/**************************************************************************** + * + * ftmoderr.h + * + * FreeType module error offsets (specification). + * + * Copyright 2001-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ + + + /************************************************************************** + * + * 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, + * 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. + * + * 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 + * + * error = FT_ERR( Invalid_Outline ); + * + * expands to + * + * error = BDF_Err_Invalid_Outline; + * + * 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: + * + * 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 + * + * if ( error == FT_Err_Invalid_Outline ) + * ... + * + * 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 + * + * { + * #undef FTMODERR_H_ + * #define FT_MODERRDEF( e, v, s ) { FT_Mod_Err_ ## e, s }, + * #define FT_MODERR_START_LIST { + * #define FT_MODERR_END_LIST { 0, 0 } }; + * + * const struct + * { + * int mod_err_offset; + * const char* mod_err_msg + * } ft_mod_errors[] = + * + * #include FT_MODULE_ERRORS_H + * } + * + */ #ifndef FTMODERR_H_ diff --git a/include/freetype/ftotval.h b/include/freetype/ftotval.h index 26731c2b9..526f1acfe 100644 --- a/include/freetype/ftotval.h +++ b/include/freetype/ftotval.h @@ -1,30 +1,30 @@ -/***************************************************************************/ -/* */ -/* ftotval.h */ -/* */ -/* FreeType API for validating OpenType tables (specification). */ -/* */ -/* Copyright 2004-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ - - -/***************************************************************************/ -/* */ -/* */ -/* Warning: This module might be moved to a different library in the */ -/* future to avoid a tight dependency between FreeType and the */ -/* OpenType specification. */ -/* */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftotval.h + * + * FreeType API for validating OpenType tables (specification). + * + * Copyright 2004-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ + + +/**************************************************************************** + * + * + * Warning: This module might be moved to a different library in the + * future to avoid a tight dependency between FreeType and the + * OpenType specification. + * + * + */ #ifndef FTOTVAL_H_ @@ -43,28 +43,28 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* ot_validation */ - /* */ - /* <Title> */ - /* OpenType Validation */ - /* */ - /* <Abstract> */ - /* 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). */ - /* */ - /* <Order> */ - /* FT_OpenType_Validate */ - /* FT_OpenType_Free */ - /* */ - /* FT_VALIDATE_OTXXX */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * ot_validation + * + * @Title: + * OpenType Validation + * + * @Abstract: + * 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). + * + * @Order: + * FT_OpenType_Validate + * FT_OpenType_Free + * + * FT_VALIDATE_OTXXX + * + */ /********************************************************************** @@ -126,27 +126,27 @@ FT_BEGIN_HEADER * * @input: * face :: - * A handle to the input face. + * A handle to the input face. * * validation_flags :: - * A bit field that specifies the tables to be validated. See - * @FT_VALIDATE_OTXXX for possible values. + * A bit field that specifies the tables to be validated. See + * @FT_VALIDATE_OTXXX for possible values. * * @output: * BASE_table :: - * A pointer to the BASE table. + * A pointer to the BASE table. * * GDEF_table :: - * A pointer to the GDEF table. + * A pointer to the GDEF table. * * GPOS_table :: - * A pointer to the GPOS table. + * A pointer to the GPOS table. * * GSUB_table :: - * A pointer to the GSUB table. + * A pointer to the GSUB table. * * JSTF_table :: - * A pointer to the JSTF table. + * A pointer to the JSTF table. * * @return: * FreeType error code. 0~means success. @@ -179,11 +179,11 @@ FT_BEGIN_HEADER * * @input: * face :: - * A handle to the input face. + * A handle to the input face. * * table :: - * The pointer to the buffer that is allocated by - * @FT_OpenType_Validate. + * The pointer to the buffer that is allocated by + * @FT_OpenType_Validate. * * @note: * This function must be used to free the buffer allocated by diff --git a/include/freetype/ftoutln.h b/include/freetype/ftoutln.h index 89389a49b..4720e8d34 100644 --- a/include/freetype/ftoutln.h +++ b/include/freetype/ftoutln.h @@ -1,20 +1,20 @@ -/***************************************************************************/ -/* */ -/* ftoutln.h */ -/* */ -/* Support for the FT_Outline type used to store glyph shapes of */ -/* most scalable font formats (specification). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftoutln.h + * + * Support for the FT_Outline type used to store glyph shapes of + * most scalable font formats (specification). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTOUTLN_H_ @@ -34,127 +34,134 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* outline_processing */ - /* */ - /* <Title> */ - /* Outline Processing */ - /* */ - /* <Abstract> */ - /* Functions to create, transform, and render vectorial glyph images. */ - /* */ - /* <Description> */ - /* This section contains routines used to create and destroy scalable */ - /* glyph images known as `outlines'. These can also be measured, */ - /* transformed, and converted into bitmaps and pixmaps. */ - /* */ - /* <Order> */ - /* FT_Outline */ - /* FT_Outline_New */ - /* FT_Outline_Done */ - /* FT_Outline_Copy */ - /* FT_Outline_Translate */ - /* FT_Outline_Transform */ - /* FT_Outline_Embolden */ - /* FT_Outline_EmboldenXY */ - /* FT_Outline_Reverse */ - /* FT_Outline_Check */ - /* */ - /* FT_Outline_Get_CBox */ - /* FT_Outline_Get_BBox */ - /* */ - /* FT_Outline_Get_Bitmap */ - /* FT_Outline_Render */ - /* FT_Outline_Decompose */ - /* FT_Outline_Funcs */ - /* FT_Outline_MoveToFunc */ - /* FT_Outline_LineToFunc */ - /* FT_Outline_ConicToFunc */ - /* FT_Outline_CubicToFunc */ - /* */ - /* FT_Orientation */ - /* FT_Outline_Get_Orientation */ - /* */ - /* FT_OUTLINE_XXX */ - /* */ - /*************************************************************************/ - - - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Outline_Decompose */ - /* */ - /* <Description> */ - /* Walk over an outline's structure to decompose it into individual */ - /* segments and Bezier arcs. This function also emits `move to' */ - /* operations to indicate the start of new contours in the outline. */ - /* */ - /* <Input> */ - /* outline :: A pointer to the source target. */ - /* */ - /* func_interface :: 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 */ - /* 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). */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Section: + * outline_processing + * + * @Title: + * Outline Processing + * + * @Abstract: + * Functions to create, transform, and render vectorial glyph images. + * + * @Description: + * This section contains routines used to create and destroy scalable + * glyph images known as `outlines'. These can also be measured, + * transformed, and converted into bitmaps and pixmaps. + * + * @Order: + * FT_Outline + * FT_Outline_New + * FT_Outline_Done + * FT_Outline_Copy + * FT_Outline_Translate + * FT_Outline_Transform + * FT_Outline_Embolden + * FT_Outline_EmboldenXY + * FT_Outline_Reverse + * FT_Outline_Check + * + * FT_Outline_Get_CBox + * FT_Outline_Get_BBox + * + * FT_Outline_Get_Bitmap + * FT_Outline_Render + * FT_Outline_Decompose + * FT_Outline_Funcs + * FT_Outline_MoveToFunc + * FT_Outline_LineToFunc + * FT_Outline_ConicToFunc + * FT_Outline_CubicToFunc + * + * FT_Orientation + * FT_Outline_Get_Orientation + * + * FT_OUTLINE_XXX + * + */ + + + /************************************************************************** + * + * @Function: + * FT_Outline_Decompose + * + * @Description: + * Walk over an outline's structure to decompose it into individual + * segments and Bezier arcs. This function also emits `move to' + * operations to indicate the start of new contours in the outline. + * + * @Input: + * outline :: + * A pointer to the source target. + * + * func_interface :: + * 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 + * 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). + * + * 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. + */ FT_EXPORT( FT_Error ) FT_Outline_Decompose( FT_Outline* outline, const FT_Outline_Funcs* func_interface, void* user ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Outline_New */ - /* */ - /* <Description> */ - /* Create a new outline of a given size. */ - /* */ - /* <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. */ - /* */ - /* numPoints :: 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'. */ - /* */ - /* <Output> */ - /* anoutline :: A handle to the new outline. */ - /* */ - /* <Return> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Outline_New + * + * @Description: + * Create a new outline of a given size. + * + * @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. + * + * numPoints :: + * 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'. + * + * @Output: + * anoutline :: + * A handle to the new outline. + * + * @Return: + * 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. + */ FT_EXPORT( FT_Error ) FT_Outline_New( FT_Library library, FT_UInt numPoints, @@ -169,27 +176,29 @@ FT_BEGIN_HEADER FT_Outline *anoutline ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Outline_Done */ - /* */ - /* <Description> */ - /* Destroy an outline created with @FT_Outline_New. */ - /* */ - /* <Input> */ - /* library :: A handle of the library object used to allocate the */ - /* outline. */ - /* */ - /* outline :: A pointer to the outline object to be discarded. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ - /* <Note> */ - /* If the outline's `owner' field is not set, only the outline */ - /* descriptor will be released. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Outline_Done + * + * @Description: + * Destroy an outline created with @FT_Outline_New. + * + * @Input: + * library :: + * A handle of the library object used to allocate the + * outline. + * + * outline :: + * A pointer to the outline object to be discarded. + * + * @Return: + * FreeType error code. 0~means success. + * + * @Note: + * 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, FT_Outline* outline ); @@ -200,293 +209,312 @@ FT_BEGIN_HEADER FT_Outline* outline ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Outline_Check */ - /* */ - /* <Description> */ - /* Check the contents of an outline descriptor. */ - /* */ - /* <Input> */ - /* outline :: A handle to a source outline. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ - /* <Note> */ - /* An empty outline, or an outline with a single point only is also */ - /* valid. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Outline_Check + * + * @Description: + * Check the contents of an outline descriptor. + * + * @Input: + * outline :: + * A handle to a source outline. + * + * @Return: + * FreeType error code. 0~means success. + * + * @Note: + * An empty outline, or an outline with a single point only is also + * valid. + */ FT_EXPORT( FT_Error ) FT_Outline_Check( FT_Outline* outline ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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 */ - /* 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). */ - /* */ - /* 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 :: A pointer to the source outline descriptor. */ - /* */ - /* <Output> */ - /* acbox :: The outline's control box. */ - /* */ - /* <Note> */ - /* See @FT_Glyph_Get_CBox for a discussion of tricky fonts. */ - /* */ + /************************************************************************** + * + * @Function: + * 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 + * 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). + * + * 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 :: + * A pointer to the source outline descriptor. + * + * @Output: + * acbox :: + * The outline's control box. + * + * @Note: + * See @FT_Glyph_Get_CBox for a discussion of tricky fonts. + */ FT_EXPORT( void ) FT_Outline_Get_CBox( const FT_Outline* outline, FT_BBox *acbox ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Outline_Translate */ - /* */ - /* <Description> */ - /* Apply a simple translation to the points of an outline. */ - /* */ - /* <InOut> */ - /* outline :: A pointer to the target outline descriptor. */ - /* */ - /* <Input> */ - /* xOffset :: The horizontal offset. */ - /* */ - /* yOffset :: The vertical offset. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Outline_Translate + * + * @Description: + * Apply a simple translation to the points of an outline. + * + * @InOut: + * outline :: + * A pointer to the target outline descriptor. + * + * @Input: + * xOffset :: + * The horizontal offset. + * + * yOffset :: + * The vertical offset. + */ FT_EXPORT( void ) FT_Outline_Translate( const FT_Outline* outline, FT_Pos xOffset, FT_Pos yOffset ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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. */ - /* */ - /* <Input> */ - /* source :: A handle to the source outline. */ - /* */ - /* <Output> */ - /* target :: A handle to the target outline. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ + /************************************************************************** + * + * @Function: + * 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. + * + * @Input: + * source :: + * A handle to the source outline. + * + * @Output: + * target :: + * A handle to the target outline. + * + * @Return: + * FreeType error code. 0~means success. + */ FT_EXPORT( FT_Error ) FT_Outline_Copy( const FT_Outline* source, FT_Outline *target ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Outline_Transform */ - /* */ - /* <Description> */ - /* Apply a simple 2x2 matrix to all of an outline's points. Useful */ - /* for applying rotations, slanting, flipping, etc. */ - /* */ - /* <InOut> */ - /* outline :: A pointer to the target outline descriptor. */ - /* */ - /* <Input> */ - /* matrix :: A pointer to the transformation matrix. */ - /* */ - /* <Note> */ - /* You can use @FT_Outline_Translate if you need to translate the */ - /* outline's points. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Outline_Transform + * + * @Description: + * Apply a simple 2x2 matrix to all of an outline's points. Useful + * for applying rotations, slanting, flipping, etc. + * + * @InOut: + * outline :: + * A pointer to the target outline descriptor. + * + * @Input: + * matrix :: + * A pointer to the transformation matrix. + * + * @Note: + * You can use @FT_Outline_Translate if you need to translate the + * outline's points. + */ FT_EXPORT( void ) FT_Outline_Transform( const FT_Outline* outline, const FT_Matrix* matrix ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Outline_Embolden */ - /* */ - /* <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 */ - /* bottom borders as unchanged. */ - /* */ - /* Negative `strength' values to reduce the outline thickness are */ - /* possible also. */ - /* */ - /* <InOut> */ - /* outline :: A handle to the target outline. */ - /* */ - /* <Input> */ - /* strength :: 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. */ - /* */ - /* If you need `better' metrics values you should call */ - /* @FT_Outline_Get_CBox or @FT_Outline_Get_BBox. */ - /* */ - /* Example call: */ - /* */ - /* { */ - /* FT_Load_Glyph( face, index, FT_LOAD_DEFAULT ); */ - /* if ( face->glyph->format == FT_GLYPH_FORMAT_OUTLINE ) */ - /* FT_Outline_Embolden( &face->glyph->outline, strength ); */ - /* } */ - /* */ - /* To get meaningful results, font scaling values must be set with */ - /* functions like @FT_Set_Char_Size before calling FT_Render_Glyph. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Outline_Embolden + * + * @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 + * bottom borders as unchanged. + * + * Negative `strength' values to reduce the outline thickness are + * possible also. + * + * @InOut: + * outline :: + * A handle to the target outline. + * + * @Input: + * strength :: + * 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. + * + * If you need `better' metrics values you should call + * @FT_Outline_Get_CBox or @FT_Outline_Get_BBox. + * + * Example call: + * + * { + * FT_Load_Glyph( face, index, FT_LOAD_DEFAULT ); + * if ( face->glyph->format == FT_GLYPH_FORMAT_OUTLINE ) + * FT_Outline_Embolden( &face->glyph->outline, strength ); + * } + * + * To get meaningful results, font scaling values must be set with + * functions like @FT_Set_Char_Size before calling FT_Render_Glyph. + */ FT_EXPORT( FT_Error ) FT_Outline_Embolden( FT_Outline* outline, FT_Pos strength ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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. */ - /* */ - /* <Since> */ - /* 2.4.10 */ - /* */ + /************************************************************************** + * + * @Function: + * 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. + * + * @Since: + * 2.4.10 + */ FT_EXPORT( FT_Error ) FT_Outline_EmboldenXY( FT_Outline* outline, FT_Pos xstrength, FT_Pos ystrength ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Outline_Reverse */ - /* */ - /* <Description> */ - /* 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. */ - /* */ - /* It shouldn't be used by a normal client application, unless it */ - /* knows what it is doing. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Outline_Reverse + * + * @Description: + * 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. + * + * 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 ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Outline_Get_Bitmap */ - /* */ - /* <Description> */ - /* Render an outline within a bitmap. The outline's image is simply */ - /* OR-ed to the target bitmap. */ - /* */ - /* <Input> */ - /* library :: A handle to a FreeType library object. */ - /* */ - /* outline :: A pointer to the source outline descriptor. */ - /* */ - /* <InOut> */ - /* abitmap :: A pointer to the target bitmap descriptor. */ - /* */ - /* <Return> */ - /* 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. */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Outline_Get_Bitmap + * + * @Description: + * Render an outline within a bitmap. The outline's image is simply + * OR-ed to the target bitmap. + * + * @Input: + * library :: + * A handle to a FreeType library object. + * + * outline :: + * A pointer to the source outline descriptor. + * + * @InOut: + * abitmap :: + * A pointer to the target bitmap descriptor. + * + * @Return: + * 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. + * + * 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. + */ FT_EXPORT( FT_Error ) FT_Outline_Get_Bitmap( FT_Library library, FT_Outline* outline, const FT_Bitmap *abitmap ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Outline_Render */ - /* */ - /* <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. */ - /* */ - /* <Input> */ - /* library :: A handle to a FreeType library object. */ - /* */ - /* outline :: A pointer to the source outline descriptor. */ - /* */ - /* <InOut> */ - /* params :: 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. */ - /* */ - /* 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 */ - /* @FT_Raster_Params structure for more details. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Outline_Render + * + * @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. + * + * @Input: + * library :: + * A handle to a FreeType library object. + * + * outline :: + * A pointer to the source outline descriptor. + * + * @InOut: + * params :: + * 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. + * + * 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 + * @FT_Raster_Params structure for more details. + */ FT_EXPORT( FT_Error ) FT_Outline_Render( FT_Library library, FT_Outline* outline, diff --git a/include/freetype/ftparams.h b/include/freetype/ftparams.h index 5a9006c50..a81c35356 100644 --- a/include/freetype/ftparams.h +++ b/include/freetype/ftparams.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftparams.h */ -/* */ -/* FreeType API for possible FT_Parameter tags (specification only). */ -/* */ -/* Copyright 2017-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftparams.h + * + * FreeType API for possible FT_Parameter tags (specification only). + * + * Copyright 2017-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTPARAMS_H_ diff --git a/include/freetype/ftpfr.h b/include/freetype/ftpfr.h index a69cc482d..54d0cc176 100644 --- a/include/freetype/ftpfr.h +++ b/include/freetype/ftpfr.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftpfr.h */ -/* */ -/* FreeType API for accessing PFR-specific data (specification only). */ -/* */ -/* Copyright 2002-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftpfr.h + * + * FreeType API for accessing PFR-specific data (specification only). + * + * Copyright 2002-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTPFR_H_ @@ -32,21 +32,21 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* pfr_fonts */ - /* */ - /* <Title> */ - /* PFR Fonts */ - /* */ - /* <Abstract> */ - /* PFR/TrueDoc specific API. */ - /* */ - /* <Description> */ - /* This section contains the declaration of PFR-specific functions. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * pfr_fonts + * + * @Title: + * PFR Fonts + * + * @Abstract: + * PFR/TrueDoc specific API. + * + * @Description: + * This section contains the declaration of PFR-specific functions. + * + */ /********************************************************************** @@ -58,7 +58,8 @@ FT_BEGIN_HEADER * Return the outline and metrics resolutions of a given PFR face. * * @input: - * face :: Handle to the input face. It can be a non-PFR face. + * face :: + * Handle to the input face. It can be a non-PFR face. * * @output: * aoutline_resolution :: @@ -105,14 +106,18 @@ FT_BEGIN_HEADER * @FT_Get_Kerning. * * @input: - * face :: A handle to the input face. + * face :: + * A handle to the input face. * - * left :: Index of the left glyph. + * left :: + * Index of the left glyph. * - * right :: Index of the right glyph. + * right :: + * Index of the right glyph. * * @output: - * avector :: A kerning vector. + * avector :: + * A kerning vector. * * @return: * FreeType error code. 0~means success. @@ -142,12 +147,15 @@ FT_BEGIN_HEADER * from a PFR font. * * @input: - * face :: A handle to the input face. + * face :: + * A handle to the input face. * - * gindex :: The glyph index. + * gindex :: + * The glyph index. * * @output: - * aadvance :: The glyph advance in metrics units. + * aadvance :: + * The glyph advance in metrics units. * * @return: * FreeType error code. 0~means success. diff --git a/include/freetype/ftrender.h b/include/freetype/ftrender.h index fa8ad22b9..fb0ee0860 100644 --- a/include/freetype/ftrender.h +++ b/include/freetype/ftrender.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftrender.h */ -/* */ -/* FreeType renderer modules public interface (specification). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftrender.h + * + * FreeType renderer modules public interface (specification). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTRENDER_H_ @@ -28,12 +28,12 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* module_management */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * module_management + * + */ /* create a new glyph object */ @@ -116,32 +116,39 @@ FT_BEGIN_HEADER #define FTRenderer_setMode FT_Renderer_SetModeFunc - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_Renderer_Class */ - /* */ - /* <Description> */ - /* The renderer module class descriptor. */ - /* */ - /* <Fields> */ - /* root :: The root @FT_Module_Class fields. */ - /* */ - /* glyph_format :: 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. */ - /* */ - /* transform_glyph :: 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. */ - /* */ - /* set_mode :: 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. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_Renderer_Class + * + * @Description: + * The renderer module class descriptor. + * + * @Fields: + * root :: + * The root @FT_Module_Class fields. + * + * glyph_format :: + * 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. + * + * transform_glyph :: + * 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. + * + * set_mode :: + * 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. + */ typedef struct FT_Renderer_Class_ { FT_Module_Class root; @@ -158,64 +165,70 @@ FT_BEGIN_HEADER } FT_Renderer_Class; - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Get_Renderer */ - /* */ - /* <Description> */ - /* Retrieve the current renderer for a given glyph format. */ - /* */ - /* <Input> */ - /* library :: A handle to the library object. */ - /* */ - /* format :: The glyph format. */ - /* */ - /* <Return> */ - /* 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. */ - /* */ - /* To add a new renderer, simply use @FT_Add_Module. To retrieve a */ - /* renderer by its name, use @FT_Get_Module. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Get_Renderer + * + * @Description: + * Retrieve the current renderer for a given glyph format. + * + * @Input: + * library :: + * A handle to the library object. + * + * format :: + * The glyph format. + * + * @Return: + * 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. + * + * To add a new renderer, simply use @FT_Add_Module. To retrieve a + * renderer by its name, use @FT_Get_Module. + */ FT_EXPORT( FT_Renderer ) FT_Get_Renderer( FT_Library library, FT_Glyph_Format format ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Set_Renderer */ - /* */ - /* <Description> */ - /* Set the current renderer to use, and set additional mode. */ - /* */ - /* <InOut> */ - /* library :: A handle to the library object. */ - /* */ - /* <Input> */ - /* renderer :: A handle to the renderer object. */ - /* */ - /* num_params :: The number of additional parameters. */ - /* */ - /* parameters :: Additional parameters. */ - /* */ - /* <Return> */ - /* 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. */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Set_Renderer + * + * @Description: + * Set the current renderer to use, and set additional mode. + * + * @InOut: + * library :: + * A handle to the library object. + * + * @Input: + * renderer :: + * A handle to the renderer object. + * + * num_params :: + * The number of additional parameters. + * + * parameters :: + * Additional parameters. + * + * @Return: + * 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. + * + * 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. + */ FT_EXPORT( FT_Error ) FT_Set_Renderer( FT_Library library, FT_Renderer renderer, diff --git a/include/freetype/ftsizes.h b/include/freetype/ftsizes.h index 72cb08bf2..cf3b16363 100644 --- a/include/freetype/ftsizes.h +++ b/include/freetype/ftsizes.h @@ -1,28 +1,28 @@ -/***************************************************************************/ -/* */ -/* ftsizes.h */ -/* */ -/* FreeType size objects management (specification). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ - - - /*************************************************************************/ - /* */ - /* 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. */ - /* */ - /*************************************************************************/ +/**************************************************************************** + * + * ftsizes.h + * + * FreeType size objects management (specification). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ + + + /************************************************************************** + * + * 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. + * + */ #ifndef FTSIZES_H_ @@ -42,109 +42,113 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* sizes_management */ - /* */ - /* <Title> */ - /* Size Management */ - /* */ - /* <Abstract> */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 99% of applications won't need the functions provided here, */ - /* especially if they use the caching sub-system, so be cautious */ - /* when using these. */ - /* */ - /*************************************************************************/ - - - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_New_Size */ - /* */ - /* <Description> */ - /* Create a new size object from a given face object. */ - /* */ - /* <Input> */ - /* face :: A handle to a parent face object. */ - /* */ - /* <Output> */ - /* asize :: A handle to a new size object. */ - /* */ - /* <Return> */ - /* 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, */ - /* @FT_Load_Glyph, @FT_Load_Char, etc. */ - /* */ + /************************************************************************** + * + * @Section: + * sizes_management + * + * @Title: + * Size Management + * + * @Abstract: + * 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. + * + * 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. + * + * 99% of applications won't need the functions provided here, + * especially if they use the caching sub-system, so be cautious + * when using these. + * + */ + + + /************************************************************************** + * + * @Function: + * FT_New_Size + * + * @Description: + * Create a new size object from a given face object. + * + * @Input: + * face :: + * A handle to a parent face object. + * + * @Output: + * asize :: + * A handle to a new size object. + * + * @Return: + * 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, + * @FT_Load_Glyph, @FT_Load_Char, etc. + */ FT_EXPORT( FT_Error ) FT_New_Size( FT_Face face, FT_Size* size ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Done_Size */ - /* */ - /* <Description> */ - /* Discard a given size object. Note that @FT_Done_Face */ - /* automatically discards all size objects allocated with */ - /* @FT_New_Size. */ - /* */ - /* <Input> */ - /* size :: A handle to a target size object. */ - /* */ - /* <Return> */ - /* FreeType error code. 0~means success. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Done_Size + * + * @Description: + * Discard a given size object. Note that @FT_Done_Face + * automatically discards all size objects allocated with + * @FT_New_Size. + * + * @Input: + * size :: + * A handle to a target size object. + * + * @Return: + * FreeType error code. 0~means success. + */ FT_EXPORT( FT_Error ) FT_Done_Size( FT_Size size ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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'. */ - /* */ - /* This function can be used to `activate' a previously created size */ - /* object. */ - /* */ - /* <Input> */ - /* size :: A handle to a target size object. */ - /* */ - /* <Return> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Function: + * 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'. + * + * This function can be used to `activate' a previously created size + * object. + * + * @Input: + * size :: + * A handle to a target size object. + * + * @Return: + * 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. + */ FT_EXPORT( FT_Error ) FT_Activate_Size( FT_Size size ); diff --git a/include/freetype/ftsnames.h b/include/freetype/ftsnames.h index 3aa0d0850..d98ad2cb6 100644 --- a/include/freetype/ftsnames.h +++ b/include/freetype/ftsnames.h @@ -1,22 +1,22 @@ -/***************************************************************************/ -/* */ -/* ftsnames.h */ -/* */ -/* 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! */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftsnames.h + * + * 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! + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTSNAMES_H_ @@ -37,72 +37,78 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* sfnt_names */ - /* */ - /* <Title> */ - /* SFNT Names */ - /* */ - /* <Abstract> */ - /* 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 definitions below are used to access them if available. */ - /* */ - /* Note that this has nothing to do with glyph names! */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * sfnt_names + * + * @Title: + * SFNT Names + * + * @Abstract: + * 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 definitions below are used to access them if available. + * + * Note that this has nothing to do with glyph names! + * + */ - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_SfntName */ - /* */ - /* <Description> */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* language_id :: 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. */ - /* */ - /* name_id :: 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. */ - /* */ - /* string_len :: The length of `string' in bytes. */ - /* */ - /* <Note> */ - /* Please refer to the TrueType or OpenType specification for more */ - /* details. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_SfntName + * + * @Description: + * 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. + * + * 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. + * + * language_id :: + * 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. + * + * name_id :: + * 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. + * + * string_len :: + * The length of `string' in bytes. + * + * @Note: + * Please refer to the TrueType or OpenType specification for more + * details. + */ typedef struct FT_SfntName_ { FT_UShort platform_id; @@ -116,90 +122,96 @@ FT_BEGIN_HEADER } FT_SfntName; - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Get_Sfnt_Name_Count */ - /* */ - /* <Description> */ - /* 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. */ - /* */ - /* <Note> */ - /* This function always returns an error if the config macro */ - /* `TT_CONFIG_OPTION_SFNT_NAMES' is not defined in `ftoption.h'. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Get_Sfnt_Name_Count + * + * @Description: + * 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. + * + * @Note: + * This function always returns an error if the config macro + * `TT_CONFIG_OPTION_SFNT_NAMES' is not defined in `ftoption.h'. + */ FT_EXPORT( FT_UInt ) FT_Get_Sfnt_Name_Count( FT_Face face ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Get_Sfnt_Name */ - /* */ - /* <Description> */ - /* 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. */ - /* */ - /* <Output> */ - /* aname :: The indexed @FT_SfntName structure. */ - /* */ - /* <Return> */ - /* 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. */ - /* */ - /* 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 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'. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Get_Sfnt_Name + * + * @Description: + * 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. + * + * @Output: + * aname :: + * The indexed @FT_SfntName structure. + * + * @Return: + * 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. + * + * 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 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'. + */ FT_EXPORT( FT_Error ) FT_Get_Sfnt_Name( FT_Face face, FT_UInt idx, FT_SfntName *aname ); - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_SfntLangTag */ - /* */ - /* <Description> */ - /* 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). */ - /* */ - /* string_len :: The length of `string' in *bytes*. */ - /* */ - /* <Note> */ - /* Please refer to the TrueType or OpenType specification for more */ - /* details. */ - /* */ - /* <Since> */ - /* 2.8 */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_SfntLangTag + * + * @Description: + * 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). + * + * string_len :: + * The length of `string' in *bytes*. + * + * @Note: + * Please refer to the TrueType or OpenType specification for more + * details. + * + * @Since: + * 2.8 + */ typedef struct FT_SfntLangTag_ { FT_Byte* string; /* this string is *not* null-terminated! */ @@ -208,44 +220,47 @@ FT_BEGIN_HEADER } FT_SfntLangTag; - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Get_Sfnt_LangTag */ - /* */ - /* <Description> */ - /* Retrieve the language tag associated with a language ID of an SFNT */ - /* `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. */ - /* */ - /* <Output> */ - /* alangTag :: 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. */ - /* */ - /* 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'. */ - /* */ - /* <Since> */ - /* 2.8 */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Get_Sfnt_LangTag + * + * @Description: + * Retrieve the language tag associated with a language ID of an SFNT + * `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. + * + * @Output: + * alangTag :: + * 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. + * + * 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'. + * + * @Since: + * 2.8 + */ FT_EXPORT( FT_Error ) FT_Get_Sfnt_LangTag( FT_Face face, FT_UInt langID, diff --git a/include/freetype/ftstroke.h b/include/freetype/ftstroke.h index 44b6fbe19..177f8c983 100644 --- a/include/freetype/ftstroke.h +++ b/include/freetype/ftstroke.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftstroke.h */ -/* */ -/* FreeType path stroker (specification). */ -/* */ -/* Copyright 2002-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftstroke.h + * + * FreeType path stroker (specification). + * + * Copyright 2002-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTSTROKE_H_ diff --git a/include/freetype/ftsynth.h b/include/freetype/ftsynth.h index ff9fb43d9..f2e785696 100644 --- a/include/freetype/ftsynth.h +++ b/include/freetype/ftsynth.h @@ -1,20 +1,20 @@ -/***************************************************************************/ -/* */ -/* ftsynth.h */ -/* */ -/* FreeType synthesizing code for emboldening and slanting */ -/* (specification). */ -/* */ -/* Copyright 2000-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftsynth.h + * + * FreeType synthesizing code for emboldening and slanting + * (specification). + * + * Copyright 2000-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ /*************************************************************************/ diff --git a/include/freetype/ftsystem.h b/include/freetype/ftsystem.h index f6b1629ef..df67f0483 100644 --- a/include/freetype/ftsystem.h +++ b/include/freetype/ftsystem.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftsystem.h */ -/* */ -/* FreeType low-level system interface definition (specification). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftsystem.h + * + * FreeType low-level system interface definition (specification). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTSYSTEM_H_ @@ -26,31 +26,31 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* system_interface */ - /* */ - /* <Title> */ - /* System Interface */ - /* */ - /* <Abstract> */ - /* 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. */ - /* */ - /*************************************************************************/ - - - /*************************************************************************/ - /* */ - /* M E M O R Y M A N A G E M E N T */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * system_interface + * + * @Title: + * System Interface + * + * @Abstract: + * 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. + * + */ + + + /************************************************************************** + * + * M E M O R Y M A N A G E M E N T + * + */ /************************************************************************* @@ -177,11 +177,11 @@ FT_BEGIN_HEADER }; - /*************************************************************************/ - /* */ - /* I / O M A N A G E M E N T */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * I / O M A N A G E M E N T + * + */ /************************************************************************* @@ -265,7 +265,7 @@ FT_BEGIN_HEADER * * @input: * stream :: - * A handle to the target stream. + * A handle to the target stream. * */ typedef void diff --git a/include/freetype/fttrigon.h b/include/freetype/fttrigon.h index 2e3f3f1f7..d3b11db15 100644 --- a/include/freetype/fttrigon.h +++ b/include/freetype/fttrigon.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* fttrigon.h */ -/* */ -/* FreeType trigonometric functions (specification). */ -/* */ -/* Copyright 2001-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * fttrigon.h + * + * FreeType trigonometric functions (specification). + * + * Copyright 2001-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTTRIGON_H_ @@ -31,12 +31,12 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* computations */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * computations + * + */ /************************************************************************* diff --git a/include/freetype/fttypes.h b/include/freetype/fttypes.h index f638c2e54..e7ff17d75 100644 --- a/include/freetype/fttypes.h +++ b/include/freetype/fttypes.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* fttypes.h */ -/* */ -/* FreeType simple types definitions (specification only). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * fttypes.h + * + * FreeType simple types definitions (specification only). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTTYPES_H_ @@ -31,326 +31,328 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* basic_types */ - /* */ - /* <Title> */ - /* Basic Data Types */ - /* */ - /* <Abstract> */ - /* The basic data types defined by the library. */ - /* */ - /* <Description> */ - /* This section contains the basic data types defined by FreeType~2, */ - /* ranging from simple scalar types to bitmap descriptors. More */ - /* font-specific structures are defined in a different section. */ - /* */ - /* <Order> */ - /* FT_Byte */ - /* FT_Bytes */ - /* FT_Char */ - /* FT_Int */ - /* FT_UInt */ - /* FT_Int16 */ - /* FT_UInt16 */ - /* FT_Int32 */ - /* FT_UInt32 */ - /* FT_Int64 */ - /* FT_UInt64 */ - /* FT_Short */ - /* FT_UShort */ - /* FT_Long */ - /* FT_ULong */ - /* FT_Bool */ - /* FT_Offset */ - /* FT_PtrDist */ - /* FT_String */ - /* FT_Tag */ - /* FT_Error */ - /* FT_Fixed */ - /* FT_Pointer */ - /* FT_Pos */ - /* FT_Vector */ - /* FT_BBox */ - /* FT_Matrix */ - /* FT_FWord */ - /* FT_UFWord */ - /* FT_F2Dot14 */ - /* FT_UnitVector */ - /* FT_F26Dot6 */ - /* FT_Data */ - /* */ - /* FT_MAKE_TAG */ - /* */ - /* FT_Generic */ - /* FT_Generic_Finalizer */ - /* */ - /* FT_Bitmap */ - /* FT_Pixel_Mode */ - /* FT_Palette_Mode */ - /* FT_Glyph_Format */ - /* FT_IMAGE_TAG */ - /* */ - /*************************************************************************/ - - - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_Bool */ - /* */ - /* <Description> */ - /* A typedef of unsigned char, used for simple booleans. As usual, */ - /* values 1 and~0 represent true and false, respectively. */ - /* */ + /************************************************************************** + * + * @Section: + * basic_types + * + * @Title: + * Basic Data Types + * + * @Abstract: + * The basic data types defined by the library. + * + * @Description: + * This section contains the basic data types defined by FreeType~2, + * ranging from simple scalar types to bitmap descriptors. More + * font-specific structures are defined in a different section. + * + * @Order: + * FT_Byte + * FT_Bytes + * FT_Char + * FT_Int + * FT_UInt + * FT_Int16 + * FT_UInt16 + * FT_Int32 + * FT_UInt32 + * FT_Int64 + * FT_UInt64 + * FT_Short + * FT_UShort + * FT_Long + * FT_ULong + * FT_Bool + * FT_Offset + * FT_PtrDist + * FT_String + * FT_Tag + * FT_Error + * FT_Fixed + * FT_Pointer + * FT_Pos + * FT_Vector + * FT_BBox + * FT_Matrix + * FT_FWord + * FT_UFWord + * FT_F2Dot14 + * FT_UnitVector + * FT_F26Dot6 + * FT_Data + * + * FT_MAKE_TAG + * + * FT_Generic + * FT_Generic_Finalizer + * + * FT_Bitmap + * FT_Pixel_Mode + * FT_Palette_Mode + * FT_Glyph_Format + * FT_IMAGE_TAG + * + */ + + + /************************************************************************** + * + * @Type: + * FT_Bool + * + * @Description: + * A typedef of unsigned char, used for simple booleans. As usual, + * values 1 and~0 represent true and false, respectively. + */ typedef unsigned char FT_Bool; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_FWord */ - /* */ - /* <Description> */ - /* A signed 16-bit integer used to store a distance in original font */ - /* units. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_FWord + * + * @Description: + * A signed 16-bit integer used to store a distance in original font + * units. + */ typedef signed short FT_FWord; /* distance in FUnits */ - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_UFWord */ - /* */ - /* <Description> */ - /* An unsigned 16-bit integer used to store a distance in original */ - /* font units. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_UFWord + * + * @Description: + * An unsigned 16-bit integer used to store a distance in original + * font units. + */ typedef unsigned short FT_UFWord; /* unsigned distance */ - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_Char */ - /* */ - /* <Description> */ - /* A simple typedef for the _signed_ char type. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_Char + * + * @Description: + * A simple typedef for the _signed_ char type. + */ typedef signed char FT_Char; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_Byte */ - /* */ - /* <Description> */ - /* A simple typedef for the _unsigned_ char type. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_Byte + * + * @Description: + * A simple typedef for the _unsigned_ char type. + */ typedef unsigned char FT_Byte; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_Bytes */ - /* */ - /* <Description> */ - /* A typedef for constant memory areas. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_Bytes + * + * @Description: + * A typedef for constant memory areas. + */ typedef const FT_Byte* FT_Bytes; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_Tag */ - /* */ - /* <Description> */ - /* A typedef for 32-bit tags (as used in the SFNT format). */ - /* */ + /************************************************************************** + * + * @Type: + * FT_Tag + * + * @Description: + * A typedef for 32-bit tags (as used in the SFNT format). + */ typedef FT_UInt32 FT_Tag; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_String */ - /* */ - /* <Description> */ - /* A simple typedef for the char type, usually used for strings. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_String + * + * @Description: + * A simple typedef for the char type, usually used for strings. + */ typedef char FT_String; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_Short */ - /* */ - /* <Description> */ - /* A typedef for signed short. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_Short + * + * @Description: + * A typedef for signed short. + */ typedef signed short FT_Short; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_UShort */ - /* */ - /* <Description> */ - /* A typedef for unsigned short. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_UShort + * + * @Description: + * A typedef for unsigned short. + */ typedef unsigned short FT_UShort; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_Int */ - /* */ - /* <Description> */ - /* A typedef for the int type. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_Int + * + * @Description: + * A typedef for the int type. + */ typedef signed int FT_Int; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_UInt */ - /* */ - /* <Description> */ - /* A typedef for the unsigned int type. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_UInt + * + * @Description: + * A typedef for the unsigned int type. + */ typedef unsigned int FT_UInt; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_Long */ - /* */ - /* <Description> */ - /* A typedef for signed long. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_Long + * + * @Description: + * A typedef for signed long. + */ typedef signed long FT_Long; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_ULong */ - /* */ - /* <Description> */ - /* A typedef for unsigned long. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_ULong + * + * @Description: + * A typedef for unsigned long. + */ typedef unsigned long FT_ULong; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_F2Dot14 */ - /* */ - /* <Description> */ - /* A signed 2.14 fixed-point type used for unit vectors. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_F2Dot14 + * + * @Description: + * A signed 2.14 fixed-point type used for unit vectors. + */ typedef signed short FT_F2Dot14; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_F26Dot6 */ - /* */ - /* <Description> */ - /* A signed 26.6 fixed-point type used for vectorial pixel */ - /* coordinates. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_F26Dot6 + * + * @Description: + * A signed 26.6 fixed-point type used for vectorial pixel + * coordinates. + */ typedef signed long FT_F26Dot6; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_Fixed */ - /* */ - /* <Description> */ - /* This type is used to store 16.16 fixed-point values, like scaling */ - /* values or matrix coefficients. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_Fixed + * + * @Description: + * This type is used to store 16.16 fixed-point values, like scaling + * values or matrix coefficients. + */ typedef signed long FT_Fixed; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_Error */ - /* */ - /* <Description> */ - /* The FreeType error code type. A value of~0 is always interpreted */ - /* as a successful operation. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_Error + * + * @Description: + * The FreeType error code type. A value of~0 is always interpreted + * as a successful operation. + */ typedef int FT_Error; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_Pointer */ - /* */ - /* <Description> */ - /* A simple typedef for a typeless pointer. */ - /* */ + /************************************************************************** + * + * @Type: + * FT_Pointer + * + * @Description: + * A simple typedef for a typeless pointer. + */ typedef void* FT_Pointer; - /*************************************************************************/ - /* */ - /* <Type> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Type: + * 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. + */ typedef size_t FT_Offset; - /*************************************************************************/ - /* */ - /* <Type> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Type: + * 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. + */ typedef ft_ptrdiff_t FT_PtrDist; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_UnitVector */ - /* */ - /* <Description> */ - /* A simple structure used to store a 2D vector unit vector. Uses */ - /* FT_F2Dot14 types. */ - /* */ - /* <Fields> */ - /* x :: Horizontal coordinate. */ - /* */ - /* y :: Vertical coordinate. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_UnitVector + * + * @Description: + * A simple structure used to store a 2D vector unit vector. Uses + * FT_F2Dot14 types. + * + * @Fields: + * x :: + * Horizontal coordinate. + * + * y :: + * Vertical coordinate. + */ typedef struct FT_UnitVector_ { FT_F2Dot14 x; @@ -359,29 +361,33 @@ FT_BEGIN_HEADER } FT_UnitVector; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_Matrix */ - /* */ - /* <Description> */ - /* 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 :: Matrix coefficient. */ - /* */ - /* xy :: Matrix coefficient. */ - /* */ - /* yx :: Matrix coefficient. */ - /* */ - /* yy :: Matrix coefficient. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_Matrix + * + * @Description: + * 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 :: + * Matrix coefficient. + * + * xy :: + * Matrix coefficient. + * + * yx :: + * Matrix coefficient. + * + * yy :: + * Matrix coefficient. + */ typedef struct FT_Matrix_ { FT_Fixed xx, xy; @@ -390,19 +396,21 @@ FT_BEGIN_HEADER } FT_Matrix; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_Data */ - /* */ - /* <Description> */ - /* Read-only binary data represented as a pointer and a length. */ - /* */ - /* <Fields> */ - /* pointer :: The data. */ - /* */ - /* length :: The length of the data in bytes. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_Data + * + * @Description: + * Read-only binary data represented as a pointer and a length. + * + * @Fields: + * pointer :: + * The data. + * + * length :: + * The length of the data in bytes. + */ typedef struct FT_Data_ { const FT_Byte* pointer; @@ -411,51 +419,53 @@ FT_BEGIN_HEADER } FT_Data; - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* 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. */ - /* */ - /* <Input> */ - /* The address of the FreeType object that is under finalization. */ - /* Its client data is accessed through its `generic' field. */ - /* */ + /************************************************************************** + * + * @FuncType: + * 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. + * + * @Input: + * 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 ); - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_Generic */ - /* */ - /* <Description> */ - /* Client applications often need to associate their own data to a */ - /* 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. */ - /* */ - /* 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). */ - /* */ - /* <Fields> */ - /* data :: 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. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_Generic + * + * @Description: + * Client applications often need to associate their own data to a + * 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. + * + * 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). + * + * @Fields: + * data :: + * 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. + */ typedef struct FT_Generic_ { void* data; @@ -464,19 +474,19 @@ FT_BEGIN_HEADER } FT_Generic; - /*************************************************************************/ - /* */ - /* <Macro> */ - /* 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. */ - /* */ - /* <Note> */ - /* The produced values *must* be 32-bit integers. Don't redefine */ - /* this macro. */ - /* */ + /************************************************************************** + * + * @Macro: + * 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. + * + * @Note: + * The produced values *must* be 32-bit integers. Don't redefine + * this macro. + */ #define FT_MAKE_TAG( _x1, _x2, _x3, _x4 ) \ (FT_Tag) \ ( ( (FT_ULong)_x1 << 24 ) | \ @@ -494,53 +504,56 @@ FT_BEGIN_HEADER /*************************************************************************/ - /*************************************************************************/ - /* */ - /* <Section> */ - /* list_processing */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * list_processing + * + */ - /*************************************************************************/ - /* */ - /* <Type> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Type: + * 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. + */ typedef struct FT_ListNodeRec_* FT_ListNode; - /*************************************************************************/ - /* */ - /* <Type> */ - /* FT_List */ - /* */ - /* <Description> */ - /* A handle to a list record (see @FT_ListRec). */ - /* */ + /************************************************************************** + * + * @Type: + * FT_List + * + * @Description: + * A handle to a list record (see @FT_ListRec). + */ typedef struct FT_ListRec_* FT_List; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_ListNodeRec */ - /* */ - /* <Description> */ - /* A structure used to hold a single list element. */ - /* */ - /* <Fields> */ - /* prev :: The previous element in the list. NULL if first. */ - /* */ - /* next :: The next element in the list. NULL if last. */ - /* */ - /* data :: A typeless pointer to the listed object. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_ListNodeRec + * + * @Description: + * A structure used to hold a single list element. + * + * @Fields: + * prev :: + * The previous element in the list. NULL if first. + * + * next :: + * The next element in the list. NULL if last. + * + * data :: + * A typeless pointer to the listed object. + */ typedef struct FT_ListNodeRec_ { FT_ListNode prev; @@ -550,20 +563,22 @@ FT_BEGIN_HEADER } FT_ListNodeRec; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_ListRec */ - /* */ - /* <Description> */ - /* A structure used to hold a simple doubly-linked list. These are */ - /* used in many parts of FreeType. */ - /* */ - /* <Fields> */ - /* head :: The head (first element) of doubly-linked list. */ - /* */ - /* tail :: The tail (last element) of doubly-linked list. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_ListRec + * + * @Description: + * A structure used to hold a simple doubly-linked list. These are + * used in many parts of FreeType. + * + * @Fields: + * head :: + * The head (first element) of doubly-linked list. + * + * tail :: + * The tail (last element) of doubly-linked list. + */ typedef struct FT_ListRec_ { FT_ListNode head; diff --git a/include/freetype/ftwinfnt.h b/include/freetype/ftwinfnt.h index 461c65b77..6e0dc8a4c 100644 --- a/include/freetype/ftwinfnt.h +++ b/include/freetype/ftwinfnt.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftwinfnt.h */ -/* */ -/* FreeType API for accessing Windows fnt-specific data. */ -/* */ -/* Copyright 2003-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftwinfnt.h + * + * FreeType API for accessing Windows fnt-specific data. + * + * Copyright 2003-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTWINFNT_H_ @@ -32,22 +32,22 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* winfnt_fonts */ - /* */ - /* <Title> */ - /* Window FNT Files */ - /* */ - /* <Abstract> */ - /* Windows FNT specific API. */ - /* */ - /* <Description> */ - /* This section contains the declaration of Windows FNT specific */ - /* functions. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * winfnt_fonts + * + * @Title: + * Window FNT Files + * + * @Abstract: + * Windows FNT specific API. + * + * @Description: + * This section contains the declaration of Windows FNT specific + * functions. + * + */ /************************************************************************* @@ -80,26 +80,26 @@ 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 - * specifies a character set that is operating-system dependent. + * 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 + * 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 * - * https://msdn.microsoft.com/en-us/goglobal/bb964655, + * https://msdn.microsoft.com/en-us/goglobal/bb964655, * - * 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. @@ -173,14 +173,14 @@ FT_BEGIN_HEADER #define FT_WinFNT_ID_OEM 255 - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_WinFNT_HeaderRec */ - /* */ - /* <Description> */ - /* Windows FNT Header info. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_WinFNT_HeaderRec + * + * @Description: + * Windows FNT Header info. + */ typedef struct FT_WinFNT_HeaderRec_ { FT_UShort version; @@ -223,14 +223,14 @@ FT_BEGIN_HEADER } FT_WinFNT_HeaderRec; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_WinFNT_Header */ - /* */ - /* <Description> */ - /* A handle to an @FT_WinFNT_HeaderRec structure. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_WinFNT_Header + * + * @Description: + * A handle to an @FT_WinFNT_HeaderRec structure. + */ typedef struct FT_WinFNT_HeaderRec_* FT_WinFNT_Header; @@ -243,10 +243,12 @@ FT_BEGIN_HEADER * Retrieve a Windows FNT font info header. * * @input: - * face :: A handle to the input face. + * face :: + * A handle to the input face. * * @output: - * aheader :: The WinFNT header. + * aheader :: + * The WinFNT header. * * @return: * FreeType error code. 0~means success. diff --git a/include/freetype/internal/autohint.h b/include/freetype/internal/autohint.h index 4991e3be7..2c51ae757 100644 --- a/include/freetype/internal/autohint.h +++ b/include/freetype/internal/autohint.h @@ -1,73 +1,73 @@ -/***************************************************************************/ -/* */ -/* autohint.h */ -/* */ -/* High-level `autohint' module-specific interface (specification). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ - - - /*************************************************************************/ - /* */ - /* The auto-hinter is used to load and automatically hint glyphs if a */ - /* format-specific hinter isn't available. */ - /* */ - /*************************************************************************/ +/**************************************************************************** + * + * autohint.h + * + * High-level `autohint' module-specific interface (specification). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ + + + /************************************************************************** + * + * The auto-hinter is used to load and automatically hint glyphs if a + * format-specific hinter isn't available. + * + */ #ifndef AUTOHINT_H_ #define AUTOHINT_H_ - /*************************************************************************/ - /* */ - /* 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). */ - /* */ - /* - 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. */ - /* */ - /* 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. */ - /* */ - /* 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 */ - /* feature is purely optional, so most client programs won't even notice */ - /* 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. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * 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). + * + * - 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. + * + * 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. + * + * 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 + * feature is purely optional, so most client programs won't even notice + * 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. + * + */ #include <ft2build.h> @@ -80,27 +80,31 @@ FT_BEGIN_HEADER typedef struct FT_AutoHinterRec_ *FT_AutoHinter; - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* FT_AutoHinter_GlobalGetFunc */ - /* */ - /* <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 */ - /* FT_AutoHinter_GlobalDoneFunc(). */ - /* */ - /* <Input> */ - /* hinter :: A handle to the source auto-hinter. */ - /* */ - /* face :: A handle to the source face object. */ - /* */ - /* <Output> */ - /* global_hints :: A typeless pointer to the global hints. */ - /* */ - /* global_len :: The size in bytes of the global hints. */ - /* */ + /************************************************************************** + * + * @FuncType: + * FT_AutoHinter_GlobalGetFunc + * + * @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 + * FT_AutoHinter_GlobalDoneFunc(). + * + * @Input: + * hinter :: + * A handle to the source auto-hinter. + * + * face :: + * A handle to the source face object. + * + * @Output: + * global_hints :: + * A typeless pointer to the global hints. + * + * global_len :: + * The size in bytes of the global hints. + */ typedef void (*FT_AutoHinter_GlobalGetFunc)( FT_AutoHinter hinter, FT_Face face, @@ -108,69 +112,76 @@ FT_BEGIN_HEADER long* global_len ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* FT_AutoHinter_GlobalDoneFunc */ - /* */ - /* <Description> */ - /* Discard the global hints retrieved through */ - /* FT_AutoHinter_GlobalGetFunc(). This is the only way these hints */ - /* are freed from memory. */ - /* */ - /* <Input> */ - /* hinter :: A handle to the auto-hinter module. */ - /* */ - /* global :: A pointer to retrieved global hints to discard. */ - /* */ + /************************************************************************** + * + * @FuncType: + * FT_AutoHinter_GlobalDoneFunc + * + * @Description: + * Discard the global hints retrieved through + * FT_AutoHinter_GlobalGetFunc(). This is the only way these hints + * are freed from memory. + * + * @Input: + * hinter :: + * A handle to the auto-hinter module. + * + * global :: + * A pointer to retrieved global hints to discard. + */ typedef void (*FT_AutoHinter_GlobalDoneFunc)( FT_AutoHinter hinter, void* global ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* 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). */ - /* */ - /* <Input> */ - /* hinter :: A handle to the source auto-hinter. */ - /* */ - /* face :: A handle to the face. */ - /* */ + /************************************************************************** + * + * @FuncType: + * 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). + * + * @Input: + * hinter :: + * A handle to the source auto-hinter. + * + * face :: + * A handle to the face. + */ typedef void (*FT_AutoHinter_GlobalResetFunc)( FT_AutoHinter hinter, FT_Face face ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* FT_AutoHinter_GlyphLoadFunc */ - /* */ - /* <Description> */ - /* This function is used to load, scale, and automatically hint a */ - /* glyph from a given face. */ - /* */ - /* <Input> */ - /* face :: A handle to the face. */ - /* */ - /* glyph_index :: The glyph index. */ - /* */ - /* load_flags :: The load flags. */ - /* */ - /* <Note> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @FuncType: + * FT_AutoHinter_GlyphLoadFunc + * + * @Description: + * This function is used to load, scale, and automatically hint a + * glyph from a given face. + * + * @Input: + * face :: + * A handle to the face. + * + * glyph_index :: + * The glyph index. + * + * load_flags :: + * The load flags. + * + * @Note: + * 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. + */ typedef FT_Error (*FT_AutoHinter_GlyphLoadFunc)( FT_AutoHinter hinter, FT_GlyphSlot slot, @@ -179,14 +190,14 @@ FT_BEGIN_HEADER FT_Int32 load_flags ); - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_AutoHinter_InterfaceRec */ - /* */ - /* <Description> */ - /* The auto-hinter module's interface. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_AutoHinter_InterfaceRec + * + * @Description: + * The auto-hinter module's interface. + */ typedef struct FT_AutoHinter_InterfaceRec_ { FT_AutoHinter_GlobalResetFunc reset_face; diff --git a/include/freetype/internal/cffotypes.h b/include/freetype/internal/cffotypes.h index 57e7591d4..a0fa85790 100644 --- a/include/freetype/internal/cffotypes.h +++ b/include/freetype/internal/cffotypes.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* cffotypes.h */ -/* */ -/* Basic OpenType/CFF object type definitions (specification). */ -/* */ -/* Copyright 2017-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * cffotypes.h + * + * Basic OpenType/CFF object type definitions (specification). + * + * Copyright 2017-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef CFFOTYPES_H_ @@ -33,14 +33,14 @@ FT_BEGIN_HEADER typedef TT_Face CFF_Face; - /*************************************************************************/ - /* */ - /* <Type> */ - /* CFF_Size */ - /* */ - /* <Description> */ - /* A handle to an OpenType size object. */ - /* */ + /************************************************************************** + * + * @Type: + * CFF_Size + * + * @Description: + * A handle to an OpenType size object. + */ typedef struct CFF_SizeRec_ { FT_SizeRec root; @@ -49,14 +49,14 @@ FT_BEGIN_HEADER } CFF_SizeRec, *CFF_Size; - /*************************************************************************/ - /* */ - /* <Type> */ - /* CFF_GlyphSlot */ - /* */ - /* <Description> */ - /* A handle to an OpenType glyph slot object. */ - /* */ + /************************************************************************** + * + * @Type: + * CFF_GlyphSlot + * + * @Description: + * A handle to an OpenType glyph slot object. + */ typedef struct CFF_GlyphSlotRec_ { FT_GlyphSlotRec root; @@ -70,14 +70,14 @@ FT_BEGIN_HEADER } CFF_GlyphSlotRec, *CFF_GlyphSlot; - /*************************************************************************/ - /* */ - /* <Type> */ - /* CFF_Internal */ - /* */ - /* <Description> */ - /* The interface to the `internal' field of `FT_Size'. */ - /* */ + /************************************************************************** + * + * @Type: + * CFF_Internal + * + * @Description: + * The interface to the `internal' field of `FT_Size'. + */ typedef struct CFF_InternalRec_ { PSH_Globals topfont; @@ -86,10 +86,10 @@ FT_BEGIN_HEADER } CFF_InternalRec, *CFF_Internal; - /*************************************************************************/ - /* */ - /* Subglyph transformation record. */ - /* */ + /************************************************************************** + * + * Subglyph transformation record. + */ typedef struct CFF_Transform_ { FT_Fixed xx, xy; /* transformation matrix coefficients */ diff --git a/include/freetype/internal/cfftypes.h b/include/freetype/internal/cfftypes.h index 7c07e1a37..af2065cf3 100644 --- a/include/freetype/internal/cfftypes.h +++ b/include/freetype/internal/cfftypes.h @@ -1,20 +1,20 @@ -/***************************************************************************/ -/* */ -/* cfftypes.h */ -/* */ -/* Basic OpenType/CFF type definitions and interface (specification */ -/* only). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * cfftypes.h + * + * Basic OpenType/CFF type definitions and interface (specification + * only). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef CFFTYPES_H_ @@ -33,34 +33,42 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Struct> */ - /* CFF_IndexRec */ - /* */ - /* <Description> */ - /* A structure used to model a CFF Index table. */ - /* */ - /* <Fields> */ - /* stream :: The source input stream. */ - /* */ - /* start :: The position of the first index byte in the */ - /* input stream. */ - /* */ - /* count :: The number of elements in the index. */ - /* */ - /* off_size :: The size in bytes of object offsets in index. */ - /* */ - /* data_offset :: 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. */ - /* */ - /* bytes :: If the index is loaded in memory, its bytes. */ - /* */ + /************************************************************************** + * + * @Struct: + * CFF_IndexRec + * + * @Description: + * A structure used to model a CFF Index table. + * + * @Fields: + * stream :: + * The source input stream. + * + * start :: + * The position of the first index byte in the + * input stream. + * + * count :: + * The number of elements in the index. + * + * off_size :: + * The size in bytes of object offsets in index. + * + * data_offset :: + * 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. + * + * bytes :: + * If the index is loaded in memory, its bytes. + */ typedef struct CFF_IndexRec_ { FT_Stream stream; diff --git a/include/freetype/internal/ftcalc.h b/include/freetype/internal/ftcalc.h index 8f3e85099..3e2dc9238 100644 --- a/include/freetype/internal/ftcalc.h +++ b/include/freetype/internal/ftcalc.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftcalc.h */ -/* */ -/* Arithmetic computations (specification). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftcalc.h + * + * Arithmetic computations (specification). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTCALC_H_ @@ -27,11 +27,11 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* FT_MulDiv() and FT_MulFix() are declared in freetype.h. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * FT_MulDiv() and FT_MulFix() are declared in freetype.h. + * + */ #ifndef FT_CONFIG_OPTION_NO_ASSEMBLER /* Provide assembler fragments for performance-critical functions. */ @@ -246,29 +246,32 @@ FT_BEGIN_HEADER #endif - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_MulDiv_No_Round */ - /* */ - /* <Description> */ - /* 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). */ - /* */ - /* This function isn't necessarily as fast as some processor specific */ - /* operations, but is at least completely portable. */ - /* */ - /* <Input> */ - /* a :: The first multiplier. */ - /* b :: The second multiplier. */ - /* c :: 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'. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_MulDiv_No_Round + * + * @Description: + * 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). + * + * This function isn't necessarily as fast as some processor specific + * operations, but is at least completely portable. + * + * @Input: + * a :: + * The first multiplier. + * b :: + * The second multiplier. + * c :: + * 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'. + */ FT_BASE( FT_Long ) FT_MulDiv_No_Round( FT_Long a, FT_Long b, @@ -276,12 +279,12 @@ 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, @@ -290,8 +293,8 @@ FT_BEGIN_HEADER /* - * A variant of FT_Vector_Transform. See comments for - * FT_Matrix_Multiply_Scaled. + * A variant of FT_Vector_Transform. See comments for + * FT_Matrix_Multiply_Scaled. */ FT_BASE( void ) FT_Vector_Transform_Scaled( FT_Vector* vector, @@ -300,22 +303,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, @@ -325,9 +328,9 @@ FT_BEGIN_HEADER /* - * Return TRUE if a corner is flat or nearly flat. This is equivalent to - * saying that the corner point is close to its neighbors, or inside an - * ellipse defined by the neighbor focal points to be more precise. + * Return TRUE if a corner is flat or nearly flat. This is equivalent to + * saying that the corner point is close to its neighbors, or inside an + * ellipse defined by the neighbor focal points to be more precise. */ FT_BASE( FT_Int ) ft_corner_is_flat( FT_Pos in_x, @@ -337,7 +340,7 @@ FT_BEGIN_HEADER /* - * Return the most significant bit index. + * Return the most significant bit index. */ #ifndef FT_CONFIG_OPTION_NO_ASSEMBLER @@ -392,8 +395,8 @@ FT_BEGIN_HEADER /* - * Return sqrt(x*x+y*y), which is the same as `FT_Vector_Length' but uses - * two fixed-point arguments instead. + * Return sqrt(x*x+y*y), which is the same as `FT_Vector_Length' but uses + * two fixed-point arguments instead. */ FT_BASE( FT_Fixed ) FT_Hypot( FT_Fixed x, @@ -402,23 +405,24 @@ FT_BEGIN_HEADER #if 0 - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_SqrtFixed */ - /* */ - /* <Description> */ - /* Computes the square root of a 16.16 fixed-point value. */ - /* */ - /* <Input> */ - /* x :: The value to compute the root for. */ - /* */ - /* <Return> */ - /* The result of `sqrt(x)'. */ - /* */ - /* <Note> */ - /* This function is not very fast. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_SqrtFixed + * + * @Description: + * Computes the square root of a 16.16 fixed-point value. + * + * @Input: + * x :: + * The value to compute the root for. + * + * @Return: + * The result of `sqrt(x)'. + * + * @Note: + * This function is not very fast. + */ FT_BASE( FT_Int32 ) FT_SqrtFixed( FT_Int32 x ); @@ -435,13 +439,13 @@ FT_BEGIN_HEADER : ( -( ( 32 - (x) ) & -64 ) ) ) /* - * The following macros have two purposes. + * The following macros have two purposes. * - * . Tag places where overflow is expected and harmless. + * - Tag places where overflow is expected and harmless. * - * . Avoid run-time sanitizer errors. + * - Avoid run-time sanitizer errors. * - * Use with care! + * Use with care! */ #define ADD_LONG( a, b ) \ (FT_Long)( (FT_ULong)(a) + (FT_ULong)(b) ) diff --git a/include/freetype/internal/ftdebug.h b/include/freetype/internal/ftdebug.h index 292a4eedb..cd7052979 100644 --- a/include/freetype/internal/ftdebug.h +++ b/include/freetype/internal/ftdebug.h @@ -1,24 +1,24 @@ -/***************************************************************************/ -/* */ -/* ftdebug.h */ -/* */ -/* Debugging and logging component (specification). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/* */ -/* IMPORTANT: A description of FreeType's debugging support can be */ -/* found in `docs/DEBUG.TXT'. Read it if you need to use or */ -/* understand this code. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftdebug.h + * + * Debugging and logging component (specification). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + * + * IMPORTANT: A description of FreeType's debugging support can be + * found in `docs/DEBUG.TXT'. Read it if you need to use or + * understand this code. + * + */ #ifndef FTDEBUG_H_ @@ -42,12 +42,12 @@ FT_BEGIN_HEADER #endif - /*************************************************************************/ - /* */ - /* 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. + * + */ #ifdef FT_DEBUG_LEVEL_TRACE @@ -70,16 +70,16 @@ FT_BEGIN_HEADER #endif /* FT_DEBUG_LEVEL_TRACE */ - /*************************************************************************/ - /* */ - /* Define the FT_TRACE macro */ - /* */ - /* IMPORTANT! */ - /* */ - /* Each component must define the macro FT_COMPONENT to a valid FT_Trace */ - /* value before using any TRACE macro. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * Define the FT_TRACE macro + * + * IMPORTANT! + * + * Each component must define the macro FT_COMPONENT to a valid FT_Trace + * value before using any TRACE macro. + * + */ #ifdef FT_DEBUG_LEVEL_TRACE @@ -97,62 +97,62 @@ FT_BEGIN_HEADER #endif /* !FT_DEBUG_LEVEL_TRACE */ - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Trace_Get_Count */ - /* */ - /* <Description> */ - /* Return the number of available trace components. */ - /* */ - /* <Return> */ - /* The number of trace components. 0 if FreeType 2 is not built with */ - /* FT_DEBUG_LEVEL_TRACE definition. */ - /* */ - /* <Note> */ - /* This function may be useful if you want to access elements of */ - /* the internal `ft_trace_levels' array by an index. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Trace_Get_Count + * + * @Description: + * Return the number of available trace components. + * + * @Return: + * The number of trace components. 0 if FreeType 2 is not built with + * FT_DEBUG_LEVEL_TRACE definition. + * + * @Note: + * This function may be useful if you want to access elements of + * the internal `ft_trace_levels' array by an index. + */ FT_BASE( FT_Int ) FT_Trace_Get_Count( void ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Trace_Get_Name */ - /* */ - /* <Description> */ - /* Return the name of a trace component. */ - /* */ - /* <Input> */ - /* The index of the trace component. */ - /* */ - /* <Return> */ - /* The name of the trace component. This is a statically allocated */ - /* C string, so do not free it after use. NULL if FreeType 2 is not */ - /* built with FT_DEBUG_LEVEL_TRACE definition. */ - /* */ - /* <Note> */ - /* Use @FT_Trace_Get_Count to get the number of available trace */ - /* components. */ - /* */ - /* This function may be useful if you want to control FreeType 2's */ - /* debug level in your application. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Trace_Get_Name + * + * @Description: + * Return the name of a trace component. + * + * @Input: + * The index of the trace component. + * + * @Return: + * The name of the trace component. This is a statically allocated + * C string, so do not free it after use. NULL if FreeType 2 is not + * built with FT_DEBUG_LEVEL_TRACE definition. + * + * @Note: + * Use @FT_Trace_Get_Count to get the number of available trace + * components. + * + * This function may be useful if you want to control FreeType 2's + * debug level in your application. + */ FT_BASE( const char* ) FT_Trace_Get_Name( FT_Int idx ); - /*************************************************************************/ - /* */ - /* You need two opening and closing parentheses! */ - /* */ - /* Example: FT_TRACE0(( "Value is %i", foo )) */ - /* */ - /* Output of the FT_TRACEX macros is sent to stderr. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * You need two opening and closing parentheses! + * + * Example: FT_TRACE0(( "Value is %i", foo )) + * + * Output of the FT_TRACEX macros is sent to stderr. + * + */ #define FT_TRACE0( varformat ) FT_TRACE( 0, varformat ) #define FT_TRACE1( varformat ) FT_TRACE( 1, varformat ) @@ -164,13 +164,13 @@ FT_BEGIN_HEADER #define FT_TRACE7( varformat ) FT_TRACE( 7, varformat ) - /*************************************************************************/ - /* */ - /* Define the FT_ERROR macro. */ - /* */ - /* Output of this macro is sent to stderr. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * Define the FT_ERROR macro. + * + * Output of this macro is sent to stderr. + * + */ #ifdef FT_DEBUG_LEVEL_ERROR @@ -183,12 +183,12 @@ FT_BEGIN_HEADER #endif /* !FT_DEBUG_LEVEL_ERROR */ - /*************************************************************************/ - /* */ - /* 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. + * + */ #ifdef FT_DEBUG_LEVEL_ERROR @@ -215,11 +215,11 @@ FT_BEGIN_HEADER #endif /* !FT_DEBUG_LEVEL_ERROR */ - /*************************************************************************/ - /* */ - /* Define `FT_Message' and `FT_Panic' when needed. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * Define `FT_Message' and `FT_Panic' when needed. + * + */ #ifdef FT_DEBUG_LEVEL_ERROR diff --git a/include/freetype/internal/ftdrv.h b/include/freetype/internal/ftdrv.h index 77f451331..bc5b69cf2 100644 --- a/include/freetype/internal/ftdrv.h +++ b/include/freetype/internal/ftdrv.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftdrv.h */ -/* */ -/* FreeType internal font driver interface (specification). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftdrv.h + * + * FreeType internal font driver interface (specification). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTDRV_H_ @@ -87,73 +87,89 @@ FT_BEGIN_HEADER FT_Fixed* advances ); - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_Driver_ClassRec */ - /* */ - /* <Description> */ - /* The font driver class. This structure mostly contains pointers to */ - /* driver methods. */ - /* */ - /* <Fields> */ - /* root :: The parent module. */ - /* */ - /* face_object_size :: The size of a face object in bytes. */ - /* */ - /* size_object_size :: The size of a size object in bytes. */ - /* */ - /* slot_object_size :: The size of a glyph object in bytes. */ - /* */ - /* init_face :: The format-specific face constructor. */ - /* */ - /* done_face :: The format-specific face destructor. */ - /* */ - /* init_size :: The format-specific size constructor. */ - /* */ - /* done_size :: The format-specific size destructor. */ - /* */ - /* init_slot :: The format-specific slot constructor. */ - /* */ - /* done_slot :: The format-specific slot destructor. */ - /* */ - /* */ - /* load_glyph :: 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* <Note> */ - /* Most function pointers, with the exception of `load_glyph', can be */ - /* set to 0 to indicate a default behaviour. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_Driver_ClassRec + * + * @Description: + * The font driver class. This structure mostly contains pointers to + * driver methods. + * + * @Fields: + * root :: + * The parent module. + * + * face_object_size :: + * The size of a face object in bytes. + * + * size_object_size :: + * The size of a size object in bytes. + * + * slot_object_size :: + * The size of a glyph object in bytes. + * + * init_face :: + * The format-specific face constructor. + * + * done_face :: + * The format-specific face destructor. + * + * init_size :: + * The format-specific size constructor. + * + * done_size :: + * The format-specific size destructor. + * + * init_slot :: + * The format-specific slot constructor. + * + * done_slot :: + * The format-specific slot destructor. + * + * + * load_glyph :: + * 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. + * + * 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. + * + * 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. + * + * 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. + * + * 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. + * @Note: + * Most function pointers, with the exception of `load_glyph', can be + * set to 0 to indicate a default behaviour. + */ typedef struct FT_Driver_ClassRec_ { FT_Module_Class root; @@ -184,28 +200,28 @@ FT_BEGIN_HEADER } FT_Driver_ClassRec, *FT_Driver_Class; - /*************************************************************************/ - /* */ - /* <Macro> */ - /* FT_DECLARE_DRIVER */ - /* */ - /* <Description> */ - /* Used to create a forward declaration of an FT_Driver_ClassRec */ - /* struct instance. */ - /* */ - /* <Macro> */ - /* FT_DEFINE_DRIVER */ - /* */ - /* <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'. */ - /* */ - /* The struct will be allocated in the global scope (or the scope */ - /* where the macro is used). */ - /* */ + /************************************************************************** + * + * @Macro: + * FT_DECLARE_DRIVER + * + * @Description: + * Used to create a forward declaration of an FT_Driver_ClassRec + * struct instance. + * + * @Macro: + * FT_DEFINE_DRIVER + * + * @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'. + * + * 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 \ const FT_Driver_ClassRec class_; diff --git a/include/freetype/internal/ftgloadr.h b/include/freetype/internal/ftgloadr.h index a002fdbfc..c1b7b4070 100644 --- a/include/freetype/internal/ftgloadr.h +++ b/include/freetype/internal/ftgloadr.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftgloadr.h */ -/* */ -/* The FreeType glyph loader (specification). */ -/* */ -/* Copyright 2002-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftgloadr.h + * + * The FreeType glyph loader (specification). + * + * Copyright 2002-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTGLOADR_H_ @@ -27,15 +27,15 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_GlyphLoader */ - /* */ - /* <Description> */ - /* The glyph loader is an internal object used to load several glyphs */ - /* together (for example, in the case of composites). */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_GlyphLoader + * + * @Description: + * The glyph loader is an internal object used to load several glyphs + * together (for example, in the case of composites). + */ typedef struct FT_SubGlyphRec_ { FT_Int index; diff --git a/include/freetype/internal/fthash.h b/include/freetype/internal/fthash.h index f22f9d5d3..249188040 100644 --- a/include/freetype/internal/fthash.h +++ b/include/freetype/internal/fthash.h @@ -1,10 +1,10 @@ -/***************************************************************************/ -/* */ -/* fthash.h */ -/* */ -/* Hashing functions (specification). */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * fthash.h + * + * Hashing functions (specification). + * + */ /* * Copyright 2000 Computing Research Labs, New Mexico State University @@ -30,13 +30,13 @@ * THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ - /*************************************************************************/ - /* */ - /* This file is based on code from bdf.c,v 1.22 2000/03/16 20:08:50 */ - /* */ - /* taken from Mark Leisher's xmbdfed package */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * This file is based on code from bdf.c,v 1.22 2000/03/16 20:08:50 + * + * taken from Mark Leisher's xmbdfed package + * + */ #ifndef FTHASH_H_ diff --git a/include/freetype/internal/ftmemory.h b/include/freetype/internal/ftmemory.h index 054eaec31..a17a7096d 100644 --- a/include/freetype/internal/ftmemory.h +++ b/include/freetype/internal/ftmemory.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftmemory.h */ -/* */ -/* The FreeType memory management macros (specification). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftmemory.h + * + * The FreeType memory management macros (specification). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTMEMORY_H_ @@ -28,16 +28,16 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Macro> */ - /* FT_SET_ERROR */ - /* */ - /* <Description> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Macro: + * FT_SET_ERROR + * + * @Description: + * 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. + */ #undef FT_SET_ERROR #define FT_SET_ERROR( expression ) \ ( ( error = (expression) ) != 0 ) @@ -58,9 +58,9 @@ 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. + * 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. */ #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,20 +253,20 @@ 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) ) ) #define FT_ARRAY_CHECK( ptr, count ) ( (count) <= FT_ARRAY_MAX( ptr ) ) - /*************************************************************************/ - /* */ - /* The following functions macros expect that their pointer argument is */ - /* _typed_ in order to automatically compute array element sizes. */ - /* */ + /************************************************************************** + * + * The following functions macros expect that their pointer argument is + * _typed_ in order to automatically compute array element sizes. + */ #define FT_MEM_NEW_ARRAY( ptr, count ) \ FT_ASSIGNP_INNER( ptr, ft_mem_realloc( memory, \ diff --git a/include/freetype/internal/ftobjs.h b/include/freetype/internal/ftobjs.h index b49c78de9..18e01b88a 100644 --- a/include/freetype/internal/ftobjs.h +++ b/include/freetype/internal/ftobjs.h @@ -1,26 +1,26 @@ -/***************************************************************************/ -/* */ -/* ftobjs.h */ -/* */ -/* The FreeType private base classes (specification). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ - - - /*************************************************************************/ - /* */ - /* This file contains the definition of all internal FreeType classes. */ - /* */ - /*************************************************************************/ +/**************************************************************************** + * + * ftobjs.h + * + * The FreeType private base classes (specification). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ + + + /************************************************************************** + * + * This file contains the definition of all internal FreeType classes. + * + */ #ifndef FTOBJS_H_ @@ -45,10 +45,10 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* Some generic definitions. */ - /* */ + /************************************************************************** + * + * Some generic definitions. + */ #ifndef TRUE #define TRUE 1 #endif @@ -62,20 +62,20 @@ FT_BEGIN_HEADER #endif - /*************************************************************************/ - /* */ - /* The min and max functions missing in C. As usual, be careful not to */ - /* write things like FT_MIN( a++, b++ ) to avoid side effects. */ - /* */ + /************************************************************************** + * + * The min and max functions missing in C. As usual, be careful not to + * write things like FT_MIN( a++, b++ ) to avoid side effects. + */ #define FT_MIN( a, b ) ( (a) < (b) ? (a) : (b) ) #define FT_MAX( a, b ) ( (a) > (b) ? (a) : (b) ) #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,9 @@ 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 ) @@ -291,74 +291,74 @@ FT_BEGIN_HEADER #endif /* FT_CONFIG_OPTION_SUBPIXEL_RENDERING */ - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_Face_InternalRec */ - /* */ - /* <Description> */ - /* 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 */ - /* 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. */ - /* */ - /* transform_delta :: */ - /* 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'. */ - /* */ - /* 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 */ - /* @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, */ - /* 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. */ - /* */ - /* lcd_weights :: */ - /* lcd_filter_func :: */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_Face_InternalRec + * + * @Description: + * 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 + * 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. + * + * transform_delta :: + * 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'. + * + * 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 + * @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, + * 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. + * + * lcd_weights :: + * lcd_filter_func :: + * 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. + */ typedef struct FT_Face_InternalRec_ { FT_Matrix transform_matrix; @@ -393,41 +393,48 @@ FT_BEGIN_HEADER } FT_Colr_InternalRec, *FT_Colr_Internal; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_Slot_InternalRec */ - /* */ - /* <Description> */ - /* This structure contains the internal fields of each FT_GlyphSlot */ - /* object. These fields may change between different releases of */ - /* FreeType. */ - /* */ - /* <Fields> */ - /* loader :: 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. */ - /* */ - /* 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(). */ - /* */ - /* glyph_matrix :: The 2x2 matrix corresponding to the glyph */ - /* transformation, if necessary. */ - /* */ - /* glyph_delta :: The 2d translation vector corresponding to */ - /* the glyph transformation, if necessary. */ - /* */ - /* glyph_hints :: Format-specific glyph hints management. */ - /* */ - /* color_layers :: Data from (SFNT) COLR/CPAL tables. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_Slot_InternalRec + * + * @Description: + * This structure contains the internal fields of each FT_GlyphSlot + * object. These fields may change between different releases of + * FreeType. + * + * @Fields: + * loader :: + * 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. + * + * 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(). + * + * glyph_matrix :: + * The 2x2 matrix corresponding to the glyph + * transformation, if necessary. + * + * glyph_delta :: + * The 2d translation vector corresponding to + * the glyph transformation, if necessary. + * + * glyph_hints :: + * Format-specific glyph hints management. + * + * color_layers :: + * Data from (SFNT) COLR/CPAL tables. + */ #define FT_GLYPH_OWN_BITMAP 0x1U @@ -445,23 +452,26 @@ FT_BEGIN_HEADER } FT_GlyphSlot_InternalRec; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_Size_InternalRec */ - /* */ - /* <Description> */ - /* This structure contains the internal fields of each FT_Size */ - /* object. */ - /* */ - /* <Fields> */ - /* module_data :: Data specific to a driver module. */ - /* */ - /* autohint_mode :: The used auto-hinting mode. */ - /* */ - /* autohint_metrics :: Metrics used by the auto-hinter. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Struct: + * FT_Size_InternalRec + * + * @Description: + * This structure contains the internal fields of each FT_Size + * object. + * + * @Fields: + * module_data :: + * Data specific to a driver module. + * + * autohint_mode :: + * The used auto-hinting mode. + * + * autohint_metrics :: + * Metrics used by the auto-hinter. + * + */ typedef struct FT_Size_InternalRec_ { @@ -486,21 +496,24 @@ FT_BEGIN_HEADER /*************************************************************************/ - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_ModuleRec */ - /* */ - /* <Description> */ - /* A module object instance. */ - /* */ - /* <Fields> */ - /* clazz :: A pointer to the module's class. */ - /* */ - /* library :: A handle to the parent library object. */ - /* */ - /* memory :: A handle to the memory manager. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_ModuleRec + * + * @Description: + * A module object instance. + * + * @Fields: + * clazz :: + * A pointer to the module's class. + * + * library :: + * A handle to the parent library object. + * + * memory :: + * A handle to the memory manager. + */ typedef struct FT_ModuleRec_ { FT_Module_Class* clazz; @@ -543,27 +556,29 @@ FT_BEGIN_HEADER FT_MODULE_DRIVER_HINTS_LIGHTLY ) - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Get_Module_Interface */ - /* */ - /* <Description> */ - /* Finds a module and returns its specific interface as a typeless */ - /* pointer. */ - /* */ - /* <Input> */ - /* library :: A handle to the library object. */ - /* */ - /* module_name :: The module's name (as an ASCII string). */ - /* */ - /* <Return> */ - /* 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 :-) */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Get_Module_Interface + * + * @Description: + * Finds a module and returns its specific interface as a typeless + * pointer. + * + * @Input: + * library :: + * A handle to the library object. + * + * module_name :: + * The module's name (as an ASCII string). + * + * @Return: + * 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 :-) + */ FT_BASE( const void* ) FT_Get_Module_Interface( FT_Library library, const char* mod_name ); @@ -614,44 +629,47 @@ FT_BEGIN_HEADER #define FT_FACE_SIZE( x ) FT_FACE( x )->size - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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. */ - /* */ - /* <Input> */ - /* face :: A handle to a parent face object. */ - /* */ - /* <Output> */ - /* aslot :: A handle to a new glyph slot object. */ - /* */ - /* <Return> */ - /* FreeType error code. 0 means success. */ - /* */ + /************************************************************************** + * + * @Function: + * 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. + * + * @Input: + * face :: + * A handle to a parent face object. + * + * @Output: + * aslot :: + * A handle to a new glyph slot object. + * + * @Return: + * FreeType error code. 0 means success. + */ FT_BASE( FT_Error ) FT_New_GlyphSlot( FT_Face face, FT_GlyphSlot *aslot ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Done_GlyphSlot */ - /* */ - /* <Description> */ - /* Destroys a given glyph slot. Remember however that all slots are */ - /* automatically destroyed with its parent. Using this function is */ - /* not always mandatory. */ - /* */ - /* <Input> */ - /* slot :: A handle to a target glyph slot. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Done_GlyphSlot + * + * @Description: + * Destroys a given glyph slot. Remember however that all slots are + * automatically destroyed with its parent. Using this function is + * not always mandatory. + * + * @Input: + * slot :: + * A handle to a target glyph slot. + */ FT_BASE( void ) FT_Done_GlyphSlot( FT_GlyphSlot slot ); @@ -773,28 +791,32 @@ FT_BEGIN_HEADER #define FT_DRIVER_CLASS( x ) FT_DRIVER( x )->clazz - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FT_DriverRec */ - /* */ - /* <Description> */ - /* 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++. */ - /* */ - /* faces_list :: The list of faces currently opened by this */ - /* driver. */ - /* */ - /* glyph_loader :: Unused. Used to be glyph loader for all faces */ - /* managed by this driver. */ - /* */ + /************************************************************************** + * + * @Struct: + * FT_DriverRec + * + * @Description: + * 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++. + * + * faces_list :: + * The list of faces currently opened by this + * driver. + * + * glyph_loader :: + * Unused. Used to be glyph loader for all faces + * managed by this driver. + */ typedef struct FT_DriverRec_ { FT_ModuleRec root; @@ -823,71 +845,86 @@ FT_BEGIN_HEADER #define FT_DEBUG_HOOK_TRUETYPE 0 - /*************************************************************************/ - /* */ - /* <Struct> */ - /* 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. */ - /* */ - /* <Fields> */ - /* memory :: The library's memory object. Manages memory */ - /* allocation. */ - /* */ - /* version_major :: The major version number of the library. */ - /* */ - /* version_minor :: The minor version number of the library. */ - /* */ - /* version_patch :: 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. */ - /* */ - /* modules :: 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* lcd_weights :: The LCD filter weights for ClearType-style */ - /* subpixel rendering. */ - /* */ - /* lcd_filter_func :: 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. */ - /* */ - /* pic_container :: 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. */ - /* */ + /************************************************************************** + * + * @Struct: + * 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. + * + * @Fields: + * memory :: + * The library's memory object. Manages memory + * allocation. + * + * version_major :: + * The major version number of the library. + * + * version_minor :: + * The minor version number of the library. + * + * version_patch :: + * 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. + * + * modules :: + * 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. + * + * 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. + * + * 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. + * + * lcd_weights :: + * The LCD filter weights for ClearType-style + * subpixel rendering. + * + * lcd_filter_func :: + * 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. + * + * pic_container :: + * 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. + */ typedef struct FT_LibraryRec_ { FT_Memory memory; /* library's memory manager */ @@ -943,32 +980,33 @@ FT_BEGIN_HEADER #ifndef FT_CONFIG_OPTION_NO_DEFAULT_SYSTEM - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_New_Memory */ - /* */ - /* <Description> */ - /* Creates a new memory object. */ - /* */ - /* <Return> */ - /* A pointer to the new memory object. 0 in case of error. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_New_Memory + * + * @Description: + * Creates a new memory object. + * + * @Return: + * A pointer to the new memory object. 0 in case of error. + */ FT_BASE( FT_Memory ) FT_New_Memory( void ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Done_Memory */ - /* */ - /* <Description> */ - /* Discards memory manager. */ - /* */ - /* <Input> */ - /* memory :: A handle to the memory manager. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Done_Memory + * + * @Description: + * Discards memory manager. + * + * @Input: + * memory :: + * A handle to the memory manager. + */ FT_BASE( void ) FT_Done_Memory( FT_Memory memory ); @@ -986,16 +1024,16 @@ FT_BEGIN_HEADER #endif - /*************************************************************************/ - /* */ - /* <Macro> */ - /* 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). */ - /* */ + /************************************************************************** + * + * @Macro: + * 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). + */ #define FT_DEFINE_OUTLINE_FUNCS( \ class_, \ move_to_, \ @@ -1015,16 +1053,16 @@ FT_BEGIN_HEADER }; - /*************************************************************************/ - /* */ - /* <Macro> */ - /* 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). */ - /* */ + /************************************************************************** + * + * @Macro: + * 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). + */ #define FT_DEFINE_RASTER_FUNCS( \ class_, \ glyph_format_, \ @@ -1045,15 +1083,15 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Macro> */ - /* FT_DEFINE_GLYPH */ - /* */ - /* <Description> */ - /* The struct will be allocated in the global scope (or the scope */ - /* where the macro is used). */ - /* */ + /************************************************************************** + * + * @Macro: + * FT_DEFINE_GLYPH + * + * @Description: + * The struct will be allocated in the global scope (or the scope + * where the macro is used). + */ #define FT_DEFINE_GLYPH( \ class_, \ size_, \ @@ -1078,24 +1116,24 @@ FT_BEGIN_HEADER }; - /*************************************************************************/ - /* */ - /* <Macro> */ - /* FT_DECLARE_RENDERER */ - /* */ - /* <Description> */ - /* Used to create a forward declaration of a */ - /* FT_Renderer_Class struct instance. */ - /* */ - /* <Macro> */ - /* FT_DEFINE_RENDERER */ - /* */ - /* <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). */ - /* */ + /************************************************************************** + * + * @Macro: + * FT_DECLARE_RENDERER + * + * @Description: + * Used to create a forward declaration of a + * FT_Renderer_Class struct instance. + * + * @Macro: + * FT_DEFINE_RENDERER + * + * @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). + */ #define FT_DECLARE_RENDERER( class_ ) \ FT_EXPORT_VAR( const FT_Renderer_Class ) class_; @@ -1139,32 +1177,32 @@ FT_BEGIN_HEADER }; - /*************************************************************************/ - /* */ - /* <Macro> */ - /* FT_DECLARE_MODULE */ - /* */ - /* <Description> */ - /* Used to create a forward declaration of a */ - /* FT_Module_Class struct instance. */ - /* */ - /* <Macro> */ - /* FT_DEFINE_MODULE */ - /* */ - /* <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). */ - /* */ - /* <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. */ - /* */ + /************************************************************************** + * + * @Macro: + * FT_DECLARE_MODULE + * + * @Description: + * Used to create a forward declaration of a + * FT_Module_Class struct instance. + * + * @Macro: + * FT_DEFINE_MODULE + * + * @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). + * + * @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. + */ #define FT_DECLARE_MODULE( class_ ) \ FT_CALLBACK_TABLE \ const FT_Module_Class class_; diff --git a/include/freetype/internal/ftpsprop.h b/include/freetype/internal/ftpsprop.h index abbb62862..dd0588fa9 100644 --- a/include/freetype/internal/ftpsprop.h +++ b/include/freetype/internal/ftpsprop.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftpsprop.h */ -/* */ -/* Get and set properties of PostScript drivers (specification). */ -/* */ -/* Copyright 2017-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftpsprop.h + * + * Get and set properties of PostScript drivers (specification). + * + * Copyright 2017-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTPSPROP_H_ diff --git a/include/freetype/internal/ftrfork.h b/include/freetype/internal/ftrfork.h index 825be9c89..5a41cbd13 100644 --- a/include/freetype/internal/ftrfork.h +++ b/include/freetype/internal/ftrfork.h @@ -1,24 +1,24 @@ -/***************************************************************************/ -/* */ -/* ftrfork.h */ -/* */ -/* Embedded resource forks accessor (specification). */ -/* */ -/* Copyright 2004-2018 by */ -/* Masatake YAMATO and Redhat K.K. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ - -/***************************************************************************/ -/* Development of the code in this file is support of */ -/* Information-technology Promotion Agency, Japan. */ -/***************************************************************************/ +/**************************************************************************** + * + * ftrfork.h + * + * Embedded resource forks accessor (specification). + * + * Copyright 2004-2018 by + * Masatake YAMATO and Redhat K.K. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ + +/**************************************************************************** + * Development of the code in this file is support of + * Information-technology Promotion Agency, Japan. + */ #ifndef FTRFORK_H_ @@ -92,45 +92,45 @@ FT_BEGIN_HEADER #endif /* FT_CONFIG_OPTION_GUESSING_EMBEDDED_RFORK */ - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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]). */ - /* */ - /* <Input> */ - /* library :: */ - /* A FreeType library instance. */ - /* */ - /* stream :: */ - /* A file stream containing the resource fork. */ - /* */ - /* base_name :: */ - /* 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'. */ - /* */ - /* offsets :: */ - /* 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]'. */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Function: + * 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]). + * + * @Input: + * library :: + * A FreeType library instance. + * + * stream :: + * A file stream containing the resource fork. + * + * base_name :: + * 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'. + * + * offsets :: + * 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]'. + * + * 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. + */ FT_BASE( void ) FT_Raccess_Guess( FT_Library library, FT_Stream stream, @@ -140,37 +140,37 @@ FT_BEGIN_HEADER FT_Error* errors ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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. */ - /* */ - /* <Input> */ - /* library :: */ - /* A FreeType library instance. */ - /* */ - /* stream :: */ - /* A file stream containing the resource fork. */ - /* */ - /* rfork_offset :: */ - /* The file offset where the resource fork starts. */ - /* */ - /* <Output> */ - /* map_offset :: */ - /* The file offset where the resource map starts. */ - /* */ - /* rdata_pos :: */ - /* The file offset where the resource data starts. */ - /* */ - /* <Return> */ - /* FreeType error code. FT_Err_Ok means success. */ - /* */ + /************************************************************************** + * + * @Function: + * 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. + * + * @Input: + * library :: + * A FreeType library instance. + * + * stream :: + * A file stream containing the resource fork. + * + * rfork_offset :: + * The file offset where the resource fork starts. + * + * @Output: + * map_offset :: + * The file offset where the resource map starts. + * + * rdata_pos :: + * The file offset where the resource data starts. + * + * @Return: + * FreeType error code. FT_Err_Ok means success. + */ FT_BASE( FT_Error ) FT_Raccess_Get_HeaderInfo( FT_Library library, FT_Stream stream, @@ -179,55 +179,55 @@ FT_BEGIN_HEADER FT_Long *rdata_pos ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* 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. */ - /* */ - /* <Input> */ - /* library :: */ - /* A FreeType library instance. */ - /* */ - /* stream :: */ - /* A file stream containing the resource fork. */ - /* */ - /* map_offset :: */ - /* The file offset where the resource map starts. */ - /* */ - /* rdata_pos :: */ - /* The file offset where the resource data starts. */ - /* */ - /* tag :: */ - /* 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. */ - /* */ - /* <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. */ - /* */ - /* count :: */ - /* The length of offsets array. */ - /* */ - /* <Return> */ - /* 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'. */ - /* */ + /************************************************************************** + * + * @Function: + * 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. + * + * @Input: + * library :: + * A FreeType library instance. + * + * stream :: + * A file stream containing the resource fork. + * + * map_offset :: + * The file offset where the resource map starts. + * + * rdata_pos :: + * The file offset where the resource data starts. + * + * tag :: + * 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. + * + * @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. + * + * count :: + * The length of offsets array. + * + * @Return: + * 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'. + */ FT_BASE( FT_Error ) FT_Raccess_Get_DataOffsets( FT_Library library, FT_Stream stream, diff --git a/include/freetype/internal/ftserv.h b/include/freetype/internal/ftserv.h index 6ca60504c..1be1d1572 100644 --- a/include/freetype/internal/ftserv.h +++ b/include/freetype/internal/ftserv.h @@ -1,31 +1,31 @@ -/***************************************************************************/ -/* */ -/* ftserv.h */ -/* */ -/* The FreeType services (specification only). */ -/* */ -/* Copyright 2003-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ - - /*************************************************************************/ - /* */ - /* 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). */ - /* */ - /*************************************************************************/ +/**************************************************************************** + * + * ftserv.h + * + * The FreeType services (specification only). + * + * Copyright 2003-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ + + /************************************************************************** + * + * 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). + * + */ #ifndef FTSERV_H_ @@ -34,7 +34,8 @@ FT_BEGIN_HEADER - /* + /************************************************************************** + * * @macro: * FT_FACE_FIND_SERVICE * @@ -85,7 +86,8 @@ FT_BEGIN_HEADER #endif /* !C++ */ - /* + /************************************************************************** + * * @macro: * FT_FACE_FIND_GLOBAL_SERVICE * @@ -144,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_ { @@ -157,26 +159,26 @@ FT_BEGIN_HEADER typedef const FT_ServiceDescRec* FT_ServiceDesc; - /*************************************************************************/ - /* */ - /* <Macro> */ - /* FT_DEFINE_SERVICEDESCREC1 */ - /* FT_DEFINE_SERVICEDESCREC2 */ - /* FT_DEFINE_SERVICEDESCREC3 */ - /* FT_DEFINE_SERVICEDESCREC4 */ - /* FT_DEFINE_SERVICEDESCREC5 */ - /* FT_DEFINE_SERVICEDESCREC6 */ - /* FT_DEFINE_SERVICEDESCREC7 */ - /* FT_DEFINE_SERVICEDESCREC8 */ - /* FT_DEFINE_SERVICEDESCREC9 */ - /* FT_DEFINE_SERVICEDESCREC10 */ - /* */ - /* <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). */ - /* */ + /************************************************************************** + * + * @Macro: + * FT_DEFINE_SERVICEDESCREC1 + * FT_DEFINE_SERVICEDESCREC2 + * FT_DEFINE_SERVICEDESCREC3 + * FT_DEFINE_SERVICEDESCREC4 + * FT_DEFINE_SERVICEDESCREC5 + * FT_DEFINE_SERVICEDESCREC6 + * FT_DEFINE_SERVICEDESCREC7 + * FT_DEFINE_SERVICEDESCREC8 + * FT_DEFINE_SERVICEDESCREC9 + * FT_DEFINE_SERVICEDESCREC10 + * + * @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). + */ #define FT_DEFINE_SERVICEDESCREC1( class_, \ serv_id_1, serv_data_1 ) \ static const FT_ServiceDescRec class_[] = \ @@ -349,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, @@ -371,16 +373,16 @@ 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. + * 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. * - * All fields should have the type FT_Pointer to relax compilation - * dependencies. We assume the developer isn't completely stupid. + * 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 - * FT_FACE_LOOKUP_SERVICE below how this is implemented. + * 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. * */ typedef struct FT_ServiceCacheRec_ @@ -396,14 +398,15 @@ FT_BEGIN_HEADER /* - * A magic number used within the services cache. + * A magic number used within the services cache. */ /* ensure that value `1' has the same width as a pointer */ #define FT_SERVICE_UNAVAILABLE ((FT_Pointer)~(FT_PtrDist)1) - /* + /************************************************************************** + * * @macro: * FT_FACE_LOOKUP_SERVICE * @@ -471,7 +474,7 @@ FT_BEGIN_HEADER #endif /* !C++ */ /* - * A macro used to define new service structure types. + * A macro used to define new service structure types. */ #define FT_DEFINE_SERVICE( name ) \ @@ -484,7 +487,7 @@ FT_BEGIN_HEADER /* */ /* - * The header files containing the services. + * The header files containing the services. */ #define FT_SERVICE_BDF_H <freetype/internal/services/svbdf.h> diff --git a/include/freetype/internal/ftstream.h b/include/freetype/internal/ftstream.h index f90002fe7..c3ab75502 100644 --- a/include/freetype/internal/ftstream.h +++ b/include/freetype/internal/ftstream.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftstream.h */ -/* */ -/* Stream handling (specification). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftstream.h + * + * Stream handling (specification). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTSTREAM_H_ @@ -147,11 +147,11 @@ FT_BEGIN_HEADER #define FT_FRAME_SKIP_BYTES( count ) { ft_frame_skip, count, 0 } - /*************************************************************************/ - /* */ - /* 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)] ) @@ -258,10 +258,10 @@ FT_BEGIN_HEADER ( (unsigned long)( buffer += 4, FT_PEEK_ULONG_LE( buffer - 4 ) ) ) - /*************************************************************************/ - /* */ - /* Each GET_xxxx() macro uses an implicit `stream' variable. */ - /* */ + /************************************************************************** + * + * Each GET_xxxx() macro uses an implicit `stream' variable. + */ #if 0 #define FT_GET_MACRO( type ) FT_NEXT_ ## type ( stream->cursor ) diff --git a/include/freetype/internal/fttrace.h b/include/freetype/internal/fttrace.h index 8092e41fd..7cf455658 100644 --- a/include/freetype/internal/fttrace.h +++ b/include/freetype/internal/fttrace.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* fttrace.h */ -/* */ -/* Tracing handling (specification only). */ -/* */ -/* Copyright 2002-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * fttrace.h + * + * Tracing handling (specification only). + * + * Copyright 2002-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ /* definitions of trace levels for FreeType 2 */ diff --git a/include/freetype/internal/ftvalid.h b/include/freetype/internal/ftvalid.h index cad47a556..265d79ba9 100644 --- a/include/freetype/internal/ftvalid.h +++ b/include/freetype/internal/ftvalid.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftvalid.h */ -/* */ -/* FreeType validation support (specification). */ -/* */ -/* Copyright 2004-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftvalid.h + * + * FreeType validation support (specification). + * + * Copyright 2004-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef FTVALID_H_ @@ -42,31 +42,31 @@ FT_BEGIN_HEADER typedef struct FT_ValidatorRec_ volatile* FT_Validator; - /*************************************************************************/ - /* */ - /* There are three distinct validation levels defined here: */ - /* */ - /* FT_VALIDATE_DEFAULT :: */ - /* A table that passes this validation level can be used reliably by */ - /* FreeType. It generally means that all offsets have been checked to */ - /* prevent out-of-bound reads, that array counts are correct, etc. */ - /* */ - /* 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). */ - /* */ - /* 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 */ - /* editors/converters. */ - /* */ + /************************************************************************** + * + * There are three distinct validation levels defined here: + * + * FT_VALIDATE_DEFAULT :: + * A table that passes this validation level can be used reliably by + * FreeType. It generally means that all offsets have been checked to + * prevent out-of-bound reads, that array counts are correct, etc. + * + * 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). + * + * 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 + * editors/converters. + */ typedef enum FT_ValidationLevel_ { FT_VALIDATE_DEFAULT = 0, diff --git a/include/freetype/internal/internal.h b/include/freetype/internal/internal.h index 53b5b17c4..826104336 100644 --- a/include/freetype/internal/internal.h +++ b/include/freetype/internal/internal.h @@ -1,27 +1,27 @@ -/***************************************************************************/ -/* */ -/* internal.h */ -/* */ -/* Internal header files (specification only). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * internal.h + * + * Internal header files (specification only). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ - /*************************************************************************/ - /* */ - /* 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! + * + */ #define FT_INTERNAL_OBJECTS_H <freetype/internal/ftobjs.h> diff --git a/include/freetype/internal/psaux.h b/include/freetype/internal/psaux.h index f77380d25..70661ead7 100644 --- a/include/freetype/internal/psaux.h +++ b/include/freetype/internal/psaux.h @@ -1,20 +1,20 @@ -/***************************************************************************/ -/* */ -/* psaux.h */ -/* */ -/* Auxiliary functions and data structures related to PostScript fonts */ -/* (specification). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * psaux.h + * + * Auxiliary functions and data structures related to PostScript fonts + * (specification). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef PSAUX_H_ @@ -35,10 +35,10 @@ FT_BEGIN_HEADER - /***********************************************************************/ - /* */ - /* PostScript modules driver class. */ - /* */ + /************************************************************************ + * + * PostScript modules driver class. + */ typedef struct PS_DriverRec_ { FT_DriverRec root; @@ -64,23 +64,27 @@ FT_BEGIN_HEADER typedef const struct PS_Table_FuncsRec_* PS_Table_Funcs; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* PS_Table_FuncsRec */ - /* */ - /* <Description> */ - /* A set of function pointers to manage PS_Table objects. */ - /* */ - /* <Fields> */ - /* table_init :: Used to initialize a table. */ - /* */ - /* table_done :: Finalizes resp. destroy a given table. */ - /* */ - /* table_add :: Adds a new object to a table. */ - /* */ - /* table_release :: Releases table data, then finalizes it. */ - /* */ + /************************************************************************** + * + * @Struct: + * PS_Table_FuncsRec + * + * @Description: + * A set of function pointers to manage PS_Table objects. + * + * @Fields: + * table_init :: + * Used to initialize a table. + * + * table_done :: + * Finalizes resp. destroy a given table. + * + * table_add :: + * Adds a new object to a table. + * + * table_release :: + * Releases table data, then finalizes it. + */ typedef struct PS_Table_FuncsRec_ { FT_Error @@ -103,41 +107,51 @@ FT_BEGIN_HEADER } PS_Table_FuncsRec; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* PS_TableRec */ - /* */ - /* <Description> */ - /* 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. */ - /* */ - /* cursor :: The current top of the grow heap within its block. */ - /* */ - /* capacity :: The current size of the heap block. Increments by */ - /* 1kByte chunks. */ - /* */ - /* init :: Set to 0xDEADBEEF if `elements' and `lengths' have */ - /* been allocated. */ - /* */ - /* max_elems :: The maximum number of elements in table. */ - /* */ - /* num_elems :: The current number of elements in table. */ - /* */ - /* elements :: A table of element addresses within the block. */ - /* */ - /* lengths :: A table of element sizes within the block. */ - /* */ - /* memory :: The object used for memory operations */ - /* (alloc/realloc). */ - /* */ - /* funcs :: A table of method pointers for this object. */ - /* */ + /************************************************************************** + * + * @Struct: + * PS_TableRec + * + * @Description: + * 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. + * + * cursor :: + * The current top of the grow heap within its block. + * + * capacity :: + * The current size of the heap block. Increments by + * 1kByte chunks. + * + * init :: + * Set to 0xDEADBEEF if `elements' and `lengths' have + * been allocated. + * + * max_elems :: + * The maximum number of elements in table. + * + * num_elems :: + * The current number of elements in table. + * + * elements :: + * A table of element addresses within the block. + * + * lengths :: + * A table of element sizes within the block. + * + * memory :: + * The object used for memory operations + * (alloc/realloc). + * + * funcs :: + * A table of method pointers for this object. + */ typedef struct PS_TableRec_ { FT_Byte* block; /* current memory block */ @@ -425,27 +439,33 @@ FT_BEGIN_HEADER } PS_Parser_FuncsRec; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* PS_ParserRec */ - /* */ - /* <Description> */ - /* A PS_Parser is an object used to parse a Type 1 font very quickly. */ - /* */ - /* <Fields> */ - /* cursor :: The current position in the text. */ - /* */ - /* base :: Start of the processed text. */ - /* */ - /* limit :: End of the processed text. */ - /* */ - /* error :: The last error returned. */ - /* */ - /* memory :: The object used for memory operations (alloc/realloc). */ - /* */ - /* funcs :: A table of functions for the parser. */ - /* */ + /************************************************************************** + * + * @Struct: + * PS_ParserRec + * + * @Description: + * A PS_Parser is an object used to parse a Type 1 font very quickly. + * + * @Fields: + * cursor :: + * The current position in the text. + * + * base :: + * Start of the processed text. + * + * limit :: + * End of the processed text. + * + * error :: + * The last error returned. + * + * memory :: + * The object used for memory operations (alloc/realloc). + * + * funcs :: + * A table of functions for the parser. + */ typedef struct PS_ParserRec_ { FT_Byte* cursor; @@ -484,51 +504,68 @@ FT_BEGIN_HEADER } PS_Builder_FuncsRec; - /*************************************************************************/ - /* */ - /* <Structure> */ - /* PS_Builder */ - /* */ - /* <Description> */ - /* A structure used during glyph loading to store its outline. */ - /* */ - /* <Fields> */ - /* memory :: The current memory object. */ - /* */ - /* face :: The current face object. */ - /* */ - /* glyph :: The current glyph slot. */ - /* */ - /* loader :: XXX */ - /* */ - /* base :: The base glyph outline. */ - /* */ - /* current :: The current glyph outline. */ - /* */ - /* pos_x :: The horizontal translation (if composite glyph). */ - /* */ - /* pos_y :: The vertical translation (if composite glyph). */ - /* */ - /* left_bearing :: The left side bearing point. */ - /* */ - /* advance :: The horizontal advance vector. */ - /* */ - /* bbox :: Unused. */ - /* */ - /* path_begun :: A flag which indicates that a new path has begun. */ - /* */ - /* load_points :: If this flag is not set, no points are loaded. */ - /* */ - /* no_recurse :: 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. */ - /* */ - /* is_t1 :: Set if current font type is Type 1. */ - /* */ - /* funcs :: An array of function pointers for the builder. */ - /* */ + /************************************************************************** + * + * @Structure: + * PS_Builder + * + * @Description: + * A structure used during glyph loading to store its outline. + * + * @Fields: + * memory :: + * The current memory object. + * + * face :: + * The current face object. + * + * glyph :: + * The current glyph slot. + * + * loader :: + * XXX + * + * base :: + * The base glyph outline. + * + * current :: + * The current glyph outline. + * + * pos_x :: + * The horizontal translation (if composite glyph). + * + * pos_y :: + * The vertical translation (if composite glyph). + * + * left_bearing :: + * The left side bearing point. + * + * advance :: + * The horizontal advance vector. + * + * bbox :: + * Unused. + * + * path_begun :: + * A flag which indicates that a new path has begun. + * + * load_points :: + * If this flag is not set, no points are loaded. + * + * no_recurse :: + * 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. + * + * is_t1 :: + * Set if current font type is Type 1. + * + * funcs :: + * An array of function pointers for the builder. + */ struct PS_Builder_ { FT_Memory memory; @@ -729,54 +766,72 @@ FT_BEGIN_HEADER } T1_ParseState; - /*************************************************************************/ - /* */ - /* <Structure> */ - /* T1_BuilderRec */ - /* */ - /* <Description> */ - /* A structure used during glyph loading to store its outline. */ - /* */ - /* <Fields> */ - /* memory :: The current memory object. */ - /* */ - /* face :: The current face object. */ - /* */ - /* glyph :: The current glyph slot. */ - /* */ - /* loader :: XXX */ - /* */ - /* base :: The base glyph outline. */ - /* */ - /* current :: The current glyph outline. */ - /* */ - /* max_points :: maximum points in builder outline */ - /* */ - /* max_contours :: Maximum number of contours in builder outline. */ - /* */ - /* pos_x :: The horizontal translation (if composite glyph). */ - /* */ - /* pos_y :: The vertical translation (if composite glyph). */ - /* */ - /* left_bearing :: The left side bearing point. */ - /* */ - /* advance :: The horizontal advance vector. */ - /* */ - /* bbox :: Unused. */ - /* */ - /* parse_state :: An enumeration which controls the charstring */ - /* parsing state. */ - /* */ - /* load_points :: If this flag is not set, no points are loaded. */ - /* */ - /* no_recurse :: 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. */ - /* */ - /* funcs :: An array of function pointers for the builder. */ - /* */ + /************************************************************************** + * + * @Structure: + * T1_BuilderRec + * + * @Description: + * A structure used during glyph loading to store its outline. + * + * @Fields: + * memory :: + * The current memory object. + * + * face :: + * The current face object. + * + * glyph :: + * The current glyph slot. + * + * loader :: + * XXX + * + * base :: + * The base glyph outline. + * + * current :: + * The current glyph outline. + * + * max_points :: + * maximum points in builder outline + * + * max_contours :: + * Maximum number of contours in builder outline. + * + * pos_x :: + * The horizontal translation (if composite glyph). + * + * pos_y :: + * The vertical translation (if composite glyph). + * + * left_bearing :: + * The left side bearing point. + * + * advance :: + * The horizontal advance vector. + * + * bbox :: + * Unused. + * + * parse_state :: + * An enumeration which controls the charstring + * parsing state. + * + * load_points :: + * If this flag is not set, no points are loaded. + * + * no_recurse :: + * 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. + * + * funcs :: + * An array of function pointers for the builder. + */ typedef struct T1_BuilderRec_ { FT_Memory memory; @@ -817,19 +872,19 @@ FT_BEGIN_HEADER #if 0 - /*************************************************************************/ - /* */ - /* T1_MAX_SUBRS_CALLS details the maximum number of nested sub-routine */ - /* calls during glyph loading. */ - /* */ + /************************************************************************** + * + * T1_MAX_SUBRS_CALLS details the maximum number of nested sub-routine + * calls during glyph loading. + */ #define T1_MAX_SUBRS_CALLS 8 - /*************************************************************************/ - /* */ - /* T1_MAX_CHARSTRING_OPERANDS is the charstring stack's capacity. A */ - /* minimum of 16 is required. */ - /* */ + /************************************************************************** + * + * T1_MAX_CHARSTRING_OPERANDS is the charstring stack's capacity. A + * minimum of 16 is required. + */ #define T1_MAX_CHARSTRINGS_OPERANDS 32 #endif /* 0 */ @@ -993,53 +1048,71 @@ FT_BEGIN_HEADER } CFF_Builder_FuncsRec; - /*************************************************************************/ - /* */ - /* <Structure> */ - /* CFF_Builder */ - /* */ - /* <Description> */ - /* A structure used during glyph loading to store its outline. */ - /* */ - /* <Fields> */ - /* memory :: The current memory object. */ - /* */ - /* face :: The current face object. */ - /* */ - /* glyph :: The current glyph slot. */ - /* */ - /* loader :: The current glyph loader. */ - /* */ - /* base :: The base glyph outline. */ - /* */ - /* current :: The current glyph outline. */ - /* */ - /* pos_x :: The horizontal translation (if composite glyph). */ - /* */ - /* pos_y :: The vertical translation (if composite glyph). */ - /* */ - /* left_bearing :: The left side bearing point. */ - /* */ - /* advance :: The horizontal advance vector. */ - /* */ - /* bbox :: Unused. */ - /* */ - /* path_begun :: A flag which indicates that a new path has begun. */ - /* */ - /* load_points :: If this flag is not set, no points are loaded. */ - /* */ - /* no_recurse :: 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. */ - /* */ - /* hints_funcs :: Auxiliary pointer for hinting. */ - /* */ - /* hints_globals :: Auxiliary pointer for hinting. */ - /* */ - /* funcs :: A table of method pointers for this object. */ - /* */ + /************************************************************************** + * + * @Structure: + * CFF_Builder + * + * @Description: + * A structure used during glyph loading to store its outline. + * + * @Fields: + * memory :: + * The current memory object. + * + * face :: + * The current face object. + * + * glyph :: + * The current glyph slot. + * + * loader :: + * The current glyph loader. + * + * base :: + * The base glyph outline. + * + * current :: + * The current glyph outline. + * + * pos_x :: + * The horizontal translation (if composite glyph). + * + * pos_y :: + * The vertical translation (if composite glyph). + * + * left_bearing :: + * The left side bearing point. + * + * advance :: + * The horizontal advance vector. + * + * bbox :: + * Unused. + * + * path_begun :: + * A flag which indicates that a new path has begun. + * + * load_points :: + * If this flag is not set, no points are loaded. + * + * no_recurse :: + * 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. + * + * hints_funcs :: + * Auxiliary pointer for hinting. + * + * hints_globals :: + * Auxiliary pointer for hinting. + * + * funcs :: + * A table of method pointers for this object. + */ struct CFF_Builder_ { FT_Memory memory; @@ -1211,25 +1284,29 @@ FT_BEGIN_HEADER typedef struct AFM_StreamRec_* AFM_Stream; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* AFM_ParserRec */ - /* */ - /* <Description> */ - /* An AFM_Parser is a parser for the AFM files. */ - /* */ - /* <Fields> */ - /* memory :: The object used for memory operations (alloc and */ - /* realloc). */ - /* */ - /* stream :: This is an opaque object. */ - /* */ - /* FontInfo :: The result will be stored here. */ - /* */ - /* get_index :: A user provided function to get a glyph index by its */ - /* name. */ - /* */ + /************************************************************************** + * + * @Struct: + * AFM_ParserRec + * + * @Description: + * An AFM_Parser is a parser for the AFM files. + * + * @Fields: + * memory :: + * The object used for memory operations (alloc and + * realloc). + * + * stream :: + * This is an opaque object. + * + * FontInfo :: + * The result will be stored here. + * + * get_index :: + * A user provided function to get a glyph index by its + * name. + */ typedef struct AFM_ParserRec_ { FT_Memory memory; diff --git a/include/freetype/internal/pshints.h b/include/freetype/internal/pshints.h index 249cf973a..90a28ac49 100644 --- a/include/freetype/internal/pshints.h +++ b/include/freetype/internal/pshints.h @@ -1,21 +1,21 @@ -/***************************************************************************/ -/* */ -/* pshints.h */ -/* */ -/* 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. */ -/* */ -/* Copyright 2001-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * pshints.h + * + * 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. + * + * Copyright 2001-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef PSHINTS_H_ diff --git a/include/freetype/internal/services/svbdf.h b/include/freetype/internal/services/svbdf.h index e2133d7c7..b29f537d5 100644 --- a/include/freetype/internal/services/svbdf.h +++ b/include/freetype/internal/services/svbdf.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* svbdf.h */ -/* */ -/* The FreeType BDF services (specification). */ -/* */ -/* Copyright 2003-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * svbdf.h + * + * The FreeType BDF services (specification). + * + * Copyright 2003-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef SVBDF_H_ diff --git a/include/freetype/internal/services/svcfftl.h b/include/freetype/internal/services/svcfftl.h index 55a3fa4a9..9e4486e3c 100644 --- a/include/freetype/internal/services/svcfftl.h +++ b/include/freetype/internal/services/svcfftl.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* svcfftl.h */ -/* */ -/* The FreeType CFF tables loader service (specification). */ -/* */ -/* Copyright 2017-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * svcfftl.h + * + * The FreeType CFF tables loader service (specification). + * + * Copyright 2017-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef SVCFFTL_H_ diff --git a/include/freetype/internal/services/svcid.h b/include/freetype/internal/services/svcid.h index fb0c90b77..9ef0a0c0c 100644 --- a/include/freetype/internal/services/svcid.h +++ b/include/freetype/internal/services/svcid.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* svcid.h */ -/* */ -/* The FreeType CID font services (specification). */ -/* */ -/* Copyright 2007-2018 by */ -/* Derek Clegg and Michael Toftdal. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * svcid.h + * + * The FreeType CID font services (specification). + * + * Copyright 2007-2018 by + * Derek Clegg and Michael Toftdal. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef SVCID_H_ diff --git a/include/freetype/internal/services/svfntfmt.h b/include/freetype/internal/services/svfntfmt.h index 3b732be1a..618236261 100644 --- a/include/freetype/internal/services/svfntfmt.h +++ b/include/freetype/internal/services/svfntfmt.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* svfntfmt.h */ -/* */ -/* The FreeType font format service (specification only). */ -/* */ -/* Copyright 2003-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * svfntfmt.h + * + * The FreeType font format service (specification only). + * + * Copyright 2003-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef SVFNTFMT_H_ @@ -26,9 +26,9 @@ 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. + * 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. */ #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 d401a4382..0840b584a 100644 --- a/include/freetype/internal/services/svgldict.h +++ b/include/freetype/internal/services/svgldict.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* svgldict.h */ -/* */ -/* The FreeType glyph dictionary services (specification). */ -/* */ -/* Copyright 2003-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * svgldict.h + * + * The FreeType glyph dictionary services (specification). + * + * Copyright 2003-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef 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/svgxval.h b/include/freetype/internal/services/svgxval.h index ed79ebeaa..7fa27ffde 100644 --- a/include/freetype/internal/services/svgxval.h +++ b/include/freetype/internal/services/svgxval.h @@ -1,28 +1,28 @@ -/***************************************************************************/ -/* */ -/* svgxval.h */ -/* */ -/* FreeType API for validating TrueTypeGX/AAT tables (specification). */ -/* */ -/* Copyright 2004-2018 by */ -/* Masatake YAMATO, Red Hat K.K., */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ - -/***************************************************************************/ -/* */ -/* gxvalid is derived from both gxlayout module and otvalid module. */ -/* Development of gxlayout is supported by the Information-technology */ -/* Promotion Agency(IPA), Japan. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * svgxval.h + * + * FreeType API for validating TrueTypeGX/AAT tables (specification). + * + * Copyright 2004-2018 by + * Masatake YAMATO, Red Hat K.K., + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ + +/**************************************************************************** + * + * gxvalid is derived from both gxlayout module and otvalid module. + * Development of gxlayout is supported by the Information-technology + * Promotion Agency(IPA), Japan. + * + */ #ifndef SVGXVAL_H_ diff --git a/include/freetype/internal/services/svkern.h b/include/freetype/internal/services/svkern.h index c7e8f6ef2..ef95b328c 100644 --- a/include/freetype/internal/services/svkern.h +++ b/include/freetype/internal/services/svkern.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* svkern.h */ -/* */ -/* The FreeType Kerning service (specification). */ -/* */ -/* Copyright 2006-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * svkern.h + * + * The FreeType Kerning service (specification). + * + * Copyright 2006-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef SVKERN_H_ diff --git a/include/freetype/internal/services/svmetric.h b/include/freetype/internal/services/svmetric.h index e5a1a0e5e..91de020bc 100644 --- a/include/freetype/internal/services/svmetric.h +++ b/include/freetype/internal/services/svmetric.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* svmetric.h */ -/* */ -/* The FreeType services for metrics variations (specification). */ -/* */ -/* Copyright 2016-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * svmetric.h + * + * The FreeType services for metrics variations (specification). + * + * Copyright 2016-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef SVMETRIC_H_ @@ -26,7 +26,7 @@ FT_BEGIN_HEADER /* - * A service to manage the `HVAR, `MVAR', and `VVAR' OpenType tables. + * A service to manage the `HVAR, `MVAR', and `VVAR' OpenType tables. * */ diff --git a/include/freetype/internal/services/svmm.h b/include/freetype/internal/services/svmm.h index 04a63c391..6aeaa4519 100644 --- a/include/freetype/internal/services/svmm.h +++ b/include/freetype/internal/services/svmm.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* svmm.h */ -/* */ -/* The FreeType Multiple Masters and GX var services (specification). */ -/* */ -/* Copyright 2003-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * svmm.h + * + * The FreeType Multiple Masters and GX var services (specification). + * + * Copyright 2003-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef SVMM_H_ @@ -26,9 +26,9 @@ FT_BEGIN_HEADER /* - * A service used to manage multiple-masters data in a given face. + * A service used to manage multiple-masters data in a given face. * - * See the related APIs in `ftmm.h' (FT_MULTIPLE_MASTERS_H). + * See the related APIs in `ftmm.h' (FT_MULTIPLE_MASTERS_H). * */ diff --git a/include/freetype/internal/services/svotval.h b/include/freetype/internal/services/svotval.h index 31294296a..9a3ff4738 100644 --- a/include/freetype/internal/services/svotval.h +++ b/include/freetype/internal/services/svotval.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* svotval.h */ -/* */ -/* The FreeType OpenType validation service (specification). */ -/* */ -/* Copyright 2004-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * svotval.h + * + * The FreeType OpenType validation service (specification). + * + * Copyright 2004-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef SVOTVAL_H_ diff --git a/include/freetype/internal/services/svpfr.h b/include/freetype/internal/services/svpfr.h index e65d57e91..21deb3174 100644 --- a/include/freetype/internal/services/svpfr.h +++ b/include/freetype/internal/services/svpfr.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* svpfr.h */ -/* */ -/* Internal PFR service functions (specification). */ -/* */ -/* Copyright 2003-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * svpfr.h + * + * Internal PFR service functions (specification). + * + * Copyright 2003-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef SVPFR_H_ diff --git a/include/freetype/internal/services/svpostnm.h b/include/freetype/internal/services/svpostnm.h index 24e0255a1..1e39dce79 100644 --- a/include/freetype/internal/services/svpostnm.h +++ b/include/freetype/internal/services/svpostnm.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* svpostnm.h */ -/* */ -/* The FreeType PostScript name services (specification). */ -/* */ -/* Copyright 2003-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * svpostnm.h + * + * The FreeType PostScript name services (specification). + * + * Copyright 2003-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef SVPOSTNM_H_ @@ -25,13 +25,13 @@ 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. + * The corresponding function can return NULL to indicate that the + * PostScript name is not available. * - * The name is owned by the face and will be destroyed with it. + * The name is owned by the face and will be destroyed with it. */ #define FT_SERVICE_ID_POSTSCRIPT_FONT_NAME "postscript-font-name" diff --git a/include/freetype/internal/services/svprop.h b/include/freetype/internal/services/svprop.h index fb762cdfe..7e84cc893 100644 --- a/include/freetype/internal/services/svprop.h +++ b/include/freetype/internal/services/svprop.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* svprop.h */ -/* */ -/* The FreeType property service (specification). */ -/* */ -/* Copyright 2012-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * svprop.h + * + * The FreeType property service (specification). + * + * Copyright 2012-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef SVPROP_H_ diff --git a/include/freetype/internal/services/svpscmap.h b/include/freetype/internal/services/svpscmap.h index 97477376d..136879d64 100644 --- a/include/freetype/internal/services/svpscmap.h +++ b/include/freetype/internal/services/svpscmap.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* svpscmap.h */ -/* */ -/* The FreeType PostScript charmap service (specification). */ -/* */ -/* Copyright 2003-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * svpscmap.h + * + * The FreeType PostScript charmap service (specification). + * + * Copyright 2003-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef SVPSCMAP_H_ @@ -29,27 +29,27 @@ FT_BEGIN_HEADER /* - * Adobe glyph name to unicode value. + * Adobe glyph name to unicode value. */ typedef FT_UInt32 (*PS_Unicode_ValueFunc)( const char* glyph_name ); /* - * Macintosh name id to glyph name. NULL if invalid index. + * Macintosh name id to glyph name. NULL if invalid index. */ typedef const char* (*PS_Macintosh_NameFunc)( FT_UInt name_index ); /* - * Adobe standard string ID to glyph name. NULL if invalid index. + * Adobe standard string ID to glyph name. NULL if invalid index. */ typedef const char* (*PS_Adobe_Std_StringsFunc)( FT_UInt string_index ); /* - * 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,16 +71,16 @@ 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, FT_UInt string_index ); /* - * A function used to release the glyph name returned by - * PS_GetGlyphNameFunc, when needed + * A function used to release the glyph name returned by + * PS_GetGlyphNameFunc, when needed */ typedef void (*PS_FreeGlyphNameFunc)( FT_Pointer data, diff --git a/include/freetype/internal/services/svpsinfo.h b/include/freetype/internal/services/svpsinfo.h index 589f573d6..214fd1e10 100644 --- a/include/freetype/internal/services/svpsinfo.h +++ b/include/freetype/internal/services/svpsinfo.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* svpsinfo.h */ -/* */ -/* The FreeType PostScript info service (specification). */ -/* */ -/* Copyright 2003-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * svpsinfo.h + * + * The FreeType PostScript info service (specification). + * + * Copyright 2003-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef SVPSINFO_H_ diff --git a/include/freetype/internal/services/svsfnt.h b/include/freetype/internal/services/svsfnt.h index 670f5e607..035e1199b 100644 --- a/include/freetype/internal/services/svsfnt.h +++ b/include/freetype/internal/services/svsfnt.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* svsfnt.h */ -/* */ -/* The FreeType SFNT table loading service (specification). */ -/* */ -/* Copyright 2003-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * svsfnt.h + * + * The FreeType SFNT table loading service (specification). + * + * Copyright 2003-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef SVSFNT_H_ @@ -27,7 +27,7 @@ FT_BEGIN_HEADER /* - * SFNT table loading service. + * SFNT table loading service. */ #define FT_SERVICE_ID_SFNT_TABLE "sfnt-table" diff --git a/include/freetype/internal/services/svttcmap.h b/include/freetype/internal/services/svttcmap.h index c0032f3ac..4b00abb40 100644 --- a/include/freetype/internal/services/svttcmap.h +++ b/include/freetype/internal/services/svttcmap.h @@ -1,20 +1,20 @@ -/***************************************************************************/ -/* */ -/* svttcmap.h */ -/* */ -/* The FreeType TrueType/sfnt cmap extra information service. */ -/* */ -/* Copyright 2003-2018 by */ -/* Masatake YAMATO, Redhat K.K., */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * svttcmap.h + * + * The FreeType TrueType/sfnt cmap extra information service. + * + * Copyright 2003-2018 by + * Masatake YAMATO, Redhat K.K., + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ /* Development of this service is support of Information-technology Promotion Agency, Japan. */ @@ -32,29 +32,29 @@ FT_BEGIN_HEADER #define FT_SERVICE_ID_TT_CMAP "tt-cmaps" - /*************************************************************************/ - /* */ - /* <Struct> */ - /* TT_CMapInfo */ - /* */ - /* <Description> */ - /* A structure used to store TrueType/sfnt specific cmap information */ - /* which is not covered by the generic @FT_CharMap structure. This */ - /* structure can be accessed with the @FT_Get_TT_CMap_Info function. */ - /* */ - /* <Fields> */ - /* language :: */ - /* The language ID used in Mac fonts. Definitions of values are in */ - /* `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). */ - /* */ + /************************************************************************** + * + * @Struct: + * TT_CMapInfo + * + * @Description: + * A structure used to store TrueType/sfnt specific cmap information + * which is not covered by the generic @FT_CharMap structure. This + * structure can be accessed with the @FT_Get_TT_CMap_Info function. + * + * @Fields: + * language :: + * The language ID used in Mac fonts. Definitions of values are in + * `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). + */ typedef struct TT_CMapInfo_ { FT_ULong language; diff --git a/include/freetype/internal/services/svtteng.h b/include/freetype/internal/services/svtteng.h index 92e3c541f..2564a419d 100644 --- a/include/freetype/internal/services/svtteng.h +++ b/include/freetype/internal/services/svtteng.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* svtteng.h */ -/* */ -/* The FreeType TrueType engine query service (specification). */ -/* */ -/* Copyright 2006-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * svtteng.h + * + * The FreeType TrueType engine query service (specification). + * + * Copyright 2006-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef SVTTENG_H_ @@ -27,7 +27,7 @@ FT_BEGIN_HEADER /* - * SFNT table loading service. + * SFNT table loading service. */ #define FT_SERVICE_ID_TRUETYPE_ENGINE "truetype-engine" diff --git a/include/freetype/internal/services/svttglyf.h b/include/freetype/internal/services/svttglyf.h index bacf8324c..38444e932 100644 --- a/include/freetype/internal/services/svttglyf.h +++ b/include/freetype/internal/services/svttglyf.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* svttglyf.h */ -/* */ -/* The FreeType TrueType glyph service. */ -/* */ -/* Copyright 2007-2018 by */ -/* David Turner. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * svttglyf.h + * + * The FreeType TrueType glyph service. + * + * Copyright 2007-2018 by + * David Turner. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef SVTTGLYF_H_ #define SVTTGLYF_H_ diff --git a/include/freetype/internal/services/svwinfnt.h b/include/freetype/internal/services/svwinfnt.h index 80d481cbd..3aaa8a8ae 100644 --- a/include/freetype/internal/services/svwinfnt.h +++ b/include/freetype/internal/services/svwinfnt.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* svwinfnt.h */ -/* */ -/* The FreeType Windows FNT/FONT service (specification). */ -/* */ -/* Copyright 2003-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * svwinfnt.h + * + * The FreeType Windows FNT/FONT service (specification). + * + * Copyright 2003-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef SVWINFNT_H_ diff --git a/include/freetype/internal/sfnt.h b/include/freetype/internal/sfnt.h index dceb8974c..00b7ae5e5 100644 --- a/include/freetype/internal/sfnt.h +++ b/include/freetype/internal/sfnt.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* sfnt.h */ -/* */ -/* High-level `sfnt' driver interface (specification). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * sfnt.h + * + * High-level `sfnt' driver interface (specification). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef SFNT_H_ @@ -28,43 +28,48 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* 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 */ - /* face->format_tag. */ - /* */ - /* <Input> */ - /* stream :: The input stream. */ - /* */ - /* face :: 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. */ - /* */ - /* num_params :: The number of additional parameters. */ - /* */ - /* params :: Optional additional parameters. */ - /* */ - /* <Return> */ - /* FreeType error code. 0 means success. */ - /* */ - /* <Note> */ - /* The stream cursor must be at the font file's origin. */ - /* */ - /* 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. */ - /* */ + /************************************************************************** + * + * @FuncType: + * 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 + * face->format_tag. + * + * @Input: + * stream :: + * The input stream. + * + * face :: + * 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. + * + * num_params :: + * The number of additional parameters. + * + * params :: + * Optional additional parameters. + * + * @Return: + * FreeType error code. 0 means success. + * + * @Note: + * The stream cursor must be at the font file's origin. + * + * 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. + */ typedef FT_Error (*TT_Init_Face_Func)( FT_Stream stream, TT_Face face, @@ -73,36 +78,41 @@ FT_BEGIN_HEADER FT_Parameter* params ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* 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. */ - /* */ - /* <Input> */ - /* stream :: The input stream. */ - /* */ - /* face :: 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. */ - /* */ - /* num_params :: The number of additional parameters. */ - /* */ - /* params :: Optional additional parameters. */ - /* */ - /* <Return> */ - /* FreeType error code. 0 means success. */ - /* */ - /* <Note> */ - /* This function must be called after TT_Init_Face_Func(). */ - /* */ + /************************************************************************** + * + * @FuncType: + * 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. + * + * @Input: + * stream :: + * The input stream. + * + * face :: + * 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. + * + * num_params :: + * The number of additional parameters. + * + * params :: + * Optional additional parameters. + * + * @Return: + * FreeType error code. 0 means success. + * + * @Note: + * This function must be called after TT_Init_Face_Func(). + */ typedef FT_Error (*TT_Load_Face_Func)( FT_Stream stream, TT_Face face, @@ -111,64 +121,70 @@ FT_BEGIN_HEADER FT_Parameter* params ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* TT_Done_Face_Func */ - /* */ - /* <Description> */ - /* A callback used to delete the common SFNT data from a face. */ - /* */ - /* <Input> */ - /* face :: A handle to the target face object. */ - /* */ - /* <Note> */ - /* This function does NOT destroy the face object. */ - /* */ + /************************************************************************** + * + * @FuncType: + * TT_Done_Face_Func + * + * @Description: + * A callback used to delete the common SFNT data from a face. + * + * @Input: + * face :: + * A handle to the target face object. + * + * @Note: + * This function does NOT destroy the face object. + */ typedef void (*TT_Done_Face_Func)( TT_Face face ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* TT_Load_Any_Func */ - /* */ - /* <Description> */ - /* Load any font table into client memory. */ - /* */ - /* <Input> */ - /* face :: 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. */ - /* */ - /* offset :: 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 == 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). */ - /* */ - /* <Output> */ - /* buffer :: The address of target buffer. */ - /* */ - /* <Return> */ - /* TrueType error code. 0 means success. */ - /* */ + /************************************************************************** + * + * @FuncType: + * TT_Load_Any_Func + * + * @Description: + * Load any font table into client memory. + * + * @Input: + * face :: + * 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. + * + * offset :: + * 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 == 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). + * + * @Output: + * buffer :: + * The address of target buffer. + * + * @Return: + * TrueType error code. 0 means success. + */ typedef FT_Error (*TT_Load_Any_Func)( TT_Face face, FT_ULong tag, @@ -177,34 +193,40 @@ FT_BEGIN_HEADER FT_ULong* length ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* TT_Find_SBit_Image_Func */ - /* */ - /* <Description> */ - /* Check whether an embedded bitmap (an `sbit') exists for a given */ - /* glyph, at a given strike. */ - /* */ - /* <Input> */ - /* face :: The target face object. */ - /* */ - /* glyph_index :: The glyph index. */ - /* */ - /* strike_index :: The current strike index. */ - /* */ - /* <Output> */ - /* arange :: The SBit range containing the glyph index. */ - /* */ - /* astrike :: The SBit strike containing the glyph index. */ - /* */ - /* aglyph_offset :: 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. */ - /* */ + /************************************************************************** + * + * @FuncType: + * TT_Find_SBit_Image_Func + * + * @Description: + * Check whether an embedded bitmap (an `sbit') exists for a given + * glyph, at a given strike. + * + * @Input: + * face :: + * The target face object. + * + * glyph_index :: + * The glyph index. + * + * strike_index :: + * The current strike index. + * + * @Output: + * arange :: + * The SBit range containing the glyph index. + * + * astrike :: + * The SBit strike containing the glyph index. + * + * aglyph_offset :: + * 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. + */ typedef FT_Error (*TT_Find_SBit_Image_Func)( TT_Face face, FT_UInt glyph_index, @@ -214,78 +236,81 @@ FT_BEGIN_HEADER FT_ULong *aglyph_offset ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* TT_Load_SBit_Metrics_Func */ - /* */ - /* <Description> */ - /* Get the big metrics for a given embedded bitmap. */ - /* */ - /* <Input> */ - /* stream :: The input stream. */ - /* */ - /* range :: The SBit range containing the glyph. */ - /* */ - /* <Output> */ - /* big_metrics :: A big SBit metrics structure for the glyph. */ - /* */ - /* <Return> */ - /* 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. */ - /* */ - /* If the image format uses variable metrics, the stream cursor is */ - /* positioned just after the metrics header in the `EBDT' table on */ - /* function exit. */ - /* */ + /************************************************************************** + * + * @FuncType: + * TT_Load_SBit_Metrics_Func + * + * @Description: + * Get the big metrics for a given embedded bitmap. + * + * @Input: + * stream :: + * The input stream. + * + * range :: + * The SBit range containing the glyph. + * + * @Output: + * big_metrics :: + * A big SBit metrics structure for the glyph. + * + * @Return: + * 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. + * + * If the image format uses variable metrics, the stream cursor is + * positioned just after the metrics header in the `EBDT' table on + * function exit. + */ typedef FT_Error (*TT_Load_SBit_Metrics_Func)( FT_Stream stream, TT_SBit_Range range, TT_SBit_Metrics metrics ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* TT_Load_SBit_Image_Func */ - /* */ - /* <Description> */ - /* Load a given glyph sbit image from the font resource. This also */ - /* returns its metrics. */ - /* */ - /* <Input> */ - /* face :: */ - /* The target face object. */ - /* */ - /* strike_index :: */ - /* The strike index. */ - /* */ - /* glyph_index :: */ - /* The current glyph index. */ - /* */ - /* load_flags :: */ - /* The current load flags. */ - /* */ - /* stream :: */ - /* The input stream. */ - /* */ - /* <Output> */ - /* amap :: */ - /* The target pixmap. */ - /* */ - /* ametrics :: */ - /* 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. */ - /* */ - /* <Note> */ - /* The `map.buffer' field is always freed before the glyph is loaded. */ - /* */ + /************************************************************************** + * + * @FuncType: + * TT_Load_SBit_Image_Func + * + * @Description: + * Load a given glyph sbit image from the font resource. This also + * returns its metrics. + * + * @Input: + * face :: + * The target face object. + * + * strike_index :: + * The strike index. + * + * glyph_index :: + * The current glyph index. + * + * load_flags :: + * The current load flags. + * + * stream :: + * The input stream. + * + * @Output: + * amap :: + * The target pixmap. + * + * ametrics :: + * 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. + * + * @Note: + * The `map.buffer' field is always freed before the glyph is loaded. + */ typedef FT_Error (*TT_Load_SBit_Image_Func)( TT_Face face, FT_ULong strike_index, @@ -296,130 +321,146 @@ FT_BEGIN_HEADER TT_SBit_MetricsRec *ametrics ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* TT_Set_SBit_Strike_Func */ - /* */ - /* <Description> */ - /* Select an sbit strike for a given size request. */ - /* */ - /* <Input> */ - /* face :: The target face object. */ - /* */ - /* req :: The size request. */ - /* */ - /* <Output> */ - /* astrike_index :: 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. */ - /* */ + /************************************************************************** + * + * @FuncType: + * TT_Set_SBit_Strike_Func + * + * @Description: + * Select an sbit strike for a given size request. + * + * @Input: + * face :: + * The target face object. + * + * req :: + * The size request. + * + * @Output: + * astrike_index :: + * 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. + */ typedef FT_Error (*TT_Set_SBit_Strike_Func)( TT_Face face, FT_Size_Request req, FT_ULong* astrike_index ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* TT_Load_Strike_Metrics_Func */ - /* */ - /* <Description> */ - /* Load the metrics of a given strike. */ - /* */ - /* <Input> */ - /* face :: The target face object. */ - /* */ - /* strike_index :: The strike index. */ - /* */ - /* <Output> */ - /* metrics :: the metrics of the strike. */ - /* */ - /* <Return> */ - /* FreeType error code. 0 means success. Returns an error if no */ - /* such sbit strike exists. */ - /* */ + /************************************************************************** + * + * @FuncType: + * TT_Load_Strike_Metrics_Func + * + * @Description: + * Load the metrics of a given strike. + * + * @Input: + * face :: + * The target face object. + * + * strike_index :: + * The strike index. + * + * @Output: + * metrics :: + * the metrics of the strike. + * + * @Return: + * 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, FT_ULong strike_index, FT_Size_Metrics* metrics ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* TT_Get_PS_Name_Func */ - /* */ - /* <Description> */ - /* Get the PostScript glyph name of a glyph. */ - /* */ - /* <Input> */ - /* idx :: 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. */ - /* */ - /* You must not modify the returned string! */ - /* */ - /* <Output> */ - /* FreeType error code. 0 means success. */ - /* */ + /************************************************************************** + * + * @FuncType: + * TT_Get_PS_Name_Func + * + * @Description: + * Get the PostScript glyph name of a glyph. + * + * @Input: + * idx :: + * 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. + * + * You must not modify the returned string! + * + * @Output: + * FreeType error code. 0 means success. + */ typedef FT_Error (*TT_Get_PS_Name_Func)( TT_Face face, FT_UInt idx, FT_String** PSname ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* TT_Load_Metrics_Func */ - /* */ - /* <Description> */ - /* Load a metrics table, which is a table with a horizontal and a */ - /* vertical version. */ - /* */ - /* <Input> */ - /* face :: A handle to the target face object. */ - /* */ - /* stream :: The input stream. */ - /* */ - /* vertical :: A boolean flag. If set, load the vertical one. */ - /* */ - /* <Return> */ - /* FreeType error code. 0 means success. */ - /* */ + /************************************************************************** + * + * @FuncType: + * TT_Load_Metrics_Func + * + * @Description: + * Load a metrics table, which is a table with a horizontal and a + * vertical version. + * + * @Input: + * face :: + * A handle to the target face object. + * + * stream :: + * The input stream. + * + * vertical :: + * A boolean flag. If set, load the vertical one. + * + * @Return: + * FreeType error code. 0 means success. + */ typedef FT_Error (*TT_Load_Metrics_Func)( TT_Face face, FT_Stream stream, FT_Bool vertical ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* TT_Get_Metrics_Func */ - /* */ - /* <Description> */ - /* Load the horizontal or vertical header in a face object. */ - /* */ - /* <Input> */ - /* face :: A handle to the target face object. */ - /* */ - /* vertical :: A boolean flag. If set, load vertical metrics. */ - /* */ - /* gindex :: The glyph index. */ - /* */ - /* <Output> */ - /* abearing :: 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. */ - /* */ + /************************************************************************** + * + * @FuncType: + * TT_Get_Metrics_Func + * + * @Description: + * Load the horizontal or vertical header in a face object. + * + * @Input: + * face :: + * A handle to the target face object. + * + * vertical :: + * A boolean flag. If set, load vertical metrics. + * + * gindex :: + * The glyph index. + * + * @Output: + * abearing :: + * 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. + */ typedef void (*TT_Get_Metrics_Func)( TT_Face face, FT_Bool vertical, @@ -428,29 +469,33 @@ FT_BEGIN_HEADER FT_UShort* aadvance ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* TT_Load_Colr_Layer_Func */ - /* */ - /* <Description> */ - /* Load the color layer data given a glyph index. */ - /* */ - /* <Input> */ - /* face :: The target face object. */ - /* */ - /* idx :: The glyph index. */ - /* */ - /* <Output> */ - /* layers :: The layer info with color index and glyph index. */ - /* Deallocate with `FT_FREE'. */ - /* */ - /* num_layers :: Number of layers. */ - /* */ - /* <Return> */ - /* FreeType error code. 0 means success. Returns an error if no */ - /* color layer information exists for `idx'. */ - /* */ + /************************************************************************** + * + * @FuncType: + * TT_Load_Colr_Layer_Func + * + * @Description: + * Load the color layer data given a glyph index. + * + * @Input: + * face :: + * The target face object. + * + * idx :: + * The glyph index. + * + * @Output: + * layers :: + * The layer info with color index and glyph index. + * Deallocate with `FT_FREE'. + * + * num_layers :: + * Number of layers. + * + * @Return: + * FreeType error code. 0 means success. Returns an error if no + * color layer information exists for `idx'. + */ typedef FT_Error (*TT_Load_Colr_Layer_Func)( TT_Face face, FT_UInt idx, @@ -458,31 +503,35 @@ FT_BEGIN_HEADER FT_UShort* num_layers ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* TT_Blend_Colr_Func */ - /* */ - /* <Description> */ - /* Blend the bitmap in `new_glyph' into `base_glyph' using the color */ - /* specified by `color_index'. */ - /* */ - /* XXX: Handle foregound color */ - /* */ - /* <Input> */ - /* face :: The target face object. */ - /* */ - /* color_index :: Color index from the COLR table. */ - /* */ - /* base_glyph :: Slot for bitmap to be merged into. The underlying */ - /* bitmap may get reallocated. */ - /* */ - /* new_glyph :: Slot to be incooperated into `base_glyph'. */ - /* */ - /* <Return> */ - /* FreeType error code. 0 means success. Returns an error if */ - /* color_index is invalid or reallocation fails. */ - /* */ + /************************************************************************** + * + * @FuncType: + * TT_Blend_Colr_Func + * + * @Description: + * Blend the bitmap in `new_glyph' into `base_glyph' using the color + * specified by `color_index'. + * + * XXX: Handle foregound color + * + * @Input: + * face :: + * The target face object. + * + * color_index :: + * Color index from the COLR table. + * + * base_glyph :: + * Slot for bitmap to be merged into. The underlying + * bitmap may get reallocated. + * + * new_glyph :: + * Slot to be incooperated into `base_glyph'. + * + * @Return: + * FreeType error code. 0 means success. Returns an error if + * color_index is invalid or reallocation fails. + */ typedef FT_Error (*TT_Blend_Colr_Func)( TT_Face face, FT_UInt color_index, @@ -490,57 +539,64 @@ FT_BEGIN_HEADER FT_GlyphSlot new_glyph ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* TT_Get_Name_Func */ - /* */ - /* <Description> */ - /* From the `name' table, return a given ENGLISH name record in */ - /* ASCII. */ - /* */ - /* <Input> */ - /* face :: A handle to the source face object. */ - /* */ - /* nameid :: The name id of the name record to return. */ - /* */ - /* <InOut> */ - /* name :: The address of an allocated string pointer. NULL if */ - /* no name is present. */ - /* */ - /* <Return> */ - /* FreeType error code. 0 means success. */ - /* */ + /************************************************************************** + * + * @FuncType: + * TT_Get_Name_Func + * + * @Description: + * From the `name' table, return a given ENGLISH name record in + * ASCII. + * + * @Input: + * face :: + * A handle to the source face object. + * + * nameid :: + * The name id of the name record to return. + * + * @InOut: + * name :: + * The address of an allocated string pointer. NULL if + * no name is present. + * + * @Return: + * FreeType error code. 0 means success. + */ typedef FT_Error (*TT_Get_Name_Func)( TT_Face face, FT_UShort nameid, FT_String** name ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* TT_Get_Name_ID_Func */ - /* */ - /* <Description> */ - /* Search whether an ENGLISH version for a given name ID is in the */ - /* `name' table. */ - /* */ - /* <Input> */ - /* face :: A handle to the source face object. */ - /* */ - /* nameid :: The name id of the name record to return. */ - /* */ - /* <Out> */ - /* win :: 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. */ - /* */ - /* <Return> */ - /* 1 if there is either a win or apple entry (or both), 0 otheriwse. */ - /* */ + /************************************************************************** + * + * @FuncType: + * TT_Get_Name_ID_Func + * + * @Description: + * Search whether an ENGLISH version for a given name ID is in the + * `name' table. + * + * @Input: + * face :: + * A handle to the source face object. + * + * nameid :: + * The name id of the name record to return. + * + * @Out: + * win :: + * 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. + * + * @Return: + * 1 if there is either a win or apple entry (or both), 0 otheriwse. + */ typedef FT_Bool (*TT_Get_Name_ID_Func)( TT_Face face, FT_UShort nameid, @@ -548,42 +604,45 @@ FT_BEGIN_HEADER FT_Int *apple ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* TT_Load_Table_Func */ - /* */ - /* <Description> */ - /* Load a given TrueType table. */ - /* */ - /* <Input> */ - /* face :: A handle to the target face object. */ - /* */ - /* stream :: The input stream. */ - /* */ - /* <Return> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @FuncType: + * TT_Load_Table_Func + * + * @Description: + * Load a given TrueType table. + * + * @Input: + * face :: + * A handle to the target face object. + * + * stream :: + * The input stream. + * + * @Return: + * 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. + */ typedef FT_Error (*TT_Load_Table_Func)( TT_Face face, FT_Stream stream ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* TT_Free_Table_Func */ - /* */ - /* <Description> */ - /* Free a given TrueType table. */ - /* */ - /* <Input> */ - /* face :: A handle to the target face object. */ - /* */ + /************************************************************************** + * + * @FuncType: + * TT_Free_Table_Func + * + * @Description: + * Free a given TrueType table. + * + * @Input: + * face :: + * A handle to the target face object. + */ typedef void (*TT_Free_Table_Func)( TT_Face face ); @@ -609,18 +668,18 @@ FT_BEGIN_HEADER FT_UInt right_glyph ); - /*************************************************************************/ - /* */ - /* <Struct> */ - /* 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. */ - /* */ - /* <Fields> */ - /* Check the various xxx_Func() descriptions for details. */ - /* */ + /************************************************************************** + * + * @Struct: + * 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. + * + * @Fields: + * Check the various xxx_Func() descriptions for details. + */ typedef struct SFNT_Interface_ { TT_Loader_GotoTableFunc goto_table; diff --git a/include/freetype/internal/t1types.h b/include/freetype/internal/t1types.h index 2118e3367..c78f7c5f6 100644 --- a/include/freetype/internal/t1types.h +++ b/include/freetype/internal/t1types.h @@ -1,20 +1,20 @@ -/***************************************************************************/ -/* */ -/* t1types.h */ -/* */ -/* Basic Type1/Type2 type definitions and interface (specification */ -/* only). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * t1types.h + * + * Basic Type1/Type2 type definitions and interface (specification + * only). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef T1TYPES_H_ @@ -45,28 +45,33 @@ FT_BEGIN_HEADER /*************************************************************************/ - /*************************************************************************/ - /* */ - /* <Struct> */ - /* T1_EncodingRec */ - /* */ - /* <Description> */ - /* A structure modeling a custom encoding. */ - /* */ - /* <Fields> */ - /* num_chars :: 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. */ - /* */ - /* char_index :: An array of corresponding glyph indices. */ - /* */ - /* char_name :: An array of corresponding glyph names. */ - /* */ + /************************************************************************** + * + * @Struct: + * T1_EncodingRec + * + * @Description: + * A structure modeling a custom encoding. + * + * @Fields: + * num_chars :: + * 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. + * + * char_index :: + * An array of corresponding glyph indices. + * + * char_name :: + * An array of corresponding glyph names. + */ typedef struct T1_EncodingRecRec_ { FT_Int num_chars; diff --git a/include/freetype/internal/tttypes.h b/include/freetype/internal/tttypes.h index 072636eca..c02d76dc6 100644 --- a/include/freetype/internal/tttypes.h +++ b/include/freetype/internal/tttypes.h @@ -1,20 +1,20 @@ -/***************************************************************************/ -/* */ -/* tttypes.h */ -/* */ -/* Basic SFNT/TrueType type definitions and interface (specification */ -/* only). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * tttypes.h + * + * Basic SFNT/TrueType type definitions and interface (specification + * only). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef TTTYPES_H_ @@ -46,27 +46,31 @@ FT_BEGIN_HEADER /*************************************************************************/ - /*************************************************************************/ - /* */ - /* <Struct> */ - /* TTC_HeaderRec */ - /* */ - /* <Description> */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* offsets :: The offsets of the font headers, one per face. */ - /* */ + /************************************************************************** + * + * @Struct: + * TTC_HeaderRec + * + * @Description: + * 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. + * + * 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. + * + * offsets :: + * The offsets of the font headers, one per face. + */ typedef struct TTC_HeaderRec_ { FT_ULong tag; @@ -77,25 +81,30 @@ FT_BEGIN_HEADER } TTC_HeaderRec; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* SFNT_HeaderRec */ - /* */ - /* <Description> */ - /* SFNT file format header. */ - /* */ - /* <Fields> */ - /* format_tag :: The font format tag. */ - /* */ - /* num_tables :: The number of tables in file. */ - /* */ - /* search_range :: Must be `16 * (max power of 2 <= num_tables)'. */ - /* */ - /* entry_selector :: Must be log2 of `search_range / 16'. */ - /* */ - /* range_shift :: Must be `num_tables * 16 - search_range'. */ - /* */ + /************************************************************************** + * + * @Struct: + * SFNT_HeaderRec + * + * @Description: + * SFNT file format header. + * + * @Fields: + * format_tag :: + * The font format tag. + * + * num_tables :: + * The number of tables in file. + * + * search_range :: + * Must be `16 * (max power of 2 <= num_tables)'. + * + * entry_selector :: + * Must be log2 of `search_range / 16'. + * + * range_shift :: + * Must be `num_tables * 16 - search_range'. + */ typedef struct SFNT_HeaderRec_ { FT_ULong format_tag; @@ -109,24 +118,28 @@ FT_BEGIN_HEADER } SFNT_HeaderRec, *SFNT_Header; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* TT_TableRec */ - /* */ - /* <Description> */ - /* This structure describes a given table of a TrueType font. */ - /* */ - /* <Fields> */ - /* Tag :: A four-bytes tag describing the table. */ - /* */ - /* CheckSum :: The table checksum. This value can be ignored. */ - /* */ - /* Offset :: The offset of the table from the start of the TrueType */ - /* font in its resource. */ - /* */ - /* Length :: The table length (in bytes). */ - /* */ + /************************************************************************** + * + * @Struct: + * TT_TableRec + * + * @Description: + * This structure describes a given table of a TrueType font. + * + * @Fields: + * Tag :: + * A four-bytes tag describing the table. + * + * CheckSum :: + * The table checksum. This value can be ignored. + * + * Offset :: + * The offset of the table from the start of the TrueType + * font in its resource. + * + * Length :: + * The table length (in bytes). + */ typedef struct TT_TableRec_ { FT_ULong Tag; /* table type */ @@ -137,19 +150,19 @@ FT_BEGIN_HEADER } TT_TableRec, *TT_Table; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* WOFF_HeaderRec */ - /* */ - /* <Description> */ - /* WOFF file format header. */ - /* */ - /* <Fields> */ - /* See */ - /* */ - /* https://www.w3.org/TR/WOFF/#WOFFHeader */ - /* */ + /************************************************************************** + * + * @Struct: + * WOFF_HeaderRec + * + * @Description: + * WOFF file format header. + * + * @Fields: + * See + * + * https://www.w3.org/TR/WOFF/#WOFFHeader + */ typedef struct WOFF_HeaderRec_ { FT_ULong signature; @@ -169,30 +182,36 @@ FT_BEGIN_HEADER } WOFF_HeaderRec, *WOFF_Header; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* WOFF_TableRec */ - /* */ - /* <Description> */ - /* This structure describes a given table of a WOFF font. */ - /* */ - /* <Fields> */ - /* Tag :: A four-bytes tag describing the table. */ - /* */ - /* Offset :: The offset of the table from the start of the WOFF */ - /* font in its resource. */ - /* */ - /* CompLength :: Compressed table length (in bytes). */ - /* */ - /* OrigLength :: Uncompressed table length (in bytes). */ - /* */ - /* CheckSum :: 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. */ - /* */ + /************************************************************************** + * + * @Struct: + * WOFF_TableRec + * + * @Description: + * This structure describes a given table of a WOFF font. + * + * @Fields: + * Tag :: + * A four-bytes tag describing the table. + * + * Offset :: + * The offset of the table from the start of the WOFF + * font in its resource. + * + * CompLength :: + * Compressed table length (in bytes). + * + * OrigLength :: + * Uncompressed table length (in bytes). + * + * CheckSum :: + * 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. + */ typedef struct WOFF_TableRec_ { FT_ULong Tag; /* table ID */ @@ -206,20 +225,22 @@ FT_BEGIN_HEADER } WOFF_TableRec, *WOFF_Table; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* TT_LongMetricsRec */ - /* */ - /* <Description> */ - /* A structure modeling the long metrics of the `hmtx' and `vmtx' */ - /* TrueType tables. The values are expressed in font units. */ - /* */ - /* <Fields> */ - /* advance :: The advance width or height for the glyph. */ - /* */ - /* bearing :: The left-side or top-side bearing for the glyph. */ - /* */ + /************************************************************************** + * + * @Struct: + * TT_LongMetricsRec + * + * @Description: + * A structure modeling the long metrics of the `hmtx' and `vmtx' + * TrueType tables. The values are expressed in font units. + * + * @Fields: + * advance :: + * The advance width or height for the glyph. + * + * bearing :: + * The left-side or top-side bearing for the glyph. + */ typedef struct TT_LongMetricsRec_ { FT_UShort advance; @@ -228,45 +249,52 @@ FT_BEGIN_HEADER } TT_LongMetricsRec, *TT_LongMetrics; - /*************************************************************************/ - /* */ - /* <Type> */ - /* TT_ShortMetrics */ - /* */ - /* <Description> */ - /* A simple type to model the short metrics of the `hmtx' and `vmtx' */ - /* tables. */ - /* */ + /************************************************************************** + * + * @Type: + * TT_ShortMetrics + * + * @Description: + * A simple type to model the short metrics of the `hmtx' and `vmtx' + * tables. + */ typedef FT_Short TT_ShortMetrics; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* 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). */ - /* */ - /* <Fields> */ - /* platformID :: The ID of the name's encoding platform. */ - /* */ - /* encodingID :: The platform-specific ID for the name's encoding. */ - /* */ - /* languageID :: The platform-specific ID for the name's language. */ - /* */ - /* nameID :: The ID specifying what kind of name this is. */ - /* */ - /* stringLength :: The length of the string in bytes. */ - /* */ - /* stringOffset :: 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. */ - /* */ + /************************************************************************** + * + * @Struct: + * 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). + * + * @Fields: + * platformID :: + * The ID of the name's encoding platform. + * + * encodingID :: + * The platform-specific ID for the name's encoding. + * + * languageID :: + * The platform-specific ID for the name's language. + * + * nameID :: + * The ID specifying what kind of name this is. + * + * stringLength :: + * The length of the string in bytes. + * + * stringOffset :: + * 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. + */ typedef struct TT_NameRec_ { FT_UShort platformID; @@ -284,23 +312,26 @@ FT_BEGIN_HEADER } TT_NameRec, *TT_Name; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* TT_LangTagRec */ - /* */ - /* <Description> */ - /* A structure modeling language tag records in SFNT `name' tables, */ - /* introduced in OpenType version 1.6. */ - /* */ - /* <Fields> */ - /* stringLength :: The length of the string in bytes. */ - /* */ - /* stringOffset :: 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. */ - /* */ + /************************************************************************** + * + * @Struct: + * TT_LangTagRec + * + * @Description: + * A structure modeling language tag records in SFNT `name' tables, + * introduced in OpenType version 1.6. + * + * @Fields: + * stringLength :: + * The length of the string in bytes. + * + * stringOffset :: + * 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. + */ typedef struct TT_LangTagRec_ { FT_UShort stringLength; @@ -314,30 +345,37 @@ FT_BEGIN_HEADER } TT_LangTagRec, *TT_LangTag; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* TT_NameTableRec */ - /* */ - /* <Description> */ - /* A structure modeling the TrueType name table. */ - /* */ - /* <Fields> */ - /* format :: The format of the name table. */ - /* */ - /* numNameRecords :: The number of names in table. */ - /* */ - /* storageOffset :: The offset of the name table in the `name' */ - /* TrueType table. */ - /* */ - /* names :: An array of name records. */ - /* */ - /* numLangTagRecords :: The number of language tags in table. */ - /* */ - /* langTags :: An array of language tag records. */ - /* */ - /* stream :: The file's input stream. */ - /* */ + /************************************************************************** + * + * @Struct: + * TT_NameTableRec + * + * @Description: + * A structure modeling the TrueType name table. + * + * @Fields: + * format :: + * The format of the name table. + * + * numNameRecords :: + * The number of names in table. + * + * storageOffset :: + * The offset of the name table in the `name' + * TrueType table. + * + * names :: + * An array of name records. + * + * numLangTagRecords :: + * The number of language tags in table. + * + * langTags :: + * An array of language tag records. + * + * stream :: + * The file's input stream. + */ typedef struct TT_NameTableRec_ { FT_UShort format; @@ -364,21 +402,23 @@ FT_BEGIN_HEADER /*************************************************************************/ - /*************************************************************************/ - /* */ - /* <Struct> */ - /* TT_GaspRangeRec */ - /* */ - /* <Description> */ - /* A tiny structure used to model a gasp range according to the */ - /* TrueType specification. */ - /* */ - /* <Fields> */ - /* maxPPEM :: The maximum ppem value to which `gaspFlag' applies. */ - /* */ - /* gaspFlag :: A flag describing the grid-fitting and anti-aliasing */ - /* modes to be used. */ - /* */ + /************************************************************************** + * + * @Struct: + * TT_GaspRangeRec + * + * @Description: + * A tiny structure used to model a gasp range according to the + * TrueType specification. + * + * @Fields: + * maxPPEM :: + * The maximum ppem value to which `gaspFlag' applies. + * + * gaspFlag :: + * A flag describing the grid-fitting and anti-aliasing + * modes to be used. + */ typedef struct TT_GaspRangeRec_ { FT_UShort maxPPEM; @@ -391,22 +431,25 @@ FT_BEGIN_HEADER #define TT_GASP_DOGRAY 0x02 - /*************************************************************************/ - /* */ - /* <Struct> */ - /* TT_GaspRec */ - /* */ - /* <Description> */ - /* A structure modeling the TrueType `gasp' table used to specify */ - /* grid-fitting and anti-aliasing behaviour. */ - /* */ - /* <Fields> */ - /* version :: The version number. */ - /* */ - /* numRanges :: The number of gasp ranges in table. */ - /* */ - /* gaspRanges :: An array of gasp ranges. */ - /* */ + /************************************************************************** + * + * @Struct: + * TT_GaspRec + * + * @Description: + * A structure modeling the TrueType `gasp' table used to specify + * grid-fitting and anti-aliasing behaviour. + * + * @Fields: + * version :: + * The version number. + * + * numRanges :: + * The number of gasp ranges in table. + * + * gaspRanges :: + * An array of gasp ranges. + */ typedef struct TT_Gasp_ { FT_UShort version; @@ -429,33 +472,41 @@ FT_BEGIN_HEADER /*************************************************************************/ - /*************************************************************************/ - /* */ - /* <Struct> */ - /* 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. */ - /* */ - /* <Fields> */ - /* height :: The glyph height in pixels. */ - /* */ - /* width :: The glyph width in pixels. */ - /* */ - /* horiBearingX :: The horizontal left bearing. */ - /* */ - /* horiBearingY :: The horizontal top bearing. */ - /* */ - /* horiAdvance :: The horizontal advance. */ - /* */ - /* vertBearingX :: The vertical left bearing. */ - /* */ - /* vertBearingY :: The vertical top bearing. */ - /* */ - /* vertAdvance :: The vertical advance. */ - /* */ + /************************************************************************** + * + * @Struct: + * 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. + * + * @Fields: + * height :: + * The glyph height in pixels. + * + * width :: + * The glyph width in pixels. + * + * horiBearingX :: + * The horizontal left bearing. + * + * horiBearingY :: + * The horizontal top bearing. + * + * horiAdvance :: + * The horizontal advance. + * + * vertBearingX :: + * The vertical left bearing. + * + * vertBearingY :: + * The vertical top bearing. + * + * vertAdvance :: + * The vertical advance. + */ typedef struct TT_SBit_MetricsRec_ { FT_UShort height; @@ -472,27 +523,32 @@ FT_BEGIN_HEADER } TT_SBit_MetricsRec, *TT_SBit_Metrics; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* 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. */ - /* */ - /* <Fields> */ - /* height :: The glyph height in pixels. */ - /* */ - /* width :: The glyph width in pixels. */ - /* */ - /* bearingX :: The left-side bearing. */ - /* */ - /* bearingY :: The top-side bearing. */ - /* */ - /* advance :: The advance width or height. */ - /* */ + /************************************************************************** + * + * @Struct: + * 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. + * + * @Fields: + * height :: + * The glyph height in pixels. + * + * width :: + * The glyph width in pixels. + * + * bearingX :: + * The left-side bearing. + * + * bearingY :: + * The top-side bearing. + * + * advance :: + * The advance width or height. + */ typedef struct TT_SBit_Small_Metrics_ { FT_Byte height; @@ -505,57 +561,68 @@ FT_BEGIN_HEADER } TT_SBit_SmallMetricsRec, *TT_SBit_SmallMetrics; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* 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. */ - /* */ - /* <Fields> */ - /* ascender :: The ascender in pixels. */ - /* */ - /* descender :: The descender in pixels. */ - /* */ - /* max_width :: The maximum glyph width in pixels. */ - /* */ - /* caret_slope_enumerator :: 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. */ - /* */ - /* caret_offset :: Offset in pixels to move the caret for */ - /* proper positioning. */ - /* */ - /* min_origin_SB :: Minimum of horiBearingX (resp. */ - /* vertBearingY). */ - /* min_advance_SB :: Minimum of */ - /* */ - /* horizontal advance - */ - /* ( horiBearingX + width ) */ - /* */ - /* resp. */ - /* */ - /* vertical advance - */ - /* ( vertBearingY + height ) */ - /* */ - /* max_before_BL :: Maximum of horiBearingY (resp. */ - /* vertBearingY). */ - /* */ - /* min_after_BL :: Minimum of */ - /* */ - /* horiBearingY - height */ - /* */ - /* resp. */ - /* */ - /* vertBearingX - width */ - /* */ - /* pads :: Unused (to make the size of the record */ - /* a multiple of 32 bits. */ - /* */ + /************************************************************************** + * + * @Struct: + * 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. + * + * @Fields: + * ascender :: + * The ascender in pixels. + * + * descender :: + * The descender in pixels. + * + * max_width :: + * The maximum glyph width in pixels. + * + * caret_slope_enumerator :: + * 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. + * + * caret_offset :: + * Offset in pixels to move the caret for + * proper positioning. + * + * min_origin_SB :: + * Minimum of horiBearingX (resp. + * vertBearingY). + * min_advance_SB :: + * Minimum of + * + * horizontal advance - + * ( horiBearingX + width ) + * + * resp. + * + * vertical advance - + * ( vertBearingY + height ) + * + * max_before_BL :: + * Maximum of horiBearingY (resp. + * vertBearingY). + * + * min_after_BL :: + * Minimum of + * + * horiBearingY - height + * + * resp. + * + * vertBearingX - width + * + * pads :: + * Unused (to make the size of the record + * a multiple of 32 bits. + */ typedef struct TT_SBit_LineMetricsRec_ { FT_Char ascender; @@ -573,43 +640,54 @@ FT_BEGIN_HEADER } TT_SBit_LineMetricsRec, *TT_SBit_LineMetrics; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* TT_SBit_RangeRec */ - /* */ - /* <Description> */ - /* A TrueType/OpenType subIndexTable as defined in the `EBLC' */ - /* (Microsoft) or `bloc' (Apple) tables. */ - /* */ - /* <Fields> */ - /* first_glyph :: The first glyph index in the range. */ - /* */ - /* last_glyph :: The last glyph index in the range. */ - /* */ - /* index_format :: The format of index table. Valid values are 1 */ - /* to 5. */ - /* */ - /* image_format :: The format of `EBDT' image data. */ - /* */ - /* image_offset :: 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. */ - /* */ - /* big_metrics :: 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. */ - /* */ - /* glyph_offsets :: For index formats 1 and 3. */ - /* */ - /* glyph_codes :: For index formats 4 and 5. */ - /* */ - /* table_offset :: The offset of the index table in the `EBLC' */ - /* table. Only used during strike loading. */ - /* */ + /************************************************************************** + * + * @Struct: + * TT_SBit_RangeRec + * + * @Description: + * A TrueType/OpenType subIndexTable as defined in the `EBLC' + * (Microsoft) or `bloc' (Apple) tables. + * + * @Fields: + * first_glyph :: + * The first glyph index in the range. + * + * last_glyph :: + * The last glyph index in the range. + * + * index_format :: + * The format of index table. Valid values are 1 + * to 5. + * + * image_format :: + * The format of `EBDT' image data. + * + * image_offset :: + * 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. + * + * big_metrics :: + * 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. + * + * glyph_offsets :: + * For index formats 1 and 3. + * + * glyph_codes :: + * For index formats 4 and 5. + * + * table_offset :: + * The offset of the index table in the `EBLC' + * table. Only used during strike loading. + */ typedef struct TT_SBit_RangeRec_ { FT_UShort first_glyph; @@ -631,47 +709,58 @@ FT_BEGIN_HEADER } TT_SBit_RangeRec, *TT_SBit_Range; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* TT_SBit_StrikeRec */ - /* */ - /* <Description> */ - /* A structure used describe a given bitmap strike in the `EBLC' */ - /* (Microsoft) or `bloc' (Apple) tables. */ - /* */ - /* <Fields> */ - /* num_index_ranges :: The number of index ranges. */ - /* */ - /* index_ranges :: 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 */ - /* */ - /* https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6bloc.html */ - /* */ - /* hori :: The line metrics for horizontal layouts. */ - /* */ - /* vert :: The line metrics for vertical layouts. */ - /* */ - /* start_glyph :: The lowest glyph index for this strike. */ - /* */ - /* end_glyph :: The highest glyph index for this strike. */ - /* */ - /* x_ppem :: The number of horizontal pixels per EM. */ - /* */ - /* y_ppem :: The number of vertical pixels per EM. */ - /* */ - /* bit_depth :: The bit depth. Valid values are 1, 2, 4, */ - /* and 8. */ - /* */ - /* flags :: Is this a vertical or horizontal strike? For */ - /* details, please see */ - /* */ - /* https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6bloc.html */ - /* */ + /************************************************************************** + * + * @Struct: + * TT_SBit_StrikeRec + * + * @Description: + * A structure used describe a given bitmap strike in the `EBLC' + * (Microsoft) or `bloc' (Apple) tables. + * + * @Fields: + * num_index_ranges :: + * The number of index ranges. + * + * index_ranges :: + * 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 + * + * https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6bloc.html + * + * hori :: + * The line metrics for horizontal layouts. + * + * vert :: + * The line metrics for vertical layouts. + * + * start_glyph :: + * The lowest glyph index for this strike. + * + * end_glyph :: + * The highest glyph index for this strike. + * + * x_ppem :: + * The number of horizontal pixels per EM. + * + * y_ppem :: + * The number of vertical pixels per EM. + * + * bit_depth :: + * The bit depth. Valid values are 1, 2, 4, + * and 8. + * + * flags :: + * Is this a vertical or horizontal strike? For + * details, please see + * + * https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6bloc.html + */ typedef struct TT_SBit_StrikeRec_ { FT_Int num_ranges; @@ -695,21 +784,24 @@ FT_BEGIN_HEADER } TT_SBit_StrikeRec, *TT_SBit_Strike; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* TT_SBit_ComponentRec */ - /* */ - /* <Description> */ - /* A simple structure to describe a compound sbit element. */ - /* */ - /* <Fields> */ - /* glyph_code :: The element's glyph index. */ - /* */ - /* x_offset :: The element's left bearing. */ - /* */ - /* y_offset :: The element's top bearing. */ - /* */ + /************************************************************************** + * + * @Struct: + * TT_SBit_ComponentRec + * + * @Description: + * A simple structure to describe a compound sbit element. + * + * @Fields: + * glyph_code :: + * The element's glyph index. + * + * x_offset :: + * The element's left bearing. + * + * y_offset :: + * The element's top bearing. + */ typedef struct TT_SBit_ComponentRec_ { FT_UShort glyph_code; @@ -719,28 +811,34 @@ FT_BEGIN_HEADER } TT_SBit_ComponentRec, *TT_SBit_Component; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* TT_SBit_ScaleRec */ - /* */ - /* <Description> */ - /* A structure used describe a given bitmap scaling table, as defined */ - /* in the `EBSC' table. */ - /* */ - /* <Fields> */ - /* hori :: The horizontal line metrics. */ - /* */ - /* vert :: The vertical line metrics. */ - /* */ - /* x_ppem :: The number of horizontal pixels per EM. */ - /* */ - /* y_ppem :: The number of vertical pixels per EM. */ - /* */ - /* x_ppem_substitute :: Substitution x_ppem value. */ - /* */ - /* y_ppem_substitute :: Substitution y_ppem value. */ - /* */ + /************************************************************************** + * + * @Struct: + * TT_SBit_ScaleRec + * + * @Description: + * A structure used describe a given bitmap scaling table, as defined + * in the `EBSC' table. + * + * @Fields: + * hori :: + * The horizontal line metrics. + * + * vert :: + * The vertical line metrics. + * + * x_ppem :: + * The number of horizontal pixels per EM. + * + * y_ppem :: + * The number of vertical pixels per EM. + * + * x_ppem_substitute :: + * Substitution x_ppem value. + * + * y_ppem_substitute :: + * Substitution y_ppem value. + */ typedef struct TT_SBit_ScaleRec_ { TT_SBit_LineMetricsRec hori; @@ -768,24 +866,28 @@ FT_BEGIN_HEADER /*************************************************************************/ - /*************************************************************************/ - /* */ - /* <Struct> */ - /* TT_Post_20Rec */ - /* */ - /* <Description> */ - /* Postscript names sub-table, format 2.0. Stores the PS name of */ - /* each glyph in the font face. */ - /* */ - /* <Fields> */ - /* num_glyphs :: The number of named glyphs in the table. */ - /* */ - /* num_names :: The number of PS names stored in the table. */ - /* */ - /* glyph_indices :: The indices of the glyphs in the names arrays. */ - /* */ - /* glyph_names :: The PS names not in Mac Encoding. */ - /* */ + /************************************************************************** + * + * @Struct: + * TT_Post_20Rec + * + * @Description: + * Postscript names sub-table, format 2.0. Stores the PS name of + * each glyph in the font face. + * + * @Fields: + * num_glyphs :: + * The number of named glyphs in the table. + * + * num_names :: + * The number of PS names stored in the table. + * + * glyph_indices :: + * The indices of the glyphs in the names arrays. + * + * glyph_names :: + * The PS names not in Mac Encoding. + */ typedef struct TT_Post_20Rec_ { FT_UShort num_glyphs; @@ -796,21 +898,23 @@ FT_BEGIN_HEADER } TT_Post_20Rec, *TT_Post_20; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* TT_Post_25Rec */ - /* */ - /* <Description> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Struct: + * TT_Post_25Rec + * + * @Description: + * 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. + */ typedef struct TT_Post_25_ { FT_UShort num_glyphs; @@ -819,21 +923,24 @@ FT_BEGIN_HEADER } TT_Post_25Rec, *TT_Post_25; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* TT_Post_NamesRec */ - /* */ - /* <Description> */ - /* Postscript names table, either format 2.0 or 2.5. */ - /* */ - /* <Fields> */ - /* loaded :: A flag to indicate whether the PS names are loaded. */ - /* */ - /* format_20 :: The sub-table used for format 2.0. */ - /* */ - /* format_25 :: The sub-table used for format 2.5. */ - /* */ + /************************************************************************** + * + * @Struct: + * TT_Post_NamesRec + * + * @Description: + * Postscript names table, either format 2.0 or 2.5. + * + * @Fields: + * loaded :: + * A flag to indicate whether the PS names are loaded. + * + * format_20 :: + * The sub-table used for format 2.0. + * + * format_25 :: + * The sub-table used for format 2.5. + */ typedef struct TT_Post_NamesRec_ { FT_Bool loaded; @@ -945,31 +1052,31 @@ 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'. */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * 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'. + * + */ - /*************************************************************************/ - /* */ - /* <Type> */ - /* 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. */ - /* */ - /* <Note> */ - /* The TT_Face structure is also used as a `parent class' for the */ - /* OpenType-CFF class (T2_Face). */ - /* */ + /************************************************************************** + * + * @Type: + * 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. + * + * @Note: + * The TT_Face structure is also used as a `parent class' for the + * OpenType-CFF class (T2_Face). + */ typedef struct TT_FaceRec_* TT_Face; @@ -981,31 +1088,35 @@ FT_BEGIN_HEADER typedef struct TT_LoaderRec_* TT_Loader; - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* TT_Loader_GotoTableFunc */ - /* */ - /* <Description> */ - /* Seeks a stream to the start of a given TrueType table. */ - /* */ - /* <Input> */ - /* face :: A handle to the target face object. */ - /* */ - /* tag :: A 4-byte tag used to name the table. */ - /* */ - /* stream :: The input stream. */ - /* */ - /* <Output> */ - /* length :: The length of the table in bytes. Set to 0 if not */ - /* needed. */ - /* */ - /* <Return> */ - /* FreeType error code. 0 means success. */ - /* */ - /* <Note> */ - /* The stream cursor must be at the font file's origin. */ - /* */ + /************************************************************************** + * + * @FuncType: + * TT_Loader_GotoTableFunc + * + * @Description: + * Seeks a stream to the start of a given TrueType table. + * + * @Input: + * face :: + * A handle to the target face object. + * + * tag :: + * A 4-byte tag used to name the table. + * + * stream :: + * The input stream. + * + * @Output: + * length :: + * The length of the table in bytes. Set to 0 if not + * needed. + * + * @Return: + * FreeType error code. 0 means success. + * + * @Note: + * The stream cursor must be at the font file's origin. + */ typedef FT_Error (*TT_Loader_GotoTableFunc)( TT_Face face, FT_ULong tag, @@ -1013,34 +1124,37 @@ FT_BEGIN_HEADER FT_ULong* length ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* TT_Loader_StartGlyphFunc */ - /* */ - /* <Description> */ - /* Seeks a stream to the start of a given glyph element, and opens a */ - /* frame for it. */ - /* */ - /* <Input> */ - /* loader :: The current TrueType glyph loader object. */ - /* */ - /* glyph index :: The index of the glyph to access. */ - /* */ - /* offset :: The offset of the glyph according to the */ - /* `locations' table. */ - /* */ - /* byte_count :: The size of the frame in bytes. */ - /* */ - /* <Return> */ - /* FreeType error code. 0 means success. */ - /* */ - /* <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 */ - /* different. */ - /* */ + /************************************************************************** + * + * @FuncType: + * TT_Loader_StartGlyphFunc + * + * @Description: + * Seeks a stream to the start of a given glyph element, and opens a + * frame for it. + * + * @Input: + * loader :: + * The current TrueType glyph loader object. + * + * glyph index :: The index of the glyph to access. + * + * offset :: + * The offset of the glyph according to the + * `locations' table. + * + * byte_count :: + * The size of the frame in bytes. + * + * @Return: + * FreeType error code. 0 means success. + * + * @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 + * different. + */ typedef FT_Error (*TT_Loader_StartGlyphFunc)( TT_Loader loader, FT_UInt glyph_index, @@ -1048,36 +1162,38 @@ FT_BEGIN_HEADER FT_UInt byte_count ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* TT_Loader_ReadGlyphFunc */ - /* */ - /* <Description> */ - /* Reads one glyph element (its header, a simple glyph, or a */ - /* composite) from the loader's current stream frame. */ - /* */ - /* <Input> */ - /* loader :: The current TrueType glyph loader object. */ - /* */ - /* <Return> */ - /* FreeType error code. 0 means success. */ - /* */ + /************************************************************************** + * + * @FuncType: + * TT_Loader_ReadGlyphFunc + * + * @Description: + * Reads one glyph element (its header, a simple glyph, or a + * composite) from the loader's current stream frame. + * + * @Input: + * loader :: + * The current TrueType glyph loader object. + * + * @Return: + * FreeType error code. 0 means success. + */ typedef FT_Error (*TT_Loader_ReadGlyphFunc)( TT_Loader loader ); - /*************************************************************************/ - /* */ - /* <FuncType> */ - /* TT_Loader_EndGlyphFunc */ - /* */ - /* <Description> */ - /* Closes the current loader stream frame for the glyph. */ - /* */ - /* <Input> */ - /* loader :: The current TrueType glyph loader object. */ - /* */ + /************************************************************************** + * + * @FuncType: + * TT_Loader_EndGlyphFunc + * + * @Description: + * Closes the current loader stream frame for the glyph. + * + * @Input: + * loader :: + * The current TrueType glyph loader object. + */ typedef void (*TT_Loader_EndGlyphFunc)( TT_Loader loader ); @@ -1124,274 +1240,347 @@ FT_BEGIN_HEADER #define TT_FACE_FLAG_VAR_MVAR ( 1 << 8 ) - /*************************************************************************/ - /* */ - /* TrueType Face Type */ - /* */ - /* <Struct> */ - /* TT_Face */ - /* */ - /* <Description> */ - /* The TrueType face class. These objects model the resolution and */ - /* point-size independent data found in a TrueType font file. */ - /* */ - /* <Fields> */ - /* root :: 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. */ - /* */ - /* format_tag :: The font format tag. */ - /* */ - /* num_tables :: The number of TrueType tables in this font */ - /* file. */ - /* */ - /* dir_tables :: The directory of TrueType tables for this */ - /* font file. */ - /* */ - /* header :: 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'). */ - /* */ - /* 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. */ - /* */ - /* vertical_info :: 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. */ - /* */ - /* num_names :: The number of name records within this */ - /* TrueType font. */ - /* */ - /* name_table :: The table of name records (`name'). */ - /* */ - /* os2 :: 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. */ - /* */ - /* cmap_table :: 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. */ - /* */ - /* 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). */ - /* */ - /* access_glyph_frame :: 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. */ - /* */ - /* read_glyph_header :: 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'. */ - /* */ - /* read_composite_glyph :: 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. */ - /* */ - /* psnames :: A pointer to the PostScript names service. */ - /* */ - /* mm :: A pointer to the Multiple Masters service. */ - /* */ - /* var :: A pointer to the Metrics Variations */ - /* service. */ - /* */ - /* hdmx :: 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. */ - /* */ - /* pclt :: 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. */ - /* */ - /* 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 */ - /* TT_CONFIG_OPTION_POSTSCRIPT_NAMES option. */ - /* */ - /* font_program_size :: 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. */ - /* */ - /* cvt_program_size :: 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. */ - /* */ - /* cvt_size :: 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. */ - /* */ - /* interpreter :: 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. */ - /* */ - /* glyf_len :: The length of the `glyf' table. Needed */ - /* for malformed `loca' tables. */ - /* */ - /* glyf_offset :: 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). */ - /* */ - /* blend :: 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. */ - /* */ - /* var_postscript_prefix :: */ - /* 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. */ - /* */ - /* horz_metrics_size :: The size of the `hmtx' table. */ - /* */ - /* vert_metrics_size :: 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. */ - /* */ - /* glyph_locations :: 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. */ - /* */ - /* hdmx_table_size :: The size of the `hdmx' table. */ - /* */ - /* hdmx_record_count :: The number of hdmx records. */ - /* */ - /* hdmx_record_size :: The size of a single hdmx record. */ - /* */ - /* hdmx_record_sizes :: An array holding the ppem sizes available */ - /* in the `hdmx' table. */ - /* */ - /* sbit_table :: A pointer to the font's embedded bitmap */ - /* location table. */ - /* */ - /* sbit_table_size :: 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. */ - /* */ - /* sbit_strike_map :: A mapping between the strike indices */ - /* exposed by the API and the indices used in */ - /* the font's sbit table. */ - /* */ - /* colr_and_cpal :: A pointer to data related to `COLR' and */ - /* `CPAL' tables. NULL if tables are not */ - /* available. */ - /* */ - /* kern_table :: A pointer to the `kern' table. */ - /* */ - /* kern_table_size :: 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). */ - /* */ - /* kern_avail_bits :: 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. */ - /* */ - /* bdf :: Data related to an SFNT font's `bdf' */ - /* table; see `tttypes.h'. */ - /* */ - /* horz_metrics_offset :: The file offset of the `hmtx' table. */ - /* */ - /* vert_metrics_offset :: 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). */ - /* */ - /* sph_compatibility_mode :: */ - /* 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.). */ - /* */ - /* ebdt_size :: The size of the sbit data table. */ - /* */ + /************************************************************************** + * + * TrueType Face Type + * + * @Struct: + * TT_Face + * + * @Description: + * The TrueType face class. These objects model the resolution and + * point-size independent data found in a TrueType font file. + * + * @Fields: + * root :: + * 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. + * + * format_tag :: + * The font format tag. + * + * num_tables :: + * The number of TrueType tables in this font + * file. + * + * dir_tables :: + * The directory of TrueType tables for this + * font file. + * + * header :: + * 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'). + * + * 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. + * + * vertical_info :: + * 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. + * + * num_names :: + * The number of name records within this + * TrueType font. + * + * name_table :: + * The table of name records (`name'). + * + * os2 :: + * 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. + * + * cmap_table :: + * 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. + * + * 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). + * + * access_glyph_frame :: + * 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. + * + * read_glyph_header :: + * 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'. + * + * read_composite_glyph :: + * 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. + * + * psnames :: + * A pointer to the PostScript names service. + * + * mm :: + * A pointer to the Multiple Masters service. + * + * var :: + * A pointer to the Metrics Variations + * service. + * + * hdmx :: + * 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. + * + * pclt :: + * 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. + * + * 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 + * TT_CONFIG_OPTION_POSTSCRIPT_NAMES option. + * + * font_program_size :: + * 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. + * + * cvt_program_size :: + * 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. + * + * cvt_size :: + * 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. + * + * interpreter :: + * 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. + * + * glyf_len :: + * The length of the `glyf' table. Needed + * for malformed `loca' tables. + * + * glyf_offset :: + * 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). + * + * blend :: + * 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. + * + * var_postscript_prefix :: + * 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. + * + * horz_metrics_size :: + * The size of the `hmtx' table. + * + * vert_metrics_size :: + * 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. + * + * glyph_locations :: + * 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. + * + * hdmx_table_size :: + * The size of the `hdmx' table. + * + * hdmx_record_count :: + * The number of hdmx records. + * + * hdmx_record_size :: + * The size of a single hdmx record. + * + * hdmx_record_sizes :: + * An array holding the ppem sizes available + * in the `hdmx' table. + * + * sbit_table :: + * A pointer to the font's embedded bitmap + * location table. + * + * sbit_table_size :: + * 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. + * + * sbit_strike_map :: + * A mapping between the strike indices + * exposed by the API and the indices used in + * the font's sbit table. + * + * colr_and_cpal :: + * A pointer to data related to `COLR' and + * `CPAL' tables. NULL if tables are not + * available. + * + * kern_table :: + * A pointer to the `kern' table. + * + * kern_table_size :: + * 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). + * + * kern_avail_bits :: + * 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. + * + * bdf :: + * Data related to an SFNT font's `bdf' + * table; see `tttypes.h'. + * + * horz_metrics_offset :: + * The file offset of the `hmtx' table. + * + * vert_metrics_offset :: + * 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). + * + * sph_compatibility_mode :: + * 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.). + * + * ebdt_size :: + * The size of the sbit data table. + */ typedef struct TT_FaceRec_ { FT_FaceRec root; @@ -1449,11 +1638,11 @@ FT_BEGIN_HEADER void* psaux; - /***********************************************************************/ - /* */ - /* Optional TrueType/OpenType tables */ - /* */ - /***********************************************************************/ + /************************************************************************ + * + * Optional TrueType/OpenType tables + * + */ /* grid-fitting and scaling table */ TT_GaspRec gasp; /* the `gasp' table */ @@ -1469,11 +1658,11 @@ FT_BEGIN_HEADER TT_Post_NamesRec postscript_names; - /***********************************************************************/ - /* */ - /* TrueType-specific fields (ignored by the CFF driver) */ - /* */ - /***********************************************************************/ + /************************************************************************ + * + * TrueType-specific fields (ignored by the CFF driver) + * + */ /* the font program, if any */ FT_ULong font_program_size; @@ -1492,12 +1681,12 @@ FT_BEGIN_HEADER TT_Interpreter interpreter; - /***********************************************************************/ - /* */ - /* Other tables or fields. This is used by derivative formats like */ - /* OpenType. */ - /* */ - /***********************************************************************/ + /************************************************************************ + * + * Other tables or fields. This is used by derivative formats like + * OpenType. + * + */ FT_Generic extra; @@ -1570,37 +1759,47 @@ FT_BEGIN_HEADER } TT_FaceRec; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* TT_GlyphZoneRec */ - /* */ - /* <Description> */ - /* A glyph zone is used to load, scale and hint glyph outline */ - /* coordinates. */ - /* */ - /* <Fields> */ - /* memory :: A handle to the memory manager. */ - /* */ - /* max_points :: The maximum size in points of the zone. */ - /* */ - /* max_contours :: Max size in links contours of the zone. */ - /* */ - /* n_points :: The current number of points in the zone. */ - /* */ - /* n_contours :: The current number of contours in the zone. */ - /* */ - /* org :: The original glyph coordinates (font */ - /* units/scaled). */ - /* */ - /* cur :: The current glyph coordinates (scaled/hinted). */ - /* */ - /* tags :: The point control tags. */ - /* */ - /* contours :: The contours end points. */ - /* */ - /* first_point :: Offset of the current subglyph's first point. */ - /* */ + /************************************************************************** + * + * @Struct: + * TT_GlyphZoneRec + * + * @Description: + * A glyph zone is used to load, scale and hint glyph outline + * coordinates. + * + * @Fields: + * memory :: + * A handle to the memory manager. + * + * max_points :: + * The maximum size in points of the zone. + * + * max_contours :: + * Max size in links contours of the zone. + * + * n_points :: + * The current number of points in the zone. + * + * n_contours :: + * The current number of contours in the zone. + * + * org :: + * The original glyph coordinates (font + * units/scaled). + * + * cur :: + * The current glyph coordinates (scaled/hinted). + * + * tags :: + * The point control tags. + * + * contours :: + * The contours end points. + * + * first_point :: + * Offset of the current subglyph's first point. + */ typedef struct TT_GlyphZoneRec_ { FT_Memory memory; @@ -1625,14 +1824,14 @@ FT_BEGIN_HEADER typedef struct TT_ExecContextRec_* TT_ExecContext; - /*************************************************************************/ - /* */ - /* <Type> */ - /* TT_Size */ - /* */ - /* <Description> */ - /* A handle to a TrueType size object. */ - /* */ + /************************************************************************** + * + * @Type: + * TT_Size + * + * @Description: + * A handle to a TrueType size object. + */ typedef struct TT_SizeRec_* TT_Size; diff --git a/include/freetype/t1tables.h b/include/freetype/t1tables.h index 3503c2616..4e4b02d32 100644 --- a/include/freetype/t1tables.h +++ b/include/freetype/t1tables.h @@ -1,20 +1,20 @@ -/***************************************************************************/ -/* */ -/* t1tables.h */ -/* */ -/* Basic Type 1/Type 2 tables definitions and interface (specification */ -/* only). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * t1tables.h + * + * Basic Type 1/Type 2 tables definitions and interface (specification + * only). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef T1TABLES_H_ @@ -34,58 +34,58 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* type1_tables */ - /* */ - /* <Title> */ - /* Type 1 Tables */ - /* */ - /* <Abstract> */ - /* Type~1 (PostScript) specific font tables. */ - /* */ - /* <Description> */ - /* This section contains the definition of Type 1-specific tables, */ - /* including structures related to other PostScript font formats. */ - /* */ - /* <Order> */ - /* PS_FontInfoRec */ - /* PS_FontInfo */ - /* PS_PrivateRec */ - /* PS_Private */ - /* */ - /* CID_FaceDictRec */ - /* CID_FaceDict */ - /* CID_FaceInfoRec */ - /* CID_FaceInfo */ - /* */ - /* FT_Has_PS_Glyph_Names */ - /* FT_Get_PS_Font_Info */ - /* FT_Get_PS_Font_Private */ - /* FT_Get_PS_Font_Value */ - /* */ - /* T1_Blend_Flags */ - /* T1_EncodingType */ - /* PS_Dict_Keys */ - /* */ - /*************************************************************************/ + /************************************************************************** + * + * @Section: + * type1_tables + * + * @Title: + * Type 1 Tables + * + * @Abstract: + * Type~1 (PostScript) specific font tables. + * + * @Description: + * This section contains the definition of Type 1-specific tables, + * including structures related to other PostScript font formats. + * + * @Order: + * PS_FontInfoRec + * PS_FontInfo + * PS_PrivateRec + * PS_Private + * + * CID_FaceDictRec + * CID_FaceDict + * CID_FaceInfoRec + * CID_FaceInfo + * + * FT_Has_PS_Glyph_Names + * FT_Get_PS_Font_Info + * FT_Get_PS_Font_Private + * FT_Get_PS_Font_Value + * + * T1_Blend_Flags + * T1_EncodingType + * PS_Dict_Keys + * + */ /* Note that we separate font data in PS_FontInfoRec and PS_PrivateRec */ /* structures in order to support Multiple Master fonts. */ - /*************************************************************************/ - /* */ - /* <Struct> */ - /* PS_FontInfoRec */ - /* */ - /* <Description> */ - /* A structure used to model a Type~1 or Type~2 FontInfo dictionary. */ - /* Note that for Multiple Master fonts, each instance has its own */ - /* FontInfo dictionary. */ - /* */ + /************************************************************************** + * + * @Struct: + * PS_FontInfoRec + * + * @Description: + * A structure used to model a Type~1 or Type~2 FontInfo dictionary. + * Note that for Multiple Master fonts, each instance has its own + * FontInfo dictionary. + */ typedef struct PS_FontInfoRec_ { FT_String* version; @@ -101,40 +101,40 @@ FT_BEGIN_HEADER } PS_FontInfoRec; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* PS_FontInfo */ - /* */ - /* <Description> */ - /* A handle to a @PS_FontInfoRec structure. */ - /* */ + /************************************************************************** + * + * @Struct: + * PS_FontInfo + * + * @Description: + * A handle to a @PS_FontInfoRec structure. + */ typedef struct PS_FontInfoRec_* PS_FontInfo; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* T1_FontInfo */ - /* */ - /* <Description> */ - /* This type is equivalent to @PS_FontInfoRec. It is deprecated but */ - /* kept to maintain source compatibility between various versions of */ - /* FreeType. */ - /* */ + /************************************************************************** + * + * @Struct: + * T1_FontInfo + * + * @Description: + * 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; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Struct: + * 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. + */ typedef struct PS_PrivateRec_ { FT_Int unique_id; @@ -176,56 +176,56 @@ FT_BEGIN_HEADER } PS_PrivateRec; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* PS_Private */ - /* */ - /* <Description> */ - /* A handle to a @PS_PrivateRec structure. */ - /* */ + /************************************************************************** + * + * @Struct: + * PS_Private + * + * @Description: + * A handle to a @PS_PrivateRec structure. + */ typedef struct PS_PrivateRec_* PS_Private; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* T1_Private */ - /* */ - /* <Description> */ - /* This type is equivalent to @PS_PrivateRec. It is deprecated but */ - /* kept to maintain source compatibility between various versions of */ - /* FreeType. */ - /* */ + /************************************************************************** + * + * @Struct: + * T1_Private + * + * @Description: + * 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; - /*************************************************************************/ - /* */ - /* <Enum> */ - /* 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. */ - /* */ - /* <Values> */ - /* T1_BLEND_UNDERLINE_POSITION :: */ - /* T1_BLEND_UNDERLINE_THICKNESS :: */ - /* T1_BLEND_ITALIC_ANGLE :: */ - /* T1_BLEND_BLUE_VALUES :: */ - /* T1_BLEND_OTHER_BLUES :: */ - /* T1_BLEND_STANDARD_WIDTH :: */ - /* T1_BLEND_STANDARD_HEIGHT :: */ - /* T1_BLEND_STEM_SNAP_WIDTHS :: */ - /* T1_BLEND_STEM_SNAP_HEIGHTS :: */ - /* T1_BLEND_BLUE_SCALE :: */ - /* T1_BLEND_BLUE_SHIFT :: */ - /* T1_BLEND_FAMILY_BLUES :: */ - /* T1_BLEND_FAMILY_OTHER_BLUES :: */ - /* T1_BLEND_FORCE_BOLD :: */ - /* */ + /************************************************************************** + * + * @Enum: + * 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. + * + * @Values: + * T1_BLEND_UNDERLINE_POSITION :: + * T1_BLEND_UNDERLINE_THICKNESS :: + * T1_BLEND_ITALIC_ANGLE :: + * T1_BLEND_BLUE_VALUES :: + * T1_BLEND_OTHER_BLUES :: + * T1_BLEND_STANDARD_WIDTH :: + * T1_BLEND_STANDARD_HEIGHT :: + * T1_BLEND_STEM_SNAP_WIDTHS :: + * T1_BLEND_STEM_SNAP_HEIGHTS :: + * T1_BLEND_BLUE_SCALE :: + * T1_BLEND_BLUE_SHIFT :: + * T1_BLEND_FAMILY_BLUES :: + * T1_BLEND_FAMILY_OTHER_BLUES :: + * T1_BLEND_FORCE_BOLD :: + */ typedef enum T1_Blend_Flags_ { /* required fields in a FontInfo blend dictionary */ @@ -330,14 +330,14 @@ FT_BEGIN_HEADER typedef PS_BlendRec T1_Blend; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* CID_FaceDictRec */ - /* */ - /* <Description> */ - /* A structure used to represent data in a CID top-level dictionary. */ - /* */ + /************************************************************************** + * + * @Struct: + * CID_FaceDictRec + * + * @Description: + * A structure used to represent data in a CID top-level dictionary. + */ typedef struct CID_FaceDictRec_ { PS_PrivateRec private_dict; @@ -359,38 +359,38 @@ FT_BEGIN_HEADER } CID_FaceDictRec; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* CID_FaceDict */ - /* */ - /* <Description> */ - /* A handle to a @CID_FaceDictRec structure. */ - /* */ + /************************************************************************** + * + * @Struct: + * CID_FaceDict + * + * @Description: + * A handle to a @CID_FaceDictRec structure. + */ typedef struct CID_FaceDictRec_* CID_FaceDict; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* CID_FontDict */ - /* */ - /* <Description> */ - /* This type is equivalent to @CID_FaceDictRec. It is deprecated but */ - /* kept to maintain source compatibility between various versions of */ - /* FreeType. */ - /* */ + /************************************************************************** + * + * @Struct: + * CID_FontDict + * + * @Description: + * This type is equivalent to @CID_FaceDictRec. It is deprecated but + * kept to maintain source compatibility between various versions of + * FreeType. + */ typedef CID_FaceDictRec CID_FontDict; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* CID_FaceInfoRec */ - /* */ - /* <Description> */ - /* A structure used to represent CID Face information. */ - /* */ + /************************************************************************** + * + * @Struct: + * CID_FaceInfoRec + * + * @Description: + * A structure used to represent CID Face information. + */ typedef struct CID_FaceInfoRec_ { FT_String* cid_font_name; @@ -421,27 +421,27 @@ FT_BEGIN_HEADER } CID_FaceInfoRec; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* CID_FaceInfo */ - /* */ - /* <Description> */ - /* A handle to a @CID_FaceInfoRec structure. */ - /* */ + /************************************************************************** + * + * @Struct: + * CID_FaceInfo + * + * @Description: + * A handle to a @CID_FaceInfoRec structure. + */ typedef struct CID_FaceInfoRec_* CID_FaceInfo; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* CID_Info */ - /* */ - /* <Description> */ - /* This type is equivalent to @CID_FaceInfoRec. It is deprecated but */ - /* kept to maintain source compatibility between various versions of */ - /* FreeType. */ - /* */ + /************************************************************************** + * + * @Struct: + * CID_Info + * + * @Description: + * 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; @@ -461,7 +461,7 @@ FT_BEGIN_HEADER * * @input: * face :: - * face handle + * face handle * * @return: * Boolean. True if glyph names are reliable. @@ -482,11 +482,11 @@ FT_BEGIN_HEADER * * @input: * face :: - * PostScript face handle. + * PostScript face handle. * * @output: * afont_info :: - * Output font info structure pointer. + * Output font info structure pointer. * * @return: * FreeType error code. 0~means success. @@ -516,11 +516,11 @@ FT_BEGIN_HEADER * * @input: * face :: - * PostScript face handle. + * PostScript face handle. * * @output: * afont_private :: - * Output private dictionary structure pointer. + * Output private dictionary structure pointer. * * @return: * FreeType error code. 0~means success. @@ -538,25 +538,25 @@ FT_BEGIN_HEADER PS_Private afont_private ); - /*************************************************************************/ - /* */ - /* <Enum> */ - /* T1_EncodingType */ - /* */ - /* <Description> */ - /* An enumeration describing the `Encoding' entry in a Type 1 */ - /* dictionary. */ - /* */ - /* <Values> */ - /* T1_ENCODING_TYPE_NONE :: */ - /* T1_ENCODING_TYPE_ARRAY :: */ - /* T1_ENCODING_TYPE_STANDARD :: */ - /* T1_ENCODING_TYPE_ISOLATIN1 :: */ - /* T1_ENCODING_TYPE_EXPERT :: */ - /* */ - /* <Since> */ - /* 2.4.8 */ - /* */ + /************************************************************************** + * + * @Enum: + * T1_EncodingType + * + * @Description: + * An enumeration describing the `Encoding' entry in a Type 1 + * dictionary. + * + * @Values: + * T1_ENCODING_TYPE_NONE :: + * T1_ENCODING_TYPE_ARRAY :: + * T1_ENCODING_TYPE_STANDARD :: + * T1_ENCODING_TYPE_ISOLATIN1 :: + * T1_ENCODING_TYPE_EXPERT :: + * + * @Since: + * 2.4.8 + */ typedef enum T1_EncodingType_ { T1_ENCODING_TYPE_NONE = 0, @@ -568,66 +568,66 @@ FT_BEGIN_HEADER } T1_EncodingType; - /*************************************************************************/ - /* */ - /* <Enum> */ - /* PS_Dict_Keys */ - /* */ - /* <Description> */ - /* 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 :: */ - /* PS_DICT_FONT_MATRIX :: */ - /* PS_DICT_FONT_BBOX :: */ - /* PS_DICT_PAINT_TYPE :: */ - /* PS_DICT_FONT_NAME :: */ - /* PS_DICT_UNIQUE_ID :: */ - /* PS_DICT_NUM_CHAR_STRINGS :: */ - /* PS_DICT_CHAR_STRING_KEY :: */ - /* PS_DICT_CHAR_STRING :: */ - /* PS_DICT_ENCODING_TYPE :: */ - /* PS_DICT_ENCODING_ENTRY :: */ - /* PS_DICT_NUM_SUBRS :: */ - /* PS_DICT_SUBR :: */ - /* PS_DICT_STD_HW :: */ - /* PS_DICT_STD_VW :: */ - /* PS_DICT_NUM_BLUE_VALUES :: */ - /* PS_DICT_BLUE_VALUE :: */ - /* PS_DICT_BLUE_FUZZ :: */ - /* PS_DICT_NUM_OTHER_BLUES :: */ - /* PS_DICT_OTHER_BLUE :: */ - /* PS_DICT_NUM_FAMILY_BLUES :: */ - /* PS_DICT_FAMILY_BLUE :: */ - /* PS_DICT_NUM_FAMILY_OTHER_BLUES :: */ - /* PS_DICT_FAMILY_OTHER_BLUE :: */ - /* PS_DICT_BLUE_SCALE :: */ - /* PS_DICT_BLUE_SHIFT :: */ - /* PS_DICT_NUM_STEM_SNAP_H :: */ - /* PS_DICT_STEM_SNAP_H :: */ - /* PS_DICT_NUM_STEM_SNAP_V :: */ - /* PS_DICT_STEM_SNAP_V :: */ - /* PS_DICT_FORCE_BOLD :: */ - /* PS_DICT_RND_STEM_UP :: */ - /* PS_DICT_MIN_FEATURE :: */ - /* PS_DICT_LEN_IV :: */ - /* PS_DICT_PASSWORD :: */ - /* PS_DICT_LANGUAGE_GROUP :: */ - /* PS_DICT_VERSION :: */ - /* PS_DICT_NOTICE :: */ - /* PS_DICT_FULL_NAME :: */ - /* PS_DICT_FAMILY_NAME :: */ - /* PS_DICT_WEIGHT :: */ - /* PS_DICT_IS_FIXED_PITCH :: */ - /* PS_DICT_UNDERLINE_POSITION :: */ - /* PS_DICT_UNDERLINE_THICKNESS :: */ - /* PS_DICT_FS_TYPE :: */ - /* PS_DICT_ITALIC_ANGLE :: */ - /* */ - /* <Since> */ - /* 2.4.8 */ - /* */ + /************************************************************************** + * + * @Enum: + * PS_Dict_Keys + * + * @Description: + * 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 :: + * PS_DICT_FONT_MATRIX :: + * PS_DICT_FONT_BBOX :: + * PS_DICT_PAINT_TYPE :: + * PS_DICT_FONT_NAME :: + * PS_DICT_UNIQUE_ID :: + * PS_DICT_NUM_CHAR_STRINGS :: + * PS_DICT_CHAR_STRING_KEY :: + * PS_DICT_CHAR_STRING :: + * PS_DICT_ENCODING_TYPE :: + * PS_DICT_ENCODING_ENTRY :: + * PS_DICT_NUM_SUBRS :: + * PS_DICT_SUBR :: + * PS_DICT_STD_HW :: + * PS_DICT_STD_VW :: + * PS_DICT_NUM_BLUE_VALUES :: + * PS_DICT_BLUE_VALUE :: + * PS_DICT_BLUE_FUZZ :: + * PS_DICT_NUM_OTHER_BLUES :: + * PS_DICT_OTHER_BLUE :: + * PS_DICT_NUM_FAMILY_BLUES :: + * PS_DICT_FAMILY_BLUE :: + * PS_DICT_NUM_FAMILY_OTHER_BLUES :: + * PS_DICT_FAMILY_OTHER_BLUE :: + * PS_DICT_BLUE_SCALE :: + * PS_DICT_BLUE_SHIFT :: + * PS_DICT_NUM_STEM_SNAP_H :: + * PS_DICT_STEM_SNAP_H :: + * PS_DICT_NUM_STEM_SNAP_V :: + * PS_DICT_STEM_SNAP_V :: + * PS_DICT_FORCE_BOLD :: + * PS_DICT_RND_STEM_UP :: + * PS_DICT_MIN_FEATURE :: + * PS_DICT_LEN_IV :: + * PS_DICT_PASSWORD :: + * PS_DICT_LANGUAGE_GROUP :: + * PS_DICT_VERSION :: + * PS_DICT_NOTICE :: + * PS_DICT_FULL_NAME :: + * PS_DICT_FAMILY_NAME :: + * PS_DICT_WEIGHT :: + * PS_DICT_IS_FIXED_PITCH :: + * PS_DICT_UNDERLINE_POSITION :: + * PS_DICT_UNDERLINE_THICKNESS :: + * PS_DICT_FS_TYPE :: + * PS_DICT_ITALIC_ANGLE :: + * + * @Since: + * 2.4.8 + */ typedef enum PS_Dict_Keys_ { /* conventionally in the font dictionary */ @@ -697,23 +697,23 @@ FT_BEGIN_HEADER * * @input: * face :: - * PostScript face handle. + * PostScript face handle. * * key :: - * An enumeration value representing the dictionary key to retrieve. + * An enumeration value representing the dictionary key to retrieve. * * idx :: - * For array values, this specifies the index to be returned. + * For array values, this specifies the index to be returned. * * value :: - * A pointer to memory into which to write the value. + * A pointer to memory into which to write the value. * * valen_len :: - * The size, in bytes, of the memory supplied for the value. + * The size, in bytes, of the memory supplied for the value. * * @output: * value :: - * The value matching the above key, if it exists. + * The value matching the above key, if it exists. * * @return: * The amount of memory (in bytes) required to hold the requested diff --git a/include/freetype/ttnameid.h b/include/freetype/ttnameid.h index 8605183dc..5e3e319c2 100644 --- a/include/freetype/ttnameid.h +++ b/include/freetype/ttnameid.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ttnameid.h */ -/* */ -/* TrueType name ID definitions (specification only). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ttnameid.h + * + * TrueType name ID definitions (specification only). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef TTNAMEID_H_ @@ -26,19 +26,19 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* truetype_tables */ - /* */ + /************************************************************************** + * + * @Section: + * truetype_tables + */ - /*************************************************************************/ - /* */ - /* 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. + * + */ /*********************************************************************** diff --git a/include/freetype/tttables.h b/include/freetype/tttables.h index ce6a61779..eac472d83 100644 --- a/include/freetype/tttables.h +++ b/include/freetype/tttables.h @@ -1,20 +1,20 @@ -/***************************************************************************/ -/* */ -/* tttables.h */ -/* */ -/* Basic SFNT/TrueType tables definitions and interface */ -/* (specification only). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * tttables.h + * + * Basic SFNT/TrueType tables definitions and interface + * (specification only). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef TTTABLES_H_ @@ -33,53 +33,53 @@ FT_BEGIN_HEADER - /*************************************************************************/ - /* */ - /* <Section> */ - /* truetype_tables */ - /* */ - /* <Title> */ - /* TrueType Tables */ - /* */ - /* <Abstract> */ - /* TrueType specific table types and functions. */ - /* */ - /* <Description> */ - /* This section contains definitions of some basic tables specific to */ - /* TrueType and OpenType as well as some routines used to access and */ - /* process them. */ - /* */ - /* <Order> */ - /* TT_Header */ - /* TT_HoriHeader */ - /* TT_VertHeader */ - /* TT_OS2 */ - /* TT_Postscript */ - /* TT_PCLT */ - /* TT_MaxProfile */ - /* */ - /* FT_Sfnt_Tag */ - /* FT_Get_Sfnt_Table */ - /* FT_Load_Sfnt_Table */ - /* FT_Sfnt_Table_Info */ - /* */ - /* FT_Get_CMap_Language_ID */ - /* FT_Get_CMap_Format */ - /* */ - /* FT_PARAM_TAG_UNPATENTED_HINTING */ - /* */ - /*************************************************************************/ - - - /*************************************************************************/ - /* */ - /* <Struct> */ - /* TT_Header */ - /* */ - /* <Description> */ - /* A structure to model a TrueType font header table. All fields */ - /* follow the OpenType specification. */ - /* */ + /************************************************************************** + * + * @Section: + * truetype_tables + * + * @Title: + * TrueType Tables + * + * @Abstract: + * TrueType specific table types and functions. + * + * @Description: + * This section contains definitions of some basic tables specific to + * TrueType and OpenType as well as some routines used to access and + * process them. + * + * @Order: + * TT_Header + * TT_HoriHeader + * TT_VertHeader + * TT_OS2 + * TT_Postscript + * TT_PCLT + * TT_MaxProfile + * + * FT_Sfnt_Tag + * FT_Get_Sfnt_Table + * FT_Load_Sfnt_Table + * FT_Sfnt_Table_Info + * + * FT_Get_CMap_Language_ID + * FT_Get_CMap_Format + * + * FT_PARAM_TAG_UNPATENTED_HINTING + * + */ + + + /************************************************************************** + * + * @Struct: + * TT_Header + * + * @Description: + * A structure to model a TrueType font header table. All fields + * follow the OpenType specification. + */ typedef struct TT_Header_ { FT_Fixed Table_Version; @@ -109,93 +109,109 @@ FT_BEGIN_HEADER } TT_Header; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* TT_HoriHeader */ - /* */ - /* <Description> */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* min_Left_Side_Bearing :: 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. */ - /* */ - /* xMax_Extent :: 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). */ - /* */ - /* caret_Slope_Run :: The run coefficient of the cursor's */ - /* slope. */ - /* */ - /* caret_Offset :: The cursor's offset for slanted fonts. */ - /* */ - /* Reserved :: 8~reserved bytes. */ - /* */ - /* metric_Data_Format :: 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. */ - /* */ - /* long_metrics :: A pointer into the `hmtx' table. */ - /* */ - /* short_metrics :: 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'. */ - /* */ + /************************************************************************** + * + * @Struct: + * TT_HoriHeader + * + * @Description: + * 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. + * + * 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. + * + * 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. + * + * 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. + * + * 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. + * + * 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. + * + * min_Left_Side_Bearing :: + * 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. + * + * xMax_Extent :: + * 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). + * + * caret_Slope_Run :: + * The run coefficient of the cursor's + * slope. + * + * caret_Offset :: + * The cursor's offset for slanted fonts. + * + * Reserved :: + * 8~reserved bytes. + * + * metric_Data_Format :: + * 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. + * + * long_metrics :: + * A pointer into the `hmtx' table. + * + * short_metrics :: + * 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'. + */ typedef struct TT_HoriHeader_ { FT_Fixed Version; @@ -227,97 +243,113 @@ FT_BEGIN_HEADER } TT_HoriHeader; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* TT_VertHeader */ - /* */ - /* <Description> */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* 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. */ - /* */ - /* min_Top_Side_Bearing :: 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. */ - /* */ - /* yMax_Extent :: 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). */ - /* */ - /* caret_Slope_Run :: The run coefficient of the cursor's */ - /* slope. */ - /* */ - /* caret_Offset :: The cursor's offset for slanted fonts. */ - /* */ - /* Reserved :: 8~reserved bytes. */ - /* */ - /* metric_Data_Format :: 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. */ - /* */ - /* long_metrics :: A pointer into the `vmtx' table. */ - /* */ - /* short_metrics :: 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'. */ - /* */ + /************************************************************************** + * + * @Struct: + * TT_VertHeader + * + * @Description: + * 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. + * + * 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. + * + * 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. + * + * 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. + * + * 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. + * + * 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. + * + * min_Top_Side_Bearing :: + * 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. + * + * yMax_Extent :: + * 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). + * + * caret_Slope_Run :: + * The run coefficient of the cursor's + * slope. + * + * caret_Offset :: + * The cursor's offset for slanted fonts. + * + * Reserved :: + * 8~reserved bytes. + * + * metric_Data_Format :: + * 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. + * + * long_metrics :: + * A pointer into the `vmtx' table. + * + * short_metrics :: + * 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'. + */ typedef struct TT_VertHeader_ { FT_Fixed Version; @@ -349,33 +381,33 @@ FT_BEGIN_HEADER } TT_VertHeader; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* TT_OS2 */ - /* */ - /* <Description> */ - /* 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> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Struct: + * TT_OS2 + * + * @Description: + * 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: + * 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_ { @@ -435,23 +467,23 @@ FT_BEGIN_HEADER } TT_OS2; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* 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. */ - /* */ - /* <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'. */ - /* */ + /************************************************************************** + * + * @Struct: + * 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. + * + * @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'. + */ typedef struct TT_Postscript_ { FT_Fixed FormatType; @@ -470,15 +502,15 @@ FT_BEGIN_HEADER } TT_Postscript; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* TT_PCLT */ - /* */ - /* <Description> */ - /* A structure to model a TrueType `PCLT' table. All fields comply */ - /* to the OpenType specification. */ - /* */ + /************************************************************************** + * + * @Struct: + * TT_PCLT + * + * @Description: + * A structure to model a TrueType `PCLT' table. All fields comply + * to the OpenType specification. + */ typedef struct TT_PCLT_ { FT_Fixed Version; @@ -500,70 +532,85 @@ FT_BEGIN_HEADER } TT_PCLT; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* 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. */ - /* */ - /* <Fields> */ - /* version :: The version number. */ - /* */ - /* numGlyphs :: The number of glyphs in this TrueType */ - /* font. */ - /* */ - /* maxPoints :: 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'. */ - /* */ - /* maxCompositePoints :: 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'. */ - /* */ - /* maxZones :: The maximum number of zones used for */ - /* glyph hinting. */ - /* */ - /* maxTwilightPoints :: 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. */ - /* */ - /* maxFunctionDefs :: 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. */ - /* */ - /* maxStackElements :: The maximum number of stack elements used */ - /* during bytecode interpretation. */ - /* */ - /* maxSizeOfInstructions :: 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. */ - /* */ - /* maxComponentDepth :: The maximum nesting depth of composite */ - /* glyphs. */ - /* */ - /* <Note> */ - /* This structure is only used during font loading. */ - /* */ + /************************************************************************** + * + * @Struct: + * 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. + * + * @Fields: + * version :: + * The version number. + * + * numGlyphs :: + * The number of glyphs in this TrueType + * font. + * + * maxPoints :: + * 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'. + * + * maxCompositePoints :: + * 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'. + * + * maxZones :: + * The maximum number of zones used for + * glyph hinting. + * + * maxTwilightPoints :: + * 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. + * + * maxFunctionDefs :: + * 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. + * + * maxStackElements :: + * The maximum number of stack elements used + * during bytecode interpretation. + * + * maxSizeOfInstructions :: + * 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. + * + * maxComponentDepth :: + * The maximum nesting depth of composite + * glyphs. + * + * @Note: + * This structure is only used during font loading. + */ typedef struct TT_MaxProfile_ { FT_Fixed version; @@ -585,31 +632,38 @@ FT_BEGIN_HEADER } TT_MaxProfile; - /*************************************************************************/ - /* */ - /* <Enum> */ - /* 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 */ - /* @FT_Get_Sfnt_Table API function. */ - /* */ - /* <Values> */ - /* FT_SFNT_HEAD :: To access the font's @TT_Header structure. */ - /* */ - /* FT_SFNT_MAXP :: To access the font's @TT_MaxProfile structure. */ - /* */ - /* FT_SFNT_OS2 :: To access the font's @TT_OS2 structure. */ - /* */ - /* FT_SFNT_HHEA :: To access the font's @TT_HoriHeader structure. */ - /* */ - /* FT_SFNT_VHEA :: To access the font's @TT_VertHeader structure. */ - /* */ - /* FT_SFNT_POST :: To access the font's @TT_Postscript structure. */ - /* */ - /* FT_SFNT_PCLT :: To access the font's @TT_PCLT structure. */ - /* */ + /************************************************************************** + * + * @Enum: + * 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 + * @FT_Get_Sfnt_Table API function. + * + * @Values: + * FT_SFNT_HEAD :: + * To access the font's @TT_Header structure. + * + * FT_SFNT_MAXP :: + * To access the font's @TT_MaxProfile structure. + * + * FT_SFNT_OS2 :: + * To access the font's @TT_OS2 structure. + * + * FT_SFNT_HHEA :: + * To access the font's @TT_HoriHeader structure. + * + * FT_SFNT_VHEA :: + * To access the font's @TT_VertHeader structure. + * + * FT_SFNT_POST :: + * To access the font's @TT_Postscript structure. + * + * FT_SFNT_PCLT :: + * To access the font's @TT_PCLT structure. + */ typedef enum FT_Sfnt_Tag_ { FT_SFNT_HEAD, @@ -635,44 +689,46 @@ FT_BEGIN_HEADER #define ft_sfnt_pclt FT_SFNT_PCLT - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Get_Sfnt_Table */ - /* */ - /* <Description> */ - /* Return a pointer to a given SFNT table stored within a face. */ - /* */ - /* <Input> */ - /* face :: A handle to the source. */ - /* */ - /* tag :: 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. */ - /* */ - /* 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. */ - /* */ - /* 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 ); */ - /* } */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Get_Sfnt_Table + * + * @Description: + * Return a pointer to a given SFNT table stored within a face. + * + * @Input: + * face :: + * A handle to the source. + * + * tag :: + * 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. + * + * 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. + * + * 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, FT_Sfnt_Tag tag ); @@ -792,46 +848,46 @@ FT_BEGIN_HEADER FT_ULong *length ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Get_CMap_Language_ID */ - /* */ - /* <Description> */ - /* Return cmap language ID as specified in the OpenType standard. */ - /* Definitions of language ID values are in file @FT_TRUETYPE_IDS_H. */ - /* */ - /* <Input> */ - /* charmap :: */ - /* 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. */ - /* */ - /* For a format~14 cmap (to access Unicode IVS), the return value is */ - /* 0xFFFFFFFF. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Get_CMap_Language_ID + * + * @Description: + * Return cmap language ID as specified in the OpenType standard. + * Definitions of language ID values are in file @FT_TRUETYPE_IDS_H. + * + * @Input: + * charmap :: + * 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. + * + * For a format~14 cmap (to access Unicode IVS), the return value is + * 0xFFFFFFFF. + */ FT_EXPORT( FT_ULong ) FT_Get_CMap_Language_ID( FT_CharMap charmap ); - /*************************************************************************/ - /* */ - /* <Function> */ - /* FT_Get_CMap_Format */ - /* */ - /* <Description> */ - /* 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. */ - /* */ + /************************************************************************** + * + * @Function: + * FT_Get_CMap_Format + * + * @Description: + * 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. + */ FT_EXPORT( FT_Long ) FT_Get_CMap_Format( FT_CharMap charmap ); diff --git a/include/freetype/tttags.h b/include/freetype/tttags.h index 36b02057a..5e5d78356 100644 --- a/include/freetype/tttags.h +++ b/include/freetype/tttags.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* tttags.h */ -/* */ -/* Tags for TrueType and OpenType tables (specification only). */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * tttags.h + * + * Tags for TrueType and OpenType tables (specification only). + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ #ifndef TTAGS_H_ diff --git a/include/ft2build.h b/include/ft2build.h index e7ce99bc9..4c770b2ab 100644 --- a/include/ft2build.h +++ b/include/ft2build.h @@ -1,34 +1,34 @@ -/***************************************************************************/ -/* */ -/* ft2build.h */ -/* */ -/* FreeType 2 build and setup macros. */ -/* */ -/* Copyright 1996-2018 by */ -/* David Turner, Robert Wilhelm, and Werner Lemberg. */ -/* */ -/* This file is part of the FreeType project, and may only be used, */ -/* modified, and distributed under the terms of the FreeType project */ -/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ -/* this file you indicate that you have read the license and */ -/* understand and accept it fully. */ -/* */ -/***************************************************************************/ - - - /*************************************************************************/ - /* */ - /* 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'). */ - /* */ - /* A typical example is */ - /* */ - /* #include <ft2build.h> */ - /* #include FT_FREETYPE_H */ - /* */ - /*************************************************************************/ +/**************************************************************************** + * + * ft2build.h + * + * FreeType 2 build and setup macros. + * + * Copyright 1996-2018 by + * David Turner, Robert Wilhelm, and Werner Lemberg. + * + * This file is part of the FreeType project, and may only be used, + * modified, and distributed under the terms of the FreeType project + * license, LICENSE.TXT. By continuing to use, modify, or distribute + * this file you indicate that you have read the license and + * understand and accept it fully. + * + */ + + + /************************************************************************** + * + * 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'). + * + * A typical example is + * + * #include <ft2build.h> + * #include FT_FREETYPE_H + * + */ #ifndef FT2BUILD_H_ |