FreeType-2.1.10 API Reference

Size Management

Synopsis

FT_New_SizeFT_Done_SizeFT_Activate_Size


When creating a new face object (e.g. with FT_New_Face), an FT_Size object is automatically created and used to store all pixel-size dependent information, available in the "face->size" field.

It is however possible to create more sizes for a given face, mostly in order to manage several character pixel sizes of the same font family and style. See FT_New_Size and FT_Done_Size.

Note that FT_Set_Pixel_Sizes and FT_Set_Char_Size only modify the contents of the current "active" size; you thus need to use FT_Activate_Size to change it.

99% of applications won't need the functions provided here, especially if they use the caching sub-system, so be cautious when using these.


FT_New_Size


  FT_EXPORT( FT_Error )
  FT_New_Size( FT_Face   face,
               FT_Size*  size );

Creates a new size object from a given face object.


input
face

A handle to a parent face object.

output
asize

A handle to a new size object.

return

FreeType error code. 0 means success.

note

You need to call FT_Activate_Size in order to select the new size for upcoming calls to FT_Set_Pixel_Sizes, FT_Set_Char_Size, FT_Load_Glyph, FT_Load_Char, etc.

FT_Done_Size


  FT_EXPORT( FT_Error )
  FT_Done_Size( FT_Size  size );

Discards a given size object. Note that FT_Done_Face automatically discards all size objects allocated with FT_New_Size.


input
size

A handle to a target size object.

return

FreeType error code. 0 means success.

FT_Activate_Size


  FT_EXPORT( FT_Error )
  FT_Activate_Size( FT_Size  size );

Even though it is possible to create several size objects for a given face (see FT_New_Size for details), functions like FT_Load_Glyph or FT_Load_Char only use the last-created one to determine the "current character pixel size".

This function can be used to "activate" a previously created size object.


input
size

A handle to a target size object.

return

FreeType error code. 0 means success.

note

If "face" is the size's parent face object, this function changes the value of "face->size" to the input size handle.