libraries/freetype-2.0.5/include/freetype/ftglyph.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftglyph.h                                                              */
   4 /*                                                                         */
   5 /*    FreeType convenience functions to handle glyphs (specification).     */
   6 /*                                                                         */
   7 /*  Copyright 1996-2001 by                                                 */
   8 /*  David Turner, Robert Wilhelm, and Werner Lemberg.                      */
   9 /*                                                                         */
  10 /*  This file is part of the FreeType project, and may only be used,       */
  11 /*  modified, and distributed under the terms of the FreeType project      */
  12 /*  license, LICENSE.TXT.  By continuing to use, modify, or distribute     */
  13 /*  this file you indicate that you have read the license and              */
  14 /*  understand and accept it fully.                                        */
  15 /*                                                                         */
  16 /***************************************************************************/
  17
  18
  19   /*************************************************************************/
  20   /*                                                                       */
  21   /* This file contains the definition of several convenience functions    */
  22   /* that can be used by client applications to easily retrieve glyph      */
  23   /* bitmaps and outlines from a given face.                               */
  24   /*                                                                       */
  25   /* These functions should be optional if you are writing a font server   */
  26   /* or text layout engine on top of FreeType.  However, they are pretty   */
  27   /* handy for many other simple uses of the library.                      */
  28   /*                                                                       */
  29   /*************************************************************************/
  30
  31
  32 #ifndef __FTGLYPH_H__
  33 #define __FTGLYPH_H__
  34
  35
  36 #include <ft2build.h>
  37 #include FT_FREETYPE_H
  38
  39
  40 FT_BEGIN_HEADER
  41
  42
  43   /*************************************************************************/
  44   /*                                                                       */
  45   /* <Section>                                                             */
  46   /*    glyph_management                                                   */
  47   /*                                                                       */
  48   /* <Title>                                                               */
  49   /*    Glyph Management                                                   */
  50   /*                                                                       */
  51   /* <Abstract>                                                            */
  52   /*    Generic interface to manage individual glyph data.                 */
  53   /*                                                                       */
  54   /* <Description>                                                         */
  55   /*    This section contains definitions used to manage glyph data        */
  56   /*    through generic FT_Glyph objects.  Each of them can contain a      */
  57   /*    bitmap, a vector outline, or even images in other formats.         */
  58   /*                                                                       */
  59   /*************************************************************************/
  60
  61
  62   /* forward declaration to a private type */
  63   typedef struct FT_Glyph_Class_  FT_Glyph_Class;
  64
  65
  66   /*************************************************************************/
  67   /*                                                                       */
  68   /* <Struct>                                                              */
  69   /*    FT_GlyphRec                                                        */
  70   /*                                                                       */
  71   /* <Description>                                                         */
  72   /*    The root glyph structure contains a given glyph image plus its     */
  73   /*    advance width in 16.16 fixed float format.                         */
  74   /*                                                                       */
  75   /* <Fields>                                                              */
  76   /*    library :: A handle to the FreeType library object.                */
  77   /*                                                                       */
  78   /*    clazz   :: A pointer to the glyph's class.  Private.               */
  79   /*                                                                       */
  80   /*    format  :: The format of the glyph's image.                        */
  81   /*                                                                       */
  82   /*    advance :: A 16.16 vector that gives the glyph's advance width.    */
  83   /*                                                                       */
  84   typedef struct  FT_GlyphRec_
  85   {
  86     FT_Library             library;
  87     const FT_Glyph_Class*  clazz;
  88     FT_Glyph_Format        format;
  89     FT_Vector              advance;
  90
  91   } FT_GlyphRec, *FT_Glyph;
  92
  93
  94   /*************************************************************************/
  95   /*                                                                       */
  96   /* <Struct>                                                              */
  97   /*    FT_BitmapGlyphRec                                                  */
  98   /*                                                                       */
  99   /* <Description>                                                         */
 100   /*    A structure used for bitmap glyph images.  This really is a        */
 101   /*    `sub-class' of `FT_GlyphRec'.                                      */
 102   /*                                                                       */
 103   /* <Fields>                                                              */
 104   /*    root   :: The root FT_Glyph fields.                                */
 105   /*                                                                       */
 106   /*    left   :: The left-side bearing, i.e., the horizontal distance     */
 107   /*              from the current pen position to the left border of the  */
 108   /*              glyph bitmap.                                            */
 109   /*                                                                       */
 110   /*    top    :: The top-side bearing, i.e., the vertical distance from   */
 111   /*              the current pen position to the top border of the glyph  */
 112   /*              bitmap.  This distance is positive for upwards-y!        */
 113   /*                                                                       */
 114   /*    bitmap :: A descriptor for the bitmap.                             */
 115   /*                                                                       */
 116   /* <Note>                                                                */
 117   /*    You can typecast FT_Glyph to FT_BitmapGlyph if you have            */
 118   /*    glyph->format == ft_glyph_format_bitmap.  This lets you access     */
 119   /*    the bitmap's contents easily.                                      */
 120   /*                                                                       */
 121   /*    The corresponding pixel buffer is always owned by the BitmapGlyph  */
 122   /*    and is thus created and destroyed with it.                         */
 123   /*                                                                       */
 124   typedef struct  FT_BitmapGlyphRec_
 125   {
 126     FT_GlyphRec  root;
 127     FT_Int       left;
 128     FT_Int       top;
 129     FT_Bitmap    bitmap;
 130
 131   } FT_BitmapGlyphRec, *FT_BitmapGlyph;
 132
 133
 134   /*************************************************************************/
 135   /*                                                                       */
 136   /* <Struct>                                                              */
 137   /*    FT_OutlineGlyphRec                                                 */
 138   /*                                                                       */
 139   /* <Description>                                                         */
 140   /*    A structure used for outline (vectorial) glyph images.  This       */
 141   /*    really is a `sub-class' of `FT_GlyphRec'.                          */
 142   /*                                                                       */
 143   /* <Fields>                                                              */
 144   /*    root    :: The root FT_Glyph fields.                               */
 145   /*                                                                       */
 146   /*    outline :: A descriptor for the outline.                           */
 147   /*                                                                       */
 148   /* <Note>                                                                */
 149   /*    You can typecast FT_Glyph to FT_OutlineGlyph if you have           */
 150   /*    glyph->format == ft_glyph_format_outline.  This lets you access    */
 151   /*    the outline's content easily.                                      */
 152   /*                                                                       */
 153   /*    As the outline is extracted from a glyph slot, its coordinates are */
 154   /*    expressed normally in 26.6 pixels, unless the flag                 */
 155   /*    FT_LOAD_NO_SCALE was used in FT_Load_Glyph() or FT_Load_Char().    */
 156   /*                                                                       */
 157   /*    The outline's tables are always owned by the object and are        */
 158   /*    destroyed with it.                                                 */
 159   /*                                                                       */
 160   typedef struct  FT_OutlineGlyphRec_
 161   {
 162     FT_GlyphRec  root;
 163     FT_Outline   outline;
 164
 165   } FT_OutlineGlyphRec, *FT_OutlineGlyph;
 166
 167
 168   /*************************************************************************/
 169   /*                                                                       */
 170   /* <Function>                                                            */
 171   /*    FT_Get_Glyph                                                       */
 172   /*                                                                       */
 173   /* <Description>                                                         */
 174   /*    A function used to extract a glyph image from a slot.              */
 175   /*                                                                       */
 176   /* <Input>                                                               */
 177   /*    slot   :: A handle to the source glyph slot.                       */
 178   /*                                                                       */
 179   /* <Output>                                                              */
 180   /*    aglyph :: A handle to the glyph object.                            */
 181   /*                                                                       */
 182   /* <Return>                                                              */
 183   /*    FreeType error code.  0 means success.                             */
 184   /*                                                                       */
 185   FT_EXPORT( FT_Error )
 186   FT_Get_Glyph( FT_GlyphSlot  slot,
 187                 FT_Glyph     *aglyph );
 188
 189
 190   /*************************************************************************/
 191   /*                                                                       */
 192   /* <Function>                                                            */
 193   /*    FT_Glyph_Copy                                                      */
 194   /*                                                                       */
 195   /* <Description>                                                         */
 196   /*    A function used to copy a glyph image.                             */
 197   /*                                                                       */
 198   /* <Input>                                                               */
 199   /*    source :: A handle to the source glyph object.                     */
 200   /*                                                                       */
 201   /* <Output>                                                              */
 202   /*    target :: A handle to the target glyph object.  0 in case of       */
 203   /*              error.                                                   */
 204   /*                                                                       */
 205   /* <Return>                                                              */
 206   /*    FreeType error code.  0 means success.                             */
 207   /*                                                                       */
 208   FT_EXPORT( FT_Error )
 209   FT_Glyph_Copy( FT_Glyph   source,
 210                  FT_Glyph  *target );
 211
 212
 213   /*************************************************************************/
 214   /*                                                                       */
 215   /* <Function>                                                            */
 216   /*    FT_Glyph_Transform                                                 */
 217   /*                                                                       */
 218   /* <Description>                                                         */
 219   /*    Transforms a glyph image if its format is scalable.                */
 220   /*                                                                       */
 221   /* <InOut>                                                               */
 222   /*    glyph  :: A handle to the target glyph object.                     */
 223   /*                                                                       */
 224   /* <Input>                                                               */
 225   /*    matrix :: A pointer to a 2x2 matrix to apply.                      */
 226   /*                                                                       */
 227   /*    delta  :: A pointer to a 2d vector to apply.  Coordinates are      */
 228   /*              expressed in 1/64th of a pixel.                          */
 229   /*                                                                       */
 230   /* <Return>                                                              */
 231   /*    FreeType error code (the glyph format is not scalable if it is     */
 232   /*    not zero).                                                         */
 233   /*                                                                       */
 234   /* <Note>                                                                */
 235   /*    The 2x2 transformation matrix is also applied to the glyph's       */
 236   /*    advance vector.                                                    */
 237   /*                                                                       */
 238   FT_EXPORT( FT_Error )
 239   FT_Glyph_Transform( FT_Glyph    glyph,
 240                       FT_Matrix*  matrix,
 241                       FT_Vector*  delta );
 242
 243   /* */
 244
 245   /*************************************************************************/
 246   /*                                                                       */
 247   /* <Function>                                                            */
 248   /*    FT_Glyph_Get_CBox                                                  */
 249   /*                                                                       */
 250   /* <Description>                                                         */
 251   /*    Returns a glyph's `control box'.  The control box encloses all the */
 252   /*    outline's points, including Bezier control points.  Though it      */
 253   /*    coincides with the exact bounding box for most glyphs, it can be   */
 254   /*    slightly larger in some situations (like when rotating an outline  */
 255   /*    which contains Bezier outside arcs).                               */
 256   /*                                                                       */
 257   /*    Computing the control box is very fast, while getting the bounding */
 258   /*    box can take much more time as it needs to walk over all segments  */
 259   /*    and arcs in the outline.  To get the latter, you can use the       */
 260   /*    `ftbbox' component which is dedicated to this single task.         */
 261   /*                                                                       */
 262   /* <Input>                                                               */
 263   /*    glyph :: A handle to the source glyph object.                      */
 264   /*                                                                       */
 265   /*    mode  :: The mode which indicates how to interpret the returned    */
 266   /*             bounding box values.                                      */
 267   /*                                                                       */
 268   /* <Output>                                                              */
 269   /*    acbox :: The glyph coordinate bounding box.  Coordinates are       */
 270   /*             expressed in 1/64th of pixels if it is grid-fitted.       */
 271   /*                                                                       */
 272   /* <Note>                                                                */
 273   /*    Coordinates are relative to the glyph origin, using the Y-upwards  */
 274   /*    convention.                                                        */
 275   /*                                                                       */
 276   /*    If the glyph has been loaded with FT_LOAD_NO_SCALE, `bbox_mode'    */
 277   /*    must be set to `ft_glyph_bbox_unscaled' to get unscaled font       */
 278   /*    units.                                                             */
 279   /*                                                                       */
 280   /*    If `bbox_mode' is set to `ft_glyph_bbox_subpixels' the bbox        */
 281   /*    coordinates are returned in 26.6 pixels (i.e. 1/64th of pixels).   */
 282   /*                                                                       */
 283   /*    Note that the maximum coordinates are exclusive, which means that  */
 284   /*    one can compute the width and height of the glyph image (be it in  */
 285   /*    integer or 26.6 pixels) as:                                        */
 286   /*                                                                       */
 287   /*      width  = bbox.xMax - bbox.xMin;                                  */
 288   /*      height = bbox.yMax - bbox.yMin;                                  */
 289   /*                                                                       */
 290   /*    Note also that for 26.6 coordinates, if `bbox_mode' is set to      */
 291   /*    `ft_glyph_bbox_gridfit', the coordinates will also be grid-fitted, */
 292   /*    which corresponds to:                                              */
 293   /*                                                                       */
 294   /*      bbox.xMin = FLOOR(bbox.xMin);                                    */
 295   /*      bbox.yMin = FLOOR(bbox.yMin);                                    */
 296   /*      bbox.xMax = CEILING(bbox.xMax);                                  */
 297   /*      bbox.yMax = CEILING(bbox.yMax);                                  */
 298   /*                                                                       */
 299   /*    To get the bbox in pixel coordinates, set `bbox_mode' to           */
 300   /*    `ft_glyph_bbox_truncate'.                                          */
 301   /*                                                                       */
 302   /*    To get the bbox in grid-fitted pixel coordinates, set `bbox_mode'  */
 303   /*    to `ft_glyph_bbox_pixels'.                                         */
 304   /*                                                                       */
 305   /*    The default value for `bbox_mode' is `ft_glyph_bbox_pixels'.       */
 306   /*                                                                       */
 307   enum
 308   {
 309     ft_glyph_bbox_unscaled  = 0, /* return unscaled font units           */
 310     ft_glyph_bbox_subpixels = 0, /* return unfitted 26.6 coordinates     */
 311     ft_glyph_bbox_gridfit   = 1, /* return grid-fitted 26.6 coordinates  */
 312     ft_glyph_bbox_truncate  = 2, /* return coordinates in integer pixels */
 313     ft_glyph_bbox_pixels    = 3  /* return grid-fitted pixel coordinates */
 314   };
 315
 316
 317   FT_EXPORT( void )
 318   FT_Glyph_Get_CBox( FT_Glyph  glyph,
 319                      FT_UInt   bbox_mode,
 320                      FT_BBox  *acbox );
 321
 322
 323   /*************************************************************************/
 324   /*                                                                       */
 325   /* <Function>                                                            */
 326   /*    FT_Glyph_To_Bitmap                                                 */
 327   /*                                                                       */
 328   /* <Description>                                                         */
 329   /*    Converts a given glyph object to a bitmap glyph object.            */
 330   /*                                                                       */
 331   /* <InOut>                                                               */
 332   /*    the_glyph   :: A pointer to a handle to the target glyph.          */
 333   /*                                                                       */
 334   /* <Input>                                                               */
 335   /*    render_mode :: A set of bit flags that describe how the data is    */
 336   /*                                                                       */
 337   /*                                                                       */
 338   /*    origin      :: A pointer to a vector used to translate the glyph   */
 339   /*                   image before rendering.  Can be 0 (if no            */
 340   /*                   translation).  The origin is expressed in           */
 341   /*                   26.6 pixels.                                        */
 342   /*                                                                       */
 343   /*    destroy     :: A boolean that indicates that the original glyph    */
 344   /*                   image should be destroyed by this function.  It is  */
 345   /*                   never destroyed in case of error.                   */
 346   /*                                                                       */
 347   /* <Return>                                                              */
 348   /*    FreeType error code.  0 means success.                             */
 349   /*                                                                       */
 350   /* <Note>                                                                */
 351   /*    The glyph image is translated with the `origin' vector before      */
 352   /*    rendering.  In case of error, it it translated back to its         */
 353   /*    original position and the glyph is left untouched.                 */
 354   /*                                                                       */
 355   /*    The first parameter is a pointer to a FT_Glyph handle, that will   */
 356   /*    be replaced by this function.  Typically, you would use (omitting  */
 357   /*    error handling):                                                   */
 358   /*                                                                       */
 359   /*                                                                       */
 360   /*      {                                                                */
 361   /*        FT_Glyph        glyph;                                         */
 362   /*        FT_BitmapGlyph  glyph_bitmap;                                  */
 363   /*                                                                       */
 364   /*                                                                       */
 365   /*        // load glyph                                                  */
 366   /*        error = FT_Load_Char( face, glyph_index, FT_LOAD_DEFAUT );     */
 367   /*                                                                       */
 368   /*        // extract glyph image                                         */
 369   /*        error = FT_Get_Glyph( face->glyph, &glyph );                   */
 370   /*                                                                       */
 371   /*        // convert to a bitmap (default render mode + destroy old)     */
 372   /*        if ( glyph->format != ft_glyph_format_bitmap )                 */
 373   /*        {                                                              */
 374   /*          error = FT_Glyph_To_Bitmap( &glyph, ft_render_mode_default,  */
 375   /*                                      0, 1 );                          */
 376   /*          if ( error ) // glyph unchanged                              */
 377   /*            ...                                                        */
 378   /*        }                                                              */
 379   /*                                                                       */
 380   /*        // access bitmap content by typecasting                        */
 381   /*        glyph_bitmap = (FT_BitmapGlyph)glyph;                          */
 382   /*                                                                       */
 383   /*        // do funny stuff with it, like blitting/drawing               */
 384   /*        ...                                                            */
 385   /*                                                                       */
 386   /*        // discard glyph image (bitmap or not)                         */
 387   /*        FT_Done_Glyph( glyph );                                        */
 388   /*      }                                                                */
 389   /*                                                                       */
 390   /*                                                                       */
 391   /*    This function will always fail if the glyph's format isn't         */
 392   /*    scalable.                                                          */
 393   /*                                                                       */
 394   FT_EXPORT( FT_Error )
 395   FT_Glyph_To_Bitmap( FT_Glyph*   the_glyph,
 396                       FT_ULong    render_mode,
 397                       FT_Vector*  origin,
 398                       FT_Bool     destroy );
 399
 400
 401   /*************************************************************************/
 402   /*                                                                       */
 403   /* <Function>                                                            */
 404   /*    FT_Done_Glyph                                                      */
 405   /*                                                                       */
 406   /* <Description>                                                         */
 407   /*    Destroys a given glyph.                                            */
 408   /*                                                                       */
 409   /* <Input>                                                               */
 410   /*    glyph :: A handle to the target glyph object.                      */
 411   /*                                                                       */
 412   FT_EXPORT( void )
 413   FT_Done_Glyph( FT_Glyph  glyph );
 414
 415
 416   /* other helpful functions */
 417
 418   /*************************************************************************/
 419   /*                                                                       */
 420   /* <Section>                                                             */
 421   /*    computations                                                       */
 422   /*                                                                       */
 423   /*************************************************************************/
 424
 425
 426   /*************************************************************************/
 427   /*                                                                       */
 428   /* <Function>                                                            */
 429   /*    FT_Matrix_Multiply                                                 */
 430   /*                                                                       */
 431   /* <Description>                                                         */
 432   /*    Performs the matrix operation `b = a*b'.                           */
 433   /*                                                                       */
 434   /* <Input>                                                               */
 435   /*    a :: A pointer to matrix `a'.                                      */
 436   /*                                                                       */
 437   /* <InOut>                                                               */
 438   /*    b :: A pointer to matrix `b'.                                      */
 439   /*                                                                       */
 440   /* <Note>                                                                */
 441   /*    The result is undefined if either `a' or `b' is zero.              */
 442   /*                                                                       */
 443   FT_EXPORT( void )
 444   FT_Matrix_Multiply( FT_Matrix*  a,
 445                       FT_Matrix*  b );
 446
 447
 448   /*************************************************************************/
 449   /*                                                                       */
 450   /* <Function>                                                            */
 451   /*    FT_Matrix_Invert                                                   */
 452   /*                                                                       */
 453   /* <Description>                                                         */
 454   /*    Inverts a 2x2 matrix.  Returns an error if it can't be inverted.   */
 455   /*                                                                       */
 456   /* <InOut>                                                               */
 457   /*    matrix :: A pointer to the target matrix.  Remains untouched in    */
 458   /*              case of error.                                           */
 459   /*                                                                       */
 460   /* <Return>                                                              */
 461   /*    FreeType error code.  0 means success.                             */
 462   /*                                                                       */
 463   FT_EXPORT( FT_Error )
 464   FT_Matrix_Invert( FT_Matrix*  matrix );
 465
 466
 467   /* */
 468
 469
 470 FT_END_HEADER
 471
 472 #endif /* __FTGLYPH_H__ */
 473
 474
 475 /* END */