Skip to content

FreeType » Docs » Support API » Computations

# Computations

## Synopsis

This section contains various functions used to perform computations on 16.16 fixed-float numbers or 2d vectors.

Attention: Most arithmetic functions take `FT_Long` as arguments. For historical reasons, FreeType was designed under the assumption that `FT_Long` is a 32-bit integer; results can thus be undefined if the arguments don't fit into 32 bits.

## FT_MulDiv

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( FT_Long )
      FT_MulDiv( FT_Long  a,
                 FT_Long  b,
                 FT_Long  c );

Compute `(a*b)/c` with maximum accuracy, using a 64-bit intermediate integer whenever necessary.

This function isn't necessarily as fast as some processor-specific operations, but is at least completely portable.

#### input

a | The first multiplier.
b | The second multiplier.
c | The divisor.

#### return

The result of `(a*b)/c`. This function never traps when trying to divide by zero; it simply returns ‘MaxInt’ or ‘MinInt’ depending on the signs of `a` and `b`.

## FT_MulFix

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( FT_Long )
      FT_MulFix( FT_Long  a,
                 FT_Long  b );

Compute `(a*b)/0x10000` with maximum accuracy. Its main use is to multiply a given value by a 16.16 fixed-point factor.

#### input

a | The first multiplier.
b | The second multiplier. Use a 16.16 factor here whenever possible (see note below).

#### return

The result of `(a*b)/0x10000`.

#### note

This function has been optimized for the case where the absolute value of `a` is less than 2048, and `b` is a 16.16 scaling factor. As this happens mainly when scaling from notional units to fractional pixels in FreeType, it resulted in noticeable speed improvements between versions 2.x and 1.x.

As a conclusion, always try to place a 16.16 factor as the second argument of this function; this can make a great difference.

## FT_DivFix

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( FT_Long )
      FT_DivFix( FT_Long  a,
                 FT_Long  b );

Compute `(a*0x10000)/b` with maximum accuracy. Its main use is to divide a given value by a 16.16 fixed-point factor.

#### input

a | The numerator.
b | The denominator. Use a 16.16 factor here.

#### return

The result of `(a*0x10000)/b`.

## FT_RoundFix

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( FT_Fixed )
      FT_RoundFix( FT_Fixed  a );

Round a 16.16 fixed number.

#### input

a | The number to be rounded.

#### return

`a` rounded to the nearest 16.16 fixed integer, halfway cases away from zero.

#### note

The function uses wrap-around arithmetic.

## FT_CeilFix

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( FT_Fixed )
      FT_CeilFix( FT_Fixed  a );

Compute the smallest following integer of a 16.16 fixed number.

#### input

a | The number for which the ceiling function is to be computed.

#### return

`a` rounded towards plus infinity.

#### note

The function uses wrap-around arithmetic.

## FT_FloorFix

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( FT_Fixed )
      FT_FloorFix( FT_Fixed  a );

Compute the largest previous integer of a 16.16 fixed number.

#### input

a | The number for which the floor function is to be computed.

#### return

`a` rounded towards minus infinity.

## FT_Vector_Transform

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( void )
      FT_Vector_Transform( FT_Vector*        vector,
                           const FT_Matrix*  matrix );

Transform a single vector through a 2x2 matrix.

#### inout

vector | The target vector to transform.

#### input

matrix | A pointer to the source 2x2 matrix.

#### note

The result is undefined if either `vector` or `matrix` is invalid.

## FT_Matrix_Multiply

Defined in FT_GLYPH_H (freetype/ftglyph.h).

      FT_EXPORT( void )
      FT_Matrix_Multiply( const FT_Matrix*  a,
                          FT_Matrix*        b );

Perform the matrix operation `b = a*b`.

#### input

a | A pointer to matrix `a`.

#### inout

b | A pointer to matrix `b`.

#### note

The result is undefined if either `a` or `b` is zero.

Since the function uses wrap-around arithmetic, results become meaningless if the arguments are very large.

## FT_Matrix_Invert

Defined in FT_GLYPH_H (freetype/ftglyph.h).

      FT_EXPORT( FT_Error )
      FT_Matrix_Invert( FT_Matrix*  matrix );

Invert a 2x2 matrix. Return an error if it can't be inverted.

#### inout

matrix | A pointer to the target matrix. Remains untouched in case of error.

#### return

FreeType error code. 0 means success.

## FT_Angle

Defined in FT_TRIGONOMETRY_H (freetype/fttrigon.h).

      typedef FT_Fixed  FT_Angle;

This type is used to model angle values in FreeType. Note that the angle is a 16.16 fixed-point value expressed in degrees.

## FT_ANGLE_PI

Defined in FT_TRIGONOMETRY_H (freetype/fttrigon.h).

    #define FT_ANGLE_PI  ( 180L << 16 )

The angle pi expressed in `FT_Angle` units.

## FT_ANGLE_2PI

Defined in FT_TRIGONOMETRY_H (freetype/fttrigon.h).

    #define FT_ANGLE_2PI  ( FT_ANGLE_PI * 2 )

The angle 2*pi expressed in `FT_Angle` units.

## FT_ANGLE_PI2

Defined in FT_TRIGONOMETRY_H (freetype/fttrigon.h).

    #define FT_ANGLE_PI2  ( FT_ANGLE_PI / 2 )

The angle pi/2 expressed in `FT_Angle` units.

## FT_ANGLE_PI4

Defined in FT_TRIGONOMETRY_H (freetype/fttrigon.h).

    #define FT_ANGLE_PI4  ( FT_ANGLE_PI / 4 )

The angle pi/4 expressed in `FT_Angle` units.

## FT_Sin

Defined in FT_TRIGONOMETRY_H (freetype/fttrigon.h).

      FT_EXPORT( FT_Fixed )
      FT_Sin( FT_Angle  angle );

Return the sinus of a given angle in fixed-point format.

#### input

angle | The input angle.

#### return

The sinus value.

#### note

If you need both the sinus and cosinus for a given angle, use the function `FT_Vector_Unit`.

## FT_Cos

Defined in FT_TRIGONOMETRY_H (freetype/fttrigon.h).

      FT_EXPORT( FT_Fixed )
      FT_Cos( FT_Angle  angle );

Return the cosinus of a given angle in fixed-point format.

#### input

angle | The input angle.

#### return

The cosinus value.

#### note

If you need both the sinus and cosinus for a given angle, use the function `FT_Vector_Unit`.

## FT_Tan

Defined in FT_TRIGONOMETRY_H (freetype/fttrigon.h).

      FT_EXPORT( FT_Fixed )
      FT_Tan( FT_Angle  angle );

Return the tangent of a given angle in fixed-point format.

#### input

angle | The input angle.

#### return

The tangent value.

## FT_Atan2

Defined in FT_TRIGONOMETRY_H (freetype/fttrigon.h).

      FT_EXPORT( FT_Angle )
      FT_Atan2( FT_Fixed  x,
                FT_Fixed  y );

Return the arc-tangent corresponding to a given vector (x,y) in the 2d plane.

#### input

x | The horizontal vector coordinate.
y | The vertical vector coordinate.

#### return

The arc-tangent value (i.e. angle).

## FT_Angle_Diff

Defined in FT_TRIGONOMETRY_H (freetype/fttrigon.h).

      FT_EXPORT( FT_Angle )
      FT_Angle_Diff( FT_Angle  angle1,
                     FT_Angle  angle2 );

Return the difference between two angles. The result is always constrained to the ]-PI..PI] interval.

#### input

angle1 | First angle.
angle2 | Second angle.

#### return

Constrained value of `angle2-angle1`.

## FT_Vector_Unit

Defined in FT_TRIGONOMETRY_H (freetype/fttrigon.h).

      FT_EXPORT( void )
      FT_Vector_Unit( FT_Vector*  vec,
                      FT_Angle    angle );

Return the unit vector corresponding to a given angle. After the call, the value of `vec.x` will be `cos(angle)`, and the value of `vec.y` will be `sin(angle)`.

This function is useful to retrieve both the sinus and cosinus of a given angle quickly.

#### output

vec | The address of target vector.

#### input

angle | The input angle.

## FT_Vector_Rotate

Defined in FT_TRIGONOMETRY_H (freetype/fttrigon.h).

      FT_EXPORT( void )
      FT_Vector_Rotate( FT_Vector*  vec,
                        FT_Angle    angle );

Rotate a vector by a given angle.

#### inout

vec | The address of target vector.

#### input

angle | The input angle.

## FT_Vector_Length

Defined in FT_TRIGONOMETRY_H (freetype/fttrigon.h).

      FT_EXPORT( FT_Fixed )
      FT_Vector_Length( FT_Vector*  vec );

Return the length of a given vector.

#### input

vec | The address of target vector.

#### return

The vector length, expressed in the same units that the original vector coordinates.

## FT_Vector_Polarize

Defined in FT_TRIGONOMETRY_H (freetype/fttrigon.h).

      FT_EXPORT( void )
      FT_Vector_Polarize( FT_Vector*  vec,
                          FT_Fixed   *length,
                          FT_Angle   *angle );

Compute both the length and angle of a given vector.

#### input

vec | The address of source vector.

#### output

length | The vector length.
angle | The vector angle.

## FT_Vector_From_Polar

Defined in FT_TRIGONOMETRY_H (freetype/fttrigon.h).

      FT_EXPORT( void )
      FT_Vector_From_Polar( FT_Vector*  vec,
                            FT_Fixed    length,
                            FT_Angle    angle );

Compute vector coordinates from a length and angle.

#### output

vec | The address of source vector.

#### input

length | The vector length.
angle | The vector angle.