diff --git a/docs/convntns.txt b/docs/convntns.txt index 327f438d6..084138325 100644 --- a/docs/convntns.txt +++ b/docs/convntns.txt @@ -334,7 +334,20 @@ points: FT_Int* pointer; - As mentioned above, multiple declarations are vertically + However, when declaring resp. defining an `output' parameter + (i.e. a pointer which will be assigned by the function), the + last `*' must be placed on the right in order to denote this, as + in: + + FT_New_Face( FT_Library library, + FT_Face *aface ); + + where the `*' is used to indicate that `aface' is returned. In + most cases, the name of such an output variable starts with `a' + or `an' (`aface' instead of `face', `anlru' instead of `lru', + etc.), following the English rules of the indefinite article. + + . As mentioned above, multiple declarations are vertically aligned: FT_Short foo; @@ -359,9 +372,11 @@ points: x = sin( y ); y = sizeof ( long ); - Except for casts, parentheses are surrounded with space: + Except for casts, empty parameters, and the closing semicolon, + parentheses are surrounded with space: x = (char*)( foo + bar ); + y = rand(); . Binary operators are surrounded by spaces; unary operators have no space after it: @@ -379,6 +394,12 @@ points: if ( x = 0; x < y; x++, y-- ) do_something(); + Exception: + + for (;;) + { + ... + . Don't use if ( x == y ) a = b; diff --git a/include/freetype/cache/ftcchunk.h b/include/freetype/cache/ftcchunk.h index afee39e0e..3866659ea 100644 --- a/include/freetype/cache/ftcchunk.h +++ b/include/freetype/cache/ftcchunk.h @@ -185,13 +185,13 @@ FT_EXPORT( FT_Error ) FTC_ChunkSet_New( FTC_Chunk_Cache cache, FT_Pointer type, - FTC_ChunkSet* aset ); + FTC_ChunkSet *aset ); FT_EXPORT( FT_Error ) FTC_ChunkSet_Lookup_Node( FTC_ChunkSet cset, FT_UInt glyph_index, FTC_ChunkNode* anode, - FT_UInt* aindex ); + FT_UInt *anindex ); #ifdef __cplusplus diff --git a/include/freetype/cache/ftcglyph.h b/include/freetype/cache/ftcglyph.h index 6e2383e14..2614c046d 100644 --- a/include/freetype/cache/ftcglyph.h +++ b/include/freetype/cache/ftcglyph.h @@ -189,12 +189,12 @@ FT_EXPORT( FT_Error ) FTC_GlyphSet_New( FTC_Glyph_Cache cache, FT_Pointer type, - FTC_GlyphSet* aset ); + FTC_GlyphSet *aset ); FT_EXPORT( FT_Error ) FTC_GlyphSet_Lookup_Node( FTC_GlyphSet gset, FT_UInt glyph_index, - FTC_GlyphNode* anode ); + FTC_GlyphNode *anode ); #ifdef __cplusplus diff --git a/include/freetype/cache/ftcimage.h b/include/freetype/cache/ftcimage.h index bf5435c12..8c457c734 100644 --- a/include/freetype/cache/ftcimage.h +++ b/include/freetype/cache/ftcimage.h @@ -120,7 +120,7 @@ /* FreeType error code. 0 means success. */ /* */ FT_EXPORT( FT_Error ) FTC_Image_Cache_New( FTC_Manager manager, - FTC_Image_Cache* acache ); + FTC_Image_Cache *acache ); /*************************************************************************/ @@ -157,7 +157,7 @@ FT_EXPORT( FT_Error ) FTC_Image_Cache_Lookup( FTC_Image_Cache cache, FTC_Image_Desc* desc, FT_UInt gindex, - FT_Glyph* aglyph ); + FT_Glyph *aglyph ); #ifdef __cplusplus diff --git a/include/freetype/cache/ftcsbits.h b/include/freetype/cache/ftcsbits.h index 71c28a1e5..a167f694c 100644 --- a/include/freetype/cache/ftcsbits.h +++ b/include/freetype/cache/ftcsbits.h @@ -54,7 +54,7 @@ FT_EXPORT( FT_Error ) FTC_SBit_Cache_New( FTC_Manager manager, - FTC_SBit_Cache* acache ); + FTC_SBit_Cache *acache ); FT_EXPORT( FT_Error ) FTC_SBit_Cache_Lookup( FTC_SBit_Cache cache, FTC_Image_Desc* desc, diff --git a/include/freetype/cache/ftlru.h b/include/freetype/cache/ftlru.h index 25fa3fb0d..d9b2e5f1d 100644 --- a/include/freetype/cache/ftlru.h +++ b/include/freetype/cache/ftlru.h @@ -146,7 +146,7 @@ FT_Pointer user_data, FT_Memory memory, FT_Bool pre_alloc, - FT_Lru* alru ); + FT_Lru *anlru ); FT_EXPORT( void ) FT_Lru_Reset( FT_Lru lru ); @@ -155,11 +155,11 @@ FT_EXPORT( FT_Error ) FT_Lru_Lookup_Node( FT_Lru lru, FT_LruKey key, - FT_LruNode* anode ); + FT_LruNode *anode ); FT_EXPORT( FT_Error ) FT_Lru_Lookup( FT_Lru lru, FT_LruKey key, - FT_Pointer* aobject ); + FT_Pointer *anobject ); FT_EXPORT( void ) FT_Lru_Remove_Node( FT_Lru lru, diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h index cae2fa3c2..f9e44f943 100644 --- a/include/freetype/freetype.h +++ b/include/freetype/freetype.h @@ -1168,12 +1168,12 @@ /* that are registered by this function is determined at build time. */ /* */ /* */ - /* library :: A handle to a new library object. */ + /* alibrary :: A handle to a new library object. */ /* */ /* */ /* FreeType error code. 0 means success. */ /* */ - FT_EXPORT( FT_Error ) FT_Init_FreeType( FT_Library* library ); + FT_EXPORT( FT_Error ) FT_Init_FreeType( FT_Library *alibrary ); /*************************************************************************/ @@ -1349,13 +1349,13 @@ /* FT_New_Face() can be used to determine and/or check the font */ /* format of a given font resource. If the `face_index' field is */ /* negative, the function will _not_ return any face handle in */ - /* `*face'. Its return value should be 0 if the resource is */ + /* `aface'. Its return value should be 0 if the resource is */ /* recognized, or non-zero if not. */ /* */ FT_EXPORT( FT_Error ) FT_New_Face( FT_Library library, const char* filepathname, FT_Long face_index, - FT_Face* face ); + FT_Face *aface ); /*************************************************************************/ @@ -1378,7 +1378,7 @@ /* face_index :: The index of the face within the resource. The */ /* first face has index 0. */ /* */ - /* face :: A handle to a new face object. */ + /* aface :: A handle to a new face object. */ /* */ /* */ /* FreeType error code. 0 means success. */ @@ -1395,14 +1395,14 @@ /* FT_New_Memory_Face() can be used to determine and/or check the */ /* font format of a given font resource. If the `face_index' field */ /* is negative, the function will _not_ return any face handle in */ - /* `*face'. Its return value should be 0 if the resource is */ + /* `aface'. Its return value should be 0 if the resource is */ /* recognized, or non-zero if not. */ /* */ FT_EXPORT( FT_Error ) FT_New_Memory_Face( FT_Library library, FT_Byte* file_base, FT_Long file_size, FT_Long face_index, - FT_Face* face ); + FT_Face *aface ); /*************************************************************************/ @@ -1448,7 +1448,7 @@ FT_EXPORT( FT_Error ) FT_Open_Face( FT_Library library, FT_Open_Args* args, FT_Long face_index, - FT_Face* face ); + FT_Face *aface ); /*************************************************************************/ @@ -1496,9 +1496,10 @@ /* This function is similar to FT_Attach_File() with the exception */ /* that it reads the attachment from an arbitrary stream. */ /* */ - /* */ + /* */ /* face :: The target face object. */ /* */ + /* */ /* parameters :: A pointer to an FT_Open_Args structure used to */ /* describe the input stream to FreeType. */ /* */ @@ -1613,10 +1614,11 @@ /* A function used to load a single glyph within a given glyph slot, */ /* for a given size. */ /* */ - /* */ + /* */ /* face :: A handle to the target face object where the glyph */ /* will be loaded. */ /* */ + /* */ /* glyph_index :: The index of the glyph in the font file. */ /* */ /* load_flags :: A flag indicating what to load for this glyph. The */ @@ -1651,10 +1653,11 @@ /* A function used to load a single glyph within a given glyph slot, */ /* for a given size, according to its character code. */ /* */ - /* */ + /* */ /* face :: A handle to a target face object where the glyph */ /* will be loaded. */ /* */ + /* */ /* char_code :: The glyph's character code, according to the */ /* current charmap used in the face. */ /* */ @@ -1968,10 +1971,11 @@ /* inspecting the glyph image format, find the relevant renderer, and */ /* invoke it. */ /* */ - /* */ + /* */ /* slot :: A handle to the glyph slot containing the image to */ /* convert. */ /* */ + /* */ /* render_mode :: This is the render mode used to render the glyph */ /* image into a bitmap. See FT_Render_Mode for a list */ /* of possible values. */ @@ -2031,7 +2035,7 @@ /* kerning vector. */ /* */ /* */ - /* kerning :: The kerning vector. This is in font units for */ + /* akerning :: The kerning vector. This is in font units for */ /* scalable formats, and in pixels for fixed-sizes */ /* formats. */ /* */ @@ -2048,7 +2052,7 @@ FT_UInt left_glyph, FT_UInt right_glyph, FT_UInt kern_mode, - FT_Vector* kerning ); + FT_Vector *akerning ); /*************************************************************************/ @@ -2065,12 +2069,13 @@ /* */ /* glyph_index :: The glyph index. */ /* */ - /* buffer :: A pointer to a target buffer where the name will be */ - /* copied to. */ - /* */ /* buffer_max :: The maximal number of bytes available in the */ /* buffer. */ /* */ + /* */ + /* buffer :: A pointer to a target buffer where the name will be */ + /* copied to. */ + /* */ /* */ /* FreeType error code. 0 means success. */ /* */ @@ -2101,9 +2106,10 @@ /* Selects a given charmap by its encoding tag (as listed in */ /* `freetype.h'). */ /* */ - /* */ + /* */ /* face :: A handle to the source face object. */ /* */ + /* */ /* encoding :: A handle to the selected charmap. */ /* */ /* */ @@ -2126,8 +2132,10 @@ /* Selects a given charmap for character code to glyph index */ /* decoding. */ /* */ - /* */ + /* */ /* face :: A handle to the source face object. */ + /* */ + /* */ /* charmap :: A handle to the selected charmap. */ /* */ /* */ diff --git a/include/freetype/ftbbox.h b/include/freetype/ftbbox.h index 629e231d7..db73d9f64 100644 --- a/include/freetype/ftbbox.h +++ b/include/freetype/ftbbox.h @@ -53,13 +53,13 @@ /* outline :: A pointer to the source outline. */ /* */ /* */ - /* bbox :: The outline's exact bounding box. */ + /* abbox :: The outline's exact bounding box. */ /* */ /* */ /* FreeType error code. 0 means success. */ /* */ FT_EXPORT( FT_Error ) FT_Outline_Get_BBox( FT_Outline* outline, - FT_BBox* bbox ); + FT_BBox *abbox ); #ifdef __cplusplus diff --git a/include/freetype/ftcache.h b/include/freetype/ftcache.h index fa9529a65..1e701ce18 100644 --- a/include/freetype/ftcache.h +++ b/include/freetype/ftcache.h @@ -200,7 +200,7 @@ FT_ULong max_bytes, FTC_Face_Requester requester, FT_Pointer req_data, - FTC_Manager* amanager ); + FTC_Manager *amanager ); /*************************************************************************/ @@ -212,7 +212,7 @@ /* Empties a given cache manager. This simply gets rid of all the */ /* currently cached FT_Face & FT_Size objects within the manager. */ /* */ - /* */ + /* */ /* manager :: A handle to the manager. */ /* */ FT_EXPORT( void ) FTC_Manager_Reset( FTC_Manager manager ); @@ -266,7 +266,7 @@ /* */ FT_EXPORT( FT_Error ) FTC_Manager_Lookup_Face( FTC_Manager manager, FTC_FaceID face_id, - FT_Face* aface ); + FT_Face *aface ); /*************************************************************************/ @@ -283,7 +283,7 @@ /* */ /* size_id :: The ID of the `font size' to use. */ /* */ - /* */ + /* */ /* aface :: A pointer to the handle of the face object. Set it to */ /* zero if you don't need it. */ /* */ @@ -310,8 +310,8 @@ /* */ FT_EXPORT( FT_Error ) FTC_Manager_Lookup_Size( FTC_Manager manager, FTC_Font font, - FT_Face* aface, - FT_Size* asize ); + FT_Face *aface, + FT_Size *asize ); /* a cache class is used to describe a unique cache type to the manager */ @@ -323,7 +323,7 @@ FT_EXPORT( FT_Error ) FTC_Manager_Register_Cache( FTC_Manager manager, FTC_Cache_Class* clazz, - FTC_Cache* acache ); + FTC_Cache *acache ); #ifdef __cplusplus diff --git a/include/freetype/ftglyph.h b/include/freetype/ftglyph.h index 7aca54f03..d1dfbfdc6 100644 --- a/include/freetype/ftglyph.h +++ b/include/freetype/ftglyph.h @@ -162,7 +162,7 @@ /* FreeType error code. 0 means success. */ /* */ FT_EXPORT( FT_Error ) FT_Get_Glyph( FT_GlyphSlot slot, - FT_Glyph* aglyph ); + FT_Glyph *aglyph ); /*************************************************************************/ @@ -184,7 +184,7 @@ /* FreeType error code. 0 means success. */ /* */ FT_EXPORT( FT_Error ) FT_Glyph_Copy( FT_Glyph source, - FT_Glyph* target ); + FT_Glyph *target ); /*************************************************************************/ @@ -195,9 +195,10 @@ /* */ /* Transforms a glyph image if its format is scalable. */ /* */ - /* */ + /* */ /* glyph :: A handle to the target glyph object. */ /* */ + /* */ /* matrix :: A pointer to a 2x2 matrix to apply. */ /* */ /* delta :: A pointer to a 2d vector to apply. Coordinates are */ @@ -232,7 +233,16 @@ /* FT_Glyph_Get_CBox */ /* */ /* */ - /* Returns the glyph image's bounding box. */ + /* Returns 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 */ + /* which 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. */ /* */ /* */ /* glyph :: A handle to the source glyph object. */ @@ -241,8 +251,8 @@ /* bounding box values. */ /* */ /* */ - /* box :: The glyph bounding box. Coordinates are expressed in */ - /* 1/64th of pixels if it is grid-fitted. */ + /* acbox :: The glyph coordinate bounding box. Coordinates are */ + /* expressed in 1/64th of pixels if it is grid-fitted. */ /* */ /* */ /* Coordinates are relative to the glyph origin, using the Y-upwards */ @@ -281,7 +291,7 @@ /* */ FT_EXPORT( void ) FT_Glyph_Get_CBox( FT_Glyph glyph, FT_UInt bbox_mode, - FT_BBox* cbox ); + FT_BBox *acbox ); /*************************************************************************/ @@ -293,7 +303,7 @@ /* Converts a given glyph object to a bitmap glyph object. */ /* */ /* */ - /* glyph :: A pointer to a handle to the target glyph. */ + /* the_glyph :: A pointer to a handle to the target glyph. */ /* */ /* */ /* render_mode :: A set of bit flags that describe how the data is */ diff --git a/include/freetype/ftmac.h b/include/freetype/ftmac.h index 466458862..42f1c0346 100644 --- a/include/freetype/ftmac.h +++ b/include/freetype/ftmac.h @@ -67,7 +67,7 @@ FT_Library library, Handle fond, FT_Long face_index, - FT_Face* aface ); + FT_Face *aface ); #ifdef __cplusplus @@ -76,3 +76,6 @@ #endif /* FT_MAC_H */ + + +/* END */ diff --git a/include/freetype/ftmm.h b/include/freetype/ftmm.h index 3d92c8289..6c9b1dca6 100644 --- a/include/freetype/ftmm.h +++ b/include/freetype/ftmm.h @@ -100,16 +100,16 @@ /* Retrieves the Multiple Master descriptor of a given font. */ /* */ /* */ - /* face :: A handle to the source face. */ + /* face :: A handle to the source face. */ /* */ /* */ - /* master :: The Multiple Masters descriptor. */ + /* amaster :: The Multiple Masters descriptor. */ /* */ /* */ /* FreeType error code. 0 means success. */ /* */ FT_EXPORT( FT_Error ) FT_Get_Multi_Master( FT_Face face, - FT_Multi_Master* master ); + FT_Multi_Master *amaster ); /*************************************************************************/ @@ -121,13 +121,14 @@ /* For Multiple Masters fonts, choose an interpolated font design */ /* through design coordinates. */ /* */ - /* */ + /* */ /* face :: A handle to the source face. */ /* */ + /* */ /* num_coords :: The number of design coordinates (must be equal to */ /* the number of axes in the font). */ /* */ - /* coords :: The design coordinates. */ + /* coords :: An array of design coordinates. */ /* */ /* */ /* FreeType error code. 0 means success. */ @@ -147,14 +148,15 @@ /* For Multiple Masters fonts, choose an interpolated font design */ /* through normalized blend coordinates. */ /* */ - /* */ + /* */ /* face :: A handle to the source face. */ /* */ + /* */ /* num_coords :: The number of design coordinates (must be equal to */ /* the number of axes in the font). */ /* */ - /* coords :: The design coordinates (each one must be between 0 */ - /* and 1.0). */ + /* coords :: The design coordinates array (each element must be */ + /* between 0 and 1.0). */ /* */ /* */ /* FreeType error code. 0 means success. */ diff --git a/include/freetype/ftmodule.h b/include/freetype/ftmodule.h index f8d32519e..055278311 100644 --- a/include/freetype/ftmodule.h +++ b/include/freetype/ftmodule.h @@ -111,9 +111,10 @@ /* */ /* Adds a new module to a given library instance. */ /* */ - /* */ + /* */ /* library :: A handle to the library object. */ /* */ + /* */ /* clazz :: A pointer to class descriptor for the module. */ /* */ /* */ @@ -159,9 +160,10 @@ /* */ /* Removes a given module from a library instance. */ /* */ - /* */ + /* */ /* library :: A handle to a library object. */ /* */ + /* */ /* module :: A handle to a module object. */ /* */ /* */ @@ -194,7 +196,7 @@ /* FreeType error code. 0 means success. */ /* */ FT_EXPORT( FT_Error ) FT_New_Library( FT_Memory memory, - FT_Library* library ); + FT_Library *alibrary ); /*************************************************************************/ @@ -228,9 +230,10 @@ /* Sets a debug hook function for debugging the interpreter of a font */ /* format. */ /* */ - /* */ + /* */ /* library :: A handle to the library object. */ /* */ + /* */ /* hook_index :: The index of the debug hook. You should use the */ /* values defined in ftobjs.h, e.g. */ /* FT_DEBUG_HOOK_TRUETYPE */ diff --git a/include/freetype/ftnames.h b/include/freetype/ftnames.h index 21abdeec7..87517e181 100644 --- a/include/freetype/ftnames.h +++ b/include/freetype/ftnames.h @@ -118,7 +118,7 @@ /* */ FT_EXPORT( FT_Error ) FT_Get_Sfnt_Name( FT_Face face, FT_UInt index, - FT_SfntName* aname ); + FT_SfntName *aname ); #ifdef __cplusplus diff --git a/include/freetype/ftoutln.h b/include/freetype/ftoutln.h index 2862da938..8010e1b71 100644 --- a/include/freetype/ftoutln.h +++ b/include/freetype/ftoutln.h @@ -45,6 +45,7 @@ /* interface :: A table of `emitters', i.e,. function pointers called */ /* during decomposition to indicate path operations. */ /* */ + /* */ /* user :: A typeless pointer which is passed to each emitter */ /* during the decomposition. It can be used to store */ /* the state during the decomposition. */ @@ -77,7 +78,7 @@ /* numContours :: The maximal number of contours within the outline. */ /* */ /* */ - /* outline :: A handle to the new outline. NULL in case of */ + /* anoutline :: A handle to the new outline. NULL in case of */ /* error. */ /* */ /* */ @@ -93,14 +94,14 @@ FT_EXPORT( FT_Error ) FT_Outline_New( FT_Library library, FT_UInt numPoints, FT_Int numContours, - FT_Outline* outline ); + FT_Outline *anoutline ); FT_EXPORT( FT_Error ) FT_Outline_New_Internal( FT_Memory memory, FT_UInt numPoints, FT_Int numContours, - FT_Outline* outline ); + FT_Outline *anoutline ); /*************************************************************************/ @@ -127,7 +128,7 @@ /* If the outline's `owner' field is not set, only the outline */ /* descriptor will be released. */ /* */ - /* The reason why this function takes an `outline' parameter is */ + /* The reason why this function takes an `library' parameter is */ /* simply to use FT_Free(). */ /* */ FT_EXPORT( FT_Error ) FT_Outline_Done( FT_Library library, @@ -159,13 +160,13 @@ /* outline :: A pointer to the source outline descriptor. */ /* */ /* */ - /* cbox :: The outline's control box. */ + /* acbox :: The outline's control box. */ /* */ /* */ /* Yes. */ /* */ FT_EXPORT( void ) FT_Outline_Get_CBox( FT_Outline* outline, - FT_BBox* cbox ); + FT_BBox *acbox ); /*************************************************************************/ @@ -176,9 +177,10 @@ /* */ /* Applies a simple translation to the points of an outline. */ /* */ - /* */ + /* */ /* outline :: A pointer to the target outline descriptor. */ /* */ + /* */ /* xOffset :: The horizontal offset. */ /* */ /* yOffset :: The vertical offset. */ @@ -211,7 +213,7 @@ /* FreeType error code. 0 means success. */ /* */ FT_EXPORT( FT_Error ) FT_Outline_Copy( FT_Outline* source, - FT_Outline* target ); + FT_Outline *target ); /*************************************************************************/ @@ -247,7 +249,7 @@ /* Reverses the drawing direction of an outline. This is used to */ /* ensure consistent fill conventions for mirrored glyphs. */ /* */ - /* */ + /* */ /* outline :: A pointer to the target outline descriptor. */ /* */ /* */ @@ -274,7 +276,8 @@ /* */ /* outline :: A pointer to the source outline descriptor. */ /* */ - /* map :: A pointer to the target bitmap descriptor. */ + /* */ + /* abitmap :: A pointer to the target bitmap descriptor. */ /* */ /* */ /* FreeType error code. 0 means success. */ @@ -291,7 +294,7 @@ /* */ FT_EXPORT( FT_Error ) FT_Outline_Get_Bitmap( FT_Library library, FT_Outline* outline, - FT_Bitmap* bitmap ); + FT_Bitmap *abitmap ); /*************************************************************************/ @@ -310,6 +313,7 @@ /* */ /* outline :: A pointer to the source outline descriptor. */ /* */ + /* */ /* params :: A pointer to a FT_Raster_Params structure used to */ /* describe the rendering operation. */ /* */ diff --git a/include/freetype/ftrender.h b/include/freetype/ftrender.h index a92bc2bf2..aab57a738 100644 --- a/include/freetype/ftrender.h +++ b/include/freetype/ftrender.h @@ -156,9 +156,10 @@ /* */ /* Sets the current renderer to use, and set additional mode. */ /* */ - /* */ + /* */ /* library :: A handle to the library object. */ /* */ + /* */ /* renderer :: A handle to the renderer object. */ /* */ /* num_params :: The number of additional parameters. */ diff --git a/include/freetype/internal/ftcalc.h b/include/freetype/internal/ftcalc.h index 382c33851..2b1745a36 100644 --- a/include/freetype/internal/ftcalc.h +++ b/include/freetype/internal/ftcalc.h @@ -62,11 +62,11 @@ FT_EXPORT( void ) FT_Add64( FT_Int64* x, FT_Int64* y, - FT_Int64* z ); + FT_Int64 *z ); FT_EXPORT( void ) FT_MulTo64( FT_Int32 x, FT_Int32 y, - FT_Int64* z ); + FT_Int64 *z ); FT_EXPORT( FT_Int32 ) FT_Div64by32( FT_Int64* x, FT_Int32 y );