# FreeType-2.1.4 API Reference

# Computations

## Synopsys

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

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 the old ?FT_MulDiv64?

#### 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_Normalize
      FT_EXPORT( void )
      FT_Vector_Normalize( FT_Vector*  vec );
Normalize a given vector (i.e. compute the equivalent unit vector).
inout
vec | The address of target vector.

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