From 8d55d62d980470291b78ba3d6f34c3911b9f1669 Mon Sep 17 00:00:00 2001 From: Pascal Serrarens Date: Mon, 10 Jan 2022 12:00:25 +0100 Subject: [PATCH] Completed documentation, cleanup code --- DoxyGen/DoxyWarnLogfile.txt | 0 DoxyGen/Doxyfile | 37 +++---- DoxyGen/DoxygenLayout.xml | 2 +- Quaternion.cpp | 13 +-- Quaternion.h | 204 +++++++++++++++++++++++++++++++----- Vector3.cpp | 44 ++------ Vector3.h | 177 ++++++++++++++++++++++++++----- 7 files changed, 359 insertions(+), 118 deletions(-) create mode 100644 DoxyGen/DoxyWarnLogfile.txt diff --git a/DoxyGen/DoxyWarnLogfile.txt b/DoxyGen/DoxyWarnLogfile.txt new file mode 100644 index 0000000..e69de29 diff --git a/DoxyGen/Doxyfile b/DoxyGen/Doxyfile index 2f1047f..fda8452 100644 --- a/DoxyGen/Doxyfile +++ b/DoxyGen/Doxyfile @@ -51,7 +51,7 @@ PROJECT_BRIEF = # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy # the logo to the output directory. -PROJECT_LOGO = +PROJECT_LOGO = //intranet/home/Afbeeldingen/PasserVR/Logos/Logo3NameRight100.png # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path # into which the generated documentation will be written. If a relative path is @@ -143,7 +143,7 @@ ALWAYS_DETAILED_SEC = NO # operators of the base classes will not be shown. # The default value is: NO. -INLINE_INHERITED_MEMB = NO +INLINE_INHERITED_MEMB = YES # If the FULL_PATH_NAMES tag is set to YES, doxygen will prepend the full path # before files name in the file list and in the header files. If set to NO the @@ -339,7 +339,7 @@ MARKDOWN_SUPPORT = YES # Minimum value: 0, maximum value: 99, default value: 5. # This tag requires that the tag MARKDOWN_SUPPORT is set to YES. -TOC_INCLUDE_HEADINGS = 5 +TOC_INCLUDE_HEADINGS = 0 # When enabled doxygen tries to link words that correspond to documented # classes, or namespaces to their corresponding documentation. Such a link can @@ -501,7 +501,7 @@ EXTRACT_PACKAGE = NO # included in the documentation. # The default value is: NO. -EXTRACT_STATIC = NO +EXTRACT_STATIC = YES # If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined # locally in source files will be included in the documentation. If set to NO, @@ -549,7 +549,7 @@ HIDE_UNDOC_MEMBERS = NO # has no effect if EXTRACT_ALL is enabled. # The default value is: NO. -HIDE_UNDOC_CLASSES = NO +HIDE_UNDOC_CLASSES = YES # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend # declarations. If set to NO, these declarations will be included in the @@ -563,7 +563,7 @@ HIDE_FRIEND_COMPOUNDS = NO # blocks will be appended to the function's detailed documentation block. # The default value is: NO. -HIDE_IN_BODY_DOCS = NO +HIDE_IN_BODY_DOCS = YES # The INTERNAL_DOCS tag determines if documentation that is typed after a # \internal command is included. If the tag is set to NO then the documentation @@ -638,7 +638,7 @@ INLINE_INFO = YES # name. If set to NO, the members will appear in declaration order. # The default value is: YES. -SORT_MEMBER_DOCS = YES +SORT_MEMBER_DOCS = NO # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief # descriptions of file, namespace and class members alphabetically by member @@ -741,14 +741,14 @@ SHOW_USED_FILES = YES # (if specified). # The default value is: YES. -SHOW_FILES = YES +SHOW_FILES = NO # Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces # page. This will remove the Namespaces entry from the Quick Index and from the # Folder Tree View (if specified). # The default value is: YES. -SHOW_NAMESPACES = YES +SHOW_NAMESPACES = NO # The FILE_VERSION_FILTER tag can be used to specify a program or script that # doxygen should invoke to get the current version for each file (typically from @@ -859,7 +859,7 @@ WARN_FORMAT = "$file:$line: $text" # messages should be written. If left blank the output is written to standard # error (stderr). -WARN_LOGFILE = +WARN_LOGFILE = DoxyWarnLogfile.txt #--------------------------------------------------------------------------- # Configuration options related to the input files @@ -871,7 +871,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = +INPUT = .. # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -951,7 +951,7 @@ FILE_PATTERNS = *.c \ # be searched for input files as well. # The default value is: NO. -RECURSIVE = NO +RECURSIVE = YES # The EXCLUDE tag can be used to specify files and/or directories that should be # excluded from the INPUT source files. This way you can easily exclude a @@ -1013,7 +1013,8 @@ EXAMPLE_RECURSIVE = NO # that contain images that are to be included in the documentation (see the # \image command). -IMAGE_PATH = +IMAGE_PATH = images \ + . # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program @@ -1293,7 +1294,7 @@ HTML_STYLESHEET = # list). For an example see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_STYLESHEET = +HTML_EXTRA_STYLESHEET = custom_doxygen.css # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note @@ -1314,7 +1315,7 @@ HTML_EXTRA_FILES = # Minimum value: 0, maximum value: 359, default value: 220. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_COLORSTYLE_HUE = 220 +HTML_COLORSTYLE_HUE = 35 # The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors # in the HTML output. For a value of 0 the output will use gray-scales only. A @@ -1322,7 +1323,7 @@ HTML_COLORSTYLE_HUE = 220 # Minimum value: 0, maximum value: 255, default value: 100. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_COLORSTYLE_SAT = 100 +HTML_COLORSTYLE_SAT = 0 # The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the # luminance component of the colors in the HTML output. Values below 100 @@ -1333,7 +1334,7 @@ HTML_COLORSTYLE_SAT = 100 # Minimum value: 40, maximum value: 240, default value: 80. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_COLORSTYLE_GAMMA = 80 +HTML_COLORSTYLE_GAMMA = 103 # If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML # page will contain the date and time when the page was generated. Setting this @@ -2231,7 +2232,7 @@ PERLMOD_MAKEVAR_PREFIX = # C-preprocessor directives found in the sources and include files. # The default value is: YES. -ENABLE_PREPROCESSING = YES +ENABLE_PREPROCESSING = NO # If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names # in the source code. If set to NO, only conditional compilation will be diff --git a/DoxyGen/DoxygenLayout.xml b/DoxyGen/DoxygenLayout.xml index 3edc922..273c519 100644 --- a/DoxyGen/DoxygenLayout.xml +++ b/DoxyGen/DoxygenLayout.xml @@ -39,7 +39,7 @@ - + diff --git a/Quaternion.cpp b/Quaternion.cpp index 1cee2d1..44f6991 100644 --- a/Quaternion.cpp +++ b/Quaternion.cpp @@ -68,13 +68,9 @@ void Quaternion::Normalize() { Quaternion Quaternion::Normalize(const Quaternion& q) { Quaternion result; - Normalize(q, result); - return result; -}; - -void Quaternion::Normalize(const Quaternion& q, Quaternion& result) { float scale = 1.0f / q.GetLength(); result = Quaternion(q.x * scale, q.y * scale, q.z * scale, q.w * scale); + return result; }; float Quaternion::Dot(Quaternion a, Quaternion b) { @@ -148,13 +144,6 @@ Quaternion Quaternion::Inverse(Quaternion r) { return Quaternion(-r.x / n, -r.y / n, -r.z / n, r.w / n); } -/// -/// Creates a quaternion with the given forward direction -/// -/// The diraction to look in -/// The rotation for this direction -/// For the rotation, Vector::up is used for the up direction. -/// Note: if the forward direction == Vector3::up, the result is Quaternion::identity Quaternion Quaternion::LookRotation(const Vector3& forward) { Vector3 up = Vector3(0, 1, 0); return LookRotation(forward, up); diff --git a/Quaternion.h b/Quaternion.h index 69ab497..6dddd1d 100644 --- a/Quaternion.h +++ b/Quaternion.h @@ -2,20 +2,32 @@ // License, v. 2.0.If a copy of the MPL was not distributed with this // file, You can obtain one at https ://mozilla.org/MPL/2.0/. -#ifndef QUATERNION_H -#define QUATERNION_H - #pragma once struct Vector3; extern "C" { + /// + /// A quaternion + /// + /// This is a C-style implementation typedef struct Quat { + /// + /// The x component + /// float x; + /// + /// The y component + /// float y; + /// + /// The z component + /// float z; + /// + /// The w component + /// float w; } Quat; - void CopyQuat(const Quat& q1, Quat& q2); } @@ -31,10 +43,10 @@ public: /// /// create a new quaternion with the given values /// - /// x axis value - /// y axis value - /// z axis value - /// w axis value + /// x component + /// y component + /// z component + /// w component Quaternion(float _x, float _y, float _z, float _w); /// /// Create a quaternion from C-style Quat @@ -48,51 +60,185 @@ public: /// const static Quaternion identity; + /// + /// Convert to unit quaternion + /// + /// This will preserve the orientation, + /// but ensures that it is a unit quaternion. void Normalize(); + /// + /// Convert to unity quaternion + /// + /// The quaternion to convert + /// A unit quaternion + /// This will preserve the orientation, + /// but ensures that it is a unit quaternion. static Quaternion Normalize(const Quaternion& q); - static void Normalize(const Quaternion& q, Quaternion& result); - static Vector3 ToAngles(const Quaternion& q1); + /// + /// Convert to euler angles + /// + /// The quaternion to convert + /// A vector containing euler angles + /// The euler angles performed in the order: Z, X, Y + static Vector3 ToAngles(const Quaternion& q); - Vector3 operator *(const Vector3& p) const; - Quaternion operator *(const Quaternion& r2) const; + /// + /// Rotate a vector using this quaterion + /// + /// The vector to rotate + /// The rotated vector + Vector3 operator *(const Vector3& vector) const; + /// + /// Multiply this quaternion with another quaternion + /// + /// The quaternion to multiply with + /// The resulting rotation + /// The result will be this quaternion rotated according to + /// the give rotation. + Quaternion operator *(const Quaternion& rotation) const; - bool operator ==(const Quaternion& q); + /// + /// Check the equality of two quaternions + /// + /// The quaternion to compare to + /// True when the components of the quaternions are identical + /// Note that this does not compare the rotations themselves. + /// Two quaternions with the same rotational effect may have different + /// components. Use Quaternion::Angle to check if the rotations are the same. + bool operator ==(const Quaternion& quaternion); - static Quaternion Inverse(Quaternion r); + /// + /// The inverse of quaterion + /// + /// The quaternion for which the inverse is needed + /// The inverted quaternion + static Quaternion Inverse(Quaternion quaternion); + + /// + /// A rotation which looks in the given direction + /// + /// The look direction + /// The up direction + /// The look rotation static Quaternion LookRotation(const Vector3& forward, const Vector3& upwards); + /// + /// Creates a quaternion with the given forward direction with up = Vector3::up + /// + /// The look direction + /// The rotation for this direction + /// For the rotation, Vector::up is used for the up direction. + /// Note: if the forward direction == Vector3::up, the result is Quaternion::identity static Quaternion LookRotation(const Vector3& forward); + /// + /// Calculat the rotation from on vector to another + /// + /// The from direction + /// The to direction + /// The rotation from the first to the second vector static Quaternion FromToRotation(Vector3 fromDirection, Vector3 toDirection); + /// + /// Rotate form one orientation to anther with a maximum amount of degrees + /// + /// The from rotation + /// The destination rotation + /// The maximum amount of degrees to rotate + /// The possibly limited rotation static Quaternion RotateTowards(const Quaternion& from, const Quaternion& to, float maxDegreesDelta); - static Quaternion AngleAxis(float angle, const Vector3& axis); - void ToAngleAxis(float* angle, Vector3* axis); - static void ToAxisAngleRad(const Quaternion& q, Vector3* const axis, float* angle); - static float Angle(Quaternion a, Quaternion b); - static Quaternion Slerp(const Quaternion& a, const Quaternion& b, float t); - static Quaternion SlerpUnclamped(const Quaternion& a, const Quaternion& b, float t); + /// + /// Convert an angle/axis representation to a quaternion + /// + /// The angle + /// The axis + /// The resulting quaternion + static Quaternion AngleAxis(float angle, const Vector3& axis); + /// + /// Convert this quaternion to angle/axis representation + /// + /// A pointer to the angle for the result + /// A pointer to the axis for the result + void ToAngleAxis(float* angle, Vector3* axis); + + /// + /// Get the angle between two orientations + /// + /// The first orientation + /// The second orientation + /// The smallest angle in degrees between the two orientations + static float Angle(Quaternion orientation1, Quaternion orientation2); + /// + /// Sherical lerp between two rotations + /// + /// The first rotation + /// The second rotation + /// The factor between 0 and 1. + /// The resulting rotation + /// A factor 0 returns rotation1, factor1 returns rotation2. + static Quaternion Slerp(const Quaternion& rotation1, const Quaternion& rotation2, float factor); + /// + /// Unclamped sherical lerp between two rotations + /// + /// The first rotation + /// The second rotation + /// The factor + /// The resulting rotation + /// A factor 0 returns rotation1, factor1 returns rotation2. + /// Values outside the 0..1 range will result in extrapolated rotations + static Quaternion SlerpUnclamped(const Quaternion& rotation1, const Quaternion& rotation2, float factor); + + /// + /// Create a rotation from euler angles + /// + /// The angle around the right axis + /// The angle around the upward axis + /// The angle around the forward axis + /// The resulting quaternion + /// Rotation are appied in the order z, X, Y. static Quaternion Euler(float x, float y, float z); - static Quaternion Euler(Vector3 euler); - static Quaternion FromEulerRad(Vector3 euler); + /// + /// Create a rotation from a vector containing euler angles + /// + /// Vector with the euler angles + /// The resulting quaternion + /// Rotation are appied in the order z, X, Y. + static Quaternion Euler(Vector3 eulerAngles); + + /// + /// Returns the angle of around the give axis for a rotation + /// + /// The axis around which the angle should be computed + /// The source rotation + /// The signed angle around the axis static float GetAngleAround(Vector3 axis, Quaternion rotation); + /// + /// Returns the rotation limited around the given axis + /// + /// The axis which which the rotation should be limited + /// The source rotation + /// The rotation around the given axis static Quaternion GetRotationAround(Vector3 axis, Quaternion rotation); + /// + /// Swing-twist decomposition of a rotation + /// + /// The base direction for the decomposition + /// The source rotation + /// A pointer to the quaternion for the swing result + /// A pointer to the quaternion for the twist result static void GetSwingTwist(Vector3 axis, Quaternion rotation, Quaternion* swing, Quaternion* twist); -protected: +private: float GetLength() const; float GetLengthSquared() const; static float GetLengthSquared(const Quaternion& q); + void ToAxisAngleRad(const Quaternion& q, Vector3* const axis, float* angle); + static Quaternion FromEulerRad(Vector3 euler); + static float Dot(Quaternion a, Quaternion b); -public: Vector3 xyz() const; }; - -//#include "Vector3.h" - - -#endif diff --git a/Vector3.cpp b/Vector3.cpp index 385946f..6d3c959 100644 --- a/Vector3.cpp +++ b/Vector3.cpp @@ -5,7 +5,6 @@ #include "pch.h" #include #include "Vector3.h" -#include "Quaternion.h" const float Deg2Rad = 0.0174532924F; const float Rad2Deg = 57.29578F; @@ -92,26 +91,6 @@ Vector3 Vector3::operator *(float f) const { return Vector3(this->x * f, this->y * f, this->z * f); } -Vector3 operator *(const Quaternion& o, const Vector3& p) { - float num = o.x * 2; - float num2 = o.y * 2; - float num3 = o.z * 2; - float num4 = o.x * num; - float num5 = o.y * num2; - float num6 = o.z * num3; - float num7 = o.x * num2; - float num8 = o.x * num3; - float num9 = o.y * num3; - float num10 = o.w * num; - float num11 = o.w * num2; - float num12 = o.w * num3; - Vector3 result = Vector3::zero; - result.x = (1 - (num5 + num6)) * p.x + (num7 - num12) * p.y + (num8 + num11) * p.z; - result.y = (num7 + num12) * p.x + (1 - (num4 + num6)) * p.y + (num9 - num10) * p.z; - result.z = (num8 - num11) * p.x + (num9 + num10) * p.y + (1 - (num4 + num5)) * p.z; - return result; -} - Vector3 Vector3::operator/(const float& d) { return Vector3(this->x / d, this->y / d, this->z / d); } @@ -156,7 +135,6 @@ float clamp(float x, float lower, float upper) { return upperClamp; } -// This function is buggy (0-1-0, 0-1-0) gives 180 degrees in return!!! float Vector3::Angle(Vector3 from, Vector3 to) { float denominator = sqrtf(from.sqrMagnitude() * to.sqrMagnitude()); if (denominator < epsilon) @@ -185,14 +163,14 @@ float Vector3::SignedAngle(Vector3 from, Vector3 to, Vector3 axis) { return signed_angle; } -void CopyVec3(const Vec3& v1, Vec3& v2) { - v2.x = v1.x; - v2.y = v1.y; - v2.z = v1.z; -} - -void Vec3_Constructor(Vec3* v, float _x, float _y, float _z) { - v->x = _x; - v->y = _y; - v->z = _z; -} +//void CopyVec3(const Vec3& v1, Vec3& v2) { +// v2.x = v1.x; +// v2.y = v1.y; +// v2.z = v1.z; +//} +// +//void Vec3_Constructor(Vec3* v, float _x, float _y, float _z) { +// v->x = _x; +// v->y = _y; +// v->z = _z; +//} diff --git a/Vector3.h b/Vector3.h index 6140482..df1d0e6 100644 --- a/Vector3.h +++ b/Vector3.h @@ -2,26 +2,35 @@ // License, v. 2.0.If a copy of the MPL was not distributed with this // file, You can obtain one at https ://mozilla.org/MPL/2.0/. -#ifndef VECTOR_H -#define VECTOR_H - #pragma once -struct Quaternion; extern "C" { + /// + /// 3-dimensional Vector representation + /// + /// This is a C-style implementation + /// This uses the right-handed coordinate system. typedef struct Vec3 { + /// + /// The right axis of the vector + /// float x; + /// + /// The upward axis of the vector + /// float y; + /// + /// The forward axis of the vector + /// float z; } Vec3; - - void CopyVec3(const Vec3& v1, Vec3& v2); } /// /// A 3-dimensional vector /// +/// This uses the right-handed coordinate system. struct Vector3 : Vec3 { public: /// @@ -71,39 +80,157 @@ public: /// const static Vector3 back; - static float Magnitude(const Vector3& a); + /// + /// The length of a vector + /// + /// The vector for which you need the length + /// The length of the given vector + static float Magnitude(const Vector3& vector); + /// + /// The length of this vector + /// + /// The length of this vector float magnitude() const; - static float SqrMagnitude(const Vector3& a); + /// + /// The squared length of a vector + /// + /// The vector for which you need the squared length + /// The squatred length + /// The squared length is computationally simpler than the real length. + /// Think of Pythagoras A^2 + B^2 = C^2. + /// This leaves out the calculation of the squared root of C. + static float SqrMagnitude(const Vector3& vector); + /// + /// The squared length of this vector + /// + /// The squared length + /// The squared length is computationally simpler than the real length. + /// Think of Pythagoras A^2 + B^2 = C^2. + /// This leaves out the calculation of the squared root of C. float sqrMagnitude() const; - static Vector3 Normalize(Vector3 v); + /// + /// Connvert a vector to a length of 1 + /// + /// The vector to convert + /// The vector with length 1 + static Vector3 Normalize(Vector3 vector); + /// + /// Convert the vector to a length of a + /// + /// The vector with length 1 Vector3 normalized() const; + /// + /// Negate the vector + /// + /// The negated vector + /// This will result in a vector pointing in the opposite direction Vector3 operator -(); - Vector3 operator -(const Vector3& p2) const; + /// + /// Subtract a vector from this vector + /// + /// The vector to subtract from this vector + /// The result of the subtraction + Vector3 operator -(const Vector3& vector) const; - Vector3 operator +(const Vector3& t1) const; - static Vector3 Scale(const Vector3& p1, const Vector3& p2); + /// + /// Add another vector to this vector + /// + /// The vector to add + /// The result of adding the vector + Vector3 operator +(const Vector3& vector2) const; - Vector3 operator *(float f) const; + /// + /// Scale a vector using another vector + /// + /// The vector to scale + /// A vector with scaling factors + /// The scaled vector + /// Each component of the vector v1 will be multiplied with the + /// component from the scaling vector v2. + static Vector3 Scale(const Vector3& vector1, const Vector3& vector2); + /// + /// Scale a vector uniformly up + /// + /// The scaling factor + /// The scaled vector + /// Each component of the vector will be multipled with the same factor. + Vector3 operator *(float factor) const; + /// + /// Scale a vector uniformy down + /// + /// The scaling factor + /// The scaled vector + /// Each componet of the vector will be divided by the same factor. + Vector3 operator /(const float& factor); - Vector3 operator /(const float& d); - static float Dot(const Vector3& v1, const Vector3& v2); + /// + /// The dot product of two vectors + /// + /// The first vector + /// The second vector + /// The dot product of the two vectors + static float Dot(const Vector3& vector1, const Vector3& vector2); - bool operator ==(const Vector3& v); + /// + /// Check is this vector is equal to the given vector + /// + /// The vector to check against + /// True if it is identical to the given vector + /// Note this uses float comparison to check equality which + /// may have strange effects. Equality on float should be avoided. + bool operator ==(const Vector3& vector); - static float Distance(const Vector3& p1, const Vector3& p2); - static Vector3 Cross(const Vector3& v1, const Vector3& v2); + /// + /// The distance between two vectors + /// + /// The first vector + /// The second vectors + /// The distance between the two vectors + static float Distance(const Vector3& vector1, const Vector3& vector2); + + /// + /// The cross product of two vectors + /// + /// The first vector + /// The second vector + /// The cross product of the two vectors + static Vector3 Cross(const Vector3& vector1, const Vector3& vector2); // Projects a vector onto another vector. + + /// + /// Project a vector on another vector + /// + /// The vector to project + /// The normal vector to project on + /// The projected vector static Vector3 Project(Vector3 vector, Vector3 onNormal); - // Projects a vector onto a plane defined by a normal orthogonal to the plane. + /// + /// Projects a vector onto a plane defined by a normal orthogonal to the plane. + /// + /// The vector to project + /// The normal of the plane to project on + /// static Vector3 ProjectOnPlane(Vector3 vector, Vector3 planeNormal); - static float Angle(Vector3 from, Vector3 to); + /// + /// Calculate the angle between two vectors + /// + /// The first vector + /// The second vector + /// + /// This reterns an unsigned angle which is the shortest distance + /// between the two vectors. Use Vector3::SignedAngle if a + /// signed angle is needed. + static float Angle(Vector3 vector1, Vector3 vector2); + + /// + /// Calculate the angle between two vectors rotation around an axis. + /// + /// The starting vector + /// The ending vector + /// The axis to rotate around + /// The signed angle static float SignedAngle(Vector3 from, Vector3 to, Vector3 axis); }; - -void Vec3_Constructor(Vec3* v, float _x, float _y, float _z); - - -#endif