ref: 7dc7f21533899dcbbc6a4dca4c2013bf808ec055
parent: 65c7c773aa813f6eb23cc481fd280e504fb52b70
author: David Turner <[email protected]>
date: Thu Apr 13 12:31:02 EDT 2006
doc updates - fixing FT_Stroker_New to use a FT_Library instead of a FT_Memory i know, i know, the ChangeLog will be updated later
--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@@ -147,12 +147,12 @@
/* FT_Attach_File */
/* FT_Attach_Stream */
/* */
- /* FT_Size_Request_Type */
- /* FT_Size_Request */
- /* FT_Request_Size */
- /* FT_Select_Size */
/* FT_Set_Char_Size */
/* FT_Set_Pixel_Sizes */
+ /* FT_Request_Size */
+ /* FT_Select_Size */
+ /* FT_Size_Request_Type */
+ /* FT_Size_Request */
/* FT_Set_Transform */
/* FT_Load_Glyph */
/* FT_Get_Char_Index */
@@ -211,8 +211,8 @@
/* <Description> */
/* A structure used 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 is used, values are returned in font units */
- /* instead. */
+ /* @FT_LOAD_NO_SCALE was used when loading the glyph, values are */
+ /* expressed in font units instead. */
/* */
/* <Fields> */
/* width :: */
@@ -407,20 +407,22 @@
/* FT_Size */
/* */
/* <Description> */
- /* A handle to a given size object which models a face object at a */
- /* given size. */
+ /* A handle to an object used to model a face scaled to a given */
+ /* character size. */
/* */
/* <Note> */
- /* Each face object owns one or more sizes. There is however a */
- /* single _active_ size for the face at any time that is used by */
- /* functions like @FT_Load_Glyph, @FT_Get_Kerning, etc. */
+ /* Each @FT_Face has an _active_ @FT_Size object that is used by */
+ /* functions like @FT_Load_Glyph to determine the scaling transform */
+ /* used to load and hint glyph and metrics. */
/* */
- /* You can use @FT_New_Size to allocate new size objects for a face */
- /* object and @FT_Activate_Size to activate. */
+ /* 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. scale) of the active @FT_Size. */
/* */
- /* You can use @FT_Request_Size, @FT_Select_Size, etc., to change the */
- /* size that the active size object models. Note that size changing */
- /* can be expensive for some font formats. */
+ /* You can use @FT_New_Size to create additionnal 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> */
/* The @FT_SizeRec structure details the publicly accessible fields */
@@ -517,17 +519,17 @@
/* FT_Encoding */
/* */
/* <Description> */
- /* An enumeration used to specify encodings supported by charmaps. */
- /* Used in the @FT_Select_Charmap API function. */
+ /* An enumeration used to specify character sets supported by */
+ /* charmaps. Used in the @FT_Select_Charmap API function. */
/* */
/* <Note> */
+ /* Despite the name, this enum lists specific character repertories */
+ /* (i.e. charsets), and not text encoding methods (e.g. UTF-8, */
+ /* UTF-16, GB2312_EUC, etc...) */
+ /* */
/* Because of 32-bit charcodes defined in Unicode (i.e., surrogates), */
/* all character codes must be expressed as FT_Longs. */
/* */
- /* The values of this type correspond to specific character */
- /* repertories (i.e. charsets), and not to text encoding methods */
- /* (like UTF-8, UTF-16, GB2312_EUC, etc.). */
- /* */
/* Other encodings might be defined in the future. */
/* */
/* <Values> */
@@ -1154,12 +1156,10 @@
* FT_HAS_FAST_GLYPHS( face )
*
* @description:
- * Deprecated; indicates that the face contains so-called `fast' glyph
- * bitmaps.
+ * Deprecated;
*
*/
-#define FT_HAS_FAST_GLYPHS( face ) \
- ( face->face_flags & FT_FACE_FLAG_FAST_GLYPHS )
+#define FT_HAS_FAST_GLYPHS( face ) 0
/*************************************************************************
@@ -1333,6 +1333,9 @@
/* 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;
@@ -1923,8 +1926,8 @@
/* <Description> */
/* `Attach' data to a face object. This is usually used to read */
/* additional information for the face object. For example, you can */
- /* attach an AFM file that come with a Type 1 font to get the kerning */
- /* values and other metrics. */
+ /* attach an AFM file that comes with a Type 1 font to get the */
+ /* kerning values and other metrics. */
/* */
/* <InOut> */
/* face :: The target face object. */
@@ -1942,7 +1945,7 @@
/* 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 */
+ /* when invoking this function. Most drivers simply do not implement */
/* file attachments. */
/* */
FT_EXPORT( FT_Error )
@@ -2090,7 +2093,7 @@
/* FT_Request_Size */
/* */
/* <Description> */
- /* Request the size of the active size object of a given face object. */
+ /* Resize the scale of the active @FT_Size object in a face. */
/* */
/* <InOut> */
/* face :: A handle to a target face object. */
@@ -2129,9 +2132,9 @@
/* */
/* char_height :: The nominal height, in 26.6 fractional points. */
/* */
- /* horz_resolution :: The horizontal resolution. */
+ /* horz_resolution :: The horizontal resolution in dpi. */
/* */
- /* vert_resolution :: The vertical resolution. */
+ /* vert_resolution :: The vertical resolution in dpi. */
/* */
/* <Return> */
/* FreeType error code. 0 means success. */
@@ -2261,7 +2264,7 @@
* 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.
+ * face's current size. If one is found, the function returns.
* The bitmap data can be accessed from the glyph slot (see note
* below).
*
@@ -2799,7 +2802,7 @@
/* FT_Get_Postscript_Name */
/* */
/* <Description> */
- /* Retriev the ASCII Postscript name of a given face, if available. */
+ /* Retrieve the ASCII Postscript name of a given face, if available. */
/* This only works with Postscript and TrueType fonts. */
/* */
/* <Input> */
@@ -2909,10 +2912,11 @@
/* The glyph index. 0 means `undefined character code'. */
/* */
/* <Note> */
- /* FreeType computes its own glyph indices which are not necessarily */
- /* the same as used in the font in case the font is based on glyph */
- /* indices. Reason for this behaviour is to assure that index 0 is */
- /* never used, representing the missing glyph. */
+ /* If you use FreeType to manipulate the content 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 correspond */
+ /* to 'missing glyph' */
/* */
FT_EXPORT( FT_UInt )
FT_Get_Char_Index( FT_Face face,
--- a/include/freetype/ftcache.h
+++ b/include/freetype/ftcache.h
@@ -285,14 +285,14 @@
/* library :: The parent FreeType library handle to use. */
/* */
/* max_faces :: Maximum number of opened @FT_Face objects managed by */
- /* this cache instance. */
+ /* this cache instance. Use 0 for defaults */
/* */
/* max_sizes :: Maximum number of opened @FT_Size objects managed by */
- /* this cache instance. */
+ /* 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. */
+ /* account for managed @FT_Face and @FT_Size objects. */
/* */
/* requester :: An application-provided callback used to translate */
/* face IDs into real @FT_Face objects. */
@@ -384,8 +384,8 @@
/* _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 */
+ /* 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 )
@@ -500,7 +500,27 @@
FTC_Manager manager );
- /* remove all nodes belonging to a given face_id */
+ /**
+ * @function: FTC_Manager_RemoveFaceID
+ *
+ * @description:
+ * a special function used to indicate to the cache manager that
+ * a given @FTC_FaceID is no longer valid, either because it
+ * content changed, or because it was deallocated/uninstalled
+ *
+ * @input:
+ * manager :: cache manager handle
+ * face_id :: the @FTC_FaceID to be removed
+ *
+ * @note:
+ * this function will flush all nodes from the cache corresponding
+ * to this face_id, with the exception of nodes with a non-0 reference
+ * count.
+ *
+ * these nodes are however modified internally so as to never appear
+ * in later lookups with the same face_id value, and to be immediately
+ * destroyed when released by all their users.
+ */
FT_EXPORT( void )
FTC_Manager_RemoveFaceID( FTC_Manager manager,
FTC_FaceID face_id );
@@ -519,7 +539,7 @@
* FTC_CMapCache
*
* @description:
- * An opaque handle used to manager a charmap cache. This cache is to
+ * An opaque handle used to model a charmap cache. This cache is to
* hold character codes -> glyph indices mappings.
*
*/
@@ -606,6 +626,18 @@
/*************************************************************************/
/*************************************************************************/
+ /**
+ * @struct: FTC_ImageTypeRec
+ *
+ * @description:
+ * a structure used to model the type of images in a glyph cache
+ *
+ * @fields:
+ * face_id :: the face id
+ * width :: width in pixels
+ * height :: height in pixels
+ * flags :: load flags, as in @FT_Load_Glyph
+ */
typedef struct FTC_ImageTypeRec_
{FTC_FaceID face_id;
@@ -615,6 +647,12 @@
} FTC_ImageTypeRec;
+ /**
+ * @type: FTC_ImageType
+ *
+ * @description:
+ * handle to an @FTC_ImageTypeRec structure
+ */
typedef struct FTC_ImageTypeRec_* FTC_ImageType;
--- a/include/freetype/ftchapters.h
+++ b/include/freetype/ftchapters.h
@@ -55,8 +55,6 @@
/* bdf_fonts */
/* pfr_fonts */
/* winfnt_fonts */
-/* ot_validation */
-/* gx_validation */
/* */
/***************************************************************************/
--- a/include/freetype/ftglyph.h
+++ b/include/freetype/ftglyph.h
@@ -150,8 +150,8 @@
/* bitmap :: A descriptor for the bitmap. */
/* */
/* <Note> */
- /* You can typecast FT_Glyph to FT_BitmapGlyph if you have */
- /* glyph->format == FT_GLYPH_FORMAT_BITMAP. This lets you access */
+ /* You can typecast a @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 the BitmapGlyph */
@@ -194,13 +194,13 @@
/* outline :: A descriptor for the outline. */
/* */
/* <Note> */
- /* You can typecast FT_Glyph to FT_OutlineGlyph if you have */
- /* glyph->format == FT_GLYPH_FORMAT_OUTLINE. This lets you access */
+ /* You can typecast a @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(). */
+ /* @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. */
@@ -277,8 +277,7 @@
/* expressed in 1/64th of a pixel. */
/* */
/* <Return> */
- /* FreeType error code (the glyph format is not scalable if it is */
- /* not zero). */
+ /* FreeType error code (if not 0, the glyph format is not scalable) */
/* */
/* <Note> */
/* The 2x2 transformation matrix is also applied to the glyph's */
@@ -379,9 +378,9 @@
/* 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' */
+ /* 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. */
/* */
/* Note that the maximum coordinates are exclusive, which means that */
@@ -388,23 +387,27 @@
/* 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'. */
+ /* @FT_GLYPH_BBOX_TRUNCATE. */
/* */
/* To get the bbox in grid-fitted pixel coordinates, set `bbox_mode' */
- /* to `FT_GLYPH_BBOX_PIXELS'. */
+ /* to @FT_GLYPH_BBOX_PIXELS. */
/* */
FT_EXPORT( void )
FT_Glyph_Get_CBox( FT_Glyph glyph,
--- a/include/freetype/ftstroke.h
+++ b/include/freetype/ftstroke.h
@@ -188,8 +188,7 @@
* `outside' borders of a given outline.
*
* @input:
- * outline ::
- * The source outline handle.
+ * outline :: The source outline handle.
*
* @return:
* The border index. @FT_STROKER_BORDER_LEFT for empty or invalid
@@ -208,17 +207,16 @@
* Create a new stroker object.
*
* @input:
- * memory ::
- * The memory manager handle.
+ * library :: FreeType library handle
*
* @output:
- * A new stroker object handle. NULL in case of error.
+ * astroker :: A new stroker object handle. NULL in case of error.
*
* @return:
* FreeType error code. 0 means success.
*/
FT_EXPORT( FT_Error )
- FT_Stroker_New( FT_Memory memory,
+ FT_Stroker_New( FT_Library library,
FT_Stroker *astroker );
--- a/src/base/ftstroke.c
+++ b/src/base/ftstroke.c
@@ -716,12 +716,17 @@
/* documentation is in ftstroke.h */
FT_EXPORT_DEF( FT_Error )
- FT_Stroker_New( FT_Memory memory,
+ FT_Stroker_New( FT_Library library,
FT_Stroker *astroker )
{FT_Error error;
+ FT_Memory memory;
FT_Stroker stroker;
+ if ( !library )
+ return FT_Err_Invalid_Argument;
+
+ memory = library->memory;
if ( !FT_NEW( stroker ) )
{--- a/src/tools/docmaker/content.py
+++ b/src/tools/docmaker/content.py
@@ -59,15 +59,15 @@
lines = self.dump_lines( 0, width )
for l in lines:
print prefix + l
-
+
def dump_lines( self, margin=0, width=60 ):
result = []
for l in self.lines:
result.append( " "*margin + l )
return result
-
+
#############################################################################
#
# The DocPara class is used to store "normal" text paragraph.
@@ -87,7 +87,7 @@
lines = self.dump_lines( 0, width )
for l in lines:
print prefix + l
-
+
def dump_lines( self, margin=0, width = 60 ):
cur = "" # current line
col = 0 # current width
@@ -110,17 +110,17 @@
if col > 0:
result.append( " "*margin + cur )
-
+
return result
-
+
#############################################################################
#
# The DocField class is used to store a list containing either DocPara or
# DocCode objects. Each DocField also has an optional "name" which is used
-# when the object corresponds to a field of value definition
+# when the object corresponds to a field or value definition
#
class DocField:
@@ -210,10 +210,10 @@
for p in self.items:
if nl:
result.append( "" )
-
+
result.extend( p.dump_lines( margin, width ) )
nl = 1
-
+
return result
# this regular expression is used to detect field definitions
@@ -261,7 +261,7 @@
except:
return None
-
+
def get_start( self ):
try:
result = ""
@@ -268,7 +268,7 @@
for word in self.fields[0].items[0].words:
result = result + " " + word
return result[1:]
-
+
except:
return "ERROR"
@@ -320,7 +320,7 @@
def process( self ):
# lookup one block that contains a valid section description
for block in self.defs:
- title = block.get_markup_text( "Title" )
+ title = block.get_markup_text( "title" )
if title:
self.title = title
self.abstract = block.get_markup_words( "abstract" )
--- a/src/tools/docmaker/sources.py
+++ b/src/tools/docmaker/sources.py
@@ -135,8 +135,8 @@
#
# used to detect italic and bold styles in paragraph text
#
-re_italic = re.compile( r"_(\w(\w|')*)_" )
-re_bold = re.compile( r"\*(\w(\w|')*)\*" )
+re_italic = re.compile( r"_(\w(\w|')*)_" ) # _italic_
+re_bold = re.compile( r"\*(\w(\w|')*)\*" ) # *bold*
#
# used to detect the end of commented source lines