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