diff --git a/include/SFML/System/Vector2.hpp b/include/SFML/System/Vector2.hpp index 71208ddbf..2bab6a327 100644 --- a/include/SFML/System/Vector2.hpp +++ b/include/SFML/System/Vector2.hpp @@ -29,9 +29,9 @@ namespace sf { //////////////////////////////////////////////////////////// -/// Vector2 is an utility class for manipulating 2 dimensional -/// vectors. Template parameter defines the type of coordinates -/// (integer, float, ...) +/// \brief Utility template class for manipulating +/// 2-dimensional vectors +/// //////////////////////////////////////////////////////////// template class Vector2 @@ -39,16 +39,16 @@ class Vector2 public : //////////////////////////////////////////////////////////// - /// Default constructor + /// \brief Default constructor /// //////////////////////////////////////////////////////////// Vector2(); //////////////////////////////////////////////////////////// - /// Construct the vector from its coordinates + /// \brief Construct the vector from its coordinates /// - /// \param X : X coordinate - /// \param Y : Y coordinate + /// \param X X coordinate + /// \param Y Y coordinate /// //////////////////////////////////////////////////////////// Vector2(T X, T Y); @@ -61,143 +61,159 @@ public : }; //////////////////////////////////////////////////////////// -/// Operator - overload ; returns the opposite of a vector +/// \brief Overload of unary operator - /// -/// \param left : Vector to negate +/// \param right Vector to negate /// -/// \return -left +/// \return Memberwise opposite of the vector /// //////////////////////////////////////////////////////////// template -Vector2 operator -(const Vector2& left); +Vector2 operator -(const Vector2& right); //////////////////////////////////////////////////////////// -/// Operator += overload ; add two vectors and assign to the first op +/// \brief Overload of binary operator += /// -/// \param left : First vector -/// \param right : Second vector +/// This operator performs a memberwise addition of both vectors, +/// and assigns the result to \a left. /// -/// \return left + right +/// \param left Left operand (a vector) +/// \param right Right operand (a vector) +/// +/// \return Reference to \a left /// //////////////////////////////////////////////////////////// template Vector2& operator +=(Vector2& left, const Vector2& right); //////////////////////////////////////////////////////////// -/// Operator -= overload ; subtract two vectors and assign to the first op +/// \brief Overload of binary operator -= /// -/// \param left : First vector -/// \param right : Second vector +/// This operator performs a memberwise subtraction of both vectors, +/// and assigns the result to \a left. /// -/// \return left - right +/// \param left Left operand (a vector) +/// \param right Right operand (a vector) +/// +/// \return Reference to \a left /// //////////////////////////////////////////////////////////// template Vector2& operator -=(Vector2& left, const Vector2& right); //////////////////////////////////////////////////////////// -/// Operator + overload ; adds two vectors +/// \brief Overload of binary operator + /// -/// \param left : First vector -/// \param right : Second vector +/// \param left Left operand (a vector) +/// \param right Right operand (a vector) /// -/// \return left + right +/// \return Memberwise addition of both vectors /// //////////////////////////////////////////////////////////// template Vector2 operator +(const Vector2& left, const Vector2& right); //////////////////////////////////////////////////////////// -/// Operator - overload ; subtracts two vectors +/// \brief Overload of binary operator - /// -/// \param left : First vector -/// \param right : Second vector +/// \param left Left operand (a vector) +/// \param right Right operand (a vector) /// -/// \return left - right +/// \return Memberwise subtraction of both vectors /// //////////////////////////////////////////////////////////// template Vector2 operator -(const Vector2& left, const Vector2& right); //////////////////////////////////////////////////////////// -/// Operator * overload ; multiply a vector by a scalar value +/// \brief Overload of binary operator * /// -/// \param left : Vector -/// \param right : Scalar value +/// \param left Left operand (a vector) +/// \param right Right operand (a scalar value) /// -/// \return left * right +/// \return Memberwise multiplication by \a right /// //////////////////////////////////////////////////////////// template Vector2 operator *(const Vector2& left, T right); //////////////////////////////////////////////////////////// -/// Operator * overload ; multiply a scalar value by a vector +/// \brief Overload of binary operator * /// -/// \param left : Scalar value -/// \param right : Vector +/// \param left Left operand (a scalar value) +/// \param right Right operand (a vector) /// -/// \return left * right +/// \return Memberwise multiplication by \a left /// //////////////////////////////////////////////////////////// template Vector2 operator *(T left, const Vector2& right); //////////////////////////////////////////////////////////// -/// Operator *= overload ; multiply-assign a vector by a scalar value +/// \brief Overload of binary operator *= /// -/// \param left : Vector -/// \param right : Scalar value +/// This operator performs a memberwise multiplication by \a right, +/// and assigns the result to \a left. /// -/// \return left * right +/// \param left Left operand (a vector) +/// \param right Right operand (a scalar value) +/// +/// \return Reference to \a left /// //////////////////////////////////////////////////////////// template Vector2& operator *=(Vector2& left, T right); //////////////////////////////////////////////////////////// -/// Operator / overload ; divide a vector by a scalar value +/// \brief Overload of binary operator / /// -/// \param left : Vector -/// \param right : Scalar value +/// \param left Left operand (a scalar value) +/// \param right Right operand (a vector) /// -/// \return left / right +/// \return Memberwise division by \a right /// //////////////////////////////////////////////////////////// template Vector2 operator /(const Vector2& left, T right); //////////////////////////////////////////////////////////// -/// Operator /= overload ; divide-assign a vector by a scalar value +/// \brief Overload of binary operator /= /// -/// \param left : Vector -/// \param right : Scalar value +/// This operator performs a memberwise division by \a right, +/// and assigns the result to \a left. /// -/// \return left / right +/// \param left Left operand (a vector) +/// \param right Right operand (a scalar value) +/// +/// \return Reference to \a left /// //////////////////////////////////////////////////////////// template Vector2& operator /=(Vector2& left, T right); //////////////////////////////////////////////////////////// -/// Operator == overload ; compares the equality of two vectors +/// \brief Overload of binary operator == /// -/// \param left : First vector -/// \param right : Second vector +/// This operator compares strict equality between two vectors. /// -/// \return True if left is equal to right +/// \param left Left operand (a vector) +/// \param right Right operand (a vector) +/// +/// \return True if \a left is equal to \a right /// //////////////////////////////////////////////////////////// template bool operator ==(const Vector2& left, const Vector2& right); //////////////////////////////////////////////////////////// -/// Operator != overload ; compares the difference of two vectors +/// \brief Overload of binary operator != /// -/// \param left : First vector -/// \param right : Second vector +/// This operator compares strict difference between two vectors. /// -/// \return True if left is different than right +/// \param left Left operand (a vector) +/// \param right Right operand (a vector) +/// +/// \return True if \a left is not equal to \a right /// //////////////////////////////////////////////////////////// template @@ -213,3 +229,42 @@ typedef Vector2 Vector2f; #endif // SFML_VECTOR2_HPP + + +//////////////////////////////////////////////////////////// +/// \class sf::Vector2 +/// +/// sf::Vector2 is a simple class that defines a mathematical +/// vector with two coordinates (x and y). It can be used to +/// represent anything that has two dimensions: a size, a point, +/// a velocity, etc. +/// +/// The template parameter T is the type of the coordinates. It +/// can be any type that supports arithmetic operations (+, -, /, *) +/// and comparisons (==, !=), for example int or float. +/// +/// You generally don't have to care about the templated form (sf::Vector2), +/// the two most common specializations have special typedefs: +/// \li sf::Vector2 is sf::Vector2f +/// \li sf::Vector2 is sf::Vector2i +/// +/// The sf::Vector2 class has a small and simple interface, its x and y members +/// can be accessed directly (there's no accessor like SetX(), GetX()) and it +/// contains no mathematical function like dot product, cross product, length, etc. +/// +/// Usage example: +/// \code +/// sf::Vector2f v1(16.5f, 24.f); +/// v1.x = 18.2f; +/// float y = v1.y; +/// +/// sf::Vector2f v2 = v1 * 5.f; +/// sf::Vector2f v3; +/// v3 = v1 + v2; +/// +/// bool different = (v2 != v3); +/// \endcode +/// +/// Note: for 3-dimensional vectors, see sf::Vector3. +/// +//////////////////////////////////////////////////////////// diff --git a/include/SFML/System/Vector2.inl b/include/SFML/System/Vector2.inl index 567cfeb73..9dec638c5 100644 --- a/include/SFML/System/Vector2.inl +++ b/include/SFML/System/Vector2.inl @@ -23,8 +23,6 @@ //////////////////////////////////////////////////////////// -//////////////////////////////////////////////////////////// -/// Default constructor //////////////////////////////////////////////////////////// template inline Vector2::Vector2() : @@ -35,8 +33,6 @@ y(0) } -//////////////////////////////////////////////////////////// -/// Construct the color from its coordinates //////////////////////////////////////////////////////////// template inline Vector2::Vector2(T X, T Y) : @@ -47,18 +43,14 @@ y(Y) } -//////////////////////////////////////////////////////////// -/// Operator - overload ; returns the opposite of a vector //////////////////////////////////////////////////////////// template -inline Vector2 operator -(const Vector2& left) +inline Vector2 operator -(const Vector2& right) { - return Vector2(-left.x, -left.y); + return Vector2(-right.x, -right.y); } -//////////////////////////////////////////////////////////// -/// Operator += overload ; add two vectors and assign to the first op //////////////////////////////////////////////////////////// template inline Vector2& operator +=(Vector2& left, const Vector2& right) @@ -70,8 +62,6 @@ inline Vector2& operator +=(Vector2& left, const Vector2& right) } -//////////////////////////////////////////////////////////// -/// Operator -= overload ; subtract two vectors and assign to the first op //////////////////////////////////////////////////////////// template inline Vector2& operator -=(Vector2& left, const Vector2& right) @@ -83,8 +73,6 @@ inline Vector2& operator -=(Vector2& left, const Vector2& right) } -//////////////////////////////////////////////////////////// -/// Operator + overload ; adds two vectors //////////////////////////////////////////////////////////// template inline Vector2 operator +(const Vector2& left, const Vector2& right) @@ -93,8 +81,6 @@ inline Vector2 operator +(const Vector2& left, const Vector2& right) } -//////////////////////////////////////////////////////////// -/// Operator - overload ; subtracts two vectors //////////////////////////////////////////////////////////// template inline Vector2 operator -(const Vector2& left, const Vector2& right) @@ -103,8 +89,6 @@ inline Vector2 operator -(const Vector2& left, const Vector2& right) } -//////////////////////////////////////////////////////////// -/// Operator * overload ; multiply a vector by a scalar value //////////////////////////////////////////////////////////// template inline Vector2 operator *(const Vector2& left, T right) @@ -113,8 +97,6 @@ inline Vector2 operator *(const Vector2& left, T right) } -//////////////////////////////////////////////////////////// -/// Operator * overload ; multiply a scalar value by a vector //////////////////////////////////////////////////////////// template inline Vector2 operator *(T left, const Vector2& right) @@ -123,8 +105,6 @@ inline Vector2 operator *(T left, const Vector2& right) } -//////////////////////////////////////////////////////////// -/// Operator *= overload ; multiply-assign a vector by a scalar value //////////////////////////////////////////////////////////// template inline Vector2& operator *=(Vector2& left, T right) @@ -136,8 +116,6 @@ inline Vector2& operator *=(Vector2& left, T right) } -//////////////////////////////////////////////////////////// -/// Operator / overload ; divide a vector by a scalar value //////////////////////////////////////////////////////////// template inline Vector2 operator /(const Vector2& left, T right) @@ -146,8 +124,6 @@ inline Vector2 operator /(const Vector2& left, T right) } -//////////////////////////////////////////////////////////// -/// Operator /= overload ; divide-assign a vector by a scalar value //////////////////////////////////////////////////////////// template inline Vector2& operator /=(Vector2& left, T right) @@ -159,8 +135,6 @@ inline Vector2& operator /=(Vector2& left, T right) } -//////////////////////////////////////////////////////////// -/// Operator == overload ; compares the equality of two vectors //////////////////////////////////////////////////////////// template inline bool operator ==(const Vector2& left, const Vector2& right) @@ -169,8 +143,6 @@ inline bool operator ==(const Vector2& left, const Vector2& right) } -//////////////////////////////////////////////////////////// -/// Operator != overload ; compares the difference of two vectors //////////////////////////////////////////////////////////// template inline bool operator !=(const Vector2& left, const Vector2& right) diff --git a/include/SFML/System/Vector3.hpp b/include/SFML/System/Vector3.hpp index 073b9cf81..954889ab1 100644 --- a/include/SFML/System/Vector3.hpp +++ b/include/SFML/System/Vector3.hpp @@ -29,9 +29,9 @@ namespace sf { //////////////////////////////////////////////////////////// -/// Vector3 is an utility class for manipulating 3 dimensional -/// vectors. Template parameter defines the type of coordinates -/// (integer, float, ...) +/// \brief Utility template class for manipulating +/// 3-dimensional vectors +/// //////////////////////////////////////////////////////////// template class Vector3 @@ -39,17 +39,17 @@ class Vector3 public : //////////////////////////////////////////////////////////// - /// Default constructor + /// \brief Default constructor /// //////////////////////////////////////////////////////////// Vector3(); //////////////////////////////////////////////////////////// - /// Construct the vector from its coordinates + /// \brief Construct the vector from its coordinates /// - /// \param X : X coordinate - /// \param Y : Y coordinate - /// \param Z : Z coordinate + /// \param X X coordinate + /// \param Y Y coordinate + /// \param Z Z coordinate /// //////////////////////////////////////////////////////////// Vector3(T X, T Y, T Z); @@ -63,143 +63,159 @@ public : }; //////////////////////////////////////////////////////////// -/// Operator - overload ; returns the opposite of a vector +/// \brief Overload of unary operator - /// -/// \param left : Vector to negate +/// \param right Vector to negate /// -/// \return -left +/// \return Memberwise opposite of the vector /// //////////////////////////////////////////////////////////// template Vector3 operator -(const Vector3& left); //////////////////////////////////////////////////////////// -/// Operator += overload ; add two vectors and assign to the first op +/// \brief Overload of binary operator += /// -/// \param left : First vector -/// \param right : Second vector +/// This operator performs a memberwise addition of both vectors, +/// and assigns the result to \a left. /// -/// \return left + V2 +/// \param left Left operand (a vector) +/// \param right Right operand (a vector) +/// +/// \return Reference to \a left /// //////////////////////////////////////////////////////////// template Vector3& operator +=(Vector3& left, const Vector3& right); //////////////////////////////////////////////////////////// -/// Operator -= overload ; subtract two vectors and assign to the first op +/// \brief Overload of binary operator -= /// -/// \param left : First vector -/// \param right : Second vector +/// This operator performs a memberwise subtraction of both vectors, +/// and assigns the result to \a left. /// -/// \return left - right +/// \param left Left operand (a vector) +/// \param right Right operand (a vector) +/// +/// \return Reference to \a left /// //////////////////////////////////////////////////////////// template Vector3& operator -=(Vector3& left, const Vector3& right); //////////////////////////////////////////////////////////// -/// Operator + overload ; adds two vectors +/// \brief Overload of binary operator + /// -/// \param left : First vector -/// \param right : Second vector +/// \param left Left operand (a vector) +/// \param right Right operand (a vector) /// -/// \return left + right +/// \return Memberwise addition of both vectors /// //////////////////////////////////////////////////////////// template Vector3 operator +(const Vector3& left, const Vector3& right); //////////////////////////////////////////////////////////// -/// Operator - overload ; subtracts two vectors +/// \brief Overload of binary operator - /// -/// \param left : First vector -/// \param right : Second vector +/// \param left Left operand (a vector) +/// \param right Right operand (a vector) /// -/// \return left - rightright +/// \return Memberwise subtraction of both vectors /// //////////////////////////////////////////////////////////// template Vector3 operator -(const Vector3& left, const Vector3& right); //////////////////////////////////////////////////////////// -/// Operator * overload ; multiply a vector by a scalar value +/// \brief Overload of binary operator * /// -/// \param left : Vector -/// \param right : Scalar value +/// \param left Left operand (a vector) +/// \param right Right operand (a scalar value) /// -/// \return left * right +/// \return Memberwise multiplication by \a right /// //////////////////////////////////////////////////////////// template Vector3 operator *(const Vector3& left, T right); //////////////////////////////////////////////////////////// -/// Operator * overload ; multiply a scalar value by a vector +/// \brief Overload of binary operator * /// -/// \param left : Scalar value -/// \param right : Vector +/// \param left Left operand (a scalar value) +/// \param right Right operand (a vector) /// -/// \return left * right +/// \return Memberwise multiplication by \a left /// //////////////////////////////////////////////////////////// template Vector3 operator *(T left, const Vector3& right); //////////////////////////////////////////////////////////// -/// Operator *= overload ; multiply-assign a vector by a scalar value +/// \brief Overload of binary operator *= /// -/// \param left : Vector -/// \param right : Scalar value +/// This operator performs a memberwise multiplication by \a right, +/// and assigns the result to \a left. /// -/// \return left * right +/// \param left Left operand (a vector) +/// \param right Right operand (a scalar value) +/// +/// \return Reference to \a left /// //////////////////////////////////////////////////////////// template Vector3& operator *=(Vector3& left, T right); //////////////////////////////////////////////////////////// -/// Operator / overload ; divide a vector by a scalar value +/// \brief Overload of binary operator / /// -/// \param left : Vector -/// \param right : Scalar value +/// \param left Left operand (a scalar value) +/// \param right Right operand (a vector) /// -/// \return left / right +/// \return Memberwise division by \a right /// //////////////////////////////////////////////////////////// template Vector3 operator /(const Vector3& left, T right); //////////////////////////////////////////////////////////// -/// Operator /= overload ; divide-assign a vector by a scalar value +/// \brief Overload of binary operator /= /// -/// \param left : Vector -/// \param right : Scalar value +/// This operator performs a memberwise division by \a right, +/// and assigns the result to \a left. /// -/// \return left / right +/// \param left Left operand (a vector) +/// \param right Right operand (a scalar value) +/// +/// \return Reference to \a left /// //////////////////////////////////////////////////////////// template Vector3& operator /=(Vector3& left, T right); //////////////////////////////////////////////////////////// -/// Operator == overload ; compares the equality of two vectors +/// \brief Overload of binary operator == /// -/// \param left : First vector -/// \param right : Second vector +/// This operator compares strict equality between two vectors. /// -/// \return True if left is equal to right +/// \param left Left operand (a vector) +/// \param right Right operand (a vector) +/// +/// \return True if \a left is equal to \a right /// //////////////////////////////////////////////////////////// template bool operator ==(const Vector3& left, const Vector3& right); //////////////////////////////////////////////////////////// -/// Operator != overload ; compares the difference of two vectors +/// \brief Overload of binary operator != /// -/// \param left : First vector -/// \param right : Second vector +/// This operator compares strict difference between two vectors. /// -/// \return True if left is different than right +/// \param left Left operand (a vector) +/// \param right Right operand (a vector) +/// +/// \return True if \a left is not equal to \a right /// //////////////////////////////////////////////////////////// template @@ -215,3 +231,43 @@ typedef Vector3 Vector3f; #endif // SFML_VECTOR3_HPP + + +//////////////////////////////////////////////////////////// +/// \class sf::Vector3 +/// +/// sf::Vector3 is a simple class that defines a mathematical +/// vector with three coordinates (x, y and z). It can be used to +/// represent anything that has three dimensions: a size, a point, +/// a velocity, etc. +/// +/// The template parameter T is the type of the coordinates. It +/// can be any type that supports arithmetic operations (+, -, /, *) +/// and comparisons (==, !=), for example int or float. +/// +/// You generally don't have to care about the templated form (sf::Vector3), +/// the two most common specializations have special typedefs: +/// \li sf::Vector3 is sf::Vector3f +/// \li sf::Vector3 is sf::Vector3i +/// +/// The sf::Vector3 class has a small and simple interface, its x and y members +/// can be accessed directly (there's no accessor like SetX(), GetX()) and it +/// contains no mathematical function like dot product, cross product, length, etc. +/// +/// Usage example: +/// \code +/// sf::Vector3f v1(16.5f, 24.f, -8.2f); +/// v1.x = 18.2f; +/// float y = v1.y; +/// float z = v1.z; +/// +/// sf::Vector3f v2 = v1 * 5.f; +/// sf::Vector3f v3; +/// v3 = v1 + v2; +/// +/// bool different = (v2 != v3); +/// \endcode +/// +/// Note: for 2-dimensional vectors, see sf::Vector2. +/// +//////////////////////////////////////////////////////////// diff --git a/include/SFML/System/Vector3.inl b/include/SFML/System/Vector3.inl index 39f3dcf3b..191c6b237 100644 --- a/include/SFML/System/Vector3.inl +++ b/include/SFML/System/Vector3.inl @@ -23,8 +23,6 @@ //////////////////////////////////////////////////////////// -//////////////////////////////////////////////////////////// -/// Default constructor //////////////////////////////////////////////////////////// template inline Vector3::Vector3() : @@ -36,8 +34,6 @@ z(0) } -//////////////////////////////////////////////////////////// -/// Construct the color from its coordinates //////////////////////////////////////////////////////////// template inline Vector3::Vector3(T X, T Y, T Z) : @@ -49,8 +45,6 @@ z(Z) } -//////////////////////////////////////////////////////////// -/// Operator - overload ; returns the opposite of a vector //////////////////////////////////////////////////////////// template inline Vector3 operator -(const Vector3& left) @@ -59,8 +53,6 @@ inline Vector3 operator -(const Vector3& left) } -//////////////////////////////////////////////////////////// -/// Operator += overload ; add two vectors and assign to the first op //////////////////////////////////////////////////////////// template inline Vector3& operator +=(Vector3& left, const Vector3& right) @@ -73,8 +65,6 @@ inline Vector3& operator +=(Vector3& left, const Vector3& right) } -//////////////////////////////////////////////////////////// -/// Operator -= overload ; subtract two vectors and assign to the first op //////////////////////////////////////////////////////////// template inline Vector3& operator -=(Vector3& left, const Vector3& right) @@ -87,8 +77,6 @@ inline Vector3& operator -=(Vector3& left, const Vector3& right) } -//////////////////////////////////////////////////////////// -/// Operator + overload ; adds two vectors //////////////////////////////////////////////////////////// template inline Vector3 operator +(const Vector3& left, const Vector3& right) @@ -97,8 +85,6 @@ inline Vector3 operator +(const Vector3& left, const Vector3& right) } -//////////////////////////////////////////////////////////// -/// Operator - overload ; subtracts two vectors //////////////////////////////////////////////////////////// template inline Vector3 operator -(const Vector3& left, const Vector3& right) @@ -107,8 +93,6 @@ inline Vector3 operator -(const Vector3& left, const Vector3& right) } -//////////////////////////////////////////////////////////// -/// Operator * overload ; multiply a vector by a scalar value //////////////////////////////////////////////////////////// template inline Vector3 operator *(const Vector3& left, T right) @@ -117,8 +101,6 @@ inline Vector3 operator *(const Vector3& left, T right) } -//////////////////////////////////////////////////////////// -/// Operator * overload ; multiply a scalar value by a vector //////////////////////////////////////////////////////////// template inline Vector3 operator *(T left, const Vector3& right) @@ -127,8 +109,6 @@ inline Vector3 operator *(T left, const Vector3& right) } -//////////////////////////////////////////////////////////// -/// Operator *= overload ; multiply-assign a vector by a scalar value //////////////////////////////////////////////////////////// template inline Vector3& operator *=(Vector3& left, T right) @@ -141,8 +121,6 @@ inline Vector3& operator *=(Vector3& left, T right) } -//////////////////////////////////////////////////////////// -/// Operator / overload ; divide a vector by a scalar value //////////////////////////////////////////////////////////// template inline Vector3 operator /(const Vector3& left, T right) @@ -151,8 +129,6 @@ inline Vector3 operator /(const Vector3& left, T right) } -//////////////////////////////////////////////////////////// -/// Operator /= overload ; divide-assign a vector by a scalar value //////////////////////////////////////////////////////////// template inline Vector3& operator /=(Vector3& left, T right) @@ -165,8 +141,6 @@ inline Vector3& operator /=(Vector3& left, T right) } -//////////////////////////////////////////////////////////// -/// Operator == overload ; compares the equality of two vectors //////////////////////////////////////////////////////////// template inline bool operator ==(const Vector3& left, const Vector3& right) @@ -175,8 +149,6 @@ inline bool operator ==(const Vector3& left, const Vector3& right) } -//////////////////////////////////////////////////////////// -/// Operator != overload ; compares the difference of two vectors //////////////////////////////////////////////////////////// template inline bool operator !=(const Vector3& left, const Vector3& right)