freetype2/freetype/fttrigon.h

0001 /****************************************************************************
0002  *
0003  * fttrigon.h
0004  *
0005  *   FreeType trigonometric functions (specification).
0006  *
0007  * Copyright (C) 2001-2023 by
0008  * David Turner, Robert Wilhelm, and Werner Lemberg.
0009  *
0010  * This file is part of the FreeType project, and may only be used,
0011  * modified, and distributed under the terms of the FreeType project
0012  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
0013  * this file you indicate that you have read the license and
0014  * understand and accept it fully.
0015  *
0016  */
0017
0018
0019 #ifndef FTTRIGON_H_
0020 #define FTTRIGON_H_
0021
0022 #include <freetype/freetype.h>
0023
0024 #ifdef FREETYPE_H
0025 #error "freetype.h of FreeType 1 has been loaded!"
0026 #error "Please fix the directory search order for header files"
0027 #error "so that freetype.h of FreeType 2 is found first."
0028 #endif
0029
0030
0031 FT_BEGIN_HEADER
0032
0033
0034   /**************************************************************************
0035    *
0036    * @section:
0037    *  computations
0038    *
0039    */
0040
0041
0042   /**************************************************************************
0043    *
0044    * @type:
0045    *   FT_Angle
0046    *
0047    * @description:
0048    *   This type is used to model angle values in FreeType.  Note that the
0049    *   angle is a 16.16 fixed-point value expressed in degrees.
0050    *
0051    */
0052   typedef FT_Fixed  FT_Angle;
0053
0054
0055   /**************************************************************************
0056    *
0057    * @macro:
0058    *   FT_ANGLE_PI
0059    *
0060    * @description:
0061    *   The angle pi expressed in @FT_Angle units.
0062    *
0063    */
0064 #define FT_ANGLE_PI  ( 180L << 16 )
0065
0066
0067   /**************************************************************************
0068    *
0069    * @macro:
0070    *   FT_ANGLE_2PI
0071    *
0072    * @description:
0073    *   The angle 2*pi expressed in @FT_Angle units.
0074    *
0075    */
0076 #define FT_ANGLE_2PI  ( FT_ANGLE_PI * 2 )
0077
0078
0079   /**************************************************************************
0080    *
0081    * @macro:
0082    *   FT_ANGLE_PI2
0083    *
0084    * @description:
0085    *   The angle pi/2 expressed in @FT_Angle units.
0086    *
0087    */
0088 #define FT_ANGLE_PI2  ( FT_ANGLE_PI / 2 )
0089
0090
0091   /**************************************************************************
0092    *
0093    * @macro:
0094    *   FT_ANGLE_PI4
0095    *
0096    * @description:
0097    *   The angle pi/4 expressed in @FT_Angle units.
0098    *
0099    */
0100 #define FT_ANGLE_PI4  ( FT_ANGLE_PI / 4 )
0101
0102
0103   /**************************************************************************
0104    *
0105    * @function:
0106    *   FT_Sin
0107    *
0108    * @description:
0109    *   Return the sinus of a given angle in fixed-point format.
0110    *
0111    * @input:
0112    *   angle ::
0113    *     The input angle.
0114    *
0115    * @return:
0116    *   The sinus value.
0117    *
0118    * @note:
0119    *   If you need both the sinus and cosinus for a given angle, use the
0120    *   function @FT_Vector_Unit.
0121    *
0122    */
0123   FT_EXPORT( FT_Fixed )
0124   FT_Sin( FT_Angle  angle );
0125
0126
0127   /**************************************************************************
0128    *
0129    * @function:
0130    *   FT_Cos
0131    *
0132    * @description:
0133    *   Return the cosinus of a given angle in fixed-point format.
0134    *
0135    * @input:
0136    *   angle ::
0137    *     The input angle.
0138    *
0139    * @return:
0140    *   The cosinus value.
0141    *
0142    * @note:
0143    *   If you need both the sinus and cosinus for a given angle, use the
0144    *   function @FT_Vector_Unit.
0145    *
0146    */
0147   FT_EXPORT( FT_Fixed )
0148   FT_Cos( FT_Angle  angle );
0149
0150
0151   /**************************************************************************
0152    *
0153    * @function:
0154    *   FT_Tan
0155    *
0156    * @description:
0157    *   Return the tangent of a given angle in fixed-point format.
0158    *
0159    * @input:
0160    *   angle ::
0161    *     The input angle.
0162    *
0163    * @return:
0164    *   The tangent value.
0165    *
0166    */
0167   FT_EXPORT( FT_Fixed )
0168   FT_Tan( FT_Angle  angle );
0169
0170
0171   /**************************************************************************
0172    *
0173    * @function:
0174    *   FT_Atan2
0175    *
0176    * @description:
0177    *   Return the arc-tangent corresponding to a given vector (x,y) in the 2d
0178    *   plane.
0179    *
0180    * @input:
0181    *   x ::
0182    *     The horizontal vector coordinate.
0183    *
0184    *   y ::
0185    *     The vertical vector coordinate.
0186    *
0187    * @return:
0188    *   The arc-tangent value (i.e. angle).
0189    *
0190    */
0191   FT_EXPORT( FT_Angle )
0192   FT_Atan2( FT_Fixed  x,
0193             FT_Fixed  y );
0194
0195
0196   /**************************************************************************
0197    *
0198    * @function:
0199    *   FT_Angle_Diff
0200    *
0201    * @description:
0202    *   Return the difference between two angles.  The result is always
0203    *   constrained to the ]-PI..PI] interval.
0204    *
0205    * @input:
0206    *   angle1 ::
0207    *     First angle.
0208    *
0209    *   angle2 ::
0210    *     Second angle.
0211    *
0212    * @return:
0213    *   Constrained value of `angle2-angle1`.
0214    *
0215    */
0216   FT_EXPORT( FT_Angle )
0217   FT_Angle_Diff( FT_Angle  angle1,
0218                  FT_Angle  angle2 );
0219
0220
0221   /**************************************************************************
0222    *
0223    * @function:
0224    *   FT_Vector_Unit
0225    *
0226    * @description:
0227    *   Return the unit vector corresponding to a given angle.  After the
0228    *   call, the value of `vec.x` will be `cos(angle)`, and the value of
0229    *   `vec.y` will be `sin(angle)`.
0230    *
0231    *   This function is useful to retrieve both the sinus and cosinus of a
0232    *   given angle quickly.
0233    *
0234    * @output:
0235    *   vec ::
0236    *     The address of target vector.
0237    *
0238    * @input:
0239    *   angle ::
0240    *     The input angle.
0241    *
0242    */
0243   FT_EXPORT( void )
0244   FT_Vector_Unit( FT_Vector*  vec,
0245                   FT_Angle    angle );
0246
0247
0248   /**************************************************************************
0249    *
0250    * @function:
0251    *   FT_Vector_Rotate
0252    *
0253    * @description:
0254    *   Rotate a vector by a given angle.
0255    *
0256    * @inout:
0257    *   vec ::
0258    *     The address of target vector.
0259    *
0260    * @input:
0261    *   angle ::
0262    *     The input angle.
0263    *
0264    */
0265   FT_EXPORT( void )
0266   FT_Vector_Rotate( FT_Vector*  vec,
0267                     FT_Angle    angle );
0268
0269
0270   /**************************************************************************
0271    *
0272    * @function:
0273    *   FT_Vector_Length
0274    *
0275    * @description:
0276    *   Return the length of a given vector.
0277    *
0278    * @input:
0279    *   vec ::
0280    *     The address of target vector.
0281    *
0282    * @return:
0283    *   The vector length, expressed in the same units that the original
0284    *   vector coordinates.
0285    *
0286    */
0287   FT_EXPORT( FT_Fixed )
0288   FT_Vector_Length( FT_Vector*  vec );
0289
0290
0291   /**************************************************************************
0292    *
0293    * @function:
0294    *   FT_Vector_Polarize
0295    *
0296    * @description:
0297    *   Compute both the length and angle of a given vector.
0298    *
0299    * @input:
0300    *   vec ::
0301    *     The address of source vector.
0302    *
0303    * @output:
0304    *   length ::
0305    *     The vector length.
0306    *
0307    *   angle ::
0308    *     The vector angle.
0309    *
0310    */
0311   FT_EXPORT( void )
0312   FT_Vector_Polarize( FT_Vector*  vec,
0313                       FT_Fixed   *length,
0314                       FT_Angle   *angle );
0315
0316
0317   /**************************************************************************
0318    *
0319    * @function:
0320    *   FT_Vector_From_Polar
0321    *
0322    * @description:
0323    *   Compute vector coordinates from a length and angle.
0324    *
0325    * @output:
0326    *   vec ::
0327    *     The address of source vector.
0328    *
0329    * @input:
0330    *   length ::
0331    *     The vector length.
0332    *
0333    *   angle ::
0334    *     The vector angle.
0335    *
0336    */
0337   FT_EXPORT( void )
0338   FT_Vector_From_Polar( FT_Vector*  vec,
0339                         FT_Fixed    length,
0340                         FT_Angle    angle );
0341
0342   /* */
0343
0344
0345 FT_END_HEADER
0346
0347 #endif /* FTTRIGON_H_ */
0348
0349
0350 /* END */