documentation updates for 2.1.2
diff --git a/include/freetype/cache/ftccmap.h b/include/freetype/cache/ftccmap.h
index 03f44bb..11f7b03 100644
--- a/include/freetype/cache/ftccmap.h
+++ b/include/freetype/cache/ftccmap.h
@@ -28,6 +28,13 @@
/*************************************************************************/
/* */
+ /* <Section> */
+ /* cache_subsystem */
+ /* */
+ /*************************************************************************/
+
+ /*************************************************************************/
+ /* */
/* @type: */
/* FTC_CmapCache */
/* */
diff --git a/include/freetype/config/ftheader.h b/include/freetype/config/ftheader.h
index 3e26c96..5c9d427 100644
--- a/include/freetype/config/ftheader.h
+++ b/include/freetype/config/ftheader.h
@@ -18,7 +18,7 @@
#ifndef __FT_HEADER_H__
#define __FT_HEADER_H__
- /*************************************************************************/
+ /*@***********************************************************************/
/* */
/* <Macro> */
/* FT_BEGIN_HEADER */
@@ -36,7 +36,7 @@
#endif
- /*************************************************************************/
+ /*@***********************************************************************/
/* */
/* <Macro> */
/* FT_END_HEADER */
diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h
index 2aafc3a..0102a37 100644
--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@@ -241,11 +241,12 @@
/* completely independent from the others; it is the `root' of a set */
/* of objects like fonts, faces, sizes, etc. */
/* */
- /* It also embeds a system object (see FT_System), as well as a */
- /* scan-line converter object (see FT_Raster). */
+ /* It also embeds a memory manager (see @FT_Memory), as well as a */
+ /* scan-line converter object (see @FT_Raster). */
/* */
/* <Note> */
- /* Library objects are created through FT_Init_FreeType(). */
+ /* Library objects are normally created by @FT_Init_FreeType, and */
+ /* destroyed with @FT_Done_FreeType */
/* */
typedef struct FT_LibraryRec_ *FT_Library;
@@ -270,11 +271,7 @@
/* */
/* <Description> */
/* A handle to a given FreeType font driver object. Each font driver */
- /* is able to create faces, sizes, glyph slots, and charmaps from the */
- /* resources whose format it supports. */
- /* */
- /* A driver can support either bitmap, graymap, or scalable font */
- /* formats. */
+ /* is a special module capable of creating faces from font files. */
/* */
typedef struct FT_DriverRec_* FT_Driver;
@@ -285,10 +282,10 @@
/* FT_Renderer */
/* */
/* <Description> */
- /* A handle to a given FreeType renderer. A renderer is in charge of */
- /* converting a glyph image to a bitmap, when necessary. Each */
- /* supports a given glyph image format, and one or more target */
- /* surface depths. */
+ /* A handle to a given FreeType renderer. A renderer is a special */
+ /* module in charge of converting a glyph image to a bitmap, when */
+ /* necessary. Each renderer supports a given glyph image format, and */
+ /* one or more target surface depths. */
/* */
typedef struct FT_RendererRec_* FT_Renderer;
@@ -299,12 +296,21 @@
/* FT_Face */
/* */
/* <Description> */
- /* A handle to a given driver face object. A face object contains */
- /* all the instance and glyph independent data of a font file */
- /* typeface. */
+ /* A handle to a given typographic face object. A face object models */
+ /* a given typeface, in a given style. */
/* */
- /* A face object is created from a resource object through the */
- /* new_face() method of a given driver. */
+ /* <Note> */
+ /* Each 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 filepathname or a custom input stream. */
+ /* */
+ /* use @FT_Done_Face to destroy it (along with its slot and sizes) */
+ /* */
+ /* <Also> */
+ /* the @FT_FaceRec details the publicly accessible fields of a given */
+ /* face object. */
/* */
typedef struct FT_FaceRec_* FT_Face;
@@ -315,12 +321,21 @@
/* FT_Size */
/* */
/* <Description> */
- /* A handle to a given driver size object. Such an object models the */
- /* _resolution_ AND _size_ dependent state of a given driver face */
- /* size. */
+ /* A handle to a given size object. Such an object models the */
+ /* data that depends on the current _resolution_ and _character_ */
+ /* _size_ in a given @FT_Face. */
/* */
- /* A size object is always created from a given face object. It is */
- /* discarded automatically by its parent face. */
+ /* <Note> */
+ /* Each face object owns one or more sizes. There is however a */
+ /* single _active_ size for the face at any time that will be */
+ /* used by functions like @FT_Load_Glyph, @FT_Get_Kerning, etc... */
+ /* */
+ /* you can use the @FT_Activate_Size API to change the current */
+ /* active size of any given face */
+ /* */
+ /* <Also> */
+ /* the @FT_SizeRec structure details the publicly accessible fields */
+ /* of a given face object. */
/* */
typedef struct FT_SizeRec_* FT_Size;
@@ -332,11 +347,16 @@
/* */
/* <Description> */
/* A handle to a given `glyph slot'. A slot is a container where it */
- /* is possible to load any of the glyphs contained within its parent */
+ /* is possible to load any one of the glyphs contained in its parent */
/* face. */
/* */
- /* A glyph slot is created from a given face object. It is discarded */
- /* automatically by 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> */
+ /* @FT_GlyphSlotRec details the publicly accessible glyph fields */
/* */
typedef struct FT_GlyphSlotRec_* FT_GlyphSlot;
@@ -352,8 +372,20 @@
/* parent's face. Some font formats may provide several charmaps per */
/* font. */
/* */
- /* A charmap is created from a given face object. It is discarded */
- /* automatically by its parent face. */
+ /* Each face object owns zero or more charmaps, but only one of */
+ /* them can be "active" and 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 */
/* */
typedef struct FT_CharMapRec_* FT_CharMap;
@@ -365,6 +397,8 @@
/* */
/* <Description> */
/* This macro converts four letter tags into an unsigned long. */
+ /* It is used to define "encoding" identifiers (see @FT_Encoding) */
+ /* */
/* */
#ifndef FT_ENC_TAG
#define FT_ENC_TAG( value, _x1, _x2, _x3, _x4 ) \
@@ -419,13 +453,13 @@
/* FT_CharMapRec */
/* */
/* <Description> */
- /* The base charmap class. */
+ /* The base charmap structure. */
/* */
/* <Fields> */
/* face :: A handle to the parent face object. */
/* */
- /* encoding :: A tag which identifies the charmap. Use this with */
- /* FT_Select_Charmap(). */
+ /* encoding :: A @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 */
@@ -436,10 +470,6 @@
/* comes from the TrueType specification and should be */
/* emulated similarly. */
/* */
- /* <Note> */
- /* We STRONGLY recommmend emulating a Unicode charmap for drivers */
- /* that do not support TrueType or OpenType. */
- /* */
typedef struct FT_CharMapRec_
{
FT_Face face;
@@ -466,9 +496,9 @@
/* */
/* <Description> */
/* An opaque handle to an FT_Face_InternalRec structure, used to */
- /* model private data of a given FT_Face object. */
+ /* model private data of a given @FT_Face object. */
/* */
- /* This field might change between releases of FreeType 2 and are */
+ /* This structure might change between releases of FreeType 2 and are */
/* not generally available to client applications. */
/* */
typedef struct FT_Face_InternalRec_* FT_Face_Internal;
@@ -476,7 +506,7 @@
/*************************************************************************/
/* */
- /* FreeType base face class */
+ /* FreeType base face object */
/* */
/* <Struct> */
/* FT_FaceRec */
@@ -487,11 +517,11 @@
/* */
/* <Fields> */
/* num_faces :: In the case where the face is located in a */
- /* collection (i.e., a resource which embeds */
+ /* collection (i.e., a file which embed */
/* several faces), this is the total number of */
/* faces found in the resource. 1 by default. */
/* */
- /* face_index :: The index of the face in its resource. */
+ /* face_index :: The index of the face in its font file. */
/* Usually, this is 0 for all normal font */
/* formats. It can be more in the case of */
/* collections (which embed several fonts in a */
@@ -499,7 +529,7 @@
/* */
/* face_flags :: A set of bit flags that give important */
/* information about the face; see the */
- /* FT_FACE_FLAG_XXX macros for details. */
+ /* FT_FACE_FLAG_XXX constants for details. */
/* */
/* style_flags :: A set of bit flags indicating the style of */
/* the face (i.e., italic, bold, underline, */
@@ -530,15 +560,14 @@
/* */
/* num_fixed_sizes :: The number of fixed sizes available in this */
/* face. This should be set to 0 for scalable */
- /* fonts, unless its resource includes a */
- /* complete set of glyphs (called a `strike') */
- /* for the specified size. */
+ /* fonts, unless its face includes a complete */
+ /* set of glyphs (called a `strike') for the */
+ /* specified sizes. */
/* */
/* available_sizes :: An array of sizes specifying the available */
/* bitmap/graymap sizes that are contained in */
- /* in the font resource. Should be set to */
- /* NULL if the field `num_fixed_sizes' is set */
- /* to 0. */
+ /* in the font face. Should be set to NULL if */
+ /* the field `num_fixed_sizes' is set to 0. */
/* */
/* num_charmaps :: The total number of character maps in the */
/* face. */
@@ -546,12 +575,12 @@
/* charmaps :: A table of pointers to the face's charmaps. */
/* Used to scan the list of available charmaps */
/* -- this table might change after a call to */
- /* FT_Attach_File/Stream (e.g. when used to */
- /* hook an additional encoding/CMap to the */
- /* face object). */
+ /* @FT_Attach_File or @FT_Attach_Stream (e.g. */
+ /* when used to hook an additional encoding or */
+ /* CMap to the face object). */
/* */
/* generic :: A field reserved for client uses. See the */
- /* FT_Generic type description. */
+ /* @FT_Generic type description. */
/* */
/* bbox :: The font bounding box. Coordinates are */
/* expressed in font units (see units_per_EM). */
@@ -619,15 +648,6 @@
/* underline for this face. Only relevant for */
/* scalable formats. */
/* */
- /* driver :: A handle to the face's parent driver */
- /* object. */
- /* */
- /* memory :: A handle to the face's parent memory */
- /* object. Used for the allocation of */
- /* subsequent objects. */
- /* */
- /* stream :: A handle to the face's stream. */
- /* */
/* glyph :: The face's associated glyph slot(s). This */
/* object is created automatically with a new */
/* face object. However, certain kinds of */
@@ -635,12 +655,9 @@
/* can need more than one slot to ease their */
/* task. */
/* */
- /* sizes_list :: The list of child sizes for this face. */
+ /* size :: the current active size for this face */
/* */
- /* internal :: A pointer to internal fields of the face */
- /* object. These fields can change freely */
- /* between releases of FreeType and are not */
- /* publicly available. */
+ /* charmap :: the current active charmap for this face */
/* */
typedef struct FT_FaceRec_
{
@@ -786,8 +803,8 @@
/* <Description> */
/* A bit-field constant, used to indicate that a given face contains */
/* kerning information. When set, this information can be retrieved */
- /* through the function FT_Get_Kerning(). Note that when unset, this */
- /* function will always return the kerning vector (0,0). */
+ /* through the function @FT_Get_Kerning(). Note that when unset, */
+ /* this function will always return the kerning vector (0,0). */
/* */
#define FT_FACE_FLAG_KERNING 0x40
@@ -806,6 +823,11 @@
/* where each glyph bitmap is available directly in binary form */
/* without any kind of compression. */
/* */
+ /* <Note> */
+ /* This bit flag is deprecated, because even if the bitmaps are */
+ /* available directly in the font file, the glyph sub-system is */
+ /* very likely to be faster anyway... */
+ /* */
#define FT_FACE_FLAG_FAST_GLYPHS 0x80
@@ -817,6 +839,7 @@
/* <Description> */
/* A bit-field constant, used to indicate that the font contains */
/* multiple masters and is capable of interpolating between them. */
+ /* See the multiple-masters specific API for more details */
/* */
#define FT_FACE_FLAG_MULTIPLE_MASTERS 0x100
@@ -828,7 +851,7 @@
/* */
/* <Description> */
/* A bit-field constant, used to indicate that the font contains */
- /* glyph names that can be retrieved through FT_Get_Glyph_Name(). */
+ /* glyph names that can be retrieved through @FT_Get_Glyph_Name(). */
/* */
#define FT_FACE_FLAG_GLYPH_NAMES 0x200
@@ -841,7 +864,7 @@
/* <Description> */
/* This bit field is used internally by FreeType to indicate that */
/* a face's stream was provided by the client application and should */
- /* not be destroyed by FT_Done_Face(). */
+ /* not be destroyed by @FT_Done_Face(). */
/* */
#define FT_FACE_FLAG_EXTERNAL_STREAM 0x4000
@@ -952,7 +975,8 @@
/* @macro: FT_HAS_FAST_GLYPHS (face) */
/* */
/* @description: */
- /* XXX */
+ /* Deprecated, indicates that the face contains so-called "fast" */
+ /* glyph bitmaps. */
/* */
#define FT_HAS_FAST_GLYPHS( face ) \
( face->face_flags & FT_FACE_FLAG_FAST_GLYPHS )
@@ -1218,8 +1242,8 @@
/* when the slot format is */
/* ft_glyph_format_bitmap. Note that the */
/* address and content of the bitmap buffer can */
- /* change between calls of FT_Load_Glyph() and a */
- /* few other functions. */
+ /* change between calls of @FT_Load_Glyph() and */
+ /* a few other functions. */
/* */
/* bitmap_left :: This is the bitmap's left bearing expressed */
/* in integer pixels. Of course, this is only */
@@ -1326,7 +1350,7 @@
/* FT_Init_FreeType */
/* */
/* <Description> */
- /* Initializes a new FreeType library object. The set of drivers */
+ /* Initializes a new FreeType library object. The set of modules */
/* that are registered by this function is determined at build time. */
/* */
/* <Output> */
@@ -1365,8 +1389,8 @@
/* certain programs implement library initialization in a custom way */
/* that doesn't use `FT_Init_FreeType'. */
/* */
- /* In such cases it can happen that the library version is not known */
- /* until the library object has been created. */
+ /* In such cases, the library version might not be available before */
+ /* the library object has been created. */
/* */
FT_EXPORT( void )
FT_Library_Version( FT_Library library,
@@ -1554,6 +1578,9 @@
/* `aface'. Its return value should be 0 if the font format is */
/* recognized, or non-zero otherwise. */
/* */
+ /* Each new face object created with this function also owns a */
+ /* default @FT_Size object, accessible as `face->size' */
+ /* */
FT_EXPORT( FT_Error )
FT_New_Face( FT_Library library,
const char* filepathname,
diff --git a/include/freetype/ftchapters.h b/include/freetype/ftchapters.h
index 3c107d8..6c20199 100644
--- a/include/freetype/ftchapters.h
+++ b/include/freetype/ftchapters.h
@@ -11,14 +11,25 @@
/* base_interface */
/* 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 */
-/* sizes_management */
-/* module_management */
-/* system_interface */
-/* header_file_macros */
+/* bdf_fonts */
/* */
/***************************************************************************/
@@ -50,6 +61,8 @@
/* list_processing */
/* outline_processing */
/* raster */
+/* system_interface */
+/* module_management */
/* */
/***************************************************************************/
diff --git a/include/freetype/ftsizes.h b/include/freetype/ftsizes.h
index 87196a5..0fd6f0f 100644
--- a/include/freetype/ftsizes.h
+++ b/include/freetype/ftsizes.h
@@ -57,7 +57,7 @@
/* 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_Character_Size only */
+ /* 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. */
/* */
diff --git a/include/freetype/fttypes.h b/include/freetype/fttypes.h
index 15aa6a5..757817f 100644
--- a/include/freetype/fttypes.h
+++ b/include/freetype/fttypes.h
@@ -36,14 +36,15 @@
/* basic_types */
/* */
/* <Title> */
- /* Basic Types */
+ /* 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 font specific ones. */
+ /* ranging from simple scalar types to bitmap descriptors. More */
+ /* font-specific structures are defined in a different section. */
/* */
/* <Order> */
/* FT_Byte */
@@ -57,6 +58,7 @@
/* FT_Bool */
/* FT_Offset */
/* FT_PtrDist */
+ /* FT_String */
/* FT_Error */
/* FT_Fixed */
/* FT_Pointer */
@@ -64,6 +66,12 @@
/* FT_Vector */
/* FT_BBox */
/* FT_Matrix */
+ /* FT_FWord */
+ /* FT_UFWord */
+ /* FT_F2Dot14 */
+ /* FT_UnitVector */
+ /* FT_F26Dot6 */
+ /* */
/* */
/* FT_Generic */
/* FT_Generic_Finalizer */
@@ -73,7 +81,6 @@
/* FT_Palette_Mode */
/* FT_Glyph_Format */
/* FT_IMAGE_TAG */
- /* FT_Glyph_Format */
/* */
/*************************************************************************/
