# HG changeset patch
# User celestar
# Date 1173195054 0
# Node ID f8302fbd236da012705efc514a816d4bc8f9471a
# Parent  11068d5559048c4acd3f16a4e6045b4cd47e098b
(svn r9026) [gamebalance] -Add: Added a new data type that allows fixed-point computations, as to enable computing non-integral numbers without worrying about the FPU rounding differences and, thus, desyncs. It is fully doxygenned, read the usage there. Thanks a bunch to KUDr for helping me with templates

diff -r 11068d555904 -r f8302fbd236d Doxyfile
--- a/Doxyfile	Tue Mar 06 15:09:50 2007 +0000
+++ b/Doxyfile	Tue Mar 06 15:30:54 2007 +0000
@@ -89,7 +89,7 @@
 EXCLUDE                =
 EXCLUDE_SYMLINKS       = NO
 EXCLUDE_PATTERNS       =
-EXAMPLE_PATH           =
+EXAMPLE_PATH           = docs/examples
 EXAMPLE_PATTERNS       = *
 EXAMPLE_RECURSIVE      = NO
 IMAGE_PATH             =
diff -r 11068d555904 -r f8302fbd236d docs/examples/fixed_ex.cpp
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/examples/fixed_ex.cpp	Tue Mar 06 15:30:54 2007 +0000
@@ -0,0 +1,22 @@
+/* $Id */
+
+#include "fixedt.h"
+
+int main()
+{
+	/* a is a Fixed-Point variable with 48 integral bits
+	 * and 16 fractional bits, automatically set to zero
+	 */
+	FixedT<int64, 16> a;
+
+	/* Assuming int is 32 bits, gives a variable of 23
+	 * integral bits and 9 fractional bits, initialized
+	 * to -4
+	 */
+	FixedT<int, 9> b = -4;
+
+	/* A Variable set to a non-integral number
+	 * in this case, -12.8
+	 */
+	FixedT<long int, 12> c(-128, 10);
+}
diff -r 11068d555904 -r f8302fbd236d src/fixedt.h
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/fixedt.h	Tue Mar 06 15:30:54 2007 +0000
@@ -0,0 +1,303 @@
+/* $Id */
+
+/**
+ * @file
+ * Implements a Fixed-point data type.
+ * This files defines a new data type
+ * "FixedT<Tstorage, Tdec_bits>", which can be used to compute fractional
+ * numbers without having to worry about network stability (because
+ * there is no real rounding taking place.
+ * Use "Fixed" for the defaults values (48 bits integral part, 16 bits
+ * fractional part) or "FixedT<typename, int>" for flexible sizes. "int"
+ * number of bits are taken from a variable of "typename" for the fractional
+ * representation, the rest stays available for the integral part.
+ * @warning More than 16 bits fractional should not be used when working
+ * with large integers.
+ * @warning More than 31 fractional bits are not supported, and will
+ * trigger a compiler warning with appropriate settings.
+ * @warning There are no warnings for buffer overflows. Those are very likely
+ * to happen with divisions, as those first shift the numerator by the number
+ * of fractional bits. Use multiplication with the reciprocal whereever
+ * it is possible.
+ * @warning Please use signed variables for storage at the moment ONLY
+ *
+ * Variables can be initialized:
+ * 	- with integers: "FixedT<int, 9> a = -5"
+ * 	- with fractionals: "FixedT<int64, 11> b(7, 2);" where the first number is
+ * the numerator and the second is the denominator.
+ * 	- not at all: "Fixed c;", which will automatically set c to zero.
+ *
+ * @example fixed_ex.cpp How to initialize Fixed-point data types
+ */
+
+/* Included to overload the stream operator << */
+#include <iostream>
+/* Needed for some ottd-specific data types */
+#include "stdafx.h"
+
+/**
+ * Base Class for storing fixed-point data types.
+ * Fixed-point data types are stored in a single integer-type variable
+ * (Tstorage) of which a certain number of bits (Tdec_bits) is used to
+ * represent the fractional part of the number.
+ */
+template <typename Tstorage, int Tdec_bits>
+class FixedRawT {
+public:
+	/** The number of bits that represent the fractional */
+	static const int dec_bits = Tdec_bits;
+
+	/** The storage of the number itself */
+	Tstorage m_data;
+
+	/**
+	 * Basic constructor for integer arguments.
+	 * @param value The raw value to which we want to initialize
+	 */
+	template <typename T>
+	FixedRawT(T value) : m_data(value) {}
+
+	/**
+	 * Make sure that a Fixed variable is always inizialized to zero by default.
+	 * We need this ctor so that we can declare variable without
+	 * the need to initialize it explicitly
+	 */
+	FixedRawT() : m_data (0) {}
+
+	/**
+	 * Returns the biggest integral number we can represent
+	 */
+	int64 FIXED_MAX() const { return m_maximum; }
+
+	/**
+	 * Returns the biggest integral number we can represent
+	 */
+	int64 FIXED_MIN() const { return m_minimum; }
+
+private:
+	/** The largest number we can hold */
+	static const int64 m_maximum = +(1ULL << ((sizeof(Tstorage) * 8) - Tdec_bits - 1)) - 1;
+
+	/** The smallest number we can hold */
+	static const int64 m_minimum = -(1ULL << ((sizeof(Tstorage) * 8) - Tdec_bits - 1)) - 0;
+};
+
+/* forward-declare some structs */
+template <typename Tstorage, int Tdec_bits> class FixedT;
+template <typename T> struct FixedHelperT;
+
+/**
+ * Specialization of FixedHelperT. Used to decimal-align two variables of Fixed type.
+ */
+template <typename Tstorage, int Tdec_bits> struct FixedHelperT<FixedRawT<Tstorage, Tdec_bits> >
+{
+	/** The number of bits used for the fraction */
+	static const int dec_bits = Tdec_bits;
+
+	/**
+	 * Gives the raw data of a FixedRaw
+	 * @param t The number to return
+	 */
+	static int64 Raw(const FixedRawT<Tstorage, Tdec_bits>& t) {return (int64)t.m_data;}
+
+	/**
+	 * Returns the data from FixedRawT aligned so that it is aligned to a given number
+	 * @param t    The number to be aligned
+	 * @param bits The number of bits in the fractional part to be aligned to
+	 */
+	static int64 Raw(const FixedRawT<Tstorage, Tdec_bits>& t, int bits)
+	{
+		return (((int64)t.m_data) << (bits > Tdec_bits ? bits - Tdec_bits : 0)) >> (bits < Tdec_bits ? Tdec_bits - bits : 0);
+	}
+};
+
+/**
+ * Specialization of FixedHelperT. Used to decimal-align two variables of Fixed type.
+ */
+template <typename Tstorage, int Tdec_bits> struct FixedHelperT<FixedT<Tstorage, Tdec_bits> > : public FixedHelperT<FixedRawT<Tstorage, Tdec_bits> > {};
+
+/**
+ * General implementation of FixedHelperT. This tempate makes sure that
+ * some number supplied is properly aligned at the decimal
+ */
+template <typename T> struct FixedHelperT
+{
+	/** This version of FixedHelperT is only used for full integers, so assume the number of dec_bits to be zero */
+	static const int dec_bits = 0;
+	/** Converts a full integer to one that has a given number of fractional bits, assumes
+	 * the number of fractional bits to be zero.
+	 * @param t the number to be converted
+	 */
+	static int64 Raw(const T& t) {return (int64)t;}
+
+	/**
+	 * Converts a full integer to one that has a given number of fractional bits
+	 * @param bits the number of bits for the fraction
+	 * @param t    the number to be converted
+	 */
+	static int64 Raw(const T& t, int bits) {return ((int64)t) << bits;}
+};
+
+
+
+/**
+ * A class that defines a fixed-point data type, which a variable length and precision.
+ * The data type that is defined is a fixed-point variable that has and number of Tdec_bits
+ * bits to represent the fractional part, the remaining bits of Tstorage are then used for
+ * the integer part of the number. This means, we always need to make a trade-off between
+ * the precision we want (higher number in Tdec_bits) and the range (smaller number of
+ * Tdec_bits). This class here only defines the constructors and the operators, everything
+ * else is happning in helper classes.
+ * @note for usage of fprintf and similar, explicit casts are needed (double or int64).
+ */
+template <typename Tstorage, int Tdec_bits> class FixedT : public FixedRawT<Tstorage, Tdec_bits> {
+/* private block up here, because we need the typedef later on */
+private:
+	/** We shortcut the underlying data type to "Raw", to save typing */
+	typedef FixedRawT<Tstorage, Tdec_bits> Raw;
+
+public:
+	/**
+	 * Ctor for assignment with other, non floating, variable types
+	 * @param value The Value we should assign to the Fixed
+	 */
+	template <typename T> FixedT(T value) : Raw(FixedHelperT<T>::Raw(value, Tdec_bits)) {}
+
+	/** As a constructor without initializing, just use the one that Raw uses. Sets a variable to zero */
+	FixedT() : Raw() {}
+
+	/**
+	 * Ctor for use with a fraction, useful for initing a variable to a non-integer number at declaration.
+	 * @param numerator   The Nominator of the fraction
+	 * @param denominator The Denominator of the fraction
+	 */
+	FixedT(int numerator, int denominator) {Raw::m_data = ((int64)numerator << Raw::dec_bits) / (int64)denominator;}
+
+	/**
+	 * Equality operator
+	 * @param comparator The non-floating point variable we want to compare against
+	 */
+	template <typename T>
+	bool operator ==(const T &comparator) const { return Raw::m_data == (Tstorage)FixedHelperT<T>::Raw(comparator, Tdec_bits); }
+
+	/**
+	 * Inequality operator
+	 * @param comparator The non-floating point variable we want to compare against
+	 */
+	template <typename T>
+	bool operator !=(const T &comparator) const { return Raw::m_data != (Tstorage)FixedHelperT<T>::Raw(comparator, Tdec_bits); }
+
+	/**
+	 * Greater or equal operator
+	 * @param comparator The non-floating point variable we want to compare against
+	 */
+	template <typename T>
+	bool operator >=(const T &comparator) const { return Raw::m_data >= (Tstorage)FixedHelperT<T>::Raw(comparator, Tdec_bits); }
+
+	/**
+	 * Less or equal operator
+	 * @param comparator The non-floating point variable we want to compare against
+	 */
+	template <typename T>
+	bool operator <=(const T &comparator) const { return Raw::m_data <= (Tstorage)FixedHelperT<T>::Raw(comparator, Tdec_bits); }
+
+	/**
+	 * Greater than operator
+	 * @param comparator The non-floating point variable we want to compare against
+	 */
+	template <typename T>
+	bool operator >(const T &comparator) const { return Raw::m_data > (Tstorage)FixedHelperT<T>::Raw(comparator, Tdec_bits); }
+
+	/**
+	 * Less than operator
+	 * @param comparator The non-floating point variable we want to compare against
+	 */
+	template <typename T>
+	bool operator <(const T &comparator) const { return Raw::m_data < (Tstorage)FixedHelperT<T>::Raw(comparator, Tdec_bits); }
+
+	/**
+	 * Addition for Fixed-point data types
+	 * @param value The non-floating point number to add
+	 */
+	template <typename T> FixedT operator +(const T &value) const
+	{
+		return Raw(Raw::m_data + (Tstorage)FixedHelperT<T>::Raw(value, Tdec_bits));
+	}
+
+	/**
+	 * Subtraction for Fixed-point data types
+	 * @param value The non-floating point number to subtract
+	 */
+	template <typename T> FixedT operator -(const T &value) const
+	{
+		return Raw(Raw::m_data - (Tstorage)FixedHelperT<T>::Raw(value, Tdec_bits));
+	}
+
+	/**
+	 * A simple multiplication for non-floating data types
+	 * @param value The non floating-point factor
+	 */
+	template <typename T> FixedT operator *(const T &value) const
+	{
+		return Raw( (((int64)Raw::m_data) * FixedHelperT<T>::Raw(value)) >> FixedHelperT<T>::dec_bits);
+	}
+
+	/**
+	 * A simple division for non-floating data types
+	 * @param value The non floating-point divisor
+	 */
+	template <typename T> FixedT operator /(const T &value) const
+	{
+		return Raw( (((int64)Raw::m_data) << FixedHelperT<T>::dec_bits) / FixedHelperT<T>::Raw(value));
+	}
+
+	/**
+	 * Addition-assignment for Fixed-point data types
+	 * @param value The non-floating point number to add
+	 */
+	template <typename T> FixedT& operator +=(const T &value)
+	{
+		Raw::m_data = Raw::m_data + (Tstorage)FixedHelperT<T>::Raw(value, Tdec_bits);
+		return *this;
+	}
+
+	/**
+	 * Subtract-assignment for Fixed-point data types
+	 * @param value The non-floating point number to subtract
+	 */
+	template <typename T> FixedT& operator -=(const T &value)
+	{
+		Raw::m_data = Raw::m_data - (Tstorage)FixedHelperT<T>::Raw(value, Tdec_bits);
+		return *this;
+	}
+
+	/**
+	 * Multiply-assignment for Fixed-point data types
+	 * @param value The non-floating point number to multiply
+	 */
+	template <typename T> FixedT& operator *=(const T &value)
+	{
+		Raw::m_data = (Raw::m_data * (Tstorage)FixedHelperT<T>::Raw(value)) >> FixedHelperT<T>::dec_bits;
+		return *this;
+	}
+
+	/**
+	 * Divide-assignment for Fixed-point data types
+	 * @param value The non-floating point number to use as divisor
+	 */
+	template <typename T> FixedT& operator /=(const T &value)
+	{
+		Raw::m_data = (Raw::m_data << FixedHelperT<T>::dec_bits) / (Tstorage)FixedHelperT<T>::Raw(value);
+		return *this;
+	}
+
+	/**
+	 * Stream operator, used for floating point output
+	 * @param os    The stream we are going to write to
+	 * @param value The Fixed-point variable we want to write in the stream
+	 */
+	friend std::ostream& operator << (std::ostream &os, const FixedT &value) { os << (double)value.m_data / (1ULL << Raw::dec_bits); return os; }
+
+};
+
+