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.


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_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(theta)", 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.


input
vec

The address of target vector.

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.


input
vec

The address of target vector.

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


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


generated on Wed Jun 27 11:53:26 2001