FreeType-2.1.10 API Reference
Computations
Synopsis
#FT_MulDiv
FT_MulDiv
#FT_Matrix_Invert
FT_Matrix_Invert
#FT_Tan
FT_Tan
#FT_MulFix
FT_MulFix
#FT_Angle
FT_Angle
#FT_Atan2
FT_Atan2
#FT_DivFix
FT_DivFix
#FT_ANGLE_PI
FT_ANGLE_PI
#FT_Angle_Diff
FT_Angle_Diff
#FT_RoundFix
FT_RoundFix
#FT_ANGLE_2PI
FT_ANGLE_2PI
#FT_Vector_Unit
FT_Vector_Unit
#FT_CeilFix
FT_CeilFix
#FT_ANGLE_PI2
FT_ANGLE_PI2
#FT_Vector_Rotate
FT_Vector_Rotate
#FT_FloorFix
FT_FloorFix
#FT_ANGLE_PI4
FT_ANGLE_PI4
#FT_Vector_Length
FT_Vector_Length
#FT_Vector_Transform
FT_Vector_Transform
#FT_Sin
FT_Sin
#FT_Vector_Polarize
FT_Vector_Polarize
#FT_Matrix_Multiply
FT_Matrix_Multiply
#FT_Cos
FT_Cos
#FT_Vector_From_Polar
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(
ft2-basic_types.html#FT_Long
FT_Long
)
FT_MulDiv
(
ft2-basic_types.html#FT_Long
FT_Long
a,
ft2-basic_types.html#FT_Long
FT_Long
b,
ft2-basic_types.html#FT_Long
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(
ft2-basic_types.html#FT_Long
FT_Long
)
FT_MulFix
(
ft2-basic_types.html#FT_Long
FT_Long
a,
ft2-basic_types.html#FT_Long
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(
ft2-basic_types.html#FT_Long
FT_Long
)
FT_DivFix
(
ft2-basic_types.html#FT_Long
FT_Long
a,
ft2-basic_types.html#FT_Long
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
ft2-computations.html#FT_MulDiv
FT_MulDiv
.
FT_RoundFix
FT_EXPORT(
ft2-basic_types.html#FT_Fixed
FT_Fixed
)
FT_RoundFix
(
ft2-basic_types.html#FT_Fixed
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(
ft2-basic_types.html#FT_Fixed
FT_Fixed
)
FT_CeilFix
(
ft2-basic_types.html#FT_Fixed
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(
ft2-basic_types.html#FT_Fixed
FT_Fixed
)
FT_FloorFix
(
ft2-basic_types.html#FT_Fixed
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
(
ft2-basic_types.html#FT_Vector
FT_Vector
*        vec,
const
ft2-basic_types.html#FT_Matrix
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
ft2-basic_types.html#FT_Matrix
FT_Matrix
*  a,
ft2-basic_types.html#FT_Matrix
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(
ft2-basic_types.html#FT_Error
FT_Error
)
FT_Matrix_Invert
(
ft2-basic_types.html#FT_Matrix
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
ft2-basic_types.html#FT_Fixed
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
ft2-computations.html#FT_Angle
FT_Angle
units.
FT_ANGLE_2PI
#define
FT_ANGLE_2PI
(
ft2-computations.html#FT_ANGLE_PI
FT_ANGLE_PI
* 2 )
The angle 2*pi expressed in
ft2-computations.html#FT_Angle
FT_Angle
units.
FT_ANGLE_PI2
#define
FT_ANGLE_PI2
(
ft2-computations.html#FT_ANGLE_PI
FT_ANGLE_PI
/ 2 )
The angle pi/2 expressed in
ft2-computations.html#FT_Angle
FT_Angle
units.
FT_ANGLE_PI4
#define
FT_ANGLE_PI4
(
ft2-computations.html#FT_ANGLE_PI
FT_ANGLE_PI
/ 4 )
The angle pi/4 expressed in
ft2-computations.html#FT_Angle
FT_Angle
units.
FT_Sin
FT_EXPORT(
ft2-basic_types.html#FT_Fixed
FT_Fixed
)
FT_Sin
(
ft2-computations.html#FT_Angle
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
ft2-computations.html#FT_Vector_Unit
FT_Vector_Unit
.
FT_Cos
FT_EXPORT(
ft2-basic_types.html#FT_Fixed
FT_Fixed
)
FT_Cos
(
ft2-computations.html#FT_Angle
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
ft2-computations.html#FT_Vector_Unit
FT_Vector_Unit
.
FT_Tan
FT_EXPORT(
ft2-basic_types.html#FT_Fixed
FT_Fixed
)
FT_Tan
(
ft2-computations.html#FT_Angle
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(
ft2-computations.html#FT_Angle
FT_Angle
)
FT_Atan2
(
ft2-basic_types.html#FT_Fixed
FT_Fixed
x,
ft2-basic_types.html#FT_Fixed
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(
ft2-computations.html#FT_Angle
FT_Angle
)
FT_Angle_Diff
(
ft2-computations.html#FT_Angle
FT_Angle
angle1,
ft2-computations.html#FT_Angle
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
(
ft2-basic_types.html#FT_Vector
FT_Vector
*  vec,
ft2-computations.html#FT_Angle
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
(
ft2-basic_types.html#FT_Vector
FT_Vector
*  vec,
ft2-computations.html#FT_Angle
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(
ft2-basic_types.html#FT_Fixed
FT_Fixed
)
FT_Vector_Length
(
ft2-basic_types.html#FT_Vector
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
(
ft2-basic_types.html#FT_Vector
FT_Vector
*  vec,
ft2-basic_types.html#FT_Fixed
FT_Fixed
*length,
ft2-computations.html#FT_Angle
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
(
ft2-basic_types.html#FT_Vector
FT_Vector
*  vec,
ft2-basic_types.html#FT_Fixed
FT_Fixed
length,
ft2-computations.html#FT_Angle
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.
