snow-math 1.2.4 → 1.3.0pre0

data/lib/snow-math/ptr.rb

@@ -7,18 +7,74 @@ require 'fiddle'
 
 module Snow
 
-  [:Vec3, :Vec4, :Quat, :Mat3, :Mat4,
-   :Vec3Array, :Vec4Array, :QuatArray, :Mat3Array, :Mat4Array].each {
-    |klass_sym|
-    if const_defined?(klass_sym)
-      const_get(klass_sym).class_exec {
+  #
+  # A module to provide to_ptr methods for all Snow math types. This is optional
+  # and only used if you require `snow-math/ptr` because it depends on Fiddle,
+  # so if you don't want Fiddle pulled into your environment, you don't want to
+  # require the file for this.
+  #
+  module FiddlePointerSupport
+    #
+    # Returns a Fiddle::Pointer to the memory address of the object that extends
+    # through the size of the object.
+    #
+    # This function is only provided if you've required `snow-math/ptr`.
+    #
+    # call-seq: to_ptr -> Fiddle::Pointer
+    #
+    def to_ptr
+      Fiddle::Pointer.new(self.address, self.size)
+    end
+  end
+
+  class Vec3
+    include ::Snow::FiddlePointerSupport
+  end
+
+  class Vec4
+    include ::Snow::FiddlePointerSupport
+  end
+
+  class Quat
+    include ::Snow::FiddlePointerSupport
+  end
 
-        def to_ptr
-          Fiddle::Pointer.new(self.address, self.size)
-        end
+  class Mat3
+    include ::Snow::FiddlePointerSupport
+  end
+
+  class Mat4
+    include ::Snow::FiddlePointerSupport
+  end
+
+  if const_defined?(:Vec3Array)
+    class Vec3Array
+      include ::Snow::FiddlePointerSupport
+    end
+  end
+
+  if const_defined?(:Vec4Array)
+    class Vec4Array
+      include ::Snow::FiddlePointerSupport
+    end
+  end
+
+  if const_defined?(:QuatArray)
+    class QuatArray
+      include ::Snow::FiddlePointerSupport
+    end
+  end
+
+  if const_defined?(:Mat3Array)
+    class Mat3Array
+      include ::Snow::FiddlePointerSupport
+    end
+  end
 
-      }
+  if const_defined?(:Mat4Array)
+    class Mat4Array
+      include ::Snow::FiddlePointerSupport
     end
-  }
+  end
 
 end

data/lib/snow-math/quat.rb

@@ -7,6 +7,11 @@ require 'snow-math/bindings'
 module Snow ; end
 
 if Snow.const_defined?(:QuatArray)
+  #
+  # A contiguous array of Quats. Allocated as a single block of memory so that
+  # it can easily be passed back to C libraries (like OpenGL) and to aid with
+  # cache locality.
+  #
   class Snow::QuatArray
     class << self ; alias_method :[], :new ; end
 
@@ -15,65 +20,116 @@ if Snow.const_defined?(:QuatArray)
   end
 end
 
+#
+# A simple quaternion class for representation rotations.
+#
 class Snow::Quat
 
   class << self ; alias_method :[], :new ; end
 
   alias_method :[], :fetch
   alias_method :[]=, :store
+  alias_method :dup, :copy
+  alias_method :clone, :copy
 
+
+  # Returns the X component of the quaternion.
+  #
+  # call-seq: x -> float
   def x
     self[0]
   end
 
+  # Sets the X component of the quaternion.
+  #
+  # call-seq: x = value -> value
   def x=(value)
     self[0] = value
   end
 
+  # Returns the Y component of the quaternion.
+  #
+  # call-seq: y -> float
   def y
     self[1]
   end
 
+  # Sets the Y component of the quaternion.
+  #
+  # call-seq: y = value -> value
   def y=(value)
     self[1] = value
   end
 
+  # Returns the Z component of the quaternion.
+  #
+  # call-seq: z -> float
   def z
     self[2]
   end
 
+  # Sets the Z component of the quaternion.
+  #
+  # call-seq: z = value -> value
   def z=(value)
     self[2] = value
   end
 
+  # Returns the W component of the quaternion.
+  #
+  # call-seq: w -> float
   def w
     self[3]
   end
 
+  # Sets the W component of the quaternion.
+  #
+  # call-seq: w = value -> value
   def w=(value)
     self[3] = value
   end
 
-  def dup
-    self.class.new(self)
-  end
-
+  # Calls #normalize(self)
+  #
+  # call-seq: normalize! -> self
   def normalize!
     normalize self
   end
 
+  # Calls #inverse(self)
+  #
+  # call-seq: inverse! -> self
   def inverse!
     inverse self
   end
 
+  # Calls #negate(self)
+  #
+  # call-seq: negate! -> self
   def negate!
     negate self
   end
 
+  # Calls #multiply_quat(rhs, self)
+  #
+  # call-seq: multiply_quat!(rhs) -> self
   def multiply_quat!(rhs)
     multiply_quat rhs, self
   end
 
+  # Calls #multiply_vec3(rhs, rhs)
+  #
+  # call-seq: multiply_vec3!(rhs) -> rhs
+  def multiply_vec3!(rhs)
+    multiply_vec3 rhs, rhs
+  end
+
+  # Wrapper around #multiply_quat, #multiply_vec3, and #scale respectively.
+  #
+  # call-seq:
+  #     multiply(quat, output = nil) -> output or new quat
+  #     multiply(scalar, output = nil) -> output or new quat
+  #     multiply(vec3, output = nil) -> output or new vec3
   def multiply(rhs, output = nil)
     case rhs
     when ::Snow::Quat then multiply_quat(rhs, output)
@@ -83,26 +139,56 @@ class Snow::Quat
     end
   end
 
+  # Calls #multiply(rhs, self) for scaling and Quat multiplication, otherwise
+  # #multiply(rhs, rhs) for Vec3 multiplication.
+  #
+  # call-seq:
+  #     multiply!(quat) -> self
+  #     multiply!(scalar) -> self
+  #     multiply!(vec3) -> vec3
   def multiply!(rhs)
-    multiply_quat! rhs
+    case rhs
+    when ::Snow::Vec3 then multiply(rhs, rhs)
+    else multiply(rhs, self)
+    end
   end
 
+  # Calls #add(rhs, self)
+  #
+  # call-seq: add!(rhs) -> self
   def add!(rhs)
     add rhs, self
   end
 
+  # Calls #subtract(rhs, self)
+  #
+  # call-seq: subtract!(rhs) -> self
   def subtract!(rhs)
     subtract rhs, self
   end
 
+  # Calls #scale(rhs, self)
+  #
+  # call-seq: scale!(rhs) -> self
   def scale!(rhs)
     scale rhs, self
   end
 
+  # Calls #divide(rhs, self)
+  #
+  # call-seq: divide!(rhs) -> self
   def divide!(rhs)
     divide rhs, self
   end
 
+  # Calls #slerp(destination, alpha, self)
+  #
+  # call-seq: slerp!(destination, alpha) -> self
+  def slerp!(destination, alpha)
+    slerp(destination, alpha, self)
+  end
+
+
   alias_method :-, :subtract
   alias_method :+, :add
   alias_method :**, :dot_product

data/lib/snow-math/swizzle.rb

@@ -6,57 +6,94 @@ require 'snow-math'
 
 module Snow ; end
 
+module Snow
+
+  #
+  # Provides swizzle function support for Vec3, Vec4, and Quat. At runtime, if
+  # a message matching `/^[xyzw]{3,4}$/`, sans `w` in Vec3's case, is sent to
+  # any of those types, a new method will be generated to return a swizzled
+  # object of that type or one that contains at least as many elements as
+  # requested.
+  #
+  # For Vec3, valid swizzle components are `x`, `y`, and `z`. If a swizzle
+  # function with three of those components is called, a new Vec3 is returned.
+  # If a swizzle function with four components is called, a Vec4 is returned.
+  # This is the same for Vec4, although it also provides a `w` component.
+  #
+  # For Quat types, behavior is similar to Vec4, though a 4-component swizzle
+  # function returns a Quat instead of a Vec4.
+  #
+  #     # Good
+  #     Vec3[1, 2, 3].xxx           # => Vec3[1, 1, 1]
+  #     Vec3[1, 2, 3].xxzz          # => Vec4[1, 1, 3, 3]
+  #     Vec4[1, 2, 3, 4].xzwy       # => Vec4[1, 3, 4, 2]
+  #     Quat[1, 2, 3, 4].wzyx       # => Quat[4, 3, 2, 1]
+  #
+  #     # Bad
+  #     Vec3[1, 2, 3].www           # => Invalid, no W component for Vec3
+  #     Vec3[1, 2, 3].xx            # => Invalid, no 2-component vector type
+  #     Vec3[1, 2, 3].xxxxx         # => Invalid, no 5-component vector type
+  #
+  module SwizzleSupport
+
+    alias_method :__under_method_missing__, :method_missing
+
+    #
+    # Generates a swizzle function according to a class's @@SWIZZLE_CHARS and
+    # @@SWIZZLE_MAPPING class variables.
+    #
+    # Overrides old method_missing implementation. The old implementation is
+    # aliased as \_\_under_method_missing__ and called when no swizzle function
+    # can be generated for a symbol.
+    #
+    def method_missing(sym, *args)
+      chars = sym.to_s
+      if chars =~ self.class.class_variable_get(:@@SWIZZLE_CHARS)
+        mapping = self.class.class_variable_get(:@@SWIZZLE_MAPPING)
+        arg_indices = chars.each_char.map {
+          |char|
+          index = mapping[char]
+          if index.nil?
+            raise ArgumentError, "No index mapping for swizzle character #{char} found"
+          end
+          index
+        }
+        swizzle_klass = mapping[chars.length]
+
+        if swizzle_klass.nil?
+          raise ArgumentError, "No swizzle class defined for #{chars.length} components"
+        end
+
+        self.class.class_exec(arg_indices, swizzle_klass) {
+          |indices, klass|
+          define_method(sym) {
+            klass.new(indices.map { |index| self.fetch(index) })
+          }
+        }
+        return self.send(sym)
+      end
+
+      __under_method_missing__ sym, *args
+    end
+
+  end
+
+end
+
 class Snow::Vec3
   @@SWIZZLE_CHARS = /^[xyz]{3,4}$/
   @@SWIZZLE_MAPPING = { 3 => self, 4 => ::Snow::Vec4, 'x' => 0, 'y' => 1, 'z' => 2 }
+  include ::Snow::SwizzleSupport
 end
 
 class Snow::Vec4
   @@SWIZZLE_CHARS = /^[xyzw]{3,4}$/
   @@SWIZZLE_MAPPING = { 3 => ::Snow::Vec3, 4 => self, 'x' => 0, 'y' => 1, 'z' => 2, 'w' => 3 }
+  include ::Snow::SwizzleSupport
 end
 
 class Snow::Quat
   @@SWIZZLE_CHARS = /^[xyzw]{3,4}$/
   @@SWIZZLE_MAPPING = { 3 => ::Snow::Vec3, 4 => self, 'x' => 0, 'y' => 1, 'z' => 2, 'w' => 3 }
-end
-
-module Snow
-
-  [:Vec3, :Vec4, :Quat].each {
-    |klass_sym|
-
-    const_get(klass_sym).class_exec {
-
-      def method_missing(sym, *args)
-        chars = sym.to_s
-        if chars =~ self.class.class_variable_get(:@@SWIZZLE_CHARS)
-          mapping = self.class.class_variable_get(:@@SWIZZLE_MAPPING)
-          arg_indices = chars.each_char.map {
-            |char|
-            index = mapping[char]
-            if index.nil?
-              raise ArgumentError, "No index mapping for swizzle character #{char} found"
-            end
-            index
-          }
-          swizzle_klass = mapping[chars.length]
-
-          if swizzle_klass.nil?
-            raise ArgumentError, "No swizzle class defined for #{chars.length} components"
-          end
-
-          self.class.class_exec(arg_indices, swizzle_klass) {
-            |indices, klass|
-            define_method(sym) { klass.new(indices.map { |index| self.fetch(index) }) }
-          }
-          return self.send(sym)
-        end
-
-        super sym, *args
-      end
-
-    }
-  }
-
+  include ::Snow::SwizzleSupport
 end

data/lib/snow-math/to_a.rb

@@ -6,43 +6,186 @@ require 'snow-math'
 
 module Snow
 
-  [:Vec3, :Vec4, :Quat, :Mat3, :Mat4,
-   :Vec3Array, :Vec4Array, :QuatArray, :Mat3Array, :Mat4Array].each {
-    |klass_sym|
-    if const_defined?(klass_sym)
-      const_get(klass_sym).class_exec {
-
-        include ::Enumerable
-
-        def to_a
-          (0 ... self.length).each.map { |index| fetch(index) }
-        end
-
-        def each(&block)
-          return to_enum(:each) unless block_given?
-          (0 ... self.length).each {
-            |index|
-            yield(fetch(index))
-          }
-          self
-        end
-
-        def map!(&block)
-          return to_enum(:map!) unless block_given?
-          (0 ... self.length).each {
-            |index|
-            store(index, yield(fetch(index)))
-          }
-          self
-        end
-
-        def map(&block)
-          return to_enum(:map) unless block_given?
-          self.dup.map!(&block)
-        end
+  #
+  # Provides basic support for converting Snow math objects to Ruby arrays. In
+  # addition, it also provides rudimentary support for each, map, and map! for
+  # all math types.
+  #
+  # For example:
+  #
+  #     # Arrays of cells by column
+  #     Mat4[*(1 .. 16)].group_by {
+  #       |cell|
+  #       (cell.floor - 1) % 4
+  #     }
+  #
+  #     # Arrays of cells by row
+  #     Mat4[*(1 .. 16)].group_by {
+  #       |cell|
+  #       ((cell - 1) / 4).floor
+  #     } # => { 0 => [1, 2, 3, 4],
+  #       #      1 => [5, 6, 7, 8],
+  #       #      2 => [9, 10, 11, 12],
+  #       #      3 => [13, 14, 15, 16] }
+  #
+  # Note that these examples are only showing that you can use these types like
+  # most others that include the Enumerable module. The above examples are not
+  # sane ways to get columns or rows out of a Mat4.
+  #
+  module ArraySupport
 
+    include ::Enumerable
+
+    #
+    # Returns an array composed of the elements of self.
+    #
+    # call-seq: to_a -> new_ary
+    #
+    def to_a
+      (0 ... self.length).each.map { |index| fetch(index) }
+    end
+
+    #
+    # Iterates over all elements of the object and yields them to a block.
+    # In the second form, returns an Enumerator.
+    #
+    # call-seq:
+    #   each { |elem| block } -> self
+    #   each -> Enumerator
+    #
+    def each(&block)
+      return to_enum(:each) unless block_given?
+      (0 ... self.length).each {
+        |index|
+        yield(fetch(index))
       }
+      self
+    end
+
+    #
+    # In the first form, iterates over all elements of the object, yields them
+    # to the block given, and overwrites the element's value with the value
+    # returned by the block.
+    #
+    # In the second form, returns an Enumerator.
+    #
+    # The return value of the block must be the same kind of object as was
+    # yielded to the block. So, if yielded a Vec3, the block must return a Vec3.
+    # If yielded a Numeric, it must return a Numeric.
+    #
+    # call-seq:
+    #   map! { |elem| block } -> self
+    #   map! -> Enumerator
+    #
+    def map!(&block)
+      return to_enum(:map!) unless block_given?
+      (0 ... self.length).each {
+        |index|
+        store(index, yield(fetch(index)))
+      }
+      self
+    end
+
+    #
+    # In the first form, duplicates self and then calls map! on the duplicated
+    # object, passing the block to map!.
+    #
+    # In the second form, returns an Enumerator.
+    #
+    # The return value of the block must be the same kind of object as was
+    # yielded to the block. So, if yielded a Vec3, the block must return a Vec3.
+    # If yielded a Numeric, it must return a Numeric.
+    #
+    # call-seq:
+    #   map { |elem| block } -> new object
+    #   map -> Enumerator
+    #
+    def map(&block)
+      return to_enum(:map) unless block_given?
+      self.dup.map!(&block)
+    end
+
+  end
+
+  class Vec3 ; include ::Snow::ArraySupport ; end
+  class Vec4 ; include ::Snow::ArraySupport ; end
+  class Quat ; include ::Snow::ArraySupport ; end
+  class Mat3 ; include ::Snow::ArraySupport ; end
+  class Mat4 ; include ::Snow::ArraySupport ; end
+
+  if const_defined?(:Vec3Array)
+    class Vec3Array
+      include ::Snow::ArraySupport
+
+      #
+      # Duplicates the Vec3Array and returns it.
+      #
+      # call-seq: dup -> new vec3_array
+      #
+      def dup
+        self.class.new(self)
+      end
+    end
+  end
+
+  if const_defined?(:Vec4Array)
+    class Vec4Array
+      include ::Snow::ArraySupport
+
+      #
+      # Duplicates the Vec4Array and returns it.
+      #
+      # call-seq: dup -> new vec4_array
+      #
+      def dup
+        self.class.new(self)
+      end
+    end
+  end
+
+  if const_defined?(:QuatArray)
+    class QuatArray
+      include ::Snow::ArraySupport
+
+      #
+      # Duplicates the QuatArray and returns it.
+      #
+      # call-seq: dup -> new quat_array
+      #
+      def dup
+        self.class.new(self)
+      end
+    end
+  end
+
+  if const_defined?(:Mat3Array)
+    class Mat3Array
+      include ::Snow::ArraySupport
+
+      #
+      # Duplicates the Mat3Array and returns it.
+      #
+      # call-seq: dup -> new mat3_array
+      #
+      def dup
+        self.class.new(self)
+      end
+    end
+  end
+
+  if const_defined?(:Mat4Array)
+    class Mat4Array
+      include ::Snow::ArraySupport
+
+      #
+      # Duplicates the Mat4Array and returns it.
+      #
+      # call-seq: dup -> new mat4_array
+      #
+      def dup
+        self.class.new(self)
+      end
     end
-  }
+  end
 
 end