fix.h

Tixys source code, include G.711, G.726, IMA-ADPCM etc.

/**
@file

@brief 32-Bit fixed-point maths routines

For latest source code see http://www.tixy.clara.net/source/

Copyright (C) 2004-2005 J.D.Medhurst (a.k.a. Tixy)

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*/

#ifndef __FIX_H__
#define __FIX_H__

/**
@defgroup fix Maths - 32bit Fixed-Point Maths

@brief Routines for performing 32bit fixed-point maths.

This code is targeted at CPUs without hardware support for division or floating point.
It has been optimised for ARM CPUs but should be suitable for other RISC architecures.
@{
*/

/**
A type representing a 32bit fixed-point number.
The binary point lies between bits 15 and 16.
*/
typedef int32 fix;

/**
A type representing a 32bit unsigned fixed-point number.
The binary point lies between bits 15 and 16.
*/
typedef uint32 ufix;

/**
A 32bit fixed-point value representing an angle.
Values are scaled by a factor of 1/(2*PI), i.e. a value of 1.0 (0x10000)
represents a full circle.
*/
typedef fix fixangle;


/**
@brief Fixed point arithmatic functions.

Operands are 32 bits in size with the binary point between bits 15 and 16.
@see fix
	 ufix
	 fixangle

@version 2005-02-26
	- Added Random(uint32& seed)
	- Added Random(uint32& seed,ufix range)
*/
class Fix
	{
public:
	/**
	Add two fixed-point numbers.
	Produces saturated result on overflow.

	@param a Augend
	@param b Addend

	@return  a+b. <BR>
			 If a+b>0x7FFF.FFFF then 0x7FFF.FFFF is returned. <BR>
			 If a+b<-0x8000.0000 then -0x8000.0000 is returned.
	*/
	IMPORT static fix Add(fix a,fix b);

	/**
	Subtract two fixed-point numbers.
	Produces saturated result on overflow.

	@param a Minuend
	@param b Subtrahend

	@return  a-b. <BR>
			 If a-b>0x7FFF.FFFF then 0x7FFF.FFFF is returned. <BR>
			 If a-b<-0x8000.0000 then -0x8000.0000 is returned.
	*/
	IMPORT static fix Sub(fix a,fix b);

	/**
	Multiply two fixed-point numbers.
	Produces saturated result on overflow.

	@param a Multiplicand
	@param b Multiplier

	@return  a*b. <BR>
			 If a*b>0x7FFF.FFFF then 0x7FFF.FFFF is returned. <BR>
			 If a*b<-0x8000.0000 then -0x8000.0000 is returned.

	@see MulNS()
	*/
	IMPORT static fix Mul(fix a,fix b);

	/**
	Multiply two fixed-point numbers.
	This is a Non-Saturating (and faster) version of Mul().
	On overflow the result is undefined.

	@param a Multiplicand
	@param b Multiplier

	@return	 a*b. <BR>
			 If a*b>0x7FFF.FFFF or a*b<-0x8000.0000 then the returned result is undefined.
	*/
	IMPORT static fix MulNS(fix a,fix b);

	/**
	Divide two fixed-point numbers.
	Produces saturated result on overflow.

	@param a Dividend
	@param b Divisor

	@return  a/b. <BR>
			 If a/b>0x7FFF.FFFF then 0x7FFF.FFFF is returned. <BR>
			 If a/b<-0x8000.0000 then -0x8000.0000 is returned. <BR>
			 If b==0 and a>=0 0x7FFF.FFFF  is returned. <BR>
			 If b==0 and a<0 -0x8000.0000 is returned. <BR>
	*/
	IMPORT static fix Div(fix a,fix b);

	/**
	Calculate the square root of a fixed-point number.

	@param a Unsigned fixed point number.

	@return  a^0.5.
	*/
	IMPORT static fix Sqrt(ufix a);

	/**
	Calculate the logarithm to base 2 of a fixed-point number .
	Accuracy is +/-8.40e-6 (+/-0.55 lsb).

	@param a Unsigned fixed point number.

	@return  log2(a). <BR>
			 If a==0 then -0x8000.0000 is returned
	*/
	IMPORT static fix Log2(ufix a);

	/**
	Raise 2 to-the-power of a fixed-point number, (2^a).
	Accuracy is +/-1.14e-5 (+/-0.75 lsb).

	@param a Fixed point number.

	@return  2^a. <BR>
			 If 2^a>0xFFFF.FFFF then 0xFFFF.FFFF is returned.
	*/
	IMPORT static ufix Exp2(fix a);

	/**
	Calculate the Sine of an angle.
	Accuracy is +/-8.55e-6 (+/-0.56 lsb).

	@param angle The angle.

	@return 	 The Sine of \a angle.
	*/
	IMPORT static fix Sin(fixangle angle);

	/**
	Calculate the Cosine of an angle.
	Accuracy is +/-8.55e-6 (+/-0.56 lsb).

	@param angle The angle.

	@return 	 The Cosine of \a angle.
	*/
	IMPORT static fix Cos(fixangle angle);

	/**
	Calculate the Tangent of an angle.
	Accuracy is +/-1.01e-5 (+/-0.66 lsb).

	@param angle The angle.

	@return 	 The Tangent of \a angle. <BR>
				 If Tan(\a angle)>0x7FFF.FFFF then 0x7FFF.FFFF is returned. <BR>
				 If Tan(\a angle)<-0x8000.0000 then -0x8000.0000 is returned.
	*/
	IMPORT static fix Tan(fixangle angle);

	/**
	Calculate the Arc-Sine of a value.
	Accuracy is +/-8.55e-6 (+/-0.56 lsb).

	@param value The value. Should be in the range -1.0 to 1.0 (-0x10000 to 0x10000).

	@return 	 The Arc-Sine of \a value. <BR>
				 If \a value<-1.0 then -0.25 (-0x4000) is returned. <BR>
				 If \a value>1.0 then 0.25 (0x4000) is returned.
	*/
	IMPORT static fixangle ASin(fix value);

	/**
	Calculate the Arc-Cosine of a value.
	Accuracy is +/-8.55e-6 (+/-0.56 lsb).

	@param value The value. Should be in the range -1.0 to 1.0 (-0x10000 to 0x10000).

	@return 	 The Arc-Cosine of \a value. <BR>
				 If \a value<-1.0 then 0.5 (0x8000) is returned. <BR>
				 If \a value>1.0 then 0.0 (0x0000) is returned.
	*/
	IMPORT static fixangle ACos(fix value);

	/**
	Calculate the Arc-Tangent of a value.
	Accuracy is +/-9.00e-6 (+/-0.59 lsb).

	@param value The value.

	@return 	 The Arc-Tangent of \a value.
	*/
	IMPORT static fixangle ATan(fix value);

	/**
	Generate a psuedo-random number.

	@param seed  A reference to the seed value. This will be updated after each call
				 to this function.

	@return		 A pseudo-random number

	@since 2005-02-26
	*/
	IMPORT static fix Random(uint32& seed);

	/**
	Generate a psuedo-random number.

	@param seed  A reference to the seed value. This will be updated after each call
				 to this function.
	@param range The range for the generated numbers.

	@return		 A pseudo-random number less than the value of \a range

	@since 2005-02-26
	*/
	IMPORT static ufix Random(uint32& seed,ufix range);
	};


/** @} */ // End of group

#endif