ref: 3a40847c60d489b15b351730c8947c92f42ecae3
parent: 8c883fb542a275f8421c899e0c3ea2f7a96d806c
author: Werner Lemberg <[email protected]>
date: Sun Nov 5 23:33:56 EST 2000
Added/restored the `*' convention for output parameters. Some documentation fixes.
--- a/docs/convntns.txt
+++ b/docs/convntns.txt
@@ -334,7 +334,20 @@
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 @@
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:
@@ -378,6 +393,12 @@
if ( x = 0; x < y; x++, y-- )
do_something();
+
+ Exception:
+
+ for (;;)
+ {+ ...
. Don't use
--- 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
--- 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
--- 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
--- 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,
--- 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,
--- 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. */
/* */
/* <Output> */
- /* library :: A handle to a new library object. */
+ /* alibrary :: A handle to a new library object. */
/* */
/* <Return> */
/* 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. */
/* <Output> */
- /* face :: A handle to a new face object. */
+ /* aface :: A handle to a new face object. */
/* */
/* <Return> */
/* FreeType error code. 0 means success. */
@@ -1395,7 +1395,7 @@
/* 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,
@@ -1402,7 +1402,7 @@
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. */
/* */
- /* <Input> */
+ /* <InOut> */
/* face :: The target face object. */
/* */
+ /* <Input> */
/* parameters :: A pointer to an FT_Open_Args structure used to */
/* describe the input stream to FreeType. */
/* <Return> */
@@ -1613,10 +1614,11 @@
/* A function used to load a single glyph within a given glyph slot, */
/* for a given size. */
/* */
- /* <Input> */
+ /* <InOut> */
/* face :: A handle to the target face object where the glyph */
/* will be loaded. */
/* */
+ /* <Input> */
/* 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. */
/* */
- /* <Input> */
+ /* <InOut> */
/* face :: A handle to a target face object where the glyph */
/* will be loaded. */
/* */
+ /* <Input> */
/* 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. */
/* */
- /* <Input> */
+ /* <InOut> */
/* slot :: A handle to the glyph slot containing the image to */
/* convert. */
/* */
+ /* <Input> */
/* 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. */
/* */
/* <Output> */
- /* 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. */
/* */
+ /* <Output> */
+ /* buffer :: A pointer to a target buffer where the name will be */
+ /* copied to. */
+ /* */
/* <Return> */
/* FreeType error code. 0 means success. */
/* */
@@ -2101,9 +2106,10 @@
/* Selects a given charmap by its encoding tag (as listed in */
/* `freetype.h'). */
/* */
- /* <Input> */
+ /* <InOut> */
/* face :: A handle to the source face object. */
/* */
+ /* <Input> */
/* encoding :: A handle to the selected charmap. */
/* */
/* <Return> */
@@ -2126,8 +2132,10 @@
/* Selects a given charmap for character code to glyph index */
/* decoding. */
/* */
- /* <Input> */
+ /* <InOut> */
/* face :: A handle to the source face object. */
+ /* */
+ /* <Input> */
/* charmap :: A handle to the selected charmap. */
/* */
/* <Return> */
--- a/include/freetype/ftbbox.h
+++ b/include/freetype/ftbbox.h
@@ -53,13 +53,13 @@
/* outline :: A pointer to the source outline. */
/* */
/* <Output> */
- /* bbox :: The outline's exact bounding box. */
+ /* abbox :: The outline's exact bounding box. */
/* */
/* <Return> */
/* 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
--- 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. */
/* */
- /* <Input> */
+ /* <InOut> */
/* 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. */
/* */
- /* <InOut> */
+ /* <Output> */
/* 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
--- 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 @@
/* <Description> */
/* Transforms a glyph image if its format is scalable. */
/* */
- /* <Input> */
+ /* <InOut> */
/* glyph :: A handle to the target glyph object. */
/* */
+ /* <Input> */
/* matrix :: A pointer to a 2x2 matrix to apply. */
/* */
/* delta :: A pointer to a 2d vector to apply. Coordinates are */
@@ -232,8 +233,17 @@
/* FT_Glyph_Get_CBox */
/* */
/* <Description> */
- /* 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. */
+ /* */
/* <Input> */
/* glyph :: A handle to the source glyph object. */
/* */
@@ -241,8 +251,8 @@
/* bounding box values. */
/* */
/* <Output> */
- /* 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. */
/* */
/* <Note> */
/* 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. */
/* */
/* <InOut> */
- /* glyph :: A pointer to a handle to the target glyph. */
+ /* the_glyph :: A pointer to a handle to the target glyph. */
/* */
/* <Input> */
/* render_mode :: A set of bit flags that describe how the data is */
--- 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 */
--- a/include/freetype/ftmm.h
+++ b/include/freetype/ftmm.h
@@ -100,16 +100,16 @@
/* Retrieves the Multiple Master descriptor of a given font. */
/* */
/* <Input> */
- /* face :: A handle to the source face. */
+ /* face :: A handle to the source face. */
/* */
/* <Output> */
- /* master :: The Multiple Masters descriptor. */
+ /* amaster :: The Multiple Masters descriptor. */
/* */
/* <Return> */
/* 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. */
/* */
- /* <Input> */
+ /* <InOut> */
/* face :: A handle to the source face. */
/* */
+ /* <Input> */
/* 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. */
/* */
/* <Return> */
/* FreeType error code. 0 means success. */
@@ -147,14 +148,15 @@
/* For Multiple Masters fonts, choose an interpolated font design */
/* through normalized blend coordinates. */
/* */
- /* <Input> */
+ /* <InOut> */
/* face :: A handle to the source face. */
/* */
+ /* <Input> */
/* 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). */
/* */
/* <Return> */
/* FreeType error code. 0 means success. */
--- a/include/freetype/ftmodule.h
+++ b/include/freetype/ftmodule.h
@@ -111,9 +111,10 @@
/* <Description> */
/* Adds a new module to a given library instance. */
/* */
- /* <Input> */
+ /* <InOut> */
/* library :: A handle to the library object. */
/* */
+ /* <Input> */
/* clazz :: A pointer to class descriptor for the module. */
/* */
/* <Return> */
@@ -159,9 +160,10 @@
/* <Description> */
/* Removes a given module from a library instance. */
/* */
- /* <Input> */
+ /* <InOut> */
/* library :: A handle to a library object. */
/* */
+ /* <Input> */
/* module :: A handle to a module object. */
/* */
/* <Return> */
@@ -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. */
/* */
- /* <Input> */
+ /* <InOut> */
/* library :: A handle to the library object. */
/* */
+ /* <Input> */
/* hook_index :: The index of the debug hook. You should use the */
/* values defined in ftobjs.h, e.g. */
/* FT_DEBUG_HOOK_TRUETYPE */
--- 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
--- 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. */
/* */
+ /* <InOut> */
/* 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. */
/* */
/* <Output> */
- /* outline :: A handle to the new outline. NULL in case of */
+ /* anoutline :: A handle to the new outline. NULL in case of */
/* error. */
/* */
/* <Return> */
@@ -93,7 +94,7 @@
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(
@@ -100,7 +101,7 @@
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. */
/* */
/* <Output> */
- /* cbox :: The outline's control box. */
+ /* acbox :: The outline's control box. */
/* */
/* <MT-Note> */
/* Yes. */
/* */
FT_EXPORT( void ) FT_Outline_Get_CBox( FT_Outline* outline,
- FT_BBox* cbox );
+ FT_BBox *acbox );
/*************************************************************************/
@@ -176,9 +177,10 @@
/* <Description> */
/* Applies a simple translation to the points of an outline. */
/* */
- /* <Input> */
+ /* <InOut> */
/* outline :: A pointer to the target outline descriptor. */
/* */
+ /* <Input> */
/* 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. */
/* */
- /* <Input> */
+ /* <InOut> */
/* outline :: A pointer to the target outline descriptor. */
/* */
/* <Note> */
@@ -274,7 +276,8 @@
/* */
/* outline :: A pointer to the source outline descriptor. */
/* */
- /* map :: A pointer to the target bitmap descriptor. */
+ /* <Output> */
+ /* abitmap :: A pointer to the target bitmap descriptor. */
/* */
/* <Return> */
/* 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. */
/* */
+ /* <InOut> */
/* params :: A pointer to a FT_Raster_Params structure used to */
/* describe the rendering operation. */
/* */
--- a/include/freetype/ftrender.h
+++ b/include/freetype/ftrender.h
@@ -156,9 +156,10 @@
/* <Description> */
/* Sets the current renderer to use, and set additional mode. */
/* */
- /* <Input> */
+ /* <InOut> */
/* library :: A handle to the library object. */
/* */
+ /* <Input> */
/* renderer :: A handle to the renderer object. */
/* */
/* num_params :: The number of additional parameters. */
--- 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 );