Sizing and Scaling - FreeType-2.13.3 API Reference
Author: FreeType Contributors
Description: API Reference Documentation for FreeType-2.13.3

Skip to content

FreeType » Docs » Core API » Sizing and Scaling

# Sizing and Scaling

## Synopsis

The functions and structures collected in this section are related to selecting and manipulating the size of a font globally.

## FT_Size

Defined in FT_FREETYPE_H (freetype/freetype.h).

      typedef struct FT_SizeRec_*  FT_Size;

A handle to an object that models a face scaled to a given character size.

#### note

An `FT_Face` has one active `FT_Size` object that is used by functions like `FT_Load_Glyph` to determine the scaling transformation that in turn is used to load and hint glyphs and metrics.

A newly created `FT_Size` object contains only meaningless zero values. You must use `FT_Set_Char_Size`, `FT_Set_Pixel_Sizes`, `FT_Request_Size` or even `FT_Select_Size` to change the content (i.e., the scaling values) of the active `FT_Size`. Otherwise, the scaling and hinting will not be performed.

You can use `FT_New_Size` to create additional size objects for a given `FT_Face`, but they won't be used by other functions until you activate it through `FT_Activate_Size`. Only one size can be activated at any given time per face.

#### also

See `FT_SizeRec` for the publicly accessible fields of a given size object.

## FT_SizeRec

Defined in FT_FREETYPE_H (freetype/freetype.h).

      typedef struct  FT_SizeRec_
      {
        FT_Face           face;      /* parent face object              */
        FT_Generic        generic;   /* generic pointer for client uses */
        FT_Size_Metrics   metrics;   /* size metrics                    */
        FT_Size_Internal  internal;

      } FT_SizeRec;

FreeType root size class structure. A size object models a face object at a given size.

#### fields

face | Handle to the parent face object.
generic | A typeless pointer, unused by the FreeType library or any of its drivers. It can be used by client applications to link their own data to each size object.
metrics | Metrics for this size object. This field is read-only.

## FT_Size_Metrics

Defined in FT_FREETYPE_H (freetype/freetype.h).

      typedef struct  FT_Size_Metrics_
      {
        FT_UShort  x_ppem;      /* horizontal pixels per EM               */
        FT_UShort  y_ppem;      /* vertical pixels per EM                 */

        FT_Fixed   x_scale;     /* scaling values used to convert font    */
        FT_Fixed   y_scale;     /* units to 26.6 fractional pixels        */

        FT_Pos     ascender;    /* ascender in 26.6 frac. pixels          */
        FT_Pos     descender;   /* descender in 26.6 frac. pixels         */
        FT_Pos     height;      /* text height in 26.6 frac. pixels       */
        FT_Pos     max_advance; /* max horizontal advance, in 26.6 pixels */

      } FT_Size_Metrics;

The size metrics structure gives the metrics of a size object.

#### fields

x_ppem | The width of the scaled EM square in pixels, hence the term ‘ppem’ (pixels per EM). It is also referred to as ‘nominal width’.
y_ppem | The height of the scaled EM square in pixels, hence the term ‘ppem’ (pixels per EM). It is also referred to as ‘nominal height’.
x_scale | A 16.16 fractional scaling value to convert horizontal metrics from font units to 26.6 fractional pixels. Only relevant for scalable font formats.
y_scale | A 16.16 fractional scaling value to convert vertical metrics from font units to 26.6 fractional pixels. Only relevant for scalable font formats.
ascender | The ascender in 26.6 fractional pixels, rounded up to an integer value. See `FT_FaceRec` for the details.
descender | The descender in 26.6 fractional pixels, rounded down to an integer value. See `FT_FaceRec` for the details.
height | The height in 26.6 fractional pixels, rounded to an integer value. See `FT_FaceRec` for the details.
max_advance | The maximum advance width in 26.6 fractional pixels, rounded to an integer value. See `FT_FaceRec` for the details.

#### note

The scaling values, if relevant, are determined first during a size changing operation. The remaining fields are then set by the driver. For scalable formats, they are usually set to scaled values of the corresponding fields in `FT_FaceRec`. Some values like ascender or descender are rounded for historical reasons; more precise values (for outline fonts) can be derived by scaling the corresponding `FT_FaceRec` values manually, with code similar to the following.

      scaled_ascender = FT_MulFix( face->ascender,
                                   size_metrics->y_scale );

Note that due to glyph hinting and the selected rendering mode these values are usually not exact; consequently, they must be treated as unreliable with an error margin of at least one pixel!

Indeed, the only way to get the exact metrics is to render all glyphs. As this would be a definite performance hit, it is up to client applications to perform such computations.

The `FT_Size_Metrics` structure is valid for bitmap fonts also.

TrueType fonts with native bytecode hinting

All applications that handle TrueType fonts with native hinting must be aware that TTFs expect different rounding of vertical font dimensions. The application has to cater for this, especially if it wants to rely on a TTF's vertical data (for example, to properly align box characters vertically).

Only the application knows in advance that it is going to use native hinting for TTFs! FreeType, on the other hand, selects the hinting mode not at the time of creating an `FT_Size` object but much later, namely while calling `FT_Load_Glyph`.

Here is some pseudo code that illustrates a possible solution.

      font_format = FT_Get_Font_Format( face );

      if ( !strcmp( font_format, "TrueType" ) &&
           do_native_bytecode_hinting         )
      {
        ascender  = ROUND( FT_MulFix( face->ascender,
                                      size_metrics->y_scale ) );
        descender = ROUND( FT_MulFix( face->descender,
                                      size_metrics->y_scale ) );
      }
      else
      {
        ascender  = size_metrics->ascender;
        descender = size_metrics->descender;
      }

      height      = size_metrics->height;
      max_advance = size_metrics->max_advance;

## FT_Bitmap_Size

Defined in FT_FREETYPE_H (freetype/freetype.h).

      typedef struct  FT_Bitmap_Size_
      {
        FT_Short  height;
        FT_Short  width;

        FT_Pos    size;

        FT_Pos    x_ppem;
        FT_Pos    y_ppem;

      } FT_Bitmap_Size;

This structure models the metrics of a bitmap strike (i.e., a set of glyphs for a given point size and resolution) in a bitmap font. It is used for the `available_sizes` field of `FT_Face`.

#### fields

height | The vertical distance, in pixels, between two consecutive baselines. It is always positive.
width | The average width, in pixels, of all glyphs in the strike.
size | The nominal size of the strike in 26.6 fractional points. This field is not very useful.
x_ppem | The horizontal ppem (nominal width) in 26.6 fractional pixels.
y_ppem | The vertical ppem (nominal height) in 26.6 fractional pixels.

#### note

Windows FNT: The nominal size given in a FNT font is not reliable. If the driver finds it incorrect, it sets `size` to some calculated values, and `x_ppem` and `y_ppem` to the pixel width and height given in the font, respectively.

TrueType embedded bitmaps: `size`, `width`, and `height` values are not contained in the bitmap strike itself. They are computed from the global font parameters.

## FT_Set_Char_Size

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( FT_Error )
      FT_Set_Char_Size( FT_Face     face,
                        FT_F26Dot6  char_width,
                        FT_F26Dot6  char_height,
                        FT_UInt     horz_resolution,
                        FT_UInt     vert_resolution );

Call `FT_Request_Size` to request the nominal size (in points).

#### inout

face | A handle to a target face object.

#### input

char_width | The nominal width, in 26.6 fractional points.
char_height | The nominal height, in 26.6 fractional points.
horz_resolution | The horizontal resolution in dpi.
vert_resolution | The vertical resolution in dpi.

#### return

FreeType error code. 0 means success.

#### note

While this function allows fractional points as input values, the resulting ppem value for the given resolution is always rounded to the nearest integer.

If either the character width or height is zero, it is set equal to the other value.

If either the horizontal or vertical resolution is zero, it is set equal to the other value.

A character width or height smaller than 1pt is set to 1pt; if both resolution values are zero, they are set to 72dpi.

Don't use this function if you are using the FreeType cache API.

## FT_Set_Pixel_Sizes

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( FT_Error )
      FT_Set_Pixel_Sizes( FT_Face  face,
                          FT_UInt  pixel_width,
                          FT_UInt  pixel_height );

Call `FT_Request_Size` to request the nominal size (in pixels).

#### inout

face | A handle to the target face object.

#### input

pixel_width | The nominal width, in pixels.
pixel_height | The nominal height, in pixels.

#### return

FreeType error code. 0 means success.

#### note

You should not rely on the resulting glyphs matching or being constrained to this pixel size. Refer to `FT_Request_Size` to understand how requested sizes relate to actual sizes.

Don't use this function if you are using the FreeType cache API.

## FT_Request_Size

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( FT_Error )
      FT_Request_Size( FT_Face          face,
                       FT_Size_Request  req );

Resize the scale of the active `FT_Size` object in a face.

#### inout

face | A handle to a target face object.

#### input

req | A pointer to a `FT_Size_RequestRec`.

#### return

FreeType error code. 0 means success.

#### note

Although drivers may select the bitmap strike matching the request, you should not rely on this if you intend to select a particular bitmap strike. Use `FT_Select_Size` instead in that case.

The relation between the requested size and the resulting glyph size is dependent entirely on how the size is defined in the source face. The font designer chooses the final size of each glyph relative to this size. For more information refer to ‘https://www.freetype.org/freetype2/docs/glyphs/glyphs-2.html’.

Contrary to `FT_Set_Char_Size`, this function doesn't have special code to normalize zero-valued widths, heights, or resolutions, which are treated as `FT_LOAD_NO_SCALE`.

Don't use this function if you are using the FreeType cache API.

## FT_Select_Size

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( FT_Error )
      FT_Select_Size( FT_Face  face,
                      FT_Int   strike_index );

Select a bitmap strike. To be more precise, this function sets the scaling factors of the active `FT_Size` object in a face so that bitmaps from this particular strike are taken by `FT_Load_Glyph` and friends.

#### inout

face | A handle to a target face object.

#### input

strike_index | The index of the bitmap strike in the `available_sizes` field of `FT_FaceRec` structure.

#### return

FreeType error code. 0 means success.

#### note

For bitmaps embedded in outline fonts it is common that only a subset of the available glyphs at a given ppem value is available. FreeType silently uses outlines if there is no bitmap for a given glyph index.

For GX and OpenType variation fonts, a bitmap strike makes sense only if the default instance is active (that is, no glyph variation takes place); otherwise, FreeType simply ignores bitmap strikes. The same is true for all named instances that are different from the default instance.

Don't use this function if you are using the FreeType cache API.

## FT_Size_Request_Type

Defined in FT_FREETYPE_H (freetype/freetype.h).

      typedef enum  FT_Size_Request_Type_
      {
        FT_SIZE_REQUEST_TYPE_NOMINAL,
        FT_SIZE_REQUEST_TYPE_REAL_DIM,
        FT_SIZE_REQUEST_TYPE_BBOX,
        FT_SIZE_REQUEST_TYPE_CELL,
        FT_SIZE_REQUEST_TYPE_SCALES,

        FT_SIZE_REQUEST_TYPE_MAX

      } FT_Size_Request_Type;

An enumeration type that lists the supported size request types, i.e., what input size (in font units) maps to the requested output size (in pixels, as computed from the arguments of `FT_Size_Request`).

#### values

FT_SIZE_REQUEST_TYPE_NOMINAL | The nominal size. The `units_per_EM` field of `FT_FaceRec` is used to determine both scaling values. This is the standard scaling found in most applications. In particular, use this size request type for TrueType fonts if they provide optical scaling or something similar. Note, however, that `units_per_EM` is a rather abstract value which bears no relation to the actual size of the glyphs in a font.
FT_SIZE_REQUEST_TYPE_REAL_DIM | The real dimension. The sum of the `ascender` and (minus of) the `descender` fields of `FT_FaceRec` is used to determine both scaling values.
FT_SIZE_REQUEST_TYPE_BBOX | The font bounding box. The width and height of the `bbox` field of `FT_FaceRec` are used to determine the horizontal and vertical scaling value, respectively.
FT_SIZE_REQUEST_TYPE_CELL | The `max_advance_width` field of `FT_FaceRec` is used to determine the horizontal scaling value; the vertical scaling value is determined the same way as `FT_SIZE_REQUEST_TYPE_REAL_DIM` does. Finally, both scaling values are set to the smaller one. This type is useful if you want to specify the font size for, say, a window of a given dimension and 80x24 cells.
FT_SIZE_REQUEST_TYPE_SCALES | Specify the scaling values directly.

#### note

The above descriptions only apply to scalable formats. For bitmap formats, the behaviour is up to the driver.

See the note section of `FT_Size_Metrics` if you wonder how size requesting relates to scaling values.

## FT_Size_RequestRec

Defined in FT_FREETYPE_H (freetype/freetype.h).

      typedef struct  FT_Size_RequestRec_
      {
        FT_Size_Request_Type  type;
        FT_Long               width;
        FT_Long               height;
        FT_UInt               horiResolution;
        FT_UInt               vertResolution;

      } FT_Size_RequestRec;

A structure to model a size request.

#### fields

type | See `FT_Size_Request_Type`.
width | The desired width, given as a 26.6 fractional point value (with 72pt = 1in).
height | The desired height, given as a 26.6 fractional point value (with 72pt = 1in).
horiResolution | The horizontal resolution (dpi, i.e., pixels per inch). If set to zero, `width` is treated as a 26.6 fractional pixel value, which gets internally rounded to an integer.
vertResolution | The vertical resolution (dpi, i.e., pixels per inch). If set to zero, `height` is treated as a 26.6 fractional pixel value, which gets internally rounded to an integer.

#### note

If `width` is zero, the horizontal scaling value is set equal to the vertical scaling value, and vice versa.

If `type` is `FT_SIZE_REQUEST_TYPE_SCALES`, `width` and `height` are interpreted directly as 16.16 fractional scaling values, without any further modification, and both `horiResolution` and `vertResolution` are ignored.

## FT_Size_Request

Defined in FT_FREETYPE_H (freetype/freetype.h).

      typedef struct FT_Size_RequestRec_  *FT_Size_Request;

A handle to a size request structure.

## FT_Set_Transform

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( void )
      FT_Set_Transform( FT_Face     face,
                        FT_Matrix*  matrix,
                        FT_Vector*  delta );

Set the transformation that is applied to glyph images when they are loaded into a glyph slot through `FT_Load_Glyph`.

#### inout

face | A handle to the source face object.

#### input

matrix | A pointer to the transformation's 2x2 matrix. Use `NULL` for the identity matrix.
delta | A pointer to the translation vector. Use `NULL` for the null vector.

#### note

This function is provided as a convenience, but keep in mind that `FT_Matrix` coefficients are only 16.16 fixed-point values, which can limit the accuracy of the results. Using floating-point computations to perform the transform directly in client code instead will always yield better numbers.

The transformation is only applied to scalable image formats after the glyph has been loaded. It means that hinting is unaltered by the transformation and is performed on the character size given in the last call to `FT_Set_Char_Size` or `FT_Set_Pixel_Sizes`.

Note that this also transforms the `face.glyph.advance` field, but not the values in `face.glyph.metrics`.

## FT_Get_Transform

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( void )
      FT_Get_Transform( FT_Face     face,
                        FT_Matrix*  matrix,
                        FT_Vector*  delta );

Return the transformation that is applied to glyph images when they are loaded into a glyph slot through `FT_Load_Glyph`. See `FT_Set_Transform` for more details.

#### input

face | A handle to the source face object.

#### output

matrix | A pointer to a transformation's 2x2 matrix. Set this to NULL if you are not interested in the value.
delta | A pointer to a translation vector. Set this to NULL if you are not interested in the value.

#### since

2.11