Allegro.pas 4.4Introduction Units Class Hierarchy Classes, Interfaces, Objects and Records Types Variables Constants Functions and Procedures Identifiers Examples, tools and demo game
|
Unit alFixed
Description
Fixed point math routines
Allegro provides some routines for working with fixed point numbers, and defines the type AL_FIXED to be a signed 32-bit integer. The high word is used for the integer part and the low word for the fraction, giving a range of -32768 to 32767 and an accuracy of about four or five decimal places. Fixed point numbers can be assigned, compared, added, subtracted, negated and shifted (for multiplying or dividing by powers of two) using the normal integer operators, but you should take care to use the appropriate conversion routines when mixing fixed point with integer or floating point values. Writing fixed_point_1 + fixed_point_2 is 0K, but fixed_point + integer is not.
One of the advantage of fixed point math routines is that you don't require a floating point coprocessor to use them. This was great in the time period of i386 and i486 machines, but stopped being so useful with the coming of the Pentium class of processors. From Pentium onwards, CPUs have increased their strength in floating point operations, equaling or even surpassing integer math performance. Other advantage is the use of fixed point indexes to arrays, wich would be faster than floating point.
Depending on the type of operations your program may need, using floating point types may be faster than fixed types if you are targeting a specific machine class. Allegro comes with a test program in the `allegro/tests' directory. Its `Misc' menu contains a basic profile test which can give you an idea of the speed difference between fixed and float types for a few basic operations on your machine. However, don't forget to profile your program in real life conditions, tight loop benchmarks are after all artificial.
The fixed point square root, sin, cos, tan, inverse sin, and inverse cos functions are implemented using lookup tables, which are very fast but not particularly accurate. At the moment the inverse tan uses an iterative search on the tan table, so it is a lot slower than the others. Note that on machines with very good floating point processors using these functions could be slower in real life code due to cache misses: it may be faster to wait a few extra cicles for a floating point sine result rather than wait for the CPU to fetch the precalculated table from main memory. Always profile your code.
Angles are represented in a binary format with 256 equal to a full circle, 64 being a right angle and so on. This has the advantage that a simple bitwise AND can be used to keep the angle within the range zero to a full circle, eliminating all those tiresome IF angle >= 360 checks.
Fixed point math is considered "add-on" material and is kept only for backwards compatibility. Whenever a future release of Allegro breaks backwards compatibility, fixed point math will likely be moved to a separate add-on package for the very few users who still find it convenient and useful, and Allegro functions using fixed point math will use other types.
Overview
Functions and Procedures
Types
Constants
Description
Functions and Procedures
FUNCTION al_itofix (x: AL_INT): AL_FIXED; INLINE; |
|
Converts an integer to fixed point. This is the same thing as x SHL 16. Remember that overflows (trying to convert an integer greater than 32767) and underflows (trying to convert an integer lesser than -32768) are not detected even in debug builds! The values simply "wrap around".
|
FUNCTION al_fixtoi (x: AL_FIXED): AL_INT; INLINE; |
|
Converts fixed point to integer, rounding as required to the nearest integer.
|
FUNCTION al_ftofix (x: AL_DOUBLE): AL_FIXED; INLINE; |
|
Converts a floating point value to fixed point. Unlike al_itofix, this function clamps values which could overflow the type conversion, setting al_errno to non-zero in the process if this happens.
|
FUNCTION al_fixtof (x: AL_FIXED): AL_DOUBLE; INLINE; |
|
Converts fixed point to floating point.
|
FUNCTION al_fixadd (x, y: AL_FIXED): AL_FIXED; INLINE; |
|
Safe function to add fixed point numbers clamping overflow.
Although fixed point numbers can be added with the normal '+' integer operator, that doesn't provide any protection against overflow. If overflow is a problem, you should use this function instead. It is slower than using integer operators, but if an overflow occurs it will set al_errno and clamp the result, rather than just letting it wrap.
|
FUNCTION al_fixsub (x, y: AL_FIXED): AL_FIXED; INLINE; |
|
Safe function to subtract fixed point numbers clamping underflow.
Although fixed point numbers can be substracted with the normal 'x' integer operator, that doesn't provide any protection against overflow. If overflow is a problem, you should use this function instead. It is slower than using integer operators, but if an overflow occurs it will set al_errno and clamp the result, rather than just letting it wrap.
|
FUNCTION al_fixmul (x, y: AL_FIXED): AL_FIXED; INLINE; |
|
A fixed point value can be multiplied or divided by an integer with the normal `*' and `/' operators. To multiply two fixed point values, though, you must use this function.
If an overflow occurs, al_errno will be set and the maximum possible value will be returned, but al_errno is not cleared if the operation is successful. This means that if you are going to test for overflow you should set al_errno := 0 before calling al_fixmul.
|
FUNCTION al_fixdiv (x, y: AL_FIXED): AL_FIXED; INLINE; |
|
A fixed point value can be divided by an integer with the normal `/' and DIV operators. To divide two fixed point values, though, you must use this function.
If an overflow occurs, al_errno will be set and the maximum possible value will be returned, but al_errno is not cleared if the operation is successful. This means that if you are going to test for overflow you should set al_errno := 0 before calling al_fixdiv.
|
FUNCTION al_fixsqrt (x: AL_FIXED): AL_FIXED; CDECL; EXTERNAL ALLEGRO_SHARED_LIBRARY_NAME NAME 'fixsqrt'; |
|
This finds out the non negative square root of `x'. If `x' is negative, al_errno is set to EDOM and the function returns zero.
|
FUNCTION al_fixsin (x: AL_FIXED): AL_FIXED; INLINE; |
|
This function finds the sine of a value using a lookup table.
|
FUNCTION al_fixcos (x: AL_FIXED): AL_FIXED; INLINE; |
|
This function finds the cosine of a value using a lookup table.
|
FUNCTION al_fixtan (x: AL_FIXED): AL_FIXED; INLINE; |
|
This function finds the tangent of a value using a lookup table.
|
FUNCTION al_fixasin (x: AL_FIXED): AL_FIXED; INLINE; |
|
This function finds the inverse sine of a value using a lookup table.
|
FUNCTION al_fixacos (x: AL_FIXED): AL_FIXED; INLINE; |
|
This function finds the inverse cosine of a value using a lookup table.
|
FUNCTION al_fixhypot (x, y: AL_FIXED): AL_FIXED; CDECL; EXTERNAL ALLEGRO_SHARED_LIBRARY_NAME NAME 'fixhypot'; |
|
Fixed point hypotenuse (returns the square root of `x*x + y*y'). This should be better than calculating the formula yourself manually, since the error is much smaller.
|
FUNCTION al_fixatan (x: AL_FIXED): AL_FIXED; CDECL; EXTERNAL ALLEGRO_SHARED_LIBRARY_NAME NAME 'fixatan'; |
|
This function finds the inverse tangent of a value using a lookup table.
|
FUNCTION al_fixatan2 (x, y: AL_FIXED): AL_FIXED; CDECL; EXTERNAL ALLEGRO_SHARED_LIBRARY_NAME NAME 'fixatan2'; |
|
This is a fixed point version of the libc atan2 () routine.
|
Types
AL_FIXEDptr = ˆAL_FIXED; |
|
Pointer to AL_FIXED.
|
AL_FIXED = AL_INT32; |
|
This is a fixed point integer which can replace float with similar results and is faster than float on low end machines.
|
Constants
al_fixpi: AL_FIXED = 205887; |
|
Fixed point PI value. Note that this is not used by this unit or Allegro, since Allegro uses binary angles (full circle is 256 degrees).
|
al_fixtorad: AL_FIXED = 1608; |
|
This constant gives a ratio which can be used to convert a fixed point number in binary angle format to a fixed point number in radians.
|
al_radtofix: AL_FIXED = 2670177; |
|
This constant gives a ratio which can be used to convert a fixed point number in radians to a fixed point number in binary angle format.
|
Generated by PasDoc 0.13.0 on 2016-07-20 12:01:35
|