FreeType-2.1.10 API Reference
Glyph Management
Synopsis
#FT_GlyphFT_Glyph #FT_OutlineGlyphRecFT_OutlineGlyphRec #ft_glyph_bbox_xxxft_glyph_bbox_xxx #FT_GlyphRecFT_GlyphRec #FT_Get_GlyphFT_Get_Glyph #FT_Glyph_Get_CBoxFT_Glyph_Get_CBox #FT_BitmapGlyphFT_BitmapGlyph #FT_Glyph_CopyFT_Glyph_Copy #FT_Glyph_To_BitmapFT_Glyph_To_Bitmap #FT_BitmapGlyphRecFT_BitmapGlyphRec #FT_Glyph_TransformFT_Glyph_Transform #FT_Done_GlyphFT_Done_Glyph #FT_OutlineGlyphFT_OutlineGlyph #FT_Glyph_BBox_ModeFT_Glyph_BBox_Mode This section contains definitions used to manage glyph data through generic FT_Glyph objects. Each of them can contain a bitmap, a vector outline, or even images in other formats.
FT_Glyph 
  
typedef struct FT_GlyphRec_*  FT_Glyph;
Handle to an object used to model generic glyph images. It is a pointer to the ft2-glyph_management.html#FT_GlyphRecFT_GlyphRec  structure and can contain a glyph bitmap or pointer.
note Glyph objects are not owned by the library. You must thus release them manually (through ft2-glyph_management.html#FT_Done_GlyphFT_Done_Glyph ) before calling ft2-base_interface.html#FT_Done_FreeTypeFT_Done_FreeType .
FT_GlyphRec 
  
typedef struct  FT_GlyphRec_
  {
    
ft2-base_interface.html#FT_LibraryFT_Library              library;
    
const FT_Glyph_Class*  clazz;
    
ft2-basic_types.html#FT_Glyph_FormatFT_Glyph_Format         format;
    
ft2-basic_types.html#FT_VectorFT_Vector               advance;
  } 
FT_GlyphRec;
The root glyph structure contains a given glyph image plus its advance width in 16.16 fixed float format.
fields library A handle to the FreeType library object.
clazz A pointer to the glyph's class. Private.
format The format of the glyph's image.
advance A 16.16 vector that gives the glyph's advance width.
FT_BitmapGlyph 
  
typedef struct FT_BitmapGlyphRec_*  FT_BitmapGlyph;
A handle to an object used to model a bitmap glyph image. This is a sub-class of ft2-glyph_management.html#FT_GlyphFT_Glyph , and a pointer to ft2-glyph_management.html#FT_BitmapGlyphRecFT_BitmapGlyphRec .
FT_BitmapGlyphRec 
  
typedef struct  FT_BitmapGlyphRec_
  {
    
ft2-glyph_management.html#FT_GlyphRecFT_GlyphRec   root;
    
ft2-basic_types.html#FT_IntFT_Int        left;
    
ft2-basic_types.html#FT_IntFT_Int        top;
    
ft2-basic_types.html#FT_BitmapFT_Bitmap     bitmap;
  } 
FT_BitmapGlyphRec;
A structure used for bitmap glyph images. This really is a `sub-class' of `FT_GlyphRec'.
fields root The root FT_Glyph fields.
left The left-side bearing, i.e., the horizontal distance from the current pen position to the left border of the glyph bitmap.
top The top-side bearing, i.e., the vertical distance from the current pen position to the top border of the glyph bitmap. This distance is positive for upwards-y!
bitmap A descriptor for the bitmap.
note You can typecast FT_Glyph to FT_BitmapGlyph if you have glyph->format == FT_GLYPH_FORMAT_BITMAP. This lets you access the bitmap's contents easily.
The corresponding pixel buffer is always owned by the BitmapGlyph and is thus created and destroyed with it.
FT_OutlineGlyph 
  
typedef struct FT_OutlineGlyphRec_*  FT_OutlineGlyph;
A handle to an object used to model an outline glyph image. This is a sub-class of ft2-glyph_management.html#FT_GlyphFT_Glyph , and a pointer to ft2-glyph_management.html#FT_OutlineGlyphRecFT_OutlineGlyphRec .
FT_OutlineGlyphRec 
  
typedef struct  FT_OutlineGlyphRec_
  {
    
ft2-glyph_management.html#FT_GlyphRecFT_GlyphRec   root;
    
ft2-outline_processing.html#FT_OutlineFT_Outline    outline;
  } 
FT_OutlineGlyphRec;
A structure used for outline (vectorial) glyph images. This really is a `sub-class' of `FT_GlyphRec'.
fields root The root FT_Glyph fields.
outline A descriptor for the outline.
note You can typecast FT_Glyph to FT_OutlineGlyph if you have glyph->format == FT_GLYPH_FORMAT_OUTLINE. This lets you access the outline's content easily.
As the outline is extracted from a glyph slot, its coordinates are expressed normally in 26.6 pixels, unless the flag FT_LOAD_NO_SCALE was used in FT_Load_Glyph() or FT_Load_Char().
The outline's tables are always owned by the object and are destroyed with it.
FT_Get_Glyph 
  FT_EXPORT( 
ft2-basic_types.html#FT_ErrorFT_Error  )
  
FT_Get_Glyph( ft2-base_interface.html#FT_GlyphSlotFT_GlyphSlot   slot,
                
ft2-glyph_management.html#FT_GlyphFT_Glyph      *aglyph );
A function used to extract a glyph image from a slot.
input slot A handle to the source glyph slot.
output aglyph A handle to the glyph object.
return FreeType error code. 0 means success.
FT_Glyph_Copy 
  FT_EXPORT( 
ft2-basic_types.html#FT_ErrorFT_Error  )
  
FT_Glyph_Copy( ft2-glyph_management.html#FT_GlyphFT_Glyph    source,
                 
ft2-glyph_management.html#FT_GlyphFT_Glyph   *target );
A function used to copy a glyph image. Note that the created ft2-glyph_management.html#FT_GlyphFT_Glyph  object must be released with ft2-glyph_management.html#FT_Done_GlyphFT_Done_Glyph .
input source A handle to the source glyph object.
output target A handle to the target glyph object. 0 in case of error.
return FreeType error code. 0 means success.
FT_Glyph_Transform 
  FT_EXPORT( 
ft2-basic_types.html#FT_ErrorFT_Error  )
  
FT_Glyph_Transform( ft2-glyph_management.html#FT_GlyphFT_Glyph     glyph,
                      
ft2-basic_types.html#FT_MatrixFT_Matrix *  matrix,
                      
ft2-basic_types.html#FT_VectorFT_Vector *  delta );
Transforms a glyph image if its format is scalable.
inout glyph A handle to the target glyph object.
input matrix A pointer to a 2x2 matrix to apply.
delta A pointer to a 2d vector to apply. Coordinates are expressed in 1/64th of a pixel.
return FreeType error code (the glyph format is not scalable if it is not zero).
note The 2x2 transformation matrix is also applied to the glyph's advance vector.
FT_Glyph_BBox_Mode 
  
typedef enum  FT_Glyph_BBox_Mode_
  {
    
ft2-glyph_management.html#FT_Glyph_BBox_ModeFT_GLYPH_BBOX_UNSCALED   = 0,
    
ft2-glyph_management.html#FT_Glyph_BBox_ModeFT_GLYPH_BBOX_SUBPIXELS  = 0,
    
ft2-glyph_management.html#FT_Glyph_BBox_ModeFT_GLYPH_BBOX_GRIDFIT    = 1,
    
ft2-glyph_management.html#FT_Glyph_BBox_ModeFT_GLYPH_BBOX_TRUNCATE   = 2,
    
ft2-glyph_management.html#FT_Glyph_BBox_ModeFT_GLYPH_BBOX_PIXELS     = 3
  } 
FT_Glyph_BBox_Mode;
The mode how the values of ft2-glyph_management.html#FT_Glyph_Get_CBoxFT_Glyph_Get_CBox  are returned.
values FT_GLYPH_BBOX_UNSCALED Return unscaled font units.
FT_GLYPH_BBOX_SUBPIXELS Return unfitted 26.6 coordinates.
FT_GLYPH_BBOX_GRIDFIT Return grid-fitted 26.6 coordinates.
FT_GLYPH_BBOX_TRUNCATE Return coordinates in integer pixels.
FT_GLYPH_BBOX_PIXELS Return grid-fitted pixel coordinates.
ft_glyph_bbox_xxx 
#define 
ft2-glyph_management.html#ft_glyph_bbox_xxxft_glyph_bbox_unscaled    ft2-glyph_management.html#FT_Glyph_BBox_ModeFT_GLYPH_BBOX_UNSCALED #define 
ft2-glyph_management.html#ft_glyph_bbox_xxxft_glyph_bbox_subpixels   ft2-glyph_management.html#FT_Glyph_BBox_ModeFT_GLYPH_BBOX_SUBPIXELS #define 
ft2-glyph_management.html#ft_glyph_bbox_xxxft_glyph_bbox_gridfit     ft2-glyph_management.html#FT_Glyph_BBox_ModeFT_GLYPH_BBOX_GRIDFIT #define 
ft2-glyph_management.html#ft_glyph_bbox_xxxft_glyph_bbox_truncate    ft2-glyph_management.html#FT_Glyph_BBox_ModeFT_GLYPH_BBOX_TRUNCATE #define 
ft2-glyph_management.html#ft_glyph_bbox_xxxft_glyph_bbox_pixels      ft2-glyph_management.html#FT_Glyph_BBox_ModeFT_GLYPH_BBOX_PIXELS These constants are deprecated. Use the corresponding ft2-glyph_management.html#FT_Glyph_BBox_ModeFT_Glyph_BBox_Mode  values instead.
values ft_glyph_bbox_unscaled see ft2-glyph_management.html#FT_Glyph_BBox_ModeFT_GLYPH_BBOX_UNSCALED 
ft_glyph_bbox_subpixels see ft2-glyph_management.html#FT_Glyph_BBox_ModeFT_GLYPH_BBOX_SUBPIXELS 
ft_glyph_bbox_gridfit see ft2-glyph_management.html#FT_Glyph_BBox_ModeFT_GLYPH_BBOX_GRIDFIT 
ft_glyph_bbox_truncate see ft2-glyph_management.html#FT_Glyph_BBox_ModeFT_GLYPH_BBOX_TRUNCATE 
ft_glyph_bbox_pixels see ft2-glyph_management.html#FT_Glyph_BBox_ModeFT_GLYPH_BBOX_PIXELS 
FT_Glyph_Get_CBox 
  FT_EXPORT( 
void )
  
FT_Glyph_Get_CBox( ft2-glyph_management.html#FT_GlyphFT_Glyph   glyph,
                     
ft2-basic_types.html#FT_UIntFT_UInt    bbox_mode,
                     
ft2-basic_types.html#FT_BBoxFT_BBox   *acbox );
Returns a glyph's `control box'. The control box encloses all the outline's points, including Bezier control points. Though it coincides with the exact bounding box for most glyphs, it can be slightly larger in some situations (like when rotating an outline which contains Bezier outside arcs).
Computing the control box is very fast, while getting the bounding box can take much more time as it needs to walk over all segments and arcs in the outline. To get the latter, you can use the `ftbbox' component which is dedicated to this single task.
input glyph A handle to the source glyph object.
mode The mode which indicates how to interpret the returned bounding box values.
output acbox The glyph coordinate bounding box. Coordinates are expressed in 1/64th of pixels if it is grid-fitted.
note Coordinates are relative to the glyph origin, using the Y-upwards convention.
If the glyph has been loaded with FT_LOAD_NO_SCALE, `bbox_mode' must be set to `FT_GLYPH_BBOX_UNSCALED' to get unscaled font units in 26.6 pixel format. The value `FT_GLYPH_BBOX_SUBPIXELS' is another name for this constant.
Note that the maximum coordinates are exclusive, which means that one can compute the width and height of the glyph image (be it in integer or 26.6 pixels) as:
width = bbox.xMax - bbox.xMin; height = bbox.yMax - bbox.yMin;
Note also that for 26.6 coordinates, if `bbox_mode' is set to `FT_GLYPH_BBOX_GRIDFIT', the coordinates will also be grid-fitted, which corresponds to:
bbox.xMin = FLOOR(bbox.xMin); bbox.yMin = FLOOR(bbox.yMin); bbox.xMax = CEILING(bbox.xMax); bbox.yMax = CEILING(bbox.yMax);
To get the bbox in pixel coordinates, set `bbox_mode' to `FT_GLYPH_BBOX_TRUNCATE'.
To get the bbox in grid-fitted pixel coordinates, set `bbox_mode' to `FT_GLYPH_BBOX_PIXELS'.
FT_Glyph_To_Bitmap 
  FT_EXPORT( 
ft2-basic_types.html#FT_ErrorFT_Error  )
  
FT_Glyph_To_Bitmap( ft2-glyph_management.html#FT_GlyphFT_Glyph *       the_glyph,
                      
ft2-base_interface.html#FT_Render_ModeFT_Render_Mode   render_mode,
                      
ft2-basic_types.html#FT_VectorFT_Vector *      origin,
                      
ft2-basic_types.html#FT_BoolFT_Bool          destroy );
Converts a given glyph object to a bitmap glyph object.
inout the_glyph A pointer to a handle to the target glyph.
input render_mode An enumeration that describe how the data is rendered.
origin A pointer to a vector used to translate the glyph image before rendering. Can be 0 (if no translation). The origin is expressed in 26.6 pixels.
destroy A boolean that indicates that the original glyph image should be destroyed by this function. It is never destroyed in case of error.
return FreeType error code. 0 means success.
note The glyph image is translated with the `origin' vector before rendering.
The first parameter is a pointer to a FT_Glyph handle, that will be replaced by this function. Typically, you would use (omitting error handling):
  FT_Glyph        glyph;                                         
  FT_BitmapGlyph  glyph_bitmap;                                  
                                                                 
                                                                 
  // load glyph                                                  
  error = FT_Load_Char( face, glyph_index, FT_LOAD_DEFAUT );     
                                                                 
  // extract glyph image                                         
  error = FT_Get_Glyph( face->glyph, &glyph );                   
                                                                 
  // convert to a bitmap (default render mode + destroy old)     
  if ( glyph->format != FT_GLYPH_FORMAT_BITMAP )                 
  {                                                              
    error = FT_Glyph_To_Bitmap( &glyph, FT_RENDER_MODE_DEFAULT,  
                                0, 1 );                          
    if ( error ) // glyph unchanged                              
      ...                                                        
  }                                                              
                                                                 
  // access bitmap content by typecasting                        
  glyph_bitmap = (FT_BitmapGlyph)glyph;                          
                                                                 
  // do funny stuff with it, like blitting/drawing               
  ...                                                            
                                                                 
  // discard glyph image (bitmap or not)                         
  FT_Done_Glyph( glyph );                                        
This function does nothing if the glyph format isn't scalable.
FT_Done_Glyph 
  FT_EXPORT( 
void )
  
FT_Done_Glyph( ft2-glyph_management.html#FT_GlyphFT_Glyph   glyph );
  /* other helpful functions */
Destroys a given glyph.
input glyph A handle to the target glyph object.
