From 0f5616a801e9401bf2e7abab3c709ada557ea6cf Mon Sep 17 00:00:00 2001 From: David Turner Date: Wed, 10 Jan 2001 11:15:48 +0000 Subject: [PATCH] updated documentation in public header files --- ChangeLog | 6 +- docs/docmaker.py | 31 +++++++--- include/freetype/cache/ftcimage.h | 7 ++- include/freetype/cache/ftcmanag.h | 3 + include/freetype/cache/ftcsbits.h | 98 ++++++++++++++++++++++++++++++- include/freetype/freetype.h | 2 +- include/freetype/ftbbox.h | 4 ++ include/freetype/ftcache.h | 13 ++++ include/freetype/ftglyph.h | 41 +++++++++---- include/freetype/ftimage.h | 2 +- include/freetype/ftmac.h | 17 ++++++ include/freetype/ftmm.h | 14 +++++ include/freetype/ftmodule.h | 12 ++++ include/freetype/ftnames.h | 21 ++++++- include/freetype/ftrender.h | 3 + include/freetype/fttypes.h | 2 +- include/freetype/t1tables.h | 12 ++++ 17 files changed, 259 insertions(+), 29 deletions(-) diff --git a/ChangeLog b/ChangeLog index b1215b7f9..ef0bfa016 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,7 +1,11 @@ 2000-01-09 David Turner * docs/docmaker.py: improved script to generate table of contents and - index pages. + index pages. it also supports wildcards on non Unix systems + + * include/freetype/*.h, include/freetype/cache/*.h: updated comments + to include section definitions / delimitations for the API Reference + generator.. 2000-01-04 Werner Lemberg diff --git a/docs/docmaker.py b/docs/docmaker.py index c3b367db0..c3d69c4c6 100644 --- a/docs/docmaker.py +++ b/docs/docmaker.py @@ -8,7 +8,7 @@ # - David # -import fileinput, sys, string +import fileinput, sys, string, glob html_header = """ @@ -771,7 +771,7 @@ class DocSectionList: def append_section( self, block ): - name = block.name + name = string.lower( block.name ) abstract = block.find_content( "abstract" ) if self.sections.has_key( name ): @@ -859,12 +859,13 @@ class DocSectionList: print "
" for section in self.list: - print "" + if section.abstract: + print "" print "
" - print '' - print section.title - print "" - section.abstract.dump_html() - print "
" + print '' + print section.title + print "" + section.abstract.dump_html() + print "
" @@ -980,6 +981,18 @@ def dump_html_1( block_list ): def make_block_list_inner(): """parse a file and extract comments blocks from it""" + file_list = [] + sys.stderr.write( repr( sys.argv[1:] ) + '\n' ) + + for pathname in sys.argv[1:]: + newpath = glob.glob( pathname ) + sys.stderr.write ( repr(newpath) + '\n' ) + last = len(file_list) + file_list[last:last] = newpath + + if len( file_list ) == 0: + file_list = None + list = [] block = [] format = 0 @@ -997,7 +1010,7 @@ def make_block_list_inner(): source = [] state = 0 - for line in fileinput.input(): + for line in fileinput.input( file_list ): l = len( line ) if l > 0 and line[l - 1] == '\012': line = line[0 : l - 1] diff --git a/include/freetype/cache/ftcimage.h b/include/freetype/cache/ftcimage.h index 58ed204b4..7c10ef51b 100644 --- a/include/freetype/cache/ftcimage.h +++ b/include/freetype/cache/ftcimage.h @@ -35,6 +35,10 @@ FT_BEGIN_HEADER + /*** + *
cache_subsystem + */ + /*************************************************************************/ /*************************************************************************/ /*************************************************************************/ @@ -60,7 +64,7 @@ FT_BEGIN_HEADER /* monochrome bitmap */ #define ftc_image_mono ftc_image_format_bitmap | \ - ftc_image_flag_monochrome + ftc_image_flag_monochrome /* anti-aliased bitmap */ #define ftc_image_grays ftc_image_format_bitmap /* scaled outline */ @@ -159,6 +163,7 @@ FT_BEGIN_HEADER FT_UInt gindex, FT_Glyph *aglyph ); + /* */ FT_END_HEADER diff --git a/include/freetype/cache/ftcmanag.h b/include/freetype/cache/ftcmanag.h index 72794da0d..40d107bdd 100644 --- a/include/freetype/cache/ftcmanag.h +++ b/include/freetype/cache/ftcmanag.h @@ -70,6 +70,9 @@ FT_BEGIN_HEADER + /*** + *
cache_subsystem + */ #define FTC_MAX_FACES_DEFAULT 2 #define FTC_MAX_SIZES_DEFAULT 4 diff --git a/include/freetype/cache/ftcsbits.h b/include/freetype/cache/ftcsbits.h index 6de4ed47b..e86ea9d37 100644 --- a/include/freetype/cache/ftcsbits.h +++ b/include/freetype/cache/ftcsbits.h @@ -29,13 +29,60 @@ FT_BEGIN_HEADER - /* handle to small bitmap */ + /*** + *
cache_subsystem + */ + + /*********************************************************************** + * + * FTC_SBit + * + * + * handle to a small bitmap descriptor. see the FTC_SBitRec + * structure for details.. + */ typedef struct FTC_SBitRec_* FTC_SBit; - /* handle to small bitmap cache */ + /*********************************************************************** + * + * FTC_SBit_Cache + * + * + * 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_Image_Cache + */ typedef struct FTC_SBit_CacheRec_* FTC_SBit_Cache; - /* a compact structure used to hold a single small bitmap */ + /*********************************************************************** + * + * FTC_SBitRec + * + * + * a very compact structure used to describe a small glyph bitmap + * + * + * width :: bitmap width in pixels + * height :: bitmap height in pixels + * + * left :: horizontal distance from pen position to left bitmap + * border (a.k.a. "left side bearing", or "lsb") + * + * top :: vertical distance from 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 :: format of glyph bitmap (mono or gray) + * + * pitch :: number of bytes per bitmap lines. may be positive or + * negative + * + * xadvance :: horizontal advance width in pixels + * yadvance :: vertical advance height in pixels + * + * buffer :: pointer to bitmap pixels + */ typedef struct FTC_SBitRec_ { FT_Byte width; @@ -53,14 +100,59 @@ FT_BEGIN_HEADER } FTC_SBitRec; + /************************************************************************* + * + *
FTC_SBit_Cache_New + * + * + * Create a new cache to store small glyph bitmaps + * + * + * manager :: handle to source cache manager + * + * + * acache :: handle to new sbit cache. NULL in case of error + * + * + * error code. 0 means success + */ FT_EXPORT( FT_Error ) FTC_SBit_Cache_New( FTC_Manager manager, FTC_SBit_Cache *acache ); + /************************************************************************* + * + *
FTC_SBit_Cache_Lookup + * + * + * Lookup a given small glyph bitmap in a given sbit cache + * + * + * cache :: handle to source sbit cache + * desc :: pointer to glyph image descriptor + * gindex :: glyph index + * + * + * sbit :: handle to a small bitmap descriptor + * + * + * error code. 0 means success + * + * + * 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 like persistent data.. + * + * the descriptor's "buffer" field is set to 0 to indicate a missing + * glyph bitmap. + */ FT_EXPORT( FT_Error ) FTC_SBit_Cache_Lookup( FTC_SBit_Cache cache, FTC_Image_Desc* desc, FT_UInt gindex, FTC_SBit *sbit ); + /* */ + FT_END_HEADER #endif /* __FTCSBITS_H__ */ diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h index e6d55e4be..17ec70761 100644 --- a/include/freetype/freetype.h +++ b/include/freetype/freetype.h @@ -57,7 +57,7 @@ FT_BEGIN_HEADER /************************************************************************* * - *
Base_Interface + *
base_interface * * Base Interface * diff --git a/include/freetype/ftbbox.h b/include/freetype/ftbbox.h index 7cf149cb4..9d9252f25 100644 --- a/include/freetype/ftbbox.h +++ b/include/freetype/ftbbox.h @@ -38,6 +38,10 @@ FT_BEGIN_HEADER + /******************************** + * <Section> outline_processing + */ + /*************************************************************************/ /* */ /* <Function> */ diff --git a/include/freetype/ftcache.h b/include/freetype/ftcache.h index 0fcca41ec..81b8d4906 100644 --- a/include/freetype/ftcache.h +++ b/include/freetype/ftcache.h @@ -50,6 +50,19 @@ FT_BEGIN_HEADER #define FT_CACHE_INTERNAL_GLYPH_H FT2_PUBLIC_FILE(cache/ftcglyph.h) #define FT_CACHE_INTERNAL_CHUNK_H FT2_PUBLIC_FILE(cache/ftcchunk.h) + /************************************************************************** + * + * <Section> cache_subsystem + * + * <Title> Cache Sub-System + * + * <Abstract> + * How to cache face, size and glyph data with FreeType 2 + * + * <Description> + * This section details the FreeType 2 cache sub-system which is still + * in beta. + */ /*************************************************************************/ /*************************************************************************/ diff --git a/include/freetype/ftglyph.h b/include/freetype/ftglyph.h index 6f2349eeb..7824b8134 100644 --- a/include/freetype/ftglyph.h +++ b/include/freetype/ftglyph.h @@ -39,6 +39,20 @@ 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 one 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; @@ -218,17 +232,8 @@ FT_BEGIN_HEADER FT_Matrix* matrix, FT_Vector* delta ); - - enum - { - ft_glyph_bbox_unscaled = 0, /* return unscaled font units */ - ft_glyph_bbox_subpixels = 0, /* return unfitted 26.6 coordinates */ - ft_glyph_bbox_gridfit = 1, /* return grid-fitted 26.6 coordinates */ - ft_glyph_bbox_truncate = 2, /* return coordinates in integer pixels */ - ft_glyph_bbox_pixels = 3 /* return grid-fitted pixel coordinates */ - }; - - + /* */ + /*************************************************************************/ /* */ /* <Function> */ @@ -291,6 +296,17 @@ FT_BEGIN_HEADER /* */ /* The default value for `bbox_mode' is `ft_glyph_bbox_pixels'. */ /* */ + + enum + { + ft_glyph_bbox_unscaled = 0, /* return unscaled font units */ + ft_glyph_bbox_subpixels = 0, /* return unfitted 26.6 coordinates */ + ft_glyph_bbox_gridfit = 1, /* return grid-fitted 26.6 coordinates */ + ft_glyph_bbox_truncate = 2, /* return coordinates in integer pixels */ + ft_glyph_bbox_pixels = 3 /* return grid-fitted pixel coordinates */ + }; + + FT_EXPORT( void ) FT_Glyph_Get_CBox( FT_Glyph glyph, FT_UInt bbox_mode, FT_BBox *acbox ); @@ -389,6 +405,9 @@ FT_BEGIN_HEADER /* other helpful functions */ + /***** + * <Section> base_interface + */ /*************************************************************************/ /* */ diff --git a/include/freetype/ftimage.h b/include/freetype/ftimage.h index 3a8138fcb..19e2b9b7e 100644 --- a/include/freetype/ftimage.h +++ b/include/freetype/ftimage.h @@ -35,7 +35,7 @@ FT_BEGIN_HEADER /*********************************************************************** * - * <Section> Basic_Types + * <Section> basic_types * */ diff --git a/include/freetype/ftmac.h b/include/freetype/ftmac.h index a258a045c..99654c742 100644 --- a/include/freetype/ftmac.h +++ b/include/freetype/ftmac.h @@ -34,6 +34,19 @@ FT_BEGIN_HEADER + /******************************************************************* + * + * <Section> Mac_Specific + * + * <Title> Mac-Specific Interface + * + * <Abstract> + * Only available on the Macintosh + * + * <Description> + * The following definitions are only available when FreeType + * is compiled on a Macintosh. + */ /*************************************************************************/ /* */ @@ -62,14 +75,18 @@ FT_BEGIN_HEADER /* This function can be used to create FT_Face abjects from fonts */ /* that are installed in the system like so: */ /* */ + /* { */ /* 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, FT_Long face_index, FT_Face *aface ); + /* */ FT_END_HEADER diff --git a/include/freetype/ftmm.h b/include/freetype/ftmm.h index 719fe6528..bf4a1e6ea 100644 --- a/include/freetype/ftmm.h +++ b/include/freetype/ftmm.h @@ -26,6 +26,20 @@ 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. choose specific design instances by setting + * design axis coordinates. + */ /*************************************************************************/ /* */ diff --git a/include/freetype/ftmodule.h b/include/freetype/ftmodule.h index 06eca0410..0416c648f 100644 --- a/include/freetype/ftmodule.h +++ b/include/freetype/ftmodule.h @@ -26,6 +26,18 @@ FT_BEGIN_HEADER + /************************************************************************** + * + * <Section> Module_Management + * + * <Title> Module Management + * + * <Abstract> How to add, upgrade and remove modules from FreeType + * + * <Description> + * The definitions below are used to manage modules within FreeType. + * Modules can be added, upgraded and removed at runtime. + */ /* module bit flags */ typedef enum FT_Module_Flags_ diff --git a/include/freetype/ftnames.h b/include/freetype/ftnames.h index 069ea3fd7..a82406577 100644 --- a/include/freetype/ftnames.h +++ b/include/freetype/ftnames.h @@ -30,6 +30,25 @@ FT_BEGIN_HEADER + /************************************************************************** + * + * <Section> SFNT_Names + * + * <Title> SFNT Names + * + * <Abstract> Access the names embedded in TrueType and OpenType files + * + * <Description> + * The TrueType and OpenType specification allow the inclusion of + * a special "names table" in font files. This table contains textual + * (and internationalised) information regarding the font, like + * family name, copyright, version, etc.. + * + * the definitions below are used to access them when available + * + * note that this has nothing to do with "glyph names" !! + */ + /*************************************************************************/ /* */ /* <Struct> */ @@ -118,7 +137,7 @@ FT_BEGIN_HEADER FT_EXPORT( FT_Error ) FT_Get_Sfnt_Name( FT_Face face, FT_UInt index, FT_SfntName *aname ); - + /* */ FT_END_HEADER diff --git a/include/freetype/ftrender.h b/include/freetype/ftrender.h index c80770523..fa4d1f908 100644 --- a/include/freetype/ftrender.h +++ b/include/freetype/ftrender.h @@ -27,6 +27,9 @@ FT_BEGIN_HEADER + /**** + * <Section> Module_Management + */ /* create a new glyph object */ typedef FT_Error (*FT_Glyph_Init_Func) ( FT_Glyph glyph, diff --git a/include/freetype/fttypes.h b/include/freetype/fttypes.h index 51c64ea20..4f03c8b9d 100644 --- a/include/freetype/fttypes.h +++ b/include/freetype/fttypes.h @@ -31,7 +31,7 @@ FT_BEGIN_HEADER /*************************************************************************/ /* */ - /* <Section> Basic_Types */ + /* <Section> basic_types */ /* */ /* <Title> Basic Data Types */ /* */ diff --git a/include/freetype/t1tables.h b/include/freetype/t1tables.h index 1091e88ae..696c4cb6d 100644 --- a/include/freetype/t1tables.h +++ b/include/freetype/t1tables.h @@ -28,6 +28,18 @@ FT_BEGIN_HEADER + /******************************************************************** + * + * <Section> Type1_Tables + * + * <Title> Type 1 Tables + * + * <Abstract> Type 1 (Postscript) specific font tables + * + * <Description> + * This section .... + */ + /* Note that we separate font data in T1_FontInfo and T1_Private */ /* structures in order to support Multiple Master fonts. */