From 0ea1e5c2ff146c1c0286c7ababbd6d4142985744 Mon Sep 17 00:00:00 2001 From: Cyberarm Date: Wed, 29 Jan 2020 10:55:51 -0600 Subject: [PATCH] Add documentation for Vector --- lib/cyberarm_engine/vector.rb | 101 +++++++++++++++++++++++++++++++--- 1 file changed, 93 insertions(+), 8 deletions(-) diff --git a/lib/cyberarm_engine/vector.rb b/lib/cyberarm_engine/vector.rb index 65a2f5b..8d9b884 100644 --- a/lib/cyberarm_engine/vector.rb +++ b/lib/cyberarm_engine/vector.rb @@ -1,25 +1,61 @@ module CyberarmEngine class Vector + ## + # Creates a up vector + # + # Vector.new(0, 1, 0) + # + # @return [CyberarmEngine::Vector] def self.up Vector.new(0, 1, 0) end + ## + # Creates a down vector + # + # Vector.new(0, -1, 0) + # + # @return [CyberarmEngine::Vector] def self.down Vector.new(0, -1, 0) end + ## + # Creates a left vector + # + # Vector.new(-1, 0, 0) + # + # @return [CyberarmEngine::Vector] def self.left Vector.new(-1, 0, 0) end + ## + # Creates a right vector + # + # Vector.new(1, 0, 0) + # + # @return [CyberarmEngine::Vector] def self.right Vector.new(1, 0, 0) end + ## + # Creates a forward vector + # + # Vector.new(0, 0, 1) + # + # @return [CyberarmEngine::Vector] def self.forward Vector.new(0, 0, 1) end + ## + # Creates a backward vector + # + # Vector.new(0, 0, -1) + # + # @return [CyberarmEngine::Vector] def self.backward Vector.new(0, 0, -1) end @@ -43,6 +79,7 @@ module CyberarmEngine alias w weight alias w= weight= + # @return [Boolean] def ==(other) if other.is_a?(Numeric) @x == other && @@ -57,11 +94,13 @@ module CyberarmEngine end end + # Create a new vector using {x} and {y} values + # @return [CyberarmEngine::Vector] def xy Vector.new(@x, @y) end - # Performs math operation, excluding @weight + # Performs math operation, excluding {weight} private def operator(function, other) if other.is_a?(Numeric) Vector.new( @@ -78,22 +117,26 @@ module CyberarmEngine end end - # Adds Vector and Numberic or Vector and Vector, excluding @weight + # Adds Vector and Numeric or Vector and Vector, excluding {weight} + # @return [CyberarmEngine::Vector] def +(other) operator("+", other) end - # Subtracts Vector and Numberic or Vector and Vector, excluding @weight + # Subtracts Vector and Numeric or Vector and Vector, excluding {weight} + # @return [CyberarmEngine::Vector] def -(other) operator("-", other) end - # Multiplies Vector and Numberic or Vector and Vector, excluding @weight + # Multiplies Vector and Numeric or Vector and Vector, excluding {weight} + # @return [CyberarmEngine::Vector] def *(other) operator("*", other) end - # Divides Vector and Numberic or Vector and Vector, excluding @weight + # Divides Vector and Numeric or Vector and Vector, excluding {weight} + # @return [CyberarmEngine::Vector] def /(other) # Duplicated to protect from DivideByZero if other.is_a?(Numeric) @@ -111,6 +154,8 @@ module CyberarmEngine end end + # dot product of {Vector} + # @return [Integer|Float] def dot(other) product = 0 @@ -124,6 +169,8 @@ module CyberarmEngine return product end + # cross product of {Vector} + # @return [CyberarmEngine::Vector] def cross(other) a = self.to_a b = other.to_a @@ -136,24 +183,40 @@ module CyberarmEngine end # returns degrees + # @return [Float] def angle(other) Math.acos( self.normalized.dot(other.normalized) ) * 180 / Math::PI end # returns magnitude of Vector, ignoring #weight + # @return [Float] def magnitude Math.sqrt((@x * @x) + (@y * @y) + (@z * @z)) end + ## + # returns normalized {Vector} + # + # @example + # CyberarmEngine::Vector.new(50, 21.2, 45).normalized + # # => + # + # @return [CyberarmEngine::Vector] def normalized mag = magnitude self / Vector.new(mag, mag, mag) end + + # returns a direction {Vector} + # + # z is pitch + # + # y is yaw + # + # x is roll + # @return [CyberarmEngine::Vector] def direction - # z is pitch - # y is yaw - # x is roll _x = -Math.sin(@y.degrees_to_radians) * Math.cos(@z.degrees_to_radians) _y = Math.sin(@z.degrees_to_radians) _z = Math.cos(@y.degrees_to_radians) * Math.cos(@z.degrees_to_radians) @@ -161,41 +224,63 @@ module CyberarmEngine Vector.new(_x, _y, _z) end + # returns an inverse {Vector} + # @return [CyberarmEngine::Vector] def inverse Vector.new(1.0 / @x, 1.0 / @y, 1.0 / @z) end + # Adds up values of {x}, {y}, and {z} + # @return [Integer|Float] def sum @x + @y + @z end + ## + # Linear interpolation: smoothly transition between two {Vector} + # + # CyberarmEngine::Vector.new(100, 100, 100).lerp( CyberarmEngine::Vector.new(0, 0, 0), 0.75 ) + # # => + # + # @param other [CyberarmEngine::Vector | Integer | Float] value to subtract from + # @param factor [Float] how complete transition to _other_ is, in range [0.0..1.0] + # @return [CyberarmEngine::Vector] def lerp(other, factor) (self - other) * factor.clamp(0.0, 1.0) end # 2D distance using X and Y + # @return [Float] def distance(other) Math.sqrt((@x-other.x)**2 + (@y-other.y)**2) end # 2D distance using X and Z + # @return [Float] def gl_distance2d(other) Math.sqrt((@x-other.x)**2 + (@z-other.z)**2) end # 3D distance using X, Y, and Z + # @return [Float] def distance3d(other) Math.sqrt((@x-other.x)**2 + (@y-other.y)**2 + (@z-other.z)**2) end + # Converts {Vector} to Array + # @return [Array] def to_a [@x, @y, @z, @weight] end + # Converts {Vector} to String + # @return [String] def to_s "X: #{@x}, Y: #{@y}, Z: #{@z}, Weight: #{@weight}" end + # Converts {Vector} to Hash + # @return [Hash] def to_h {x: @x, y: @y, z: @z, weight: @weight} end