src/freetype/freetype/ftglyph.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftglyph.h                                                              */
   4 /*                                                                         */
   5 /*    FreeType convenience functions to handle glyphs (specification).     */
   6 /*                                                                         */
   7 /*  Copyright 1996-2000 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 #include <freetype/freetype.h>
  36
  37 #ifdef __cplusplus
  38   extern "C" {
  39 #endif
  40
  41   /* forward declaration to a private type */
  42   typedef struct FT_Glyph_Class_  FT_Glyph_Class;
  43
  44
  45   /*************************************************************************/
  46   /*                                                                       */
  47   /* <Struct>                                                              */
  48   /*    FT_GlyphRec                                                        */
  49   /*                                                                       */
  50   /* <Description>                                                         */
  51   /*    The root glyph structure contains a given glyph image plus its     */
  52   /*    advance width in 16.16 fixed float format.                         */
  53   /*                                                                       */
  54   /* <Fields>                                                              */
  55   /*    library :: A handle to the FreeType library object.                */
  56   /*                                                                       */
  57   /*    clazz   :: A pointer to the glyph's class.  Private.               */
  58   /*                                                                       */
  59   /*    format  :: The format of the glyph's image.                        */
  60   /*                                                                       */
  61   /*    advance :: A 16.16 vector that gives the glyph's advance width.    */
  62   /*                                                                       */
  63   typedef struct  FT_GlyphRec_
  64   {
  65     FT_Library             library;
  66     const FT_Glyph_Class*  clazz;
  67     FT_Glyph_Format        format;
  68     FT_Vector              advance;
  69
  70   } FT_GlyphRec, *FT_Glyph;
  71
  72
  73   /*************************************************************************/
  74   /*                                                                       */
  75   /* <Struct>                                                              */
  76   /*    FT_BitmapGlyphRec                                                  */
  77   /*                                                                       */
  78   /* <Description>                                                         */
  79   /*    A structure used for bitmap glyph images.  This really is a        */
  80   /*    `sub-class' of `FT_GlyphRec'.                                      */
  81   /*                                                                       */
  82   /* <Fields>                                                              */
  83   /*    root   :: The root FT_Glyph fields.                                */
  84   /*                                                                       */
  85   /*    left   :: The left-side bearing, i.e., the horizontal distance     */
  86   /*              from the current pen position to the left border of the  */
  87   /*              glyph bitmap.                                            */
  88   /*                                                                       */
  89   /*    top    :: The top-side bearing, i.e., the vertical distance from   */
  90   /*              the current pen position to the top border of the glyph  */
  91   /*              bitmap.  This distance is positive for upwards-y!        */
  92   /*                                                                       */
  93   /*    bitmap :: A descriptor for the bitmap.                             */
  94   /*                                                                       */
  95   /* <Note>                                                                */
  96   /*    You can typecast FT_Glyph to FT_BitmapGlyph if you have            */
  97   /*    glyph->format == ft_glyph_format_bitmap.  This lets you access     */
  98   /*    the bitmap's contents easily.                                      */
  99   /*                                                                       */
 100   /*    The corresponding pixel buffer is always owned by the BitmapGlyph  */
 101   /*    and is thus created and destroyed with it.                         */
 102   /*                                                                       */
 103   typedef struct  FT_BitmapGlyphRec_
 104   {
 105     FT_GlyphRec  root;
 106     FT_Int       left;
 107     FT_Int       top;
 108     FT_Bitmap    bitmap;
 109
 110   } FT_BitmapGlyphRec, *FT_BitmapGlyph;
 111
 112
 113   /*************************************************************************/
 114   /*                                                                       */
 115   /* <Struct>                                                              */
 116   /*    FT_OutlineGlyphRec                                                 */
 117   /*                                                                       */
 118   /* <Description>                                                         */
 119   /*    A structure used for outline (vectorial) glyph images.  This       */
 120   /*    really is a `sub-class' of `FT_GlyphRec'.                          */
 121   /*                                                                       */
 122   /* <Fields>                                                              */
 123   /*    root    :: The root FT_Glyph fields.                               */
 124   /*                                                                       */
 125   /*    outline :: A descriptor for the outline.                           */
 126   /*                                                                       */
 127   /* <Note>                                                                */
 128   /*    You can typecast FT_Glyph to FT_OutlineGlyph if you have           */
 129   /*    glyph->format == ft_glyph_format_outline.  This lets you access    */
 130   /*    the outline's content easily.                                      */
 131   /*                                                                       */
 132   /*    As the outline is extracted from a glyph slot, its coordinates are */
 133   /*    expressed normally in 26.6 pixels, unless the flag                 */
 134   /*    FT_LOAD_NO_SCALE was used in FT_Load_Glyph() or FT_Load_Char().    */
 135   /*                                                                       */
 136   /*    The outline's tables are always owned by the object and are        */
 137   /*    destroyed with it.                                                 */
 138   /*                                                                       */
 139   typedef struct  FT_OutlineGlyphRec_
 140   {
 141     FT_GlyphRec  root;
 142     FT_Outline   outline;
 143
 144   } FT_OutlineGlyphRec, *FT_OutlineGlyph;
 145
 146
 147   /*************************************************************************/
 148   /*                                                                       */
 149   /* <Function>                                                            */
 150   /*    FT_Get_Glyph                                                       */
 151   /*                                                                       */
 152   /* <Description>                                                         */
 153   /*    A function used to extract a glyph image from a slot.              */
 154   /*                                                                       */
 155   /* <Input>                                                               */
 156   /*    slot   :: A handle to the source glyph slot.                       */
 157   /*                                                                       */
 158   /* <Output>                                                              */
 159   /*    aglyph :: A handle to the glyph object.                            */
 160   /*                                                                       */
 161   /* <Return>                                                              */
 162   /*    FreeType error code.  0 means success.                             */
 163   /*                                                                       */
 164   FT_EXPORT_DEF( FT_Error )  FT_Get_Glyph( FT_GlyphSlot  slot,
 165                                            FT_Glyph*     aglyph );
 166
 167
 168   /*************************************************************************/
 169   /*                                                                       */
 170   /* <Function>                                                            */
 171   /*    FT_Glyph_Copy                                                      */
 172   /*                                                                       */
 173   /* <Description>                                                         */
 174   /*    A function used to copy a glyph image.                             */
 175   /*                                                                       */
 176   /* <Input>                                                               */
 177   /*    source :: A handle to the source glyph object.                     */
 178   /*                                                                       */
 179   /* <Output>                                                              */
 180   /*    target :: A handle to the target glyph object.  0 in case of       */
 181   /*              error.                                                   */
 182   /*                                                                       */
 183   /* <Return>                                                              */
 184   /*    FreeType error code.  0 means success.                             */
 185   /*                                                                       */
 186   FT_EXPORT_DEF( FT_Error )  FT_Glyph_Copy( FT_Glyph   source,
 187                                             FT_Glyph*  target );
 188
 189
 190   /*************************************************************************/
 191   /*                                                                       */
 192   /* <Function>                                                            */
 193   /*    FT_Glyph_Transform                                                 */
 194   /*                                                                       */
 195   /* <Description>                                                         */
 196   /*    Transforms a glyph image if its format is scalable.                */
 197   /*                                                                       */
 198   /* <Input>                                                               */
 199   /*    glyph  :: A handle to the target glyph object.                     */
 200   /*                                                                       */
 201   /*    matrix :: A pointer to a 2x2 matrix to apply.                      */
 202   /*                                                                       */
 203   /*    delta  :: A pointer to a 2d vector to apply.  Coordinates are      */
 204   /*              expressed in 1/64th of a pixel.                          */
 205   /*                                                                       */
 206   /* <Return>                                                              */
 207   /*    FreeType error code (the glyph format is not scalable if it is     */
 208   /*    not zero).                                                         */
 209   /*                                                                       */
 210   /* <Note>                                                                */
 211   /*    The 2x2 transformation matrix is also applied to the glyph's       */
 212   /*    advance vector.                                                    */
 213   /*                                                                       */
 214   FT_EXPORT_DEF( FT_Error )  FT_Glyph_Transform( FT_Glyph    glyph,
 215                                                  FT_Matrix*  matrix,
 216                                                  FT_Vector*  delta );
 217
 218
 219   enum
 220   {
 221     ft_glyph_bbox_pixels    = 0,
 222     ft_glyph_bbox_subpixels = 1,
 223     ft_glyph_bbox_gridfit   = 2
 224   };
 225
 226
 227   /*************************************************************************/
 228   /*                                                                       */
 229   /* <Function>                                                            */
 230   /*    FT_Glyph_Get_CBox                                                  */
 231   /*                                                                       */
 232   /* <Description>                                                         */
 233   /*    Returns the glyph image's bounding box.                            */
 234   /*                                                                       */
 235   /* <Input>                                                               */
 236   /*    glyph :: A handle to the source glyph object.                      */
 237   /*                                                                       */
 238   /*    mode  :: A set of bit flags that indicate how to interpret the     */
 239   /*             returned bounding box values.                             */
 240   /*                                                                       */
 241   /* <Output>                                                              */
 242   /*    box   :: The glyph bounding box.  Coordinates are expressed in     */
 243   /*             1/64th of pixels if it is grid-fitted.                    */
 244   /*                                                                       */
 245   /* <Note>                                                                */
 246   /*    Coordinates are relative to the glyph origin, using the Y-upwards  */
 247   /*    convention.                                                        */
 248   /*                                                                       */
 249   /*    If `ft_glyph_bbox_subpixels' is set in `mode', the bbox            */
 250   /*    coordinates are returned in 26.6 pixels (i.e. 1/64th of pixels).   */
 251   /*    Otherwise, coordinates are expressed in integer pixels.            */
 252   /*                                                                       */
 253   /*    Note that the maximum coordinates are exclusive, which means that  */
 254   /*    one can compute the width and height of the glyph image (be it in  */
 255   /*    integer or 26.6 pixels) as:                                        */
 256   /*                                                                       */
 257   /*      width  = bbox.xMax - bbox.xMin;                                  */
 258   /*      height = bbox.yMax - bbox.yMin;                                  */
 259   /*                                                                       */
 260   /*    Note also that for 26.6 coordinates, if the                        */
 261   /*    `ft_glyph_bbox_gridfit' flag is set in `mode;, the coordinates     */
 262   /*    will also be grid-fitted, which corresponds to:                    */
 263   /*                                                                       */
 264   /*      bbox.xMin = FLOOR(bbox.xMin);                                    */
 265   /*      bbox.yMin = FLOOR(bbox.yMin);                                    */
 266   /*      bbox.xMax = CEILING(bbox.xMax);                                  */
 267   /*      bbox.yMax = CEILING(bbox.yMax);                                  */
 268   /*                                                                       */
 269   /*    The default value (0) for `bbox_mode' is `ft_glyph_bbox_pixels'.   */
 270   /*                                                                       */
 271   FT_EXPORT_DEF( void )  FT_Glyph_Get_CBox( FT_Glyph  glyph,
 272                                             FT_UInt   bbox_mode,
 273                                             FT_BBox*  cbox );
 274
 275
 276   /*************************************************************************/
 277   /*                                                                       */
 278   /* <Function>                                                            */
 279   /*    FT_Glyph_To_Bitmap                                                 */
 280   /*                                                                       */
 281   /* <Description>                                                         */
 282   /*    Converts a given glyph object to a bitmap glyph object.            */
 283   /*                                                                       */
 284   /* <InOut>                                                               */
 285   /*    glyph       :: A pointer to a handle to the target glyph.          */
 286   /*                                                                       */
 287   /* <Input>                                                               */
 288   /*    render_mode :: A set of bit flags that describe how the data is    */
 289   /*                                                                       */
 290   /*                                                                       */
 291   /*    origin      :: A pointer to a vector used to translate the glyph   */
 292   /*                   image before rendering.  Can be 0 (if no            */
 293   /*                   translation).  The origin is expressed in           */
 294   /*                   26.6 pixels.                                        */
 295   /*                                                                       */
 296   /*    destroy     :: A boolean that indicates that the original glyph    */
 297   /*                   image should be destroyed by this function.  It is  */
 298   /*                   never destroyed in case of error.                   */
 299   /*                                                                       */
 300   /* <Return>                                                              */
 301   /*    FreeType error code.  0 means success.                             */
 302   /*                                                                       */
 303   /* <Note>                                                                */
 304   /*    The glyph image is translated with the `origin' vector before      */
 305   /*    rendering.  In case of error, it it translated back to its         */
 306   /*    original position and the glyph is left untouched.                 */
 307   /*                                                                       */
 308   /*    The first parameter is a pointer to a FT_Glyph handle, that will   */
 309   /*    be replaced by this function.  Typically, you would use (omitting  */
 310   /*    error handling):                                                   */
 311   /*                                                                       */
 312   /*                                                                       */
 313   /*      {                                                                */
 314   /*        FT_Glyph        glyph;                                         */
 315   /*        FT_BitmapGlyph  glyph_bitmap;                                  */
 316   /*                                                                       */
 317   /*                                                                       */
 318   /*        // load glyph                                                  */
 319   /*        error = FT_Load_Char( face, glyph_index, FT_LOAD_DEFAUT );     */
 320   /*                                                                       */
 321   /*        // extract glyph image                                         */
 322   /*        error = FT_Get_Glyph( face->glyph, &glyph );                   */
 323   /*                                                                       */
 324   /*        // convert to a bitmap (default render mode + destroy old)     */
 325   /*        if ( glyph->format != ft_glyph_format_bitmap )                 */
 326   /*        {                                                              */
 327   /*          error = FT_Glyph_To_Bitmap( &glyph, ft_render_mode_default,  */
 328   /*                                      0, 1 );                          */
 329   /*          if ( error ) // glyph unchanged                              */
 330   /*            ...                                                        */
 331   /*        }                                                              */
 332   /*                                                                       */
 333   /*        // access bitmap content by typecasting                        */
 334   /*        glyph_bitmap = (FT_BitmapGlyph)glyph;                          */
 335   /*                                                                       */
 336   /*        // do funny stuff with it, like blitting/drawing               */
 337   /*        ...                                                            */
 338   /*                                                                       */
 339   /*        // discard glyph image (bitmap or not)                         */
 340   /*        FT_Done_Glyph( glyph );                                        */
 341   /*      }                                                                */
 342   /*                                                                       */
 343   /*                                                                       */
 344   /*    This function will always fail if the glyph's format isn't         */
 345   /*    scalable.                                                          */
 346   /*                                                                       */
 347   FT_EXPORT_DEF( FT_Error )  FT_Glyph_To_Bitmap( FT_Glyph*   the_glyph,
 348                                                  FT_ULong    render_mode,
 349                                                  FT_Vector*  origin,
 350                                                  FT_Bool     destroy );
 351
 352
 353   /*************************************************************************/
 354   /*                                                                       */
 355   /* <Function>                                                            */
 356   /*    FT_Done_Glyph                                                      */
 357   /*                                                                       */
 358   /* <Description>                                                         */
 359   /*    Destroys a given glyph.                                            */
 360   /*                                                                       */
 361   /* <Input>                                                               */
 362   /*    glyph :: A handle to the target glyph object.                      */
 363   /*                                                                       */
 364   FT_EXPORT_DEF( void )  FT_Done_Glyph( FT_Glyph  glyph );
 365
 366
 367   /* other helpful functions */
 368
 369
 370   /*************************************************************************/
 371   /*                                                                       */
 372   /* <Function>                                                            */
 373   /*    FT_Matrix_Multiply                                                 */
 374   /*                                                                       */
 375   /* <Description>                                                         */
 376   /*    Performs the matrix operation `b = a*b'.                           */
 377   /*                                                                       */
 378   /* <Input>                                                               */
 379   /*    a :: A pointer to matrix `a'.                                      */
 380   /*                                                                       */
 381   /* <InOut>                                                               */
 382   /*    b :: A pointer to matrix `b'.                                      */
 383   /*                                                                       */
 384   /* <MT-Note>                                                             */
 385   /*    Yes.                                                               */
 386   /*                                                                       */
 387   /* <Note>                                                                */
 388   /*    The result is undefined if either `a' or `b' is zero.              */
 389   /*                                                                       */
 390   FT_EXPORT_DEF( void )  FT_Matrix_Multiply( FT_Matrix*  a,
 391                                              FT_Matrix*  b );
 392
 393
 394   /*************************************************************************/
 395   /*                                                                       */
 396   /* <Function>                                                            */
 397   /*    FT_Matrix_Invert                                                   */
 398   /*                                                                       */
 399   /* <Description>                                                         */
 400   /*    Inverts a 2x2 matrix.  Returns an error if it can't be inverted.   */
 401   /*                                                                       */
 402   /* <InOut>                                                               */
 403   /*    matrix :: A pointer to the target matrix.  Remains untouched in    */
 404   /*              case of error.                                           */
 405   /*                                                                       */
 406   /* <Return>                                                              */
 407   /*    FreeType error code.  0 means success.                             */
 408   /*                                                                       */
 409   /* <MT-Note>                                                             */
 410   /*    Yes.                                                               */
 411   /*                                                                       */
 412   FT_EXPORT_DEF( FT_Error )  FT_Matrix_Invert( FT_Matrix*  matrix );
 413
 414
 415 #ifdef __cplusplus
 416   }
 417 #endif
 418
 419 #endif /* FTGLYPH_H */
 420
 421
 422 /* END */