[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[freetype2] master f999375: [GSoC] include/*.*, devel/*.*: Convert block
|
From: |
Werner LEMBERG |
|
Subject: |
[freetype2] master f999375: [GSoC] include/*.*, devel/*.*: Convert block comments to `light' style. |
|
Date: |
Sun, 3 Jun 2018 16:03:06 -0400 (EDT) |
branch: master
commit f999375a9a834666f82928f9ad6293d9b25213a5
Author: Werner Lemberg <address@hidden>
Commit: Werner Lemberg <address@hidden>
[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.
---
devel/ft2build.h | 44 +-
devel/ftoption.h | 1228 ++---
include/freetype/config/ftconfig.h | 266 +-
include/freetype/config/ftheader.h | 104 +-
include/freetype/config/ftmodule.h | 12 +-
include/freetype/config/ftoption.h | 1284 ++---
include/freetype/config/ftstdlib.h | 150 +-
include/freetype/freetype.h | 6613 +++++++++++++------------
include/freetype/ftadvanc.h | 247 +-
include/freetype/ftbbox.h | 130 +-
include/freetype/ftbdf.h | 79 +-
include/freetype/ftbitmap.h | 363 +-
include/freetype/ftbzip2.h | 62 +-
include/freetype/ftcache.h | 1123 +++--
include/freetype/ftchapters.h | 252 +-
include/freetype/ftcid.h | 82 +-
include/freetype/ftcolor.h | 32 +-
include/freetype/ftdriver.h | 34 +-
include/freetype/fterrdef.h | 102 +-
include/freetype/fterrors.h | 196 +-
include/freetype/ftfntfmt.h | 118 +-
include/freetype/ftgasp.h | 38 +-
include/freetype/ftglyph.h | 974 ++--
include/freetype/ftgxval.h | 158 +-
include/freetype/ftgzip.h | 64 +-
include/freetype/ftimage.h | 1789 +++----
include/freetype/ftincrem.h | 32 +-
include/freetype/ftlcdfil.h | 37 +-
include/freetype/ftlist.h | 422 +-
include/freetype/ftlzw.h | 68 +-
include/freetype/ftmac.h | 406 +-
include/freetype/ftmm.h | 1033 ++--
include/freetype/ftmodapi.h | 791 +--
include/freetype/ftmoderr.h | 182 +-
include/freetype/ftotval.h | 120 +-
include/freetype/ftoutln.h | 816 +--
include/freetype/ftparams.h | 32 +-
include/freetype/ftpfr.h | 86 +-
include/freetype/ftrender.h | 215 +-
include/freetype/ftsizes.h | 242 +-
include/freetype/ftsnames.h | 405 +-
include/freetype/ftstroke.h | 32 +-
include/freetype/ftsynth.h | 34 +-
include/freetype/ftsystem.h | 94 +-
include/freetype/fttrigon.h | 44 +-
include/freetype/fttypes.h | 849 ++--
include/freetype/ftwinfnt.h | 132 +-
include/freetype/internal/autohint.h | 303 +-
include/freetype/internal/cffotypes.h | 88 +-
include/freetype/internal/cfftypes.h | 98 +-
include/freetype/internal/ftcalc.h | 182 +-
include/freetype/internal/ftdebug.h | 206 +-
include/freetype/internal/ftdrv.h | 226 +-
include/freetype/internal/ftgloadr.h | 50 +-
include/freetype/internal/fthash.h | 28 +-
include/freetype/internal/ftmemory.h | 78 +-
include/freetype/internal/ftobjs.h | 856 ++--
include/freetype/internal/ftpsprop.h | 32 +-
include/freetype/internal/ftrfork.h | 280 +-
include/freetype/internal/ftserv.h | 143 +-
include/freetype/internal/ftstream.h | 50 +-
include/freetype/internal/fttrace.h | 32 +-
include/freetype/internal/ftvalid.h | 82 +-
include/freetype/internal/internal.h | 44 +-
include/freetype/internal/psaux.h | 603 ++-
include/freetype/internal/pshints.h | 36 +-
include/freetype/internal/services/svbdf.h | 32 +-
include/freetype/internal/services/svcfftl.h | 32 +-
include/freetype/internal/services/svcid.h | 32 +-
include/freetype/internal/services/svfntfmt.h | 38 +-
include/freetype/internal/services/svgldict.h | 36 +-
include/freetype/internal/services/svgxval.h | 50 +-
include/freetype/internal/services/svkern.h | 32 +-
include/freetype/internal/services/svmetric.h | 34 +-
include/freetype/internal/services/svmm.h | 36 +-
include/freetype/internal/services/svotval.h | 32 +-
include/freetype/internal/services/svpfr.h | 32 +-
include/freetype/internal/services/svpostnm.h | 42 +-
include/freetype/internal/services/svprop.h | 32 +-
include/freetype/internal/services/svpscmap.h | 50 +-
include/freetype/internal/services/svpsinfo.h | 32 +-
include/freetype/internal/services/svsfnt.h | 34 +-
include/freetype/internal/services/svttcmap.h | 80 +-
include/freetype/internal/services/svtteng.h | 34 +-
include/freetype/internal/services/svttglyf.h | 32 +-
include/freetype/internal/services/svwinfnt.h | 32 +-
include/freetype/internal/sfnt.h | 993 ++--
include/freetype/internal/t1types.h | 83 +-
include/freetype/internal/tttypes.h | 2041 ++++----
include/freetype/t1tables.h | 554 +--
include/freetype/ttnameid.h | 54 +-
include/freetype/tttables.h | 972 ++--
include/freetype/tttags.h | 32 +-
include/ft2build.h | 62 +-
94 files changed, 15815 insertions(+), 14763 deletions(-)
diff --git a/devel/ft2build.h b/devel/ft2build.h
index 1d17141..bd4dddb 100644
--- a/devel/ft2build.h
+++ b/devel/ft2build.h
@@ -1,29 +1,29 @@
-/***************************************************************************/
-/* */
-/* ft2build.h */
-/* */
-/* FreeType 2 build and setup macros (development version). */
-/* */
-/* 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. */
-/* */
-/***************************************************************************/
+/****************************************************************************
+ *
+ * ft2build.h
+ *
+ * FreeType 2 build and setup macros (development version).
+ *
+ * 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 a development version of <ft2build.h> to build the library in
- * debug mode. Its only difference to the default version is that it
- * includes a local `ftoption.h' header file with different settings for
- * many configuration macros.
+ * This is a development version of <ft2build.h> to build the library in
+ * debug mode. Its only difference to the default version is that it
+ * includes a local `ftoption.h' header file with different settings for
+ * many configuration macros.
*
- * To use it, simply ensure that the directory containing this file is
- * scanned by the compiler before the default FreeType header directory.
+ * To use it, simply ensure that the directory containing this file is
+ * scanned by the compiler before the default FreeType header directory.
*
*/
diff --git a/devel/ftoption.h b/devel/ftoption.h
index 2bc2a76..db87238 100644
--- a/devel/ftoption.h
+++ b/devel/ftoption.h
@@ -1,19 +1,19 @@
-/***************************************************************************/
-/* */
-/* ftoption.h (for development) */
-/* */
-/* 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 (for development)
+ *
+ * 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.
+ *
+ */
/*************************************************************************/
@@ -75,395 +75,395 @@ FT_BEGIN_HEADER
/*************************************************************************/
- /*************************************************************************/
- /* */
- /* If you enable this configuration option, FreeType recognizes an */
- /* environment variable called `FREETYPE_PROPERTIES', which can be used */
- /* to control the various font drivers and modules. The controllable */
- /* properties are listed in the section `Controlling FreeType Modules' */
- /* in the reference's table of contents; currently there are properties */
- /* for the auto-hinter (file `ftautoh.h'), CFF (file `ftcffdrv.h'), */
- /* TrueType (file `ftttdrv.h'), and PCF (file `ftpcfdrv.h'). */
- /* */
- /* `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 */
- /* */
+ /**************************************************************************
+ *
+ * If you enable this configuration option, FreeType recognizes an
+ * environment variable called `FREETYPE_PROPERTIES', which can be used
+ * to control the various font drivers and modules. The controllable
+ * properties are listed in the section `Controlling FreeType Modules'
+ * in the reference's table of contents; currently there are properties
+ * for the auto-hinter (file `ftautoh.h'), CFF (file `ftcffdrv.h'),
+ * TrueType (file `ftttdrv.h'), and PCF (file `ftpcfdrv.h').
+ *
+ * `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
+ */
#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. */
- /* */
-/* #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.
+ *
+ */
- /*************************************************************************/
- /* */
- /* 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'. */
- /* */
+ /**************************************************************************
+ *
+ * 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'.
+ */
#define FT_CONFIG_OPTION_USE_BZIP2
- /*************************************************************************/
- /* */
- /* 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'. */
- /* */
+ /**************************************************************************
+ *
+ * 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'.
+ */
#define FT_CONFIG_OPTION_USE_PNG
- /*************************************************************************/
- /* */
- /* 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'. */
- /* */
+ /**************************************************************************
+ *
+ * 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'.
+ */
#define FT_CONFIG_OPTION_USE_HARFBUZZ
- /*************************************************************************/
- /* */
- /* 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. */
- /* */
+ /**************************************************************************
+ *
+ * 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
- /*************************************************************************/
- /* */
- /* 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. */
- /* */
+ /**************************************************************************
+ *
+ * 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
- /*************************************************************************/
- /* */
- /* 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. */
- /* */
+ /**************************************************************************
+ *
+ * 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
- /*************************************************************************/
- /* */
- /* 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
@@ -476,59 +476,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
@@ -548,122 +548,122 @@ 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 options. */
- /* */
- /* 1. This option 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. */
- /* */
- /* 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. */
- /* */
- /* 3. Compile both. */
- /* */
- /* 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. */
- /* */
- /* 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 2 */
+ /**************************************************************************
+ *
+ * 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 options.
+ *
+ * 1. This option 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.
+ *
+ * 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.
+ *
+ * 3. Compile both.
+ *
+ * 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.
+ *
+ * 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 ( 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
@@ -678,59 +678,59 @@ 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. */
- /* */
+ /**************************************************************************
+ *
+ * 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
@@ -743,17 +743,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 of the cff driver module (file */
- /* `ftcffdrv.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 of the cff driver module (file
+ * `ftcffdrv.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
@@ -767,13 +767,13 @@ 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. */
- /* */
+ /**************************************************************************
+ *
+ * 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
@@ -786,21 +786,21 @@ 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. */
- /* */
+ /**************************************************************************
+ *
+ * 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
@@ -813,32 +813,32 @@ 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 Indic script support. */
- /* */
+ /**************************************************************************
+ *
+ * Compile autofit module with Indic script support.
+ */
#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 `ftautoh.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 `ftautoh.h' for more
+ * information; by default it is switched off).
+ */
#define AF_CONFIG_OPTION_USE_WARPER
/* */
diff --git a/include/freetype/config/ftconfig.h
b/include/freetype/config/ftconfig.h
index 52c5e33..c76816e 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 13e5de7..6a73685 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 76d271a..820c11c 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 3b6603b..c030a88 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 <address@hidden> */
- /* */
- /* [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 <address@hidden>
+ *
+ * [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 42f9a06..a744d0d 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 a6f0d80..736c251 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,229 +394,229 @@ 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. */
- /* */
-
-#ifndef FT_ENC_TAG
-#define FT_ENC_TAG( value, a, b, c, d ) \
- value = ( ( (FT_UInt32)(a) << 24 ) | \
+ /**************************************************************************
+ *
+ * @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 ) \
+ value = ( ( (FT_UInt32)(a) << 24 ) | \
( (FT_UInt32)(b) << 16 ) | \
( (FT_UInt32)(c) << 8 ) | \
(FT_UInt32)(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 */
- /* */
- 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_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
+ */
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 f78e8b1..6198006 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 f9eb70b..08095ea 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 1b6dea6..f10b0c2 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 cbdccc2..809e3bd 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 6edfa03..7450f14 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 52d5f00..08d3316 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 51257bb..0bb8229 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 5e9100a..2095773 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 3065fde..4c326c3 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 e90475b..510f0c0 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 8ffd346..1179fa9 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 f6ee5c2..e9bcf4d 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 cc86efa..c073e37 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 fc1248f..4e512be 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 08cf585..626a0d5 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 8382d59..6cec81d 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 db033da..f0f6d87 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 79ede19..dad6ca9 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 44619f9..08bba73 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 a71113e..ce5ea35 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 117473b..d130989 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 1615912..d639eb1 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 c1e497c..56140b2 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 9948102..fdf2bed 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 a6eb876..1693411 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 e0fc131..1f71633 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 26731c2..526f1ac 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 89389a4..4720e8d 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 5a9006c..a81c353 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 a69cc48..54d0cc1 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 fa8ad22..fb0ee08 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 72cb08b..cf3b163 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 3aa0d08..d98ad2c 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 44b6fbe..177f8c9 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 ff9fb43..f2e7856 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 f6b1629..df67f04 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 2e3f3f1..d3b11db 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 f638c2e..e7ff17d 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 461c65b..6e0dc8a 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 <address@hidden>:
*
- * 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 4991e3b..2c51ae7 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 57e7591..a0fa857 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 7c07e1a..af2065c 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 8f3e850..3e2dc92 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 292a4ee..cd70529 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 77f4513..bc5b69c 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 a002fdb..c1b7b40 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 f22f9d5..2491880 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 054eaec..a17a709 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 b49c78d..18e01b8 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 abbb628..dd0588f 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 825be9c..5a41cbd 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 6ca6050..1be1d15 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 f90002f..c3ab755 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 8092e41..7cf4556 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 cad47a5..265d79b 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 53b5b17..8261043 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 f77380d..70661ea 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 249cf97..90a28ac 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 e2133d7..b29f537 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 55a3fa4..9e4486e 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 fb0c90b..9ef0a0c 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 3b732be..6182362 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 d401a43..0840b58 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 ed79ebe..7fa27ff 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 c7e8f6e..ef95b32 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 e5a1a0e..91de020 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 04a63c3..6aeaa45 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 3129429..9a3ff47 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 e65d57e..21deb31 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 24e0255..1e39dce 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 fb762cd..7e84cc8 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 9747737..136879d 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 589f573..214fd1e 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 670f5e6..035e119 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 c0032f3..4b00abb 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 92e3c54..2564a41 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 bacf832..38444e9 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 80d481c..3aaa8a8 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 dceb897..00b7ae5 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 2118e33..c78f7c5 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 072636e..c02d76d 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 3503c26..4e4b02d 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 8605183..5e3e319 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 ce6a617..eac472d 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 36b0205..5e5d783 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 e7ce99b..4c770b2 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_
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [freetype2] master f999375: [GSoC] include/*.*, devel/*.*: Convert block comments to `light' style.,
Werner LEMBERG <=