From 360fe27b55c93c9c6c86895dbbf5db3efc66cc43 Mon Sep 17 00:00:00 2001 From: Mike DePaulo Date: Sat, 28 Feb 2015 07:31:25 -0500 Subject: Updated to freetype 2.5.5 Conflicts: freetype/src/base/ftbdf.c freetype/src/base/fttype1.c freetype/src/pfr/pfrobjs.c --- freetype/docs/reference/ft2-computations.html | 1002 +++++++++++-------------- 1 file changed, 435 insertions(+), 567 deletions(-) (limited to 'freetype/docs/reference/ft2-computations.html') diff --git a/freetype/docs/reference/ft2-computations.html b/freetype/docs/reference/ft2-computations.html index 3bee10452..a7771ef41 100644 --- a/freetype/docs/reference/ft2-computations.html +++ b/freetype/docs/reference/ft2-computations.html @@ -3,830 +3,698 @@ -FreeType-2.5.3 API Reference +FreeType-2.5.5 API Reference - - -
[Index][TOC]
-

FreeType-2.5.3 API Reference

+
[Index][TOC]
+

FreeType-2.5.5 API Reference

-

-Computations -

+

Computations

Synopsis

- - - - - - - - - -
FT_MulDivFT_Matrix_InvertFT_Tan
FT_MulFixFT_AngleFT_Atan2
FT_DivFixFT_ANGLE_PIFT_Angle_Diff
FT_RoundFixFT_ANGLE_2PIFT_Vector_Unit
FT_CeilFixFT_ANGLE_PI2FT_Vector_Rotate
FT_FloorFixFT_ANGLE_PI4FT_Vector_Length
FT_Vector_TransformFT_SinFT_Vector_Polarize
FT_Matrix_MultiplyFT_CosFT_Vector_From_Polar


- -
+ + + + + + + + + + +
FT_MulDiv FT_Atan2
FT_MulFixFT_AngleFT_Angle_Diff
FT_DivFixFT_ANGLE_PIFT_Vector_Unit
FT_RoundFixFT_ANGLE_2PIFT_Vector_Rotate
FT_CeilFixFT_ANGLE_PI2FT_Vector_Length
FT_FloorFixFT_ANGLE_PI4FT_Vector_Polarize
FT_Vector_TransformFT_SinFT_Vector_From_Polar
FT_Matrix_MultiplyFT_Cos
FT_Matrix_InvertFT_Tan
+ +

This section contains various functions used to perform computations on 16.16 fixed-float numbers or 2d vectors.

-

-
-

FT_MulDiv

-
-Defined in FT_FREETYPE_H (freetype.h). -

-
 
+

+
FT_MulDiv

+
Defined in FT_FREETYPE_H (freetype.h).

+
   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 maximum 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 + +

input

+ + - -
a

The first multiplier.

b +
b

The second multiplier.

c +
c

The divisor.

-
-
return
+ +

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

-
-
-
- - -
[Index][TOC]
- -
-

FT_MulFix

-
-Defined in FT_FREETYPE_H (freetype.h). -

-
 
+

+
[Index][Top][TOC]

+
+

+
FT_MulFix

+
Defined in FT_FREETYPE_H (freetype.h).

+
   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 maximum accuracy. Most of the time this is used to multiply a given value by a 16.16 fixed-point factor.

-

-
input
-

- -
a + +

input

+ + -
a

The first multiplier.

b +
b

The second multiplier. Use a 16.16 factor here whenever possible (see note below).

-
-
return
+ +

return

The result of ‘(a*b)/0x10000’.

-
-
note
+ +

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.

-
-
-
- - -
[Index][TOC]
- -
-

FT_DivFix

-
-Defined in FT_FREETYPE_H (freetype.h). -

-
 
+

+
[Index][Top][TOC]

+
+

+
FT_DivFix

+
Defined in FT_FREETYPE_H (freetype.h).

+
   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 maximum accuracy. Most of the time, this is used to divide a given value by a 16.16 fixed-point factor.

-

-
input
-

- -
a -

The first multiplier.

+ +

input

+ + -
a +

The numerator.

b -

The second multiplier. Use a 16.16 factor here whenever possible (see note below).

+
b +

The denominator. Use a 16.16 factor here.

-
-
return
+ +

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

-
-
-
- - -
[Index][TOC]
- -
-

FT_RoundFix

-
-Defined in FT_FREETYPE_H (freetype.h). -

-
 
+

+
[Index][Top][TOC]

+
+

+
FT_RoundFix

+
Defined in FT_FREETYPE_H (freetype.h).

+
   FT_EXPORT( FT_Fixed )
   FT_RoundFix( FT_Fixed  a );
+

 
-

-

A very simple function used to round a 16.16 fixed number.

-

-
input
-

- -
a + +

input

+ +
a

The number to be rounded.

-
-
return
+ +

return

The result of ‘(a + 0x8000) & -0x10000’.

-
-
-
- - -
[Index][TOC]
- -
-

FT_CeilFix

-
-Defined in FT_FREETYPE_H (freetype.h). -

-
 
+

+
[Index][Top][TOC]

+
+

+
FT_CeilFix

+
Defined in FT_FREETYPE_H (freetype.h).

+
   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 + +

input

+ +
a

The number for which the ceiling function is to be computed.

-
-
return
+ +

return

The result of ‘(a + 0x10000 - 1) & -0x10000’.

-
-
-
- - -
[Index][TOC]
- -
-

FT_FloorFix

-
-Defined in FT_FREETYPE_H (freetype.h). -

-
 
+

+
[Index][Top][TOC]

+
+

+
FT_FloorFix

+
Defined in FT_FREETYPE_H (freetype.h).

+
   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 + +

input

+ +
a

The number for which the floor function is to be computed.

-
-
return
+ +

return

The result of ‘a & -0x10000’.

-
-
-
- - -
[Index][TOC]
- -
-

FT_Vector_Transform

-
-Defined in FT_FREETYPE_H (freetype.h). -

-
 
+

+
[Index][Top][TOC]

+
+

+
FT_Vector_Transform

+
Defined in FT_FREETYPE_H (freetype.h).

+
   FT_EXPORT( void )
   FT_Vector_Transform( FT_Vector*        vec,
                        const FT_Matrix*  matrix );
+

 
-

-

Transform a single vector through a 2x2 matrix.

-

-
inout
-

- -
vector + +

inout

+ +
vector

The target vector to transform.

-
-
input
-

- -
matrix + +

input

+ +
matrix

A pointer to the source 2x2 matrix.

-
-
note
+ +

note

The result is undefined if either ‘vector’ or ‘matrix’ is invalid.

-
-
-
- - -
[Index][TOC]
- -
-

FT_Matrix_Multiply

-
-Defined in FT_GLYPH_H (ftglyph.h). -

-
 
+

+
[Index][Top][TOC]

+
+

+
FT_Matrix_Multiply

+
Defined in FT_GLYPH_H (ftglyph.h).

+
   FT_EXPORT( void )
   FT_Matrix_Multiply( const FT_Matrix*  a,
                       FT_Matrix*        b );
+

 
-

-

Perform the matrix operation ‘b = a*b’.

-

-
input
-

- -
a + +

input

+ +
a

A pointer to matrix ‘a’.

-
-
inout
-

- -
b + +

inout

+ +
b

A pointer to matrix ‘b’.

-
-
note
+ +

note

The result is undefined if either ‘a’ or ‘b’ is zero.

-
-
-
- - -
[Index][TOC]
- -
-

FT_Matrix_Invert

-
-Defined in FT_GLYPH_H (ftglyph.h). -

-
 
+

+
[Index][Top][TOC]

+
+

+
FT_Matrix_Invert

+
Defined in FT_GLYPH_H (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 + +

inout

+ +
matrix

A pointer to the target matrix. Remains untouched in case of error.

-
-
return
+ +

return

FreeType error code. 0 means success.

-
-
-
- - -
[Index][TOC]
- -
-

FT_Angle

-
-Defined in FT_TRIGONOMETRY_H (fttrigon.h). -

-
 
+

+
[Index][Top][TOC]

+
+

+
FT_Angle

+
Defined in FT_TRIGONOMETRY_H (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.

-

-
-
- - -
[Index][TOC]
- -
-

FT_ANGLE_PI

-
-Defined in FT_TRIGONOMETRY_H (fttrigon.h). -

-
 
+

+
[Index][Top][TOC]

+
+

+
FT_ANGLE_PI

+
Defined in FT_TRIGONOMETRY_H (fttrigon.h).

+
 #define FT_ANGLE_PI  ( 180L << 16 )
+

 
-

-

The angle pi expressed in FT_Angle units.

-

-
-
- - -
[Index][TOC]
- -
-

FT_ANGLE_2PI

-
-Defined in FT_TRIGONOMETRY_H (fttrigon.h). -

-
 
+

+
[Index][Top][TOC]

+
+

+
FT_ANGLE_2PI

+
Defined in FT_TRIGONOMETRY_H (fttrigon.h).

+
 #define FT_ANGLE_2PI  ( FT_ANGLE_PI * 2 )
+

 
-

-

The angle 2*pi expressed in FT_Angle units.

-

-
-
- - -
[Index][TOC]
- -
-

FT_ANGLE_PI2

-
-Defined in FT_TRIGONOMETRY_H (fttrigon.h). -

-
 
+

+
[Index][Top][TOC]

+
+

+
FT_ANGLE_PI2

+
Defined in FT_TRIGONOMETRY_H (fttrigon.h).

+
 #define FT_ANGLE_PI2  ( FT_ANGLE_PI / 2 )
+

 
-

-

The angle pi/2 expressed in FT_Angle units.

-

-
-
- - -
[Index][TOC]
- -
-

FT_ANGLE_PI4

-
-Defined in FT_TRIGONOMETRY_H (fttrigon.h). -

-
 
+

+
[Index][Top][TOC]

+
+

+
FT_ANGLE_PI4

+
Defined in FT_TRIGONOMETRY_H (fttrigon.h).

+
 #define FT_ANGLE_PI4  ( FT_ANGLE_PI / 4 )
+

 
-

-

The angle pi/4 expressed in FT_Angle units.

-

-
-
- - -
[Index][TOC]
- -
-

FT_Sin

-
-Defined in FT_TRIGONOMETRY_H (fttrigon.h). -

-
 
+

+
[Index][Top][TOC]

+
+

+
FT_Sin

+
Defined in FT_TRIGONOMETRY_H (fttrigon.h).

+
   FT_EXPORT( FT_Fixed )
   FT_Sin( FT_Angle  angle );
+

 
-

-

Return the sinus of a given angle in fixed-point format.

-

-
input
-

- -
angle + +

input

+ +
angle

The input angle.

-
-
return
+ +

return

The sinus value.

-
-
note
+ +

note

If you need both the sinus and cosinus for a given angle, use the function FT_Vector_Unit.

-
-
-
- - -
[Index][TOC]
- -
-

FT_Cos

-
-Defined in FT_TRIGONOMETRY_H (fttrigon.h). -

-
 
+

+
[Index][Top][TOC]

+
+

+
FT_Cos

+
Defined in FT_TRIGONOMETRY_H (fttrigon.h).

+
   FT_EXPORT( FT_Fixed )
   FT_Cos( FT_Angle  angle );
+

 
-

-

Return the cosinus of a given angle in fixed-point format.

-

-
input
-

- -
angle + +

input

+ +
angle

The input angle.

-
-
return
+ +

return

The cosinus value.

-
-
note
+ +

note

If you need both the sinus and cosinus for a given angle, use the function FT_Vector_Unit.

-
-
-
- - -
[Index][TOC]
- -
-

FT_Tan

-
-Defined in FT_TRIGONOMETRY_H (fttrigon.h). -

-
 
+

+
[Index][Top][TOC]

+
+

+
FT_Tan

+
Defined in FT_TRIGONOMETRY_H (fttrigon.h).

+
   FT_EXPORT( FT_Fixed )
   FT_Tan( FT_Angle  angle );
+

 
-

-

Return the tangent of a given angle in fixed-point format.

-

-
input
-

- -
angle + +

input

+ +
angle

The input angle.

-
-
return
+ +

return

The tangent value.

-
-
-
- - -
[Index][TOC]
- -
-

FT_Atan2

-
-Defined in FT_TRIGONOMETRY_H (fttrigon.h). -

-
 
+

+
[Index][Top][TOC]

+
+

+
FT_Atan2

+
Defined in FT_TRIGONOMETRY_H (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 + +

input

+ + -
x

The horizontal vector coordinate.

y +
y

The vertical vector coordinate.

-
-
return
+ +

return

The arc-tangent value (i.e. angle).

-
-
-
- - -
[Index][TOC]
- -
-

FT_Angle_Diff

-
-Defined in FT_TRIGONOMETRY_H (fttrigon.h). -

-
 
+

+
[Index][Top][TOC]

+
+

+
FT_Angle_Diff

+
Defined in FT_TRIGONOMETRY_H (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 + +

input

+ + -
angle1

First angle.

angle2 +
angle2

Second angle.

-
-
return
+ +

return

Constrained value of ‘value2-value1’.

-
-
-
- - -
[Index][TOC]
- -
-

FT_Vector_Unit

-
-Defined in FT_TRIGONOMETRY_H (fttrigon.h). -

-
 
+

+
[Index][Top][TOC]

+
+

+
FT_Vector_Unit

+
Defined in FT_TRIGONOMETRY_H (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 ‘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 + +

output

+ +
vec

The address of target vector.

-
-
input
-

- -
angle -

The address of angle.

+ +

input

+ +
angle +

The input angle.

-
-
-
- - -
[Index][TOC]
- -
-

FT_Vector_Rotate

-
-Defined in FT_TRIGONOMETRY_H (fttrigon.h). -

-
 
+

+
[Index][Top][TOC]

+
+

+
FT_Vector_Rotate

+
Defined in FT_TRIGONOMETRY_H (fttrigon.h).

+
   FT_EXPORT( void )
   FT_Vector_Rotate( FT_Vector*  vec,
                     FT_Angle    angle );
+

 
-

-

Rotate a vector by a given angle.

-

-
inout
-

- -
vec + +

inout

+ +
vec

The address of target vector.

-
-
input
-

- -
angle -

The address of angle.

+ +

input

+ +
angle +

The input angle.

-
-
-
- - -
[Index][TOC]
- -
-

FT_Vector_Length

-
-Defined in FT_TRIGONOMETRY_H (fttrigon.h). -

-
 
+

+
[Index][Top][TOC]

+
+

+
FT_Vector_Length

+
Defined in FT_TRIGONOMETRY_H (fttrigon.h).

+
   FT_EXPORT( FT_Fixed )
   FT_Vector_Length( FT_Vector*  vec );
+

 
-

-

Return the length of a given vector.

-

-
input
-

- -
vec + +

input

+ +
vec

The address of target vector.

-
-
return
+ +

return

The vector length, expressed in the same units that the original vector coordinates.

-
-
-
- - -
[Index][TOC]
- -
-

FT_Vector_Polarize

-
-Defined in FT_TRIGONOMETRY_H (fttrigon.h). -

-
 
+

+
[Index][Top][TOC]

+
+

+
FT_Vector_Polarize

+
Defined in FT_TRIGONOMETRY_H (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 + +

input

+ +
vec

The address of source vector.

-
-
output
-

- -
length + +

output

+ + -
length

The vector length.

angle +
angle

The vector angle.

-
-
-
- - -
[Index][TOC]
- -
-

FT_Vector_From_Polar

-
-Defined in FT_TRIGONOMETRY_H (fttrigon.h). -

-
 
+

+
[Index][Top][TOC]

+
+

+
FT_Vector_From_Polar

+
Defined in FT_TRIGONOMETRY_H (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 + +

output

+ +
vec

The address of source vector.

-
-
input
-

- -
length + +

input

+ + -
length

The vector length.

angle +
angle

The vector angle.

-
-
-
- - -
[Index][TOC]
+ +
+
[Index][Top][TOC]
-- cgit v1.2.3