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.

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.