FreeType 2 API Reference

FreeType 2 API Reference

Computations

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