The SGADE Documentation

the SGADE The Socrates Gameboy Advance Development Engine

The SGADE is a development library for the Nintendo Gameboy Advance. It's free for all uses and is distributed without guarantees. For more information visit the SGADE page.

Main Page   Modules   Data Structures   File List   Data Fields   Globals   Related Pages  

SoMath

All math related stuff. More...

Files

file  SoMath.c
file  SoMath.h

Defines

#define SO_FIXED_Q
 Number of bits reserved for the fraction in fixed point numbers.

#define SO_FIXED_PI
 PI a.k.a. 3.14 etc. in a fixed point format.

#define SO_MIN(x, y)
 Returns the minimum of a pair of numbers.

#define SO_MAX(x, y)
 Returns the maximum of a pair of numbers.

#define SO_ABS(x)
 Returns the absolute value of a number.

#define SO_NUMBER_IS_EVEN(n)
 Evaluates to true when a number is even, false otherwise.

#define SO_NUMBER_IS_UNEVEN(n)
 Evaluates to false when a number is even, true otherwise.

#define SO_FIXED_FROM_WHOLE(n)
 Converts a whole (integer) number to a fixedpoint number.

#define SO_FIXED_TO_WHOLE(n)
 Converts a fixed point number to a whole number. Cuts of the fraction.

#define SO_FIXED_FROM_FLOAT(n)
 Converts a whole number to a fixedpoint number.

#define SO_FIXED_TO_FLOAT(n)
 Converts a fixed point number to a whole number.

#define SO_FIXED_TO_FRACTION(n)
 Leaves only the fraction of a fixed point number.

#define SO_FIXED_MAKE_WHOLE(n)
 Makes a fixed point number whole.

#define SO_FIXED_CEIL_WHOLE(n)
 Returns the whole ceiling of the fixed point number.

#define SO_FIXED_TO_N_8_FORMAT(n)
 Converts our fixed point format to a 24.8 format.

#define SO_FIXED_MULTIPLY_SMALL_SMALL(n, m)
 NOTE: all of the SO_FIXED_MULTIPLY_* macros are very sensitive to input data.

#define SO_FIXED_MULTIPLY_BIG_SMALL(big, small)
 Multiply macro to multiply a relatively small fixed point number by a relatively big one.

#define SO_FIXED_MULTIPLY(n, m)
 Multiply macro to multiply two fixed point numbers.

#define SO_FIXED_DIVIDE_SMALL_BIG(n, m)
 Divide macro to divide a small fixed number by a big fixed point number.

#define SO_FIXED_DIVIDE(n, m)
 Divide macro to divide a fixed point number by another fixed point number.

#define SO_FIXED_ONE_OVER_FAST_INACCURATE(n)
 One-over macro that uses a repricocal-table.

#define SO_FIXED_ONE_OVER_SLOW_ACCURATE(n)
 Macro to calculate one-over-N the slow and accurate way.

#define SO_SINE(n)
 Returns the fixed point sine of an angle. A full circle is 256 degrees.

#define SO_COSINE(n)
 Returns the fixed point cosine of an angle.


Functions

sofixedpoint SoMathFixedMultiply (sofixedpoint a_A, sofixedpoint a_B)
 Fixed-point multiplication function.

sofixedpoint SoMathFixedMultiplyByFraction (sofixedpoint a_A, sofixedpoint a_B)
 Fixed-point multiplication by fraction function.

sofixedpoint SoMathFixedSqrt (sofixedpoint a_FixedValue)
 Squareroot function.

void SoMathRandSeed (u32 a_Seed)
 Seeds the random number generator.

u32 SoMathRand (void)
 Returns a pseudo random number.

s32 SoMathDivideAndModulus (s32 a_Numerator, s32 a_Denominator, s32 *a_Remainder)
 Fast divide and modulus function.

s32 SoMathModulus (s32 a_Numerator, s32 a_Denominator)
 Fast modulus function.

s32 SoMathDivide (s32 a_Numerator, s32 a_Denominator)
 Fast divide function.

Detailed Description

All math related stuff.

Singleton

This file contains all math related stuff. It has a couple of constants, fixed point macros, precalculated sine and cosine tables, a pseudo random number generator and some math functions.

Define Documentation

#define SO_COSINE (  n    ) 
 

Returns the fixed point cosine of an angle.

A full circle is 256 degrees. See SO_SINE for more information.

#define SO_FIXED_FROM_FLOAT (  n    ) 
 

Converts a whole number to a fixedpoint number.

Warning:
Slow, so please avoid floats

#define SO_FIXED_MULTIPLY_SMALL_SMALL (  n,
m    ) 
 

NOTE: all of the SO_FIXED_MULTIPLY_* macros are very sensitive to input data.

They can easily overflow, so use with extreme caution.

Multiply macro to multiply two relatively small fixed point numbers.

#define SO_FIXED_ONE_OVER_FAST_INACCURATE (  n    ) 
 

One-over macro that uses a repricocal-table.

This can only be used when the denominator is a positive number smaller than SO_ONE_OVER_N_MAX_N. Be carefull with this one, and only use it if you understand its limitations.

#define SO_FIXED_ONE_OVER_SLOW_ACCURATE (  n    ) 
 

Macro to calculate one-over-N the slow and accurate way.

Well, slow. Uses a bios SWI call for faster divides.

#define SO_FIXED_Q
 

Number of bits reserved for the fraction in fixed point numbers.

We use a N.Q fixed point format where Q is the number of bits for the fraction.

Notice that some of the macros below rely heavily (hardcoded) on Q. This means that if you change this number, you will have to change these macros as well as some hardcoded stuff in some assembly code.

If you change this macro, then an assertion is triggered during compilation of the SoSystem.c file to remind you about this.

#define SO_FIXED_TO_FLOAT (  n    ) 
 

Converts a fixed point number to a whole number.

Cuts of the fraction.

Warning:
Very slow cause it uses a divide.

#define SO_SINE (  n    ) 
 

Returns the fixed point sine of an angle. A full circle is 256 degrees.

Parameters:
n  Any 32 bits value.
Because we are using a 256-degree system we can do an easy and fast modulus by bitwise-anding with 0xFF. Therefore we can use any angle. Negative, positive and beyond the 256 range.

Some examples: 

        SO_SINE( 256 ) == SO_SINE( 0 ) == SO_SINE( -256 ) == SO_SINE( 1024 )

        SO_COSINE( 64 ) == SO_COSINE( -192 )

Function Documentation

s32 SoMathDivide (  s32    a_Numerator,
s32    a_Denominator
) 
 

Fast divide function.

Parameters:
a_Numerator  Whole numerator.
a_Denominator  Whole denominator.
Returns :
a_Numerator divided by a_Denominator (whole format).
Divide function that uses an SWI (bios) call instead of the slow software emulated divide. However, note that it's still faster to use the g_OneOver table also availabe in the SoMath module.

Note, that in order to use this on an emulator you need a bios that supports SWI 6 calls;

s32 SoMathDivideAndModulus (  s32    a_Numerator,
s32    a_Denominator,
s32 *    a_Remainder
) 
 

Fast divide and modulus function.

Parameters:
a_Numerator  Whole numerator.
a_Denominator  Whole denominator.
Returns :
a_Numerator divided by a_Denominator (whole format).
Return values:
a_Remainder  a_Numerator modulus a_Denominator.
Divide function that uses an SWI (bios) call instead of the slow software emulated divide. However, note that it's still faster to use the g_OneOver table also availabe in the SoMath module.

Because sometimes you also need them modulus at the same time, and it's a by-product of the divide, you can use this routine if you need both.

Note, that in order to use this on an emulator you need a bios that supports SWI 6 calls;

sofixedpoint SoMathFixedMultiply (  sofixedpoint    a_A,
sofixedpoint    a_B
) 
 

Fixed-point multiplication function.

Parameters:
a_A  Fixed point number A
a_B  Fixed point number B
Returns :
The fixed point multiple of a_A * a_B
Safe fixed point multiplication routine. This routine will return the most accurate representation of the multiplied number as long as it fits within the limits of the fixed point number range.

sofixedpoint SoMathFixedMultiplyByFraction (  sofixedpoint    a_A,
sofixedpoint    a_B
) 
 

Fixed-point multiplication by fraction function.

Parameters:
a_A  Fixed point number A
a_B  Fractional fixed point number B (less than one)
Returns :
The fixed point multiple of a_A * a_B
Safe fixed point multiplication routine. This routine multiplies an arbitrary fixed point number by a fractional fixed point number. This routine will only work if the SO_FIXED_Q value is less than or equal to 16. This routine will return the most accurate representation of the multiplied number.

sofixedpoint SoMathFixedSqrt (  sofixedpoint    a_FixedValue ) 
 

Squareroot function.

Parameters:
a_FixedValue  Some fixedpoint number in the range [0...64K] (+ the fraction ofcourse) Note that the number is always treated as unsigned.;
Returns :
The fixed point squareroot of a_FixedValue.
Warning:
This routine is not very precise, but for my purposes it gets the job done. It might suit your needs too, but just be carefull when using it.

Todo:
Replace with another version of that provides as many bits of accuracy as possible (i.e. no ending shift).

Squareroot method taken from the internet. No credits were given. If you think this is your routine and I stole it, let me know and I'll give you credit.

This was originally a squareroot function for integer math, but I adapted it to work for fixed point math. I don't know whether this is the fastest way, but it works. I don't want to spend more thinking on it anyway, cause you shouldn't be doing squareroots at runtime anyway.

s32 SoMathModulus (  s32    a_Numerator,
s32    a_Denominator
) 
 

Fast modulus function.

Parameters:
a_Numerator  Whole numerator.
a_Denominator  Whole denominator.
Returns :
a_Numerator modulus a_Denominator.
Modulus function that uses an SWI (bios) call instead of the slow software emulated modulus.

Note, that in order to use this on an emulator you need a bios that supports SWI 6 calls;

u32 SoMathRand (  void    )  [inline]
 

Returns a pseudo random number.

Returns :
A 32 bits random number
Pseudo random number generator based on the Mersenne Twister. It's implementation is taken from the internet and changed to adapt my code style. Credits go to Shawn J.Cokus.

void SoMathRandSeed (  u32    a_Seed ) 
 

Seeds the random number generator.

Parameters:
a_Seed  Any 32 bits number can be used.
Pseudo random number generator based on the Mersenne Twister. To obtain a good seed, I suggest you take some user-input based number (which is very pseudo-random), for example the amount of milliseconds elapsed since the Gameboy Advance was turned on, until the user pressed start.

Copyright 2002 by the SGADE authors. See SoLicense.h or Visit the SGADE page for more information.