Skip to content

FreeType » Docs » Extended API » Size Management

# Size Management

## Synopsis

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

Defined in FT_SIZES_H (freetype/ftsizes.h).

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

Create 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

Defined in FT_SIZES_H (freetype/ftsizes.h).

      FT_EXPORT( FT_Error )
      FT_Done_Size( FT_Size  size );

Discard 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

Defined in FT_SIZES_H (freetype/ftsizes.h).

      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 one that has been activated last 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.