numerix 1.0.0

data/lib/numerix/plane.rb

@@ -0,0 +1,154 @@
+module Numerix
+
+  ##
+  # A structure encapsulating a 3D Plane.
+  class Plane < Structure
+
+    ##
+    # @return [Vector3] the normal vector of the plane.
+    attr_accessor :normal
+
+    ##
+    # @return [Float] the distance of the plane along its normal from the
+    #   origin.
+    attr_accessor :distance
+
+    ##
+    # @overload initialize
+    #   Creates a new plane will all values default to `0.0`.
+    #
+    # @overload initialize(vector)
+    #   Constructs a Plane from the given Vector4.
+    #
+    #   @param vector [Vector4] A vector whose first 3 elements describe the
+    #     normal vector, and whose W component defines the distance along that
+    #     normal from the origin.
+    # 
+    # @overload initialize(normal, distance)
+    #   Constructs a Plane from the given normal and distance along the normal
+    #   from the origin.
+    #
+    #   @param normal [Vector3] The normal vector of the plane.
+    #   @param distance [Float] The distance of the plane along its normal from
+    #     the origin.
+    #
+    # @overload initialize(x, y, z, distance)
+    #   Constructs a plane from the X, Y, and Z components of its normal, and
+    #   its distance from the origin on that normal.
+    #
+    #   @param x [Float] The normal X component.
+    #   @param y [Float] The normal Y component.
+    #   @param z [Float] The normal Z component.
+    #   @param distance [Float] The distance of the Plane along its normal from
+    #     the origin.
+    def initialize(*args)
+    end
+
+    ##
+    # @note This plane must already be normalized, so that its normal vector is
+    #   of unit length, before this method is called.
+    #
+    # Applies a transformation to the plane.
+    #
+    # @overload transform(matrix)
+    #
+    #   Transforms a normalized plane by a matrix.
+    #
+    #   @param matrix [Matrix4x4] The transformation matrix.
+    #
+    #   @return [Plane] the transformed plane.
+    #
+    # @overload transform(rotation)
+    #   Transforms a normalized plane by a quaternion rotation.
+    #
+    #   @param rotation [Quaternion] The rotation to apply.
+    #
+    # @return [Plane] A new plane that results from applying the rotation.
+    def transform(other)
+    end
+
+    ##
+    # @note This plane must already be normalized, so that its normal vector is
+    #   of unit length, before this method is called.
+    #
+    # Applies a transformation to the plane.
+    #
+    # @overload transform!(matrix)
+    #
+    #   Transforms a normalized plane by a matrix.
+    #
+    #   @param matrix [Matrix4x4] The transformation matrix.
+    #
+    # @overload transform!(rotation)
+    #   Transforms a normalized plane by a quaternion rotation.
+    #
+    #   @param rotation [Quaternion] The rotation to apply.
+    #
+    # @return [self] 
+    def transform!(other)
+    end
+
+    ##
+    # Calculates the dot product of a plane and {Vector4}.
+    #
+    # @param other [Vector4] The vector to compute.
+    #
+    # @return [Float] the dot product.
+    def dot(other)
+    end
+
+    ##
+    # Returns the dot product of a specified {Vector3} and the normal vector of
+    # this Plane plus the distance value of the plane.
+    #
+    # @param other [Vector3] The vector to compute.
+    #
+    # @return [Float] the dot product.
+    def dot_coord(other)
+    end
+
+    ##
+    # Returns the dot product of a specified Vector3 and the normal vector of
+    # this plane.
+    #
+    # @param other [Vector3] The vector to compute.
+    #
+    # @return [Float]
+    def dot_norm(other)
+    end
+
+    ##
+    # Creates a new plane whose normal vector is the source plane's normal
+    # vector normalized.
+    #
+    # @return [Plane] newly created normalized plane.
+    def normalize
+    end
+
+    ##
+    # Normalizes this plane's normal vector.
+    #
+    # @return [self]
+    def normalize!
+    end
+
+    ##
+    # @return [String] a String representation of this instance.
+    def to_s
+    end
+
+    class << self
+
+      ##
+      # Creates a Plane that contains the three given points.
+      #
+      # @param pnt1 [Vector3] The first point defining the plane.
+      # @param pnt2 [Vector3] The second point defining the plane.
+      # @param pnt3 [Vector3] The third point defining the plane.
+      #
+      # @return [Plane] the plane containing the three points.
+      def from_vertices(pnt1, pnt2, pnt3)
+      end
+    end
+  end
+end

data/lib/numerix/quaternion.rb

@@ -0,0 +1,355 @@
+module Numerix
+
+  ##
+  # A structure encapsulating a four-dimensional vector (x,y,z,w), which is used
+  # to efficiently rotate an object about the (x,y,z) vector by the angle theta,
+  # where `w = cos(theta / 2)`.
+  class Quaternion < Structure
+
+    ##
+    # @return [Float] the X-value of the quaternion component of the quaternion.
+    attr_accessor :x
+
+    ##
+    # @return [Float] the Y-value of the quaternion component of the quaternion.
+    attr_accessor :y
+
+    ##
+    # @return [Float] the Z-value of the quaternion component of the quaternion.
+    attr_accessor :z
+
+    ##
+    # @return [Float] the rotation component of the quaternion.
+    attr_accessor :w
+
+    ##
+    # @overload initialize
+    #   Constructs a default quaternion with all components set to `0.0`.
+    #
+    # @overload initialize(x, y, z, w)
+    #   Constructs a Quaternion from the given components.
+    #
+    #   @param x [Float] The X component of the quaternion.
+    #   @param y [Float] The Y component of the quaternion.
+    #   @param z [Float] The Z component of the quaternion.
+    #   @param w [Float] The W component of the quaternion.
+    #
+    # @overload initialize(vector, scalar)
+    #   Constructs a Quaternion from the given vector and rotation parts.
+    #
+    #   @param vector [Vector3] The vector part of the quaternion.
+    #   @param scalar [Float] The rotation part of the quaternion.
+    #
+    def initialize(*args) # TODO
+    end
+
+    ##
+    # @return [Boolean] `true` if the quaternion is the identity quaternion,
+    #   otherwise `false`.
+    def identity?
+    end
+
+    ##
+    # @return [Float] the length of the quaternion.
+    def length
+    end
+
+    alias_method :magnitude, :length
+
+    ##
+    # @return [Float] the length of the quaternion squared.
+    def length_squared
+    end
+
+    ##
+    # Returns a new quaternion with the same direction as the given quaternion,
+    # but with a length of `1.0`.
+    #
+    # @return [Quaternion] a normalized quaternion.
+    def normalize
+    end
+
+    ##
+    # Alters this quaternion instance to maintain same direction, but adjust
+    # values so that quaternion has a length of `1.0`.
+    #
+    # @return [self]
+    def normalize!
+    end
+
+    ##
+    # Creates the conjugate of this quaternion.
+    #
+    # @return [Quaternion] the conjugate of the os instance.
+    #
+    # @see conjugate!
+    def conjugate
+    end
+
+    ##
+    # Alters this instance to be its conjugate.
+    #
+    # @return [self]
+    #
+    # @see conjugate
+    def conjugate!
+    end
+
+    ##
+    # @return [Quaternion] the inverse of this quaternion.
+    def inverse
+    end
+
+    ##
+    # Calculates the dot product of two quaternions.
+    #
+    # @param other [Quaternion] The source quaternion to compute product from.
+    #
+    # @return [Float] the dot product of the quaternions.
+    def dot(other)
+    end
+
+    ##
+    # Concatenates this quaternion and another, the result represents the this
+    # rotation followed by the given quaternion's rotation.
+    #
+    # @param other [Quaternion] The rotation to add in the series.
+    #
+    # @return [Quaternion] a new quaternion representing the concatenation this
+    #   rotation followed by the other rotation.
+    #
+    # @see concatenate!
+    def concatenate(other)
+    end
+
+    ##
+    # @note This function is identical to {#concatenate}, but alters the values
+    #   of this instance without creating a new object.
+    #
+    # Concatenates this quaternion and another, the result represents the this
+    # rotation followed by the given quaternion's rotation.
+    #
+    # @param other [Quaternion] The rotation to add in the series.
+    #
+    # @return [self]
+    #
+    # @see concatenate
+    def concatenate!(other)
+    end
+
+    ##
+    # Linearly interpolates between this quaternion and another based on the
+    # given weighting.
+    #
+    # @param quaternion [Quaternion] The source quaternion to interpolate
+    #   between.
+    # @param amount [Float] Value between `0.0` and `1.0` indicating the weight
+    #   of the given quaternion.
+    #
+    # @return [Quaternion] the interpolated quaternion.
+    #
+    # @see lerp!
+    def lerp(quaternion, amount)
+    end
+
+    ##
+    # Linearly interpolates between this quaternion and another based on the given
+    # weighting, altering the values of this quaternion.
+    #
+    # @param quaternion [Quaternion] The source quaternion to interpolate between.
+    # @param amount [Float] Value between `0.0` and `1.0` indicating the weight
+    #   of the given quaternion.
+    #
+    # @return [self]
+    #
+    # @see lerp
+    def lerp!(quaternion, amount)
+    end
+
+    ##
+    # Interpolates between this quaternion and another using spherical linear
+    # interpolation.
+    #
+    # @param quaternion [Quaternion] The source quaternion to interpolate between.
+    # @param amount [Float] Value between `0.0` and `1.0` indicating the weight
+    #   of the given quaternion.
+    #
+    # @return [Quaternion] the interpolated quaternion.
+    #
+    # @see slerp!
+    def slerp(quaternion, amount)
+    end
+
+    ##
+    # @note This function is identical to {#slerp}, but alters the values of
+    #   this instance without creating a new object.
+    #
+    # Interpolates between this quaternion and another using spherical linear
+    # interpolation.
+    #
+    # @param quaternion [Quaternion] The source quaternion to interpolate between.
+    # @param amount [Float] Value between `0.0` and `1.0` indicating the weight
+    #   of the given quaternion.
+    #
+    # @return [self]
+    #
+    # @see slerp
+    def slerp!(quaternion, amount)
+    end
+
+    ##
+    # @return [String] a String representation of this instance.
+    def to_s
+    end
+
+    ##
+    # @return [Array<Float>] an Array representation of this instance.
+    def to_a
+    end
+
+    alias_method :elements, :to_a
+
+    ##
+    # @return [Hash{Symbol => Float}] a Hash representation of this instance.
+    def to_h
+    end
+
+    ##
+    # @return [Vector4] a {Vector4} representation of this instance.
+    def to_vec4
+    end
+
+    ##
+    # Performs unary negation on this quaternion instance.
+    #
+    # @return [Quaternion] the vector with swapped +/- values.
+    def -@
+    end
+
+    ##
+    # Adds this quaternion with another.
+    #
+    # @param other [Quaternion] The quaternion to add.
+    #
+    # @return [Quaternion] the sum of the quaternions.
+    def +(other)
+    end
+
+    # Gets the difference of this quaternion and another.
+    #
+    # @param other [Quaternion] The quaternion to subtract.
+    #
+    # @return [Quaternion] the difference of the quaternions.
+    def -(other)
+    end
+
+    ##
+    # Quaternion multiplication.
+    #
+    # @overload *(scalar)
+    #   Scalar quaternion multiplication.
+    #
+    #   @param scalar [Float] The scalar value.
+    #
+    # @overload *(other)
+    #   Multiplies this quaternion by another.
+    #
+    #   @param other [Quaternion] The source quaternion to multiply.
+    #
+    # @return [Quaternion] the product quaternion.
+    def *(other)
+    end
+
+    ##
+    # Quaternion division.
+    #
+    # @overload *(scalar)
+    #   Scalar quaternion division.
+    #
+    #   @param scalar [Float] The scalar value.
+    #
+    # @overload *(other)
+    #   Divides this quaternion by another.
+    #
+    #   @param other [Quaternion] The source quaternion to divide.
+    #
+    # @return [Quaternion] the resulting quaternion.
+    def /(other)
+    end
+
+    ##
+    # Returns flag if this quaternion instance is equal to the given object.
+    #
+    # @param other [Object] The object to compare.
+    #
+    # @return [Boolean] `true` if objects are equal, otherwise `false`.
+    def ==(other)
+    end
+
+    class << self
+
+      ##
+      # @return [Quaternion] a quaternion representing no rotation.
+      def identity
+      end
+
+      ##
+      # Creates a quaternion from a vector and an angle to rotate about the
+      # vector.
+      #
+      # @param axis [Vector3] The vector to rotate around.
+      # @param angle [Float] The angle, in radians, to rotate around the vector.
+      #
+      # @return [Quaternion] the created quaternion.
+      def from_axis_angle(axis, angle)
+      end
+
+      ##
+      # Creates a new quaternion from the given yaw, pitch, and roll, in
+      # radians.
+      #
+      # @param yaw [Float] The yaw angle, in radians, around the Y-axis.
+      # @param pitch [Float] The pitch angle, in radians, around the X-axis.
+      # @param roll [Float] The roll angle, in radians, around the Z-axis.
+      #
+      # @return [Quaternion] the created quaternion.
+      def from_yaw_pitch_roll(yaw, pitch, roll)
+      end
+
+      ##
+      # Creates a quaternion from the given rotation matrix.
+      #
+      # @param matrix [Matrix4x4] The rotation matrix
+      #
+      # @return [Quaternion] the created quaternion.
+      def from_rotation_matrix(matrix)
+      end
+
+      ##
+      # Interpolates between two quaternions, using spherical linear
+      # interpolation.
+      #
+      # @param quaternion1 [Quaternion] The first source quaternion.
+      # @param quaternion2 [Quaternion] The second source quaternion.
+      # @param amount [Float] Value between `0.0` and `1.0` indicating the
+      #   weight of the second source quaternion.
+      #
+      # @return [Quaternion] the interpolated quaternion.
+      def slerp(quaternion1, quaternion2, amount)
+      end
+
+      ##
+      # Linearly interpolates between two quaternions based on the given
+      # weighting.
+      #
+      # @param quaternion1 [Quaternion] The first source quaternion.
+      # @param quaternion2 [Quaternion] The second source quaternion.
+      # @param amount [Float] Value between `0.0` and `1.0` indicating the
+      #   weight of the second source quaternion.
+      #
+      # @return [Quaternion] the interpolated quaternion.
+      def lerp(quaternion1, quaternion2, amount)
+      end
+    end
+  end
+end

data/lib/numerix/structure.rb

@@ -0,0 +1,124 @@
+
+module Numerix
+
+  ##
+  # @abstract Abstract class providing common functionality to the base classes.
+  #
+  # This class cannot be instantiated, it of only for providing a common base
+  # class for all Numerix types and provide common functionality.
+  class Structure
+
+    private_class_method :new
+
+    ##
+    # @return [Object] an exact duplicate of the object.
+    def dup
+    end
+
+    ##
+    # @return [Integer] the address of the internal C-struct in memory.
+    def address
+    end
+
+    ##
+    # Enumerates over the components of the structure.
+    #
+    # @overload each
+    #   When called with a block, enumerates through each component of the
+    #   structure, yielding each before returning self;
+    #
+    #   @yield [component] Yields a component to the block.
+    #   @yieldparam component [Float] The current component.
+    #
+    #   @return [self]
+    #
+    # @overload each
+    #
+    #   When called without a block, returned an Enumerator for the structure.
+    #
+    #   @return [Enumerator] the enumerator for the structure.
+    def each
+    end
+
+    ##
+    # Retrieves the component of the structure at the specified position.
+    #
+    # @param index [Integer] The position of the component to retrieve.
+    #
+    # @return [Float, nil] the value at the given position, or +nil+ if _index_
+    #   is out of range.
+    #
+    # @see []=
+    def [](index)
+    end
+
+    ##
+    # Sets the component of the structure at the specified position.
+    #
+    # If _index_ is out of range, the method does nothing.
+    #
+    # @param index [Integer] The position of the component to set.
+    # @param value [Float] The value to set.
+    #
+    # @return [Float] the value
+    #
+    # @see []
+    def []=(index, value)
+    end
+
+    ##
+    # Packs the structures memory into a binary string.
+    #
+    # This is the equivalent of taking its values into an array and calling
+    # `array.pack('f*')` on it, though considerably faster as the parser is
+    # bypassed and done directly in C by accessing the memory directly.
+    #
+    # @return [String] the packed binary string.
+    #
+    # @see pack
+    def pack
+    end
+
+    alias_method :_dump, :pack
+
+    if RUBY_VERSION >= '2.0'
+
+      require 'fiddle'
+
+      ##
+      # @note This method only exists in Ruby 2.0 and higher, and will not be
+      #   present in lower versions.
+      #
+      # @return [Fiddle::Pointer] a sized pointer to the structure in memory.
+      #
+      # @see address
+      def ptr
+      end
+    end
+
+    class << self
+
+      ##
+      # @return [Integer] the size, in bytes, the structure contains in memory.
+      def size
+      end
+
+      ##
+      # Unpacks a binary string of data into a structure.
+      #
+      # This is the equivalent of calling `binary.unpack('f*')` on the string
+      # and using the values to create a new structure, but much faster as it
+      # bypasses the parser and is done in C directly with a pointer in memory.
+      #
+      # @param binary [String] Binary string of data.
+      #
+      # @return [Object] the unpacked structure.
+      #
+      # @see pack
+      def unpack(binary)
+      end
+
+      alias_method :_load, :unpack
+    end
+  end
+end

data/lib/numerix/vector.rb

@@ -0,0 +1,13 @@
+
+module Numerix
+
+  ##
+  # Analog of Ruby's standard library `Vector` class implemented in `C`.
+  #
+  # @note This class is not fully implemented integrated into the "core" 
+  #   Numerix classes as of version `1.0.0`. This will likely change in future
+  #   releases.
+  class Vector 
+    # @todo Document
+  end
+end