diff --git a/.swiftlint.yml b/.swiftlint.yml index bf40b6c..ca9f13e 100644 --- a/.swiftlint.yml +++ b/.swiftlint.yml @@ -17,7 +17,7 @@ opt_in_rules: #- file_name #- file_types_order #- indentation_width - #- missing_docs + - missing_docs #- multiline_arguments_brackets #- multiline_literal_brackets #- multiline_parameters_brackets diff --git a/Sources/FirebladeMath/Functions/radians.swift b/Sources/FirebladeMath/Functions/radians.swift index 1f771f9..b3215be 100644 --- a/Sources/FirebladeMath/Functions/radians.swift +++ b/Sources/FirebladeMath/Functions/radians.swift @@ -14,6 +14,10 @@ public func radians(_ degrees: Double) -> Double { degrees * kDegreeToRadians64 } +/// Converts degress to radians. +/// +/// - Parameter degrees: an angle vector (in degrees) +/// - Returns: the argument converted to radians. @inline(__always) public func radians(_ degrees: Vec3f) -> Vec3f { Vec3f(x: FirebladeMath.radians(degrees.x), diff --git a/Sources/FirebladeMath/Quat/Quat4f+Euler.swift b/Sources/FirebladeMath/Quat/Quat4f+Euler.swift index 2043d62..14cddc6 100644 --- a/Sources/FirebladeMath/Quat/Quat4f+Euler.swift +++ b/Sources/FirebladeMath/Quat/Quat4f+Euler.swift @@ -12,6 +12,9 @@ extension Quat4f { // return Quat4f(q1, q2, q3, q4) // } + /// Creates a quaternion from Euler angles using 1-2-3 (X-Y-Z) rotation sequence. + /// - Parameter euler: Euler angles in radians. + /// - Returns: A quaternion representing the rotation. public static func fromEulerAngles_123(_ euler: Vec3f) -> Quat4f { let c1 = cos(euler.x / 2.0) let s1 = sin(euler.x / 2.0) @@ -41,6 +44,9 @@ extension Quat4f { // return Quat4f(q1, q2, q3, q4) // } + /// Creates a quaternion from Euler angles using 1-3-2 (X-Z-Y) rotation sequence. + /// - Parameter euler: Euler angles in radians. + /// - Returns: A quaternion representing the rotation. public static func fromEulerAngles_132(_ euler: Vec3f) -> Quat4f { let c1 = cos(euler.x / 2.0) let s1 = sin(euler.x / 2.0) @@ -70,6 +76,9 @@ extension Quat4f { // return Quat4f(q1, q2, q3, q4) // } + /// Creates a quaternion from Euler angles using 2-1-3 (Y-X-Z) rotation sequence. + /// - Parameter euler: Euler angles in radians. + /// - Returns: A quaternion representing the rotation. public static func fromEulerAngles_213(_ euler: Vec3f) -> Quat4f { let c1 = cos(euler.x / 2.0) let s1 = sin(euler.x / 2.0) @@ -86,6 +95,9 @@ extension Quat4f { return Quat4f(q1, q2, q3, q4) } + /// Creates a quaternion from Euler angles using 2-3-1 (Y-Z-X) rotation sequence. + /// - Parameter euler: Euler angles in radians. + /// - Returns: A quaternion representing the rotation. public static func fromEulerAngles_231(_ euler: Vec3f) -> Quat4f { let c1 = cos(euler.x / 2.0) let s1 = sin(euler.x / 2.0) @@ -115,6 +127,9 @@ extension Quat4f { // return Quat4f(q1, q2, q3, q4) // } + /// Creates a quaternion from Euler angles using 3-1-2 (Z-X-Y) rotation sequence. + /// - Parameter euler: Euler angles in radians. + /// - Returns: A quaternion representing the rotation. public static func fromEulerAngles_312(_ euler: Vec3f) -> Quat4f { let c1 = cos(euler.x / 2.0) let s1 = sin(euler.x / 2.0) @@ -144,6 +159,9 @@ extension Quat4f { // return Quat4f(q1, q2, q3, q4) // } + /// Creates a quaternion from Euler angles using 3-2-1 (Z-Y-X) rotation sequence. + /// - Parameter euler: Euler angles in radians. + /// - Returns: A quaternion representing the rotation. public static func fromEulerAngles_321(_ euler: Vec3f) -> Quat4f { let c1 = cos(euler.x / 2.0) let s1 = sin(euler.x / 2.0) @@ -160,23 +178,32 @@ extension Quat4f { return Quat4f(q1, q2, q3, q4) } + /// Creates a quaternion from pitch, yaw, and roll angles in radians. + /// - Parameters: + /// - pitch: Rotation around the X axis in radians. + /// - yaw: Rotation around the Y axis in radians. + /// - roll: Rotation around the Z axis in radians. @inlinable public init(pitch: Float, yaw: Float, roll: Float) { self = Quat4f.fromEulerAngles_321(Vec3f(pitch, yaw, roll)) } + /// The Euler angles (pitch, yaw, roll) in radians. @inlinable public var eulerAngles: Vec3f { quaternionToEulerAngles_321(self) } + /// The pitch angle in radians (rotation around the X axis). @inlinable public var pitch: Float { eulerAngles.x } + /// The yaw angle in radians (rotation around the Y axis). @inlinable public var yaw: Float { eulerAngles.y } + /// The roll angle in radians (rotation around the Z axis). @inlinable public var roll: Float { eulerAngles.z } @@ -208,6 +235,9 @@ extension Quat4f { // return Vec3f(e1, e2, e3) // } +/// Converts a quaternion to Euler angles using 1-2-3 (X-Y-Z) rotation sequence. +/// - Parameter quat: The input quaternion. +/// - Returns: The Euler angles in radians. public func quaternionToEulerAngles_123(_ quat: Quat4f) -> Vec3f { let q0 = quat.w let q1 = quat.z @@ -231,6 +261,9 @@ public func quaternionToEulerAngles_123(_ quat: Quat4f) -> Vec3f { // return Vec3f(e1, e2, e3) // } +/// Converts a quaternion to Euler angles using 1-3-2 (X-Z-Y) rotation sequence. +/// - Parameter quat: The input quaternion. +/// - Returns: The Euler angles in radians. public func quaternionToEulerAngles_132(_ quat: Quat4f) -> Vec3f { let q0 = quat.w let q1 = quat.z @@ -255,6 +288,9 @@ public func quaternionToEulerAngles_132(_ quat: Quat4f) -> Vec3f { // return Vec3f(e1, e2, e3) // } +/// Converts a quaternion to Euler angles using 2-1-3 (Y-X-Z) rotation sequence. +/// - Parameter quat: The input quaternion. +/// - Returns: The Euler angles in radians. public func quaternionToEulerAngles_213(_ quat: Quat4f) -> Vec3f { let q0 = quat.w let q1 = quat.z @@ -268,6 +304,9 @@ public func quaternionToEulerAngles_213(_ quat: Quat4f) -> Vec3f { return Vec3f(e1, e2, e3) } +/// Converts a quaternion to Euler angles using 2-3-1 (Y-Z-X) rotation sequence. +/// - Parameter quat: The input quaternion. +/// - Returns: The Euler angles in radians. public func quaternionToEulerAngles_231(_ quat: Quat4f) -> Vec3f { let q0 = quat.w let q1 = quat.z @@ -292,6 +331,9 @@ public func quaternionToEulerAngles_231(_ quat: Quat4f) -> Vec3f { // return Vec3f(e1, e2, e3) // } +/// Converts a quaternion to Euler angles using 3-1-2 (Z-X-Y) rotation sequence. +/// - Parameter quat: The input quaternion. +/// - Returns: The Euler angles in radians. public func quaternionToEulerAngles_312(_ quat: Quat4f) -> Vec3f { let q0 = quat.w let q1 = quat.z @@ -316,6 +358,9 @@ public func quaternionToEulerAngles_312(_ quat: Quat4f) -> Vec3f { // return Vec3f(e1, e2, e3) // } +/// Converts a quaternion to Euler angles using 3-2-1 (Z-Y-X) rotation sequence. +/// - Parameter quat: The input quaternion. +/// - Returns: The Euler angles in radians. public func quaternionToEulerAngles_321(_ quat: Quat4f) -> Vec3f { let q0 = quat.w let q1 = quat.z diff --git a/Sources/FirebladeMath/Quat/Quaternion+Identity.swift b/Sources/FirebladeMath/Quat/Quaternion+Identity.swift index 7493851..406bd4f 100644 --- a/Sources/FirebladeMath/Quat/Quaternion+Identity.swift +++ b/Sources/FirebladeMath/Quat/Quaternion+Identity.swift @@ -1,10 +1,12 @@ extension Quat4d { + /// Returns the identity quaternion. public static var identity: Quat4d { Quat4d(0.0, 0.0, 0.0, 1.0) } } extension Quat4f { + /// Returns the identity quaternion. public static var identity: Quat4f { Quat4f(0.0, 0.0, 0.0, 1.0) }