00001 /***************************************************************************/ 00002 /* */ 00003 /* ftglyph.h */ 00004 /* */ 00005 /* FreeType convenience functions to handle glyphs (specification). */ 00006 /* */ 00007 /* Copyright 1996-2001, 2002, 2003, 2006, 2008, 2009 by */ 00008 /* David Turner, Robert Wilhelm, and Werner Lemberg. */ 00009 /* */ 00010 /* This file is part of the FreeType project, and may only be used, */ 00011 /* modified, and distributed under the terms of the FreeType project */ 00012 /* license, LICENSE.TXT. By continuing to use, modify, or distribute */ 00013 /* this file you indicate that you have read the license and */ 00014 /* understand and accept it fully. */ 00015 /* */ 00016 /***************************************************************************/ 00017 00018 00019 /*************************************************************************/ 00020 /* */ 00021 /* This file contains the definition of several convenience functions */ 00022 /* that can be used by client applications to easily retrieve glyph */ 00023 /* bitmaps and outlines from a given face. */ 00024 /* */ 00025 /* These functions should be optional if you are writing a font server */ 00026 /* or text layout engine on top of FreeType. However, they are pretty */ 00027 /* handy for many other simple uses of the library. */ 00028 /* */ 00029 /*************************************************************************/ 00030 00031 00032 #ifndef __FTGLYPH_H__ 00033 #define __FTGLYPH_H__ 00034 00035 00036 #include <ft2build.h> 00037 #include FT_FREETYPE_H 00038 00039 #ifdef FREETYPE_H 00040 #error "freetype.h of FreeType 1 has been loaded!" 00041 #error "Please fix the directory search order for header files" 00042 #error "so that freetype.h of FreeType 2 is found first." 00043 #endif 00044 00045 00046 FT_BEGIN_HEADER 00047 00048 00049 /*************************************************************************/ 00050 /* */ 00051 /* <Section> */ 00052 /* glyph_management */ 00053 /* */ 00054 /* <Title> */ 00055 /* Glyph Management */ 00056 /* */ 00057 /* <Abstract> */ 00058 /* Generic interface to manage individual glyph data. */ 00059 /* */ 00060 /* <Description> */ 00061 /* This section contains definitions used to manage glyph data */ 00062 /* through generic FT_Glyph objects. Each of them can contain a */ 00063 /* bitmap, a vector outline, or even images in other formats. */ 00064 /* */ 00065 /*************************************************************************/ 00066 00067 00068 /* forward declaration to a private type */ 00069 typedef struct FT_Glyph_Class_ FT_Glyph_Class; 00070 00071 00072 /*************************************************************************/ 00073 /* */ 00074 /* <Type> */ 00075 /* FT_Glyph */ 00076 /* */ 00077 /* <Description> */ 00078 /* Handle to an object used to model generic glyph images. It is a */ 00079 /* pointer to the @FT_GlyphRec structure and can contain a glyph */ 00080 /* bitmap or pointer. */ 00081 /* */ 00082 /* <Note> */ 00083 /* Glyph objects are not owned by the library. You must thus release */ 00084 /* them manually (through @FT_Done_Glyph) _before_ calling */ 00085 /* @FT_Done_FreeType. */ 00086 /* */ 00087 typedef struct FT_GlyphRec_* FT_Glyph; 00088 00089 00090 /*************************************************************************/ 00091 /* */ 00092 /* <Struct> */ 00093 /* FT_GlyphRec */ 00094 /* */ 00095 /* <Description> */ 00096 /* The root glyph structure contains a given glyph image plus its */ 00097 /* advance width in 16.16 fixed float format. */ 00098 /* */ 00099 /* <Fields> */ 00100 /* library :: A handle to the FreeType library object. */ 00101 /* */ 00102 /* clazz :: A pointer to the glyph's class. Private. */ 00103 /* */ 00104 /* format :: The format of the glyph's image. */ 00105 /* */ 00106 /* advance :: A 16.16 vector that gives the glyph's advance width. */ 00107 /* */ 00108 typedef struct FT_GlyphRec_ 00109 { 00110 FT_Library library; 00111 const FT_Glyph_Class* clazz; 00112 FT_Glyph_Format format; 00113 FT_Vector advance; 00114 00115 } FT_GlyphRec; 00116 00117 00118 /*************************************************************************/ 00119 /* */ 00120 /* <Type> */ 00121 /* FT_BitmapGlyph */ 00122 /* */ 00123 /* <Description> */ 00124 /* A handle to an object used to model a bitmap glyph image. This is */ 00125 /* a sub-class of @FT_Glyph, and a pointer to @FT_BitmapGlyphRec. */ 00126 /* */ 00127 typedef struct FT_BitmapGlyphRec_* FT_BitmapGlyph; 00128 00129 00130 /*************************************************************************/ 00131 /* */ 00132 /* <Struct> */ 00133 /* FT_BitmapGlyphRec */ 00134 /* */ 00135 /* <Description> */ 00136 /* A structure used for bitmap glyph images. This really is a */ 00137 /* `sub-class' of @FT_GlyphRec. */ 00138 /* */ 00139 /* <Fields> */ 00140 /* root :: The root @FT_Glyph fields. */ 00141 /* */ 00142 /* left :: The left-side bearing, i.e., the horizontal distance */ 00143 /* from the current pen position to the left border of the */ 00144 /* glyph bitmap. */ 00145 /* */ 00146 /* top :: The top-side bearing, i.e., the vertical distance from */ 00147 /* the current pen position to the top border of the glyph */ 00148 /* bitmap. This distance is positive for upwards~y! */ 00149 /* */ 00150 /* bitmap :: A descriptor for the bitmap. */ 00151 /* */ 00152 /* <Note> */ 00153 /* You can typecast an @FT_Glyph to @FT_BitmapGlyph if you have */ 00154 /* `glyph->format == FT_GLYPH_FORMAT_BITMAP'. This lets you access */ 00155 /* the bitmap's contents easily. */ 00156 /* */ 00157 /* The corresponding pixel buffer is always owned by @FT_BitmapGlyph */ 00158 /* and is thus created and destroyed with it. */ 00159 /* */ 00160 typedef struct FT_BitmapGlyphRec_ 00161 { 00162 FT_GlyphRec root; 00163 FT_Int left; 00164 FT_Int top; 00165 FT_Bitmap bitmap; 00166 00167 } FT_BitmapGlyphRec; 00168 00169 00170 /*************************************************************************/ 00171 /* */ 00172 /* <Type> */ 00173 /* FT_OutlineGlyph */ 00174 /* */ 00175 /* <Description> */ 00176 /* A handle to an object used to model an outline glyph image. This */ 00177 /* is a sub-class of @FT_Glyph, and a pointer to @FT_OutlineGlyphRec. */ 00178 /* */ 00179 typedef struct FT_OutlineGlyphRec_* FT_OutlineGlyph; 00180 00181 00182 /*************************************************************************/ 00183 /* */ 00184 /* <Struct> */ 00185 /* FT_OutlineGlyphRec */ 00186 /* */ 00187 /* <Description> */ 00188 /* A structure used for outline (vectorial) glyph images. This */ 00189 /* really is a `sub-class' of @FT_GlyphRec. */ 00190 /* */ 00191 /* <Fields> */ 00192 /* root :: The root @FT_Glyph fields. */ 00193 /* */ 00194 /* outline :: A descriptor for the outline. */ 00195 /* */ 00196 /* <Note> */ 00197 /* You can typecast an @FT_Glyph to @FT_OutlineGlyph if you have */ 00198 /* `glyph->format == FT_GLYPH_FORMAT_OUTLINE'. This lets you access */ 00199 /* the outline's content easily. */ 00200 /* */ 00201 /* As the outline is extracted from a glyph slot, its coordinates are */ 00202 /* expressed normally in 26.6 pixels, unless the flag */ 00203 /* @FT_LOAD_NO_SCALE was used in @FT_Load_Glyph() or @FT_Load_Char(). */ 00204 /* */ 00205 /* The outline's tables are always owned by the object and are */ 00206 /* destroyed with it. */ 00207 /* */ 00208 typedef struct FT_OutlineGlyphRec_ 00209 { 00210 FT_GlyphRec root; 00211 FT_Outline outline; 00212 00213 } FT_OutlineGlyphRec; 00214 00215 00216 /*************************************************************************/ 00217 /* */ 00218 /* <Function> */ 00219 /* FT_Get_Glyph */ 00220 /* */ 00221 /* <Description> */ 00222 /* A function used to extract a glyph image from a slot. Note that */ 00223 /* the created @FT_Glyph object must be released with @FT_Done_Glyph. */ 00224 /* */ 00225 /* <Input> */ 00226 /* slot :: A handle to the source glyph slot. */ 00227 /* */ 00228 /* <Output> */ 00229 /* aglyph :: A handle to the glyph object. */ 00230 /* */ 00231 /* <Return> */ 00232 /* FreeType error code. 0~means success. */ 00233 /* */ 00234 FT_EXPORT( FT_Error ) 00235 FT_Get_Glyph( FT_GlyphSlot slot, 00236 FT_Glyph *aglyph ); 00237 00238 00239 /*************************************************************************/ 00240 /* */ 00241 /* <Function> */ 00242 /* FT_Glyph_Copy */ 00243 /* */ 00244 /* <Description> */ 00245 /* A function used to copy a glyph image. Note that the created */ 00246 /* @FT_Glyph object must be released with @FT_Done_Glyph. */ 00247 /* */ 00248 /* <Input> */ 00249 /* source :: A handle to the source glyph object. */ 00250 /* */ 00251 /* <Output> */ 00252 /* target :: A handle to the target glyph object. 0~in case of */ 00253 /* error. */ 00254 /* */ 00255 /* <Return> */ 00256 /* FreeType error code. 0~means success. */ 00257 /* */ 00258 FT_EXPORT( FT_Error ) 00259 FT_Glyph_Copy( FT_Glyph source, 00260 FT_Glyph *target ); 00261 00262 00263 /*************************************************************************/ 00264 /* */ 00265 /* <Function> */ 00266 /* FT_Glyph_Transform */ 00267 /* */ 00268 /* <Description> */ 00269 /* Transform a glyph image if its format is scalable. */ 00270 /* */ 00271 /* <InOut> */ 00272 /* glyph :: A handle to the target glyph object. */ 00273 /* */ 00274 /* <Input> */ 00275 /* matrix :: A pointer to a 2x2 matrix to apply. */ 00276 /* */ 00277 /* delta :: A pointer to a 2d vector to apply. Coordinates are */ 00278 /* expressed in 1/64th of a pixel. */ 00279 /* */ 00280 /* <Return> */ 00281 /* FreeType error code (if not 0, the glyph format is not scalable). */ 00282 /* */ 00283 /* <Note> */ 00284 /* The 2x2 transformation matrix is also applied to the glyph's */ 00285 /* advance vector. */ 00286 /* */ 00287 FT_EXPORT( FT_Error ) 00288 FT_Glyph_Transform( FT_Glyph glyph, 00289 FT_Matrix* matrix, 00290 FT_Vector* delta ); 00291 00292 00293 /*************************************************************************/ 00294 /* */ 00295 /* <Enum> */ 00296 /* FT_Glyph_BBox_Mode */ 00297 /* */ 00298 /* <Description> */ 00299 /* The mode how the values of @FT_Glyph_Get_CBox are returned. */ 00300 /* */ 00301 /* <Values> */ 00302 /* FT_GLYPH_BBOX_UNSCALED :: */ 00303 /* Return unscaled font units. */ 00304 /* */ 00305 /* FT_GLYPH_BBOX_SUBPIXELS :: */ 00306 /* Return unfitted 26.6 coordinates. */ 00307 /* */ 00308 /* FT_GLYPH_BBOX_GRIDFIT :: */ 00309 /* Return grid-fitted 26.6 coordinates. */ 00310 /* */ 00311 /* FT_GLYPH_BBOX_TRUNCATE :: */ 00312 /* Return coordinates in integer pixels. */ 00313 /* */ 00314 /* FT_GLYPH_BBOX_PIXELS :: */ 00315 /* Return grid-fitted pixel coordinates. */ 00316 /* */ 00317 typedef enum FT_Glyph_BBox_Mode_ 00318 { 00319 FT_GLYPH_BBOX_UNSCALED = 0, 00320 FT_GLYPH_BBOX_SUBPIXELS = 0, 00321 FT_GLYPH_BBOX_GRIDFIT = 1, 00322 FT_GLYPH_BBOX_TRUNCATE = 2, 00323 FT_GLYPH_BBOX_PIXELS = 3 00324 00325 } FT_Glyph_BBox_Mode; 00326 00327 00328 /*************************************************************************/ 00329 /* */ 00330 /* <Enum> */ 00331 /* ft_glyph_bbox_xxx */ 00332 /* */ 00333 /* <Description> */ 00334 /* These constants are deprecated. Use the corresponding */ 00335 /* @FT_Glyph_BBox_Mode values instead. */ 00336 /* */ 00337 /* <Values> */ 00338 /* ft_glyph_bbox_unscaled :: See @FT_GLYPH_BBOX_UNSCALED. */ 00339 /* ft_glyph_bbox_subpixels :: See @FT_GLYPH_BBOX_SUBPIXELS. */ 00340 /* ft_glyph_bbox_gridfit :: See @FT_GLYPH_BBOX_GRIDFIT. */ 00341 /* ft_glyph_bbox_truncate :: See @FT_GLYPH_BBOX_TRUNCATE. */ 00342 /* ft_glyph_bbox_pixels :: See @FT_GLYPH_BBOX_PIXELS. */ 00343 /* */ 00344 #define ft_glyph_bbox_unscaled FT_GLYPH_BBOX_UNSCALED 00345 #define ft_glyph_bbox_subpixels FT_GLYPH_BBOX_SUBPIXELS 00346 #define ft_glyph_bbox_gridfit FT_GLYPH_BBOX_GRIDFIT 00347 #define ft_glyph_bbox_truncate FT_GLYPH_BBOX_TRUNCATE 00348 #define ft_glyph_bbox_pixels FT_GLYPH_BBOX_PIXELS 00349 00350 00351 /*************************************************************************/ 00352 /* */ 00353 /* <Function> */ 00354 /* FT_Glyph_Get_CBox */ 00355 /* */ 00356 /* <Description> */ 00357 /* Return a glyph's `control box'. The control box encloses all the */ 00358 /* outline's points, including Bézier control points. Though it */ 00359 /* coincides with the exact bounding box for most glyphs, it can be */ 00360 /* slightly larger in some situations (like when rotating an outline */ 00361 /* which contains Bézier outside arcs). */ 00362 /* */ 00363 /* Computing the control box is very fast, while getting the bounding */ 00364 /* box can take much more time as it needs to walk over all segments */ 00365 /* and arcs in the outline. To get the latter, you can use the */ 00366 /* `ftbbox' component which is dedicated to this single task. */ 00367 /* */ 00368 /* <Input> */ 00369 /* glyph :: A handle to the source glyph object. */ 00370 /* */ 00371 /* mode :: The mode which indicates how to interpret the returned */ 00372 /* bounding box values. */ 00373 /* */ 00374 /* <Output> */ 00375 /* acbox :: The glyph coordinate bounding box. Coordinates are */ 00376 /* expressed in 1/64th of pixels if it is grid-fitted. */ 00377 /* */ 00378 /* <Note> */ 00379 /* Coordinates are relative to the glyph origin, using the y~upwards */ 00380 /* convention. */ 00381 /* */ 00382 /* If the glyph has been loaded with @FT_LOAD_NO_SCALE, `bbox_mode' */ 00383 /* must be set to @FT_GLYPH_BBOX_UNSCALED to get unscaled font */ 00384 /* units in 26.6 pixel format. The value @FT_GLYPH_BBOX_SUBPIXELS */ 00385 /* is another name for this constant. */ 00386 /* */ 00387 /* Note that the maximum coordinates are exclusive, which means that */ 00388 /* one can compute the width and height of the glyph image (be it in */ 00389 /* integer or 26.6 pixels) as: */ 00390 /* */ 00391 /* { */ 00392 /* width = bbox.xMax - bbox.xMin; */ 00393 /* height = bbox.yMax - bbox.yMin; */ 00394 /* } */ 00395 /* */ 00396 /* Note also that for 26.6 coordinates, if `bbox_mode' is set to */ 00397 /* @FT_GLYPH_BBOX_GRIDFIT, the coordinates will also be grid-fitted, */ 00398 /* which corresponds to: */ 00399 /* */ 00400 /* { */ 00401 /* bbox.xMin = FLOOR(bbox.xMin); */ 00402 /* bbox.yMin = FLOOR(bbox.yMin); */ 00403 /* bbox.xMax = CEILING(bbox.xMax); */ 00404 /* bbox.yMax = CEILING(bbox.yMax); */ 00405 /* } */ 00406 /* */ 00407 /* To get the bbox in pixel coordinates, set `bbox_mode' to */ 00408 /* @FT_GLYPH_BBOX_TRUNCATE. */ 00409 /* */ 00410 /* To get the bbox in grid-fitted pixel coordinates, set `bbox_mode' */ 00411 /* to @FT_GLYPH_BBOX_PIXELS. */ 00412 /* */ 00413 FT_EXPORT( void ) 00414 FT_Glyph_Get_CBox( FT_Glyph glyph, 00415 FT_UInt bbox_mode, 00416 FT_BBox *acbox ); 00417 00418 00419 /*************************************************************************/ 00420 /* */ 00421 /* <Function> */ 00422 /* FT_Glyph_To_Bitmap */ 00423 /* */ 00424 /* <Description> */ 00425 /* Convert a given glyph object to a bitmap glyph object. */ 00426 /* */ 00427 /* <InOut> */ 00428 /* the_glyph :: A pointer to a handle to the target glyph. */ 00429 /* */ 00430 /* <Input> */ 00431 /* render_mode :: An enumeration that describes how the data is */ 00432 /* rendered. */ 00433 /* */ 00434 /* origin :: A pointer to a vector used to translate the glyph */ 00435 /* image before rendering. Can be~0 (if no */ 00436 /* translation). The origin is expressed in */ 00437 /* 26.6 pixels. */ 00438 /* */ 00439 /* destroy :: A boolean that indicates that the original glyph */ 00440 /* image should be destroyed by this function. It is */ 00441 /* never destroyed in case of error. */ 00442 /* */ 00443 /* <Return> */ 00444 /* FreeType error code. 0~means success. */ 00445 /* */ 00446 /* <Note> */ 00447 /* This function does nothing if the glyph format isn't scalable. */ 00448 /* */ 00449 /* The glyph image is translated with the `origin' vector before */ 00450 /* rendering. */ 00451 /* */ 00452 /* The first parameter is a pointer to an @FT_Glyph handle, that will */ 00453 /* be _replaced_ by this function (with newly allocated data). */ 00454 /* Typically, you would use (omitting error handling): */ 00455 /* */ 00456 /* */ 00457 /* { */ 00458 /* FT_Glyph glyph; */ 00459 /* FT_BitmapGlyph glyph_bitmap; */ 00460 /* */ 00461 /* */ 00462 /* // load glyph */ 00463 /* error = FT_Load_Char( face, glyph_index, FT_LOAD_DEFAUT ); */ 00464 /* */ 00465 /* // extract glyph image */ 00466 /* error = FT_Get_Glyph( face->glyph, &glyph ); */ 00467 /* */ 00468 /* // convert to a bitmap (default render mode + destroying old) */ 00469 /* if ( glyph->format != FT_GLYPH_FORMAT_BITMAP ) */ 00470 /* { */ 00471 /* error = FT_Glyph_To_Bitmap( &glyph, FT_RENDER_MODE_NORMAL, */ 00472 /* 0, 1 ); */ 00473 /* if ( error ) // `glyph' unchanged */ 00474 /* ... */ 00475 /* } */ 00476 /* */ 00477 /* // access bitmap content by typecasting */ 00478 /* glyph_bitmap = (FT_BitmapGlyph)glyph; */ 00479 /* */ 00480 /* // do funny stuff with it, like blitting/drawing */ 00481 /* ... */ 00482 /* */ 00483 /* // discard glyph image (bitmap or not) */ 00484 /* FT_Done_Glyph( glyph ); */ 00485 /* } */ 00486 /* */ 00487 /* */ 00488 /* Here another example, again without error handling: */ 00489 /* */ 00490 /* */ 00491 /* { */ 00492 /* FT_Glyph glyphs[MAX_GLYPHS] */ 00493 /* */ 00494 /* */ 00495 /* ... */ 00496 /* */ 00497 /* for ( idx = 0; i < MAX_GLYPHS; i++ ) */ 00498 /* error = FT_Load_Glyph( face, idx, FT_LOAD_DEFAULT ) || */ 00499 /* FT_Get_Glyph ( face->glyph, &glyph[idx] ); */ 00500 /* */ 00501 /* ... */ 00502 /* */ 00503 /* for ( idx = 0; i < MAX_GLYPHS; i++ ) */ 00504 /* { */ 00505 /* FT_Glyph bitmap = glyphs[idx]; */ 00506 /* */ 00507 /* */ 00508 /* ... */ 00509 /* */ 00510 /* // after this call, `bitmap' no longer points into */ 00511 /* // the `glyphs' array (and the old value isn't destroyed) */ 00512 /* FT_Glyph_To_Bitmap( &bitmap, FT_RENDER_MODE_MONO, 0, 0 ); */ 00513 /* */ 00514 /* ... */ 00515 /* */ 00516 /* FT_Done_Glyph( bitmap ); */ 00517 /* } */ 00518 /* */ 00519 /* ... */ 00520 /* */ 00521 /* for ( idx = 0; i < MAX_GLYPHS; i++ ) */ 00522 /* FT_Done_Glyph( glyphs[idx] ); */ 00523 /* } */ 00524 /* */ 00525 FT_EXPORT( FT_Error ) 00526 FT_Glyph_To_Bitmap( FT_Glyph* the_glyph, 00527 FT_Render_Mode render_mode, 00528 FT_Vector* origin, 00529 FT_Bool destroy ); 00530 00531 00532 /*************************************************************************/ 00533 /* */ 00534 /* <Function> */ 00535 /* FT_Done_Glyph */ 00536 /* */ 00537 /* <Description> */ 00538 /* Destroy a given glyph. */ 00539 /* */ 00540 /* <Input> */ 00541 /* glyph :: A handle to the target glyph object. */ 00542 /* */ 00543 FT_EXPORT( void ) 00544 FT_Done_Glyph( FT_Glyph glyph ); 00545 00546 /* */ 00547 00548 00549 /* other helpful functions */ 00550 00551 /*************************************************************************/ 00552 /* */ 00553 /* <Section> */ 00554 /* computations */ 00555 /* */ 00556 /*************************************************************************/ 00557 00558 00559 /*************************************************************************/ 00560 /* */ 00561 /* <Function> */ 00562 /* FT_Matrix_Multiply */ 00563 /* */ 00564 /* <Description> */ 00565 /* Perform the matrix operation `b = a*b'. */ 00566 /* */ 00567 /* <Input> */ 00568 /* a :: A pointer to matrix `a'. */ 00569 /* */ 00570 /* <InOut> */ 00571 /* b :: A pointer to matrix `b'. */ 00572 /* */ 00573 /* <Note> */ 00574 /* The result is undefined if either `a' or `b' is zero. */ 00575 /* */ 00576 FT_EXPORT( void ) 00577 FT_Matrix_Multiply( const FT_Matrix* a, 00578 FT_Matrix* b ); 00579 00580 00581 /*************************************************************************/ 00582 /* */ 00583 /* <Function> */ 00584 /* FT_Matrix_Invert */ 00585 /* */ 00586 /* <Description> */ 00587 /* Invert a 2x2 matrix. Return an error if it can't be inverted. */ 00588 /* */ 00589 /* <InOut> */ 00590 /* matrix :: A pointer to the target matrix. Remains untouched in */ 00591 /* case of error. */ 00592 /* */ 00593 /* <Return> */ 00594 /* FreeType error code. 0~means success. */ 00595 /* */ 00596 FT_EXPORT( FT_Error ) 00597 FT_Matrix_Invert( FT_Matrix* matrix ); 00598 00599 00600 /* */ 00601 00602 00603 FT_END_HEADER 00604 00605 #endif /* __FTGLYPH_H__ */ 00606 00607 00608 /* END */ 00609 00610 00611 /* Local Variables: */ 00612 /* coding: utf-8 */ 00613 /* End: */
1.5.1