# FreeType-2.1.8 API Reference

# Computations

## Synopsis

| FT_MulDiv |  | FT_Matrix_Invert |  | FT_Tan
| FT_MulFix |  | FT_Angle |  | FT_Atan2
| FT_DivFix |  | FT_ANGLE_PI |  | FT_Angle_Diff
| FT_RoundFix |  | FT_ANGLE_2PI |  | FT_Vector_Unit
| FT_CeilFix |  | FT_ANGLE_PI2 |  | FT_Vector_Rotate
| FT_FloorFix |  | FT_ANGLE_PI4 |  | FT_Vector_Length
| FT_Vector_Transform |  | FT_Sin |  | FT_Vector_Polarize
| FT_Matrix_Multiply |  | FT_Cos |  | FT_Vector_From_Polar

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

#### FT_MulDiv

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

A very simple function used to perform the computation `(a*b)/c' with maximal accuracy (it uses 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

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

A very simple function used to perform the computation `(a*b)/0x10000' with maximal accuracy. Most of the time this is used to multiply a given value by a 16.16 fixed float 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

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

A very simple function used to perform the computation `(a*0x10000)/b' with maximal accuracy. Most of the time, this is used to divide a given value by a 16.16 fixed float 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*0x10000)/b'.

note
The optimization for FT_DivFix() is simple: If (a << 16) fits in 32 bits, then the division is computed directly. Otherwise, we use a specialized version of FT_MulDiv.

#### FT_RoundFix

      FT_EXPORT( FT_Fixed )
      FT_RoundFix( FT_Fixed  a );

A very simple function used to round a 16.16 fixed number.

input

a | The number to be rounded.

return
The result of `(a + 0x8000) & -0x10000'.

#### FT_CeilFix

      FT_EXPORT( FT_Fixed )
      FT_CeilFix( FT_Fixed  a );

A very simple function used to compute the ceiling function of a 16.16 fixed number.

input

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

return
The result of `(a + 0x10000 - 1) & -0x10000'.

#### FT_FloorFix

      FT_EXPORT( FT_Fixed )
      FT_FloorFix( FT_Fixed  a );

A very simple function used to compute the floor function of a 16.16 fixed number.

input

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

return
The result of `a & -0x10000'.

#### FT_Vector_Transform

      FT_EXPORT( void )
      FT_Vector_Transform( FT_Vector*  vec,
                           FT_Matrix*  matrix );

Transforms 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

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

Performs 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.

#### FT_Matrix_Invert

      FT_EXPORT( FT_Error )
      FT_Matrix_Invert( FT_Matrix*  matrix );

Inverts a 2x2 matrix. Returns 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

      typedef FT_Fixed  FT_Angle;

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

#### FT_ANGLE_PI

    #define FT_ANGLE_PI  ( 180L << 16 )

The angle pi expressed in FT_Angle units.

#### FT_ANGLE_2PI

    #define FT_ANGLE_2PI  ( FT_ANGLE_PI * 2 )

The angle 2*pi expressed in FT_Angle units.

#### FT_ANGLE_PI2

    #define FT_ANGLE_PI2  ( FT_ANGLE_PI / 2 )

The angle pi/2 expressed in FT_Angle units.

#### FT_ANGLE_PI4

    #define FT_ANGLE_PI4  ( FT_ANGLE_PI / 4 )

The angle pi/4 expressed in FT_Angle units.

#### FT_Sin

      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

      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

      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

      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

      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
Contrainted value of `value2-value1'.

#### FT_Vector_Unit

      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 `sin(angle)', and the value of `vec.y' will be `cos(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 address of angle.

#### FT_Vector_Rotate

      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 address of angle.

#### FT_Vector_Length

      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

      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

      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.