lib/freetype/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   /* <Type>                                                                */
  69   /*    FT_Glyph                                                           */
  70   /*                                                                       */
  71   /* <Description>                                                         */
  72   /*    Handle to an object used to model generic glyph images.  It is a   */
  73   /*    pointer to the @FT_GlyphRec structure and can contain a glyph      */
  74   /*    bitmap or pointer.                                                 */
  75   /*                                                                       */
  76   /* <Note>                                                                */
  77   /*    Glyph objects are not owned by the library.  You must thus release */
  78   /*    them manually (through @FT_Done_Glyph) _before_ calling            */
  79   /*    @FT_Done_FreeType.                                                 */
  80   /*                                                                       */
  81   typedef struct FT_GlyphRec_*  FT_Glyph;
  82
  83
  84   /*************************************************************************/
  85   /*                                                                       */
  86   /* <Struct>                                                              */
  87   /*    FT_GlyphRec                                                        */
  88   /*                                                                       */
  89   /* <Description>                                                         */
  90   /*    The root glyph structure contains a given glyph image plus its     */
  91   /*    advance width in 16.16 fixed float format.                         */
  92   /*                                                                       */
  93   /* <Fields>                                                              */
  94   /*    library :: A handle to the FreeType library object.                */
  95   /*                                                                       */
  96   /*    clazz   :: A pointer to the glyph's class.  Private.               */
  97   /*                                                                       */
  98   /*    format  :: The format of the glyph's image.                        */
  99   /*                                                                       */
 100   /*    advance :: A 16.16 vector that gives the glyph's advance width.    */
 101   /*                                                                       */
 102   typedef struct  FT_GlyphRec_
 103   {
 104     FT_Library             library;
 105     const FT_Glyph_Class*  clazz;
 106     FT_Glyph_Format        format;
 107     FT_Vector              advance;
 108
 109   } FT_GlyphRec;
 110
 111
 112   /*************************************************************************/
 113   /*                                                                       */
 114   /* <Type>                                                                */
 115   /*    FT_BitmapGlyph                                                     */
 116   /*                                                                       */
 117   /* <Description>                                                         */
 118   /*    A handle to an object used to model a bitmap glyph image.  This is */
 119   /*    a sub-class of @FT_Glyph, and a pointer to @FT_BitmapGlyphRec.     */
 120   /*                                                                       */
 121   typedef struct FT_BitmapGlyphRec_*  FT_BitmapGlyph;
 122
 123
 124   /*************************************************************************/
 125   /*                                                                       */
 126   /* <Struct>                                                              */
 127   /*    FT_BitmapGlyphRec                                                  */
 128   /*                                                                       */
 129   /* <Description>                                                         */
 130   /*    A structure used for bitmap glyph images.  This really is a        */
 131   /*    `sub-class' of `FT_GlyphRec'.                                      */
 132   /*                                                                       */
 133   /* <Fields>                                                              */
 134   /*    root   :: The root FT_Glyph fields.                                */
 135   /*                                                                       */
 136   /*    left   :: The left-side bearing, i.e., the horizontal distance     */
 137   /*              from the current pen position to the left border of the  */
 138   /*              glyph bitmap.                                            */
 139   /*                                                                       */
 140   /*    top    :: The top-side bearing, i.e., the vertical distance from   */
 141   /*              the current pen position to the top border of the glyph  */
 142   /*              bitmap.  This distance is positive for upwards-y!        */
 143   /*                                                                       */
 144   /*    bitmap :: A descriptor for the bitmap.                             */
 145   /*                                                                       */
 146   /* <Note>                                                                */
 147   /*    You can typecast FT_Glyph to FT_BitmapGlyph if you have            */
 148   /*    glyph->format == FT_GLYPH_FORMAT_BITMAP.  This lets you access     */
 149   /*    the bitmap's contents easily.                                      */
 150   /*                                                                       */
 151   /*    The corresponding pixel buffer is always owned by the BitmapGlyph  */
 152   /*    and is thus created and destroyed with it.                         */
 153   /*                                                                       */
 154   typedef struct  FT_BitmapGlyphRec_
 155   {
 156     FT_GlyphRec  root;
 157     FT_Int       left;
 158     FT_Int       top;
 159     FT_Bitmap    bitmap;
 160
 161   } FT_BitmapGlyphRec;
 162
 163
 164   /*************************************************************************/
 165   /*                                                                       */
 166   /* <Type>                                                                */
 167   /*    FT_OutlineGlyph                                                    */
 168   /*                                                                       */
 169   /* <Description>                                                         */
 170   /*    A handle to an object used to model an outline glyph image.  This  */
 171   /*    is a sub-class of @FT_Glyph, and a pointer to @FT_OutlineGlyphRec. */
 172   /*                                                                       */
 173   typedef struct FT_OutlineGlyphRec_*  FT_OutlineGlyph;
 174
 175
 176   /*************************************************************************/
 177   /*                                                                       */
 178   /* <Struct>                                                              */
 179   /*    FT_OutlineGlyphRec                                                 */
 180   /*                                                                       */
 181   /* <Description>                                                         */
 182   /*    A structure used for outline (vectorial) glyph images.  This       */
 183   /*    really is a `sub-class' of `FT_GlyphRec'.                          */
 184   /*                                                                       */
 185   /* <Fields>                                                              */
 186   /*    root    :: The root FT_Glyph fields.                               */
 187   /*                                                                       */
 188   /*    outline :: A descriptor for the outline.                           */
 189   /*                                                                       */
 190   /* <Note>                                                                */
 191   /*    You can typecast FT_Glyph to FT_OutlineGlyph if you have           */
 192   /*    glyph->format == FT_GLYPH_FORMAT_OUTLINE.  This lets you access    */
 193   /*    the outline's content easily.                                      */
 194   /*                                                                       */
 195   /*    As the outline is extracted from a glyph slot, its coordinates are */
 196   /*    expressed normally in 26.6 pixels, unless the flag                 */
 197   /*    FT_LOAD_NO_SCALE was used in FT_Load_Glyph() or FT_Load_Char().    */
 198   /*                                                                       */
 199   /*    The outline's tables are always owned by the object and are        */
 200   /*    destroyed with it.                                                 */
 201   /*                                                                       */
 202   typedef struct  FT_OutlineGlyphRec_
 203   {
 204     FT_GlyphRec  root;
 205     FT_Outline   outline;
 206
 207   } FT_OutlineGlyphRec;
 208
 209
 210   /*************************************************************************/
 211   /*                                                                       */
 212   /* <Function>                                                            */
 213   /*    FT_Get_Glyph                                                       */
 214   /*                                                                       */
 215   /* <Description>                                                         */
 216   /*    A function used to extract a glyph image from a slot.              */
 217   /*                                                                       */
 218   /* <Input>                                                               */
 219   /*    slot   :: A handle to the source glyph slot.                       */
 220   /*                                                                       */
 221   /* <Output>                                                              */
 222   /*    aglyph :: A handle to the glyph object.                            */
 223   /*                                                                       */
 224   /* <Return>                                                              */
 225   /*    FreeType error code.  0 means success.                             */
 226   /*                                                                       */
 227   FT_EXPORT( FT_Error )
 228   FT_Get_Glyph( FT_GlyphSlot  slot,
 229                 FT_Glyph     *aglyph );
 230
 231
 232   /*************************************************************************/
 233   /*                                                                       */
 234   /* <Function>                                                            */
 235   /*    FT_Glyph_Copy                                                      */
 236   /*                                                                       */
 237   /* <Description>                                                         */
 238   /*    A function used to copy a glyph image.                             */
 239   /*                                                                       */
 240   /* <Input>                                                               */
 241   /*    source :: A handle to the source glyph object.                     */
 242   /*                                                                       */
 243   /* <Output>                                                              */
 244   /*    target :: A handle to the target glyph object.  0 in case of       */
 245   /*              error.                                                   */
 246   /*                                                                       */
 247   /* <Return>                                                              */
 248   /*    FreeType error code.  0 means success.                             */
 249   /*                                                                       */
 250   FT_EXPORT( FT_Error )
 251   FT_Glyph_Copy( FT_Glyph   source,
 252                  FT_Glyph  *target );
 253
 254
 255   /*************************************************************************/
 256   /*                                                                       */
 257   /* <Function>                                                            */
 258   /*    FT_Glyph_Transform                                                 */
 259   /*                                                                       */
 260   /* <Description>                                                         */
 261   /*    Transforms a glyph image if its format is scalable.                */
 262   /*                                                                       */
 263   /* <InOut>                                                               */
 264   /*    glyph  :: A handle to the target glyph object.                     */
 265   /*                                                                       */
 266   /* <Input>                                                               */
 267   /*    matrix :: A pointer to a 2x2 matrix to apply.                      */
 268   /*                                                                       */
 269   /*    delta  :: A pointer to a 2d vector to apply.  Coordinates are      */
 270   /*              expressed in 1/64th of a pixel.                          */
 271   /*                                                                       */
 272   /* <Return>                                                              */
 273   /*    FreeType error code (the glyph format is not scalable if it is     */
 274   /*    not zero).                                                         */
 275   /*                                                                       */
 276   /* <Note>                                                                */
 277   /*    The 2x2 transformation matrix is also applied to the glyph's       */
 278   /*    advance vector.                                                    */
 279   /*                                                                       */
 280   FT_EXPORT( FT_Error )
 281   FT_Glyph_Transform( FT_Glyph    glyph,
 282                       FT_Matrix*  matrix,
 283                       FT_Vector*  delta );
 284
 285   /* */
 286
 287   /*************************************************************************/
 288   /*                                                                       */
 289   /* <Function>                                                            */
 290   /*    FT_Glyph_Get_CBox                                                  */
 291   /*                                                                       */
 292   /* <Description>                                                         */
 293   /*    Returns a glyph's `control box'.  The control box encloses all the */
 294   /*    outline's points, including Bezier control points.  Though it      */
 295   /*    coincides with the exact bounding box for most glyphs, it can be   */
 296   /*    slightly larger in some situations (like when rotating an outline  */
 297   /*    which contains Bezier outside arcs).                               */
 298   /*                                                                       */
 299   /*    Computing the control box is very fast, while getting the bounding */
 300   /*    box can take much more time as it needs to walk over all segments  */
 301   /*    and arcs in the outline.  To get the latter, you can use the       */
 302   /*    `ftbbox' component which is dedicated to this single task.         */
 303   /*                                                                       */
 304   /* <Input>                                                               */
 305   /*    glyph :: A handle to the source glyph object.                      */
 306   /*                                                                       */
 307   /*    mode  :: The mode which indicates how to interpret the returned    */
 308   /*             bounding box values.                                      */
 309   /*                                                                       */
 310   /* <Output>                                                              */
 311   /*    acbox :: The glyph coordinate bounding box.  Coordinates are       */
 312   /*             expressed in 1/64th of pixels if it is grid-fitted.       */
 313   /*                                                                       */
 314   /* <Note>                                                                */
 315   /*    Coordinates are relative to the glyph origin, using the Y-upwards  */
 316   /*    convention.                                                        */
 317   /*                                                                       */
 318   /*    If the glyph has been loaded with FT_LOAD_NO_SCALE, `bbox_mode'    */
 319   /*    must be set to `ft_glyph_bbox_unscaled' to get unscaled font       */
 320   /*    units.                                                             */
 321   /*                                                                       */
 322   /*    If `bbox_mode' is set to `ft_glyph_bbox_subpixels' the bbox        */
 323   /*    coordinates are returned in 26.6 pixels (i.e. 1/64th of pixels).   */
 324   /*                                                                       */
 325   /*    Note that the maximum coordinates are exclusive, which means that  */
 326   /*    one can compute the width and height of the glyph image (be it in  */
 327   /*    integer or 26.6 pixels) as:                                        */
 328   /*                                                                       */
 329   /*      width  = bbox.xMax - bbox.xMin;                                  */
 330   /*      height = bbox.yMax - bbox.yMin;                                  */
 331   /*                                                                       */
 332   /*    Note also that for 26.6 coordinates, if `bbox_mode' is set to      */
 333   /*    `ft_glyph_bbox_gridfit', the coordinates will also be grid-fitted, */
 334   /*    which corresponds to:                                              */
 335   /*                                                                       */
 336   /*      bbox.xMin = FLOOR(bbox.xMin);                                    */
 337   /*      bbox.yMin = FLOOR(bbox.yMin);                                    */
 338   /*      bbox.xMax = CEILING(bbox.xMax);                                  */
 339   /*      bbox.yMax = CEILING(bbox.yMax);                                  */
 340   /*                                                                       */
 341   /*    To get the bbox in pixel coordinates, set `bbox_mode' to           */
 342   /*    `ft_glyph_bbox_truncate'.                                          */
 343   /*                                                                       */
 344   /*    To get the bbox in grid-fitted pixel coordinates, set `bbox_mode'  */
 345   /*    to `ft_glyph_bbox_pixels'.                                         */
 346   /*                                                                       */
 347   /*    The default value for `bbox_mode' is `ft_glyph_bbox_pixels'.       */
 348   /*                                                                       */
 349   enum
 350   {
 351     ft_glyph_bbox_unscaled  = 0, /* return unscaled font units           */
 352     ft_glyph_bbox_subpixels = 0, /* return unfitted 26.6 coordinates     */
 353     ft_glyph_bbox_gridfit   = 1, /* return grid-fitted 26.6 coordinates  */
 354     ft_glyph_bbox_truncate  = 2, /* return coordinates in integer pixels */
 355     ft_glyph_bbox_pixels    = 3  /* return grid-fitted pixel coordinates */
 356   };
 357
 358
 359   FT_EXPORT( void )
 360   FT_Glyph_Get_CBox( FT_Glyph  glyph,
 361                      FT_UInt   bbox_mode,
 362                      FT_BBox  *acbox );
 363
 364
 365   /*************************************************************************/
 366   /*                                                                       */
 367   /* <Function>                                                            */
 368   /*    FT_Glyph_To_Bitmap                                                 */
 369   /*                                                                       */
 370   /* <Description>                                                         */
 371   /*    Converts a given glyph object to a bitmap glyph object.            */
 372   /*                                                                       */
 373   /* <InOut>                                                               */
 374   /*    the_glyph   :: A pointer to a handle to the target glyph.          */
 375   /*                                                                       */
 376   /* <Input>                                                               */
 377   /*    render_mode :: An enumeration that describe how the data is        */
 378   /*                   rendered.                                           */
 379   /*                                                                       */
 380   /*    origin      :: A pointer to a vector used to translate the glyph   */
 381   /*                   image before rendering.  Can be 0 (if no            */
 382   /*                   translation).  The origin is expressed in           */
 383   /*                   26.6 pixels.                                        */
 384   /*                                                                       */
 385   /*    destroy     :: A boolean that indicates that the original glyph    */
 386   /*                   image should be destroyed by this function.  It is  */
 387   /*                   never destroyed in case of error.                   */
 388   /*                                                                       */
 389   /* <Return>                                                              */
 390   /*    FreeType error code.  0 means success.                             */
 391   /*                                                                       */
 392   /* <Note>                                                                */
 393   /*    The glyph image is translated with the `origin' vector before      */
 394   /*    rendering.  In case of error, it it translated back to its         */
 395   /*    original position and the glyph is left untouched.                 */
 396   /*                                                                       */
 397   /*    The first parameter is a pointer to a FT_Glyph handle, that will   */
 398   /*    be replaced by this function.  Typically, you would use (omitting  */
 399   /*    error handling):                                                   */
 400   /*                                                                       */
 401   /*                                                                       */
 402   /*      {                                                                */
 403   /*        FT_Glyph        glyph;                                         */
 404   /*        FT_BitmapGlyph  glyph_bitmap;                                  */
 405   /*                                                                       */
 406   /*                                                                       */
 407   /*        // load glyph                                                  */
 408   /*        error = FT_Load_Char( face, glyph_index, FT_LOAD_DEFAUT );     */
 409   /*                                                                       */
 410   /*        // extract glyph image                                         */
 411   /*        error = FT_Get_Glyph( face->glyph, &glyph );                   */
 412   /*                                                                       */
 413   /*        // convert to a bitmap (default render mode + destroy old)     */
 414   /*        if ( glyph->format != FT_GLYPH_FORMAT_BITMAP )                 */
 415   /*        {                                                              */
 416   /*          error = FT_Glyph_To_Bitmap( &glyph, ft_render_mode_default,  */
 417   /*                                      0, 1 );                          */
 418   /*          if ( error ) // glyph unchanged                              */
 419   /*            ...                                                        */
 420   /*        }                                                              */
 421   /*                                                                       */
 422   /*        // access bitmap content by typecasting                        */
 423   /*        glyph_bitmap = (FT_BitmapGlyph)glyph;                          */
 424   /*                                                                       */
 425   /*        // do funny stuff with it, like blitting/drawing               */
 426   /*        ...                                                            */
 427   /*                                                                       */
 428   /*        // discard glyph image (bitmap or not)                         */
 429   /*        FT_Done_Glyph( glyph );                                        */
 430   /*      }                                                                */
 431   /*                                                                       */
 432   /*                                                                       */
 433   /*    This function will always fail if the glyph's format isn't         */
 434   /*    scalable.                                                          */
 435   /*                                                                       */
 436   FT_EXPORT( FT_Error )
 437   FT_Glyph_To_Bitmap( FT_Glyph*       the_glyph,
 438                       FT_Render_Mode  render_mode,
 439                       FT_Vector*      origin,
 440                       FT_Bool         destroy );
 441
 442
 443   /*************************************************************************/
 444   /*                                                                       */
 445   /* <Function>                                                            */
 446   /*    FT_Done_Glyph                                                      */
 447   /*                                                                       */
 448   /* <Description>                                                         */
 449   /*    Destroys a given glyph.                                            */
 450   /*                                                                       */
 451   /* <Input>                                                               */
 452   /*    glyph :: A handle to the target glyph object.                      */
 453   /*                                                                       */
 454   FT_EXPORT( void )
 455   FT_Done_Glyph( FT_Glyph  glyph );
 456
 457
 458   /* other helpful functions */
 459
 460   /*************************************************************************/
 461   /*                                                                       */
 462   /* <Section>                                                             */
 463   /*    computations                                                       */
 464   /*                                                                       */
 465   /*************************************************************************/
 466
 467
 468   /*************************************************************************/
 469   /*                                                                       */
 470   /* <Function>                                                            */
 471   /*    FT_Matrix_Multiply                                                 */
 472   /*                                                                       */
 473   /* <Description>                                                         */
 474   /*    Performs the matrix operation `b = a*b'.                           */
 475   /*                                                                       */
 476   /* <Input>                                                               */
 477   /*    a :: A pointer to matrix `a'.                                      */
 478   /*                                                                       */
 479   /* <InOut>                                                               */
 480   /*    b :: A pointer to matrix `b'.                                      */
 481   /*                                                                       */
 482   /* <Note>                                                                */
 483   /*    The result is undefined if either `a' or `b' is zero.              */
 484   /*                                                                       */
 485   FT_EXPORT( void )
 486   FT_Matrix_Multiply( const FT_Matrix*  a,
 487                       FT_Matrix*  b );
 488
 489
 490   /*************************************************************************/
 491   /*                                                                       */
 492   /* <Function>                                                            */
 493   /*    FT_Matrix_Invert                                                   */
 494   /*                                                                       */
 495   /* <Description>                                                         */
 496   /*    Inverts a 2x2 matrix.  Returns an error if it can't be inverted.   */
 497   /*                                                                       */
 498   /* <InOut>                                                               */
 499   /*    matrix :: A pointer to the target matrix.  Remains untouched in    */
 500   /*              case of error.                                           */
 501   /*                                                                       */
 502   /* <Return>                                                              */
 503   /*    FreeType error code.  0 means success.                             */
 504   /*                                                                       */
 505   FT_EXPORT( FT_Error )
 506   FT_Matrix_Invert( FT_Matrix*  matrix );
 507
 508
 509   /* */
 510
 511
 512 FT_END_HEADER
 513
 514 #endif /* __FTGLYPH_H__ */
 515
 516
 517 /* END */