diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h index 8ef489c4c..267456309 100644 --- a/include/freetype/freetype.h +++ b/include/freetype/freetype.h @@ -147,12 +147,12 @@ FT_BEGIN_HEADER /* 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 @@ FT_BEGIN_HEADER /* */ /* 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. */ /* */ /* */ /* width :: */ @@ -407,20 +407,22 @@ FT_BEGIN_HEADER /* FT_Size */ /* */ /* */ - /* 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. */ /* */ /* */ - /* 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. */ /* */ /* */ /* The @FT_SizeRec structure details the publicly accessible fields */ @@ -517,17 +519,17 @@ FT_BEGIN_HEADER /* FT_Encoding */ /* */ /* */ - /* 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. */ /* */ /* */ + /* 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. */ /* */ /* */ @@ -1154,12 +1156,10 @@ FT_BEGIN_HEADER * 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 @@ FT_BEGIN_HEADER /* 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 @@ FT_BEGIN_HEADER /* */ /* `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. */ /* */ /* */ /* face :: The target face object. */ @@ -1942,7 +1945,7 @@ FT_BEGIN_HEADER /* 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_BEGIN_HEADER /* FT_Request_Size */ /* */ /* */ - /* 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. */ /* */ /* */ /* face :: A handle to a target face object. */ @@ -2129,9 +2132,9 @@ FT_BEGIN_HEADER /* */ /* 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. */ /* */ /* */ /* FreeType error code. 0 means success. */ @@ -2261,7 +2264,7 @@ 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. + * 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_BEGIN_HEADER /* FT_Get_Postscript_Name */ /* */ /* */ - /* 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. */ /* */ /* */ @@ -2909,10 +2912,11 @@ FT_BEGIN_HEADER /* The glyph index. 0 means `undefined character code'. */ /* */ /* */ - /* 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, diff --git a/include/freetype/ftcache.h b/include/freetype/ftcache.h index c63b2b2fa..430f4afee 100644 --- a/include/freetype/ftcache.h +++ b/include/freetype/ftcache.h @@ -285,14 +285,14 @@ FT_BEGIN_HEADER /* 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 @@ FT_BEGIN_HEADER /* _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 @@ FT_BEGIN_HEADER 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 @@ FT_BEGIN_HEADER * 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 @@ FT_BEGIN_HEADER /*************************************************************************/ /*************************************************************************/ + /** + * @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 @@ FT_BEGIN_HEADER } FTC_ImageTypeRec; + /** + * @type: FTC_ImageType + * + * @description: + * handle to an @FTC_ImageTypeRec structure + */ typedef struct FTC_ImageTypeRec_* FTC_ImageType; diff --git a/include/freetype/ftchapters.h b/include/freetype/ftchapters.h index 9fd25a376..7b59ccf75 100644 --- a/include/freetype/ftchapters.h +++ b/include/freetype/ftchapters.h @@ -55,8 +55,6 @@ /* bdf_fonts */ /* pfr_fonts */ /* winfnt_fonts */ -/* ot_validation */ -/* gx_validation */ /* */ /***************************************************************************/ diff --git a/include/freetype/ftglyph.h b/include/freetype/ftglyph.h index 14050a21d..2b6b4b51f 100644 --- a/include/freetype/ftglyph.h +++ b/include/freetype/ftglyph.h @@ -150,8 +150,8 @@ FT_BEGIN_HEADER /* bitmap :: A descriptor for the bitmap. */ /* */ /* */ - /* 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 @@ FT_BEGIN_HEADER /* outline :: A descriptor for the outline. */ /* */ /* */ - /* 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 @@ FT_BEGIN_HEADER /* expressed in 1/64th of a pixel. */ /* */ /* */ - /* 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) */ /* */ /* */ /* The 2x2 transformation matrix is also applied to the glyph's */ @@ -379,32 +378,36 @@ FT_BEGIN_HEADER /* 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 */ /* 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, diff --git a/include/freetype/ftstroke.h b/include/freetype/ftstroke.h index 83a1ed5e2..00ec08558 100644 --- a/include/freetype/ftstroke.h +++ b/include/freetype/ftstroke.h @@ -188,8 +188,7 @@ FT_BEGIN_HEADER * `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 @@ FT_BEGIN_HEADER * 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 ); diff --git a/src/base/ftstroke.c b/src/base/ftstroke.c index 26ff21511..c5200b32f 100644 --- 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 ) ) { diff --git a/src/tools/docmaker/content.py b/src/tools/docmaker/content.py index ebfeb8bf4..22753dcd1 100644 --- a/src/tools/docmaker/content.py +++ b/src/tools/docmaker/content.py @@ -59,13 +59,13 @@ class DocCode: 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 - + ############################################################################# @@ -87,7 +87,7 @@ class DocPara: 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 @@ class DocPara: 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 @@ class DocField: 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,14 +261,14 @@ class DocMarkup: except: return None - + def get_start( self ): try: result = "" for word in self.fields[0].items[0].words: result = result + " " + word return result[1:] - + except: return "ERROR" @@ -320,7 +320,7 @@ class DocSection: 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" ) diff --git a/src/tools/docmaker/sources.py b/src/tools/docmaker/sources.py index edc9f6c0c..923fa7b6e 100644 --- a/src/tools/docmaker/sources.py +++ b/src/tools/docmaker/sources.py @@ -135,8 +135,8 @@ re_crossref = re.compile( r'@(\w*)(.*)' ) # # 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