From 414d242701fca49f39f8e1062234e15ff7eaf365 Mon Sep 17 00:00:00 2001 From: David Williams Date: Sun, 9 Dec 2012 18:45:02 +0100 Subject: [PATCH] Updated Vector documentation. --- .../PolyVoxCore/include/PolyVoxCore/Vector.h | 41 ++++++++----------- 1 file changed, 18 insertions(+), 23 deletions(-) diff --git a/library/PolyVoxCore/include/PolyVoxCore/Vector.h b/library/PolyVoxCore/include/PolyVoxCore/Vector.h index e38c04ee..12c3c201 100644 --- a/library/PolyVoxCore/include/PolyVoxCore/Vector.h +++ b/library/PolyVoxCore/include/PolyVoxCore/Vector.h @@ -38,33 +38,28 @@ namespace PolyVox /** * Represents a vector in space. * - * This Vector class is templated on both size and data type. It is designed to be - * generic but so far had only been tested with vectors of size 2 and 3. Also note - * that some of the operations do not make sense with integer types, for example it - * does not make conceptual sense to try and normalise an integer Vector. + * This is a generl purpose vector class designed to represent both positions and directions. It is templatised + * on both size and data type but note that some of the operations do not make sense with integer types. For + * example it does not make conceptual sense to try and normalise an integer Vector. + * + * Every Vector must have at at least two elements, and the first four elements of any vector are known as the + * X, Y, Z and W elements. Note that W is last even though it comes before X in the alphabet. These elements can + * be accessed through getX(), setX(), getY(), setY(), getZ(), setZ(), getW() and setW(), while other elements + * can be accessed through getElemen() and setElement(). * - * The elements of the Vector are accessed via the overloaded () operator which takes - * an index indicating the element to fetch. They are set using the set() function which - * takes an index indicating the element to set and a new value for that element. For - * convienience, the functions getX(), setX(), getY(), setY(), getZ(), setZ(), getw() and setW() - * do the same thing for the first 4 elements of the Vector. - * - * A variety of overloaded operators are also provided for comparison and arithmetic - * operations. For most of these arithmetic operators only the unary versions are - * documented below - however often binary versions are also generated by std::operators. - * - * Lastly, note that for convienience a set of typedefs are included for 2 and 3 dimensional - * vectors with type float, double, int32_t, and uint32_t. They are used as follows: + * This class includes a number of common mathematical operations (addition, subtraction, etc) as well as vector + * specific operations such as the dot and cross products. Note that this class is also templatised on an + * OperationType which is used for many internal calculations and some results. For example, the square of a + * vector's length will always be an integer if all the elements are integers, but the value might be outside + * that which can be represented by the StorageType. You don't need to worry about this as long as you are using + * the built in typedefs for common configurations. + * + * Typedefs are provided for 2, 3 and 4 dimensional vector with int8_t, uint8_t, int16_t, uint6_t, int32_t, + * uint32_t, float and double types. These typedefs are used as follows: * * \code - * Vector2DInt4 test(1,2); //Declares a 2 dimensional Vector of type int4. + * Vector2DInt32 test(1,2); //Declares a 2 dimensional Vector of type int32_t. * \endcode - * - * Extra things to mention when I when I fill this out shortly: - * Vector must have at least two elements. - * Use of 'OperationType' - * Floating point return values are always single precision - * Component order is WYZW */ template class Vector