snow-math 1.2.4 → 1.3.0pre0

data/ext/snow-math/vec3.c

@@ -87,9 +87,9 @@ void vec3_negate(const vec3_t v, vec3_t out)
 
 void vec3_inverse(const vec3_t v, vec3_t out)
 {
-  out[2] = (v[2] != s_float_lit(0.0) && v[2] != s_float_lit(-0.0)) ? (s_float_lit(1.0) / v[2]) : v[2];
-  out[1] = (v[1] != s_float_lit(0.0) && v[1] != s_float_lit(-0.0)) ? (s_float_lit(1.0) / v[1]) : v[1];
-  out[0] = (v[0] != s_float_lit(0.0) && v[0] != s_float_lit(-0.0)) ? (s_float_lit(1.0) / v[0]) : v[0];
+  out[2] = (!float_is_zero(v[2])) ? (s_float_lit(1.0) / v[2]) : v[2];
+  out[1] = (!float_is_zero(v[1])) ? (s_float_lit(1.0) / v[1]) : v[1];
+  out[0] = (!float_is_zero(v[0])) ? (s_float_lit(1.0) / v[0]) : v[0];
 }
 
 void vec3_project(const vec3_t in, const vec3_t normal, vec3_t out)

data/ext/snow-math/vec4.c

@@ -95,10 +95,10 @@ void vec4_negate(const vec4_t v, vec4_t out)
 
 void vec4_inverse(const vec4_t v, vec4_t out)
 {
-  out[3] = (v[3] != s_float_lit(0.0) && v[3] != s_float_lit(-0.0)) ? (s_float_lit(1.0) / v[3]) : v[3];
-  out[2] = (v[2] != s_float_lit(0.0) && v[2] != s_float_lit(-0.0)) ? (s_float_lit(1.0) / v[2]) : v[2];
-  out[1] = (v[1] != s_float_lit(0.0) && v[1] != s_float_lit(-0.0)) ? (s_float_lit(1.0) / v[1]) : v[1];
-  out[0] = (v[0] != s_float_lit(0.0) && v[0] != s_float_lit(-0.0)) ? (s_float_lit(1.0) / v[0]) : v[0];
+  out[3] = (!float_is_zero(v[3])) ? (s_float_lit(1.0) / v[3]) : v[3];
+  out[2] = (!float_is_zero(v[2])) ? (s_float_lit(1.0) / v[2]) : v[2];
+  out[1] = (!float_is_zero(v[1])) ? (s_float_lit(1.0) / v[1]) : v[1];
+  out[0] = (!float_is_zero(v[0])) ? (s_float_lit(1.0) / v[0]) : v[0];
 }
 
 void vec4_project(const vec4_t in, const vec4_t normal, vec4_t out)

data/lib/snow-math.rb

@@ -11,6 +11,16 @@ require 'snow-math/quat'
 require 'snow-math/swizzle'
 require 'snow-math/inspect'
 require 'snow-math/to_a'
-require 'snow-math/array_cache'
+require 'snow-math/marshal'
 
-module Snow ; end
+#
+# Snow module -- covers Snow-related classes and methods.
+#
+module Snow
+
+  #
+  # snow-math bindings version string.
+  #
+  SNOW_MATH_VERSION = '1.3.0pre0'
+
+end

data/lib/snow-math/inspect.rb

@@ -6,30 +6,58 @@ require 'snow-math'
 
 module Snow
 
-  [:Vec3, :Vec4, :Quat, :Mat3, :Mat4].each {
-    |klass_sym|
-    if const_defined?(klass_sym)
-      const_get(klass_sym).class_exec {
+  #
+  # Provides support for inspect calls on Snow math types.
+  #
+  module InspectSupport
+
+    #
+    # Returns a serializable string for a given type.
+    #
+    # Output is defined as `<Type:Address Elements>`. For example:
+    #
+    #     Vec4[1, 2, 3, 4]   # => <Snow::Vec4:0x7f831981f5e0 1.0 2.0 3.0 4.0>
+    #
+    #     # The following example inner Vec3's elements have been made 0.0 even
+    #     # though they would ordinarily be garbage values.
+    #     Vec3Array[1]       # => <Snow::Vec3Array:0x7fe193b297a0 <Snow::Vec3:0x7fe193b297a0 0.0 0.0 0.0>>
+    #
+    # Bear in mind that the address may not be useful for serialization beyond
+    # determining when a given object has already been deserialized. You may
+    # want to treat it as semi-unique ID if serializing a math object, though
+    # there is absolutely no guarantee it will be unique between allocations and
+    # deallocations, as memory may obviously be reused.
+    #
+    def inspect
+      "<#{self.class.name}:0x#{self.address.to_s(16)} #{(0 ... self.length).map { |i| self.fetch(i).inspect }.join(' ')}>"
+    end
 
-        def inspect
-          "<#{self.class.name}:0x#{self.address.to_s(16)} #{(0 ... self.length).map { |i| self.fetch(i) }.join(' ')}>"
-        end
+  end
 
-      }
-    end
-  }
+  class Vec3 ; include ::Snow::InspectSupport ; end
+  class Vec4 ; include ::Snow::InspectSupport ; end
+  class Quat ; include ::Snow::InspectSupport ; end
+  class Mat3 ; include ::Snow::InspectSupport ; end
+  class Mat4 ; include ::Snow::InspectSupport ; end
 
-  [:Vec3Array, :Vec4Array, :QuatArray, :Mat3Array, :Mat4Array].each {
-    |klass_sym|
-    if const_defined?(klass_sym)
-      const_get(klass_sym).class_exec {
+  if const_defined?(:Vec3Array)
+    class Vec3Array ; include ::Snow::InspectSupport ; end
+  end
 
-        def inspect
-          "<#{self.class.name}:0x#{self.address.to_s(16)} #{(0 ... self.length).map { |i| self.fetch(i).inspect }.join(' ')}>"
-        end
+  if const_defined?(:Vec4Array)
+    class Vec4Array ; include ::Snow::InspectSupport ; end
+  end
 
-      }
-    end
-  }
+  if const_defined?(:QuatArray)
+    class QuatArray ; include ::Snow::InspectSupport ; end
+  end
+
+  if const_defined?(:Mat3Array)
+    class Mat3Array ; include ::Snow::InspectSupport ; end
+  end
+
+  if const_defined?(:Mat4Array)
+    class Mat4Array ; include ::Snow::InspectSupport ; end
+  end
 
 end

data/lib/snow-math/marshal.rb

@@ -0,0 +1,75 @@
+require 'snow-math/bindings'
+
+module Snow ; end
+
+module Snow::BaseMarshalSupport # :nodoc: all
+
+  #
+  def _dump(level)
+    # level ignored because it's not applicable
+    Marshal.dump(self.to_a)
+  end
+
+  module MarshalLoadSupport
+    def _load(args)
+      new(*Marshal.load(args))
+    end
+  end
+
+  def self.included(base)
+    base.extend(MarshalLoadSupport)
+  end
+
+end
+
+module Snow::ArrayMarshalSupport # :nodoc: all
+
+  def _dump(level)
+    to_dump = [self.length, *self.to_a.map { |elem| elem.copy }]
+    Marshal.dump(to_dump)
+  end
+
+  module MarshalLoadSupport
+    def _load(args)
+      info = Marshal.load(args)
+      arr = new(info[0])
+      # if not equal, then either something is corrupt or depth was 0
+      (1 ... info.length).each { |index| arr.store(index - 1, info[index]) }
+      arr
+    end
+  end
+
+  def self.included(base)
+    base.extend(MarshalLoadSupport)
+  end
+
+end
+
+module Snow
+  class Vec3 ; include ::Snow::BaseMarshalSupport ; end
+  class Vec4 ; include ::Snow::BaseMarshalSupport ; end
+  class Quat ; include ::Snow::BaseMarshalSupport ; end
+  class Mat3 ; include ::Snow::BaseMarshalSupport ; end
+  class Mat4 ; include ::Snow::BaseMarshalSupport ; end
+
+  if const_defined?(:Vec3Array)
+    class Vec3Array ; include ::Snow::ArrayMarshalSupport ; end
+  end
+
+  if const_defined?(:Vec4Array)
+    class Vec4Array ; include ::Snow::ArrayMarshalSupport ; end
+  end
+
+  if const_defined?(:QuatArray)
+    class QuatArray ; include ::Snow::ArrayMarshalSupport ; end
+  end
+
+  if const_defined?(:Mat3Array)
+    class Mat3Array ; include ::Snow::ArrayMarshalSupport ; end
+  end
+
+  if const_defined?(:Mat4Array)
+    class Mat4Array ; include ::Snow::ArrayMarshalSupport ; end
+  end
+
+end

data/lib/snow-math/mat3.rb

@@ -6,7 +6,15 @@ require 'snow-math/bindings'
 
 module Snow ; end
 
-if Snow.const_defined?(:Mat4Array)
+if Snow.const_defined?(:Mat3Array)
+  #
+  # A contiguous array of Mat3s. 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.
+  #
+  # May be useful when subclassed as a stack to recreate now-drepcated OpenGL
+  # functionality, though perhaps less-so than a Mat4 stack.
+  #
   class Snow::Mat3Array
     class << self ; alias_method :[], :new ; end
 
@@ -15,33 +23,77 @@ if Snow.const_defined?(:Mat4Array)
   end
 end
 
+#
+# A 3x3 matrix class. Often useful for representation rotations.
+#
 class Snow::Mat3
 
   class << self ; alias_method :[], :new ; end
 
   alias_method :[], :fetch
   alias_method :[]=, :store
+  alias_method :dup, :copy
+  alias_method :clone, :copy
 
+
+  #
+  # Calls #transpose(self)
+  #
+  # call-seq: transpose! -> self
+  #
   def transpose!
     transpose self
   end
 
+  #
+  # Calls #inverse(self)
+  #
+  # call-seq: inverse! -> self
+  #
   def inverse!
     inverse self
   end
 
+  #
+  # Calls #adjoint(self)
+  #
+  # call-seq: adjoint! -> self
+  #
   def adjoint!
     adjoint self
   end
 
+  #
+  # Calls #cofactor(self)
+  #
+  # call-seq: cofactor! -> self
+  #
   def cofactor!
     cofactor self
   end
 
+  #
+  # Calls #multiply_mat3(rhs, self)
+  #
+  # call-seq: multiply_mat3!(rhs) -> self
+  #
   def multiply_mat3!(rhs)
     multiply_mat3 rhs, self
   end
 
+  #
+  # Multiplies self and RHS and returns the result. This is a wrapper around
+  # other multiply methods. See multiply_mat3, rotate_vec3, and #scale for more
+  # reference.
+  #
+  # In the third form, the scalar value provided is passed for all three columns
+  # when calling scale.
+  #
+  # call-seq:
+  #   multiply(mat3, output = nil) -> output or new mat3
+  #   multiply(vec3, output = nil) -> output or new vec3
+  #   multiply(scalar, output = nil) -> output or new mat3
+  #
   def multiply(rhs, out = nil)
     raise "Invalid type for output, must be the same as RHS" if !out.nil? && !out.kind_of?(rhs.class)
     case rhs
@@ -52,6 +104,13 @@ class Snow::Mat3
     end
   end
 
+  #
+  # Calls #multiply(rhs, self).
+  #
+  # call-seq: multiply!(mat3) -> self
+  # call-seq: multiply!(vec3) -> vec3
+  # call-seq: multiply!(scalar) -> self
+  #
   def multiply!(rhs)
     multiply rhs, case rhs
       when Mat3, Numeric then self
@@ -60,10 +119,16 @@ class Snow::Mat3
       end
   end
 
+  #
+  # Calls scale(x, y, z, self)
+  #
+  # call-seq: scale!(x, y, z) -> self
+  #
   def scale!(x, y, z)
     scale x, y, z, self
   end
 
+
   alias_method :*, :multiply
   alias_method :**, :scale
   alias_method :~, :transpose

data/lib/snow-math/mat4.rb

@@ -7,6 +7,14 @@ require 'snow-math/bindings'
 module Snow ; end
 
 if Snow.const_defined?(:Mat4Array)
+  #
+  # A contiguous array of Mat4s. 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.
+  #
+  # May also be useful to subclass as a stack of Mat4s akin to now-deprecated
+  # functionality in OpenGL.
+  #
   class Snow::Mat4Array
     class << self ; alias_method :[], :new ; end
 
@@ -15,29 +23,87 @@ if Snow.const_defined?(:Mat4Array)
   end
 end
 
+#
+# A 4x4 matrix. Useful for anything from rotation to projection to almost any
+# other 3D transformation you might need.
+#
 class Snow::Mat4
 
   class << self ; alias_method :[], :new ; end
 
   alias_method :[], :fetch
   alias_method :[]=, :store
+  alias_method :dup, :copy
+  alias_method :clone, :copy
 
+
+  # Calls #transpose(self)
+  #
+  # call-seq: transpose! -> self
   def transpose!
     transpose self
   end
 
+  # Calls #inverse_orthogonal(self)
+  #
+  # call-seq: inverse_orthogonal! -> self
   def inverse_orthogonal!
     inverse_orthogonal self
   end
 
+  # Calls #adjoint(self)
+  #
+  # call-seq: adjoint! -> self
   def adjoint!
     adjoint self
   end
 
+  # Calls #multiply_mat4(rhs, self)
+  #
+  # call-seq: multiply_mat4!(rhs) -> self
   def multiply_mat4!(rhs)
     multiply_mat4 rhs, self
   end
 
+  # Calls #multiply_vec4(rhs, rhs)
+  #
+  # call-seq: multiply_vec4!(rhs) -> rhs
+  def multiply_vec4!(rhs)
+    multiply_vec4 rhs, rhs
+  end
+
+  # Calls #transform_vec3(rhs, rhs)
+  #
+  # call-seq: transform_vec3!(rhs) -> rhs
+  def transform_vec3!(rhs)
+    transform_vec3 rhs, rhs
+  end
+
+  # Calls #inverse_transform_vec3(rhs, rhs)
+  #
+  # call-seq: inverse_transform_vec3!(rhs) -> rhs
+  def rotate_vec3!(rhs)
+    inverse_transform_vec3 rhs, rhs
+  end
+
+  # Calls #inverse_rotate_vec3(rhs, rhs)
+  #
+  # call-seq: inverse_rotate_vec3!(rhs) -> rhs
+  def inverse_rotate_vec3!(rhs)
+    inverse_rotate_vec3 rhs, rhs
+  end
+
+  # Calls #multiply_mat4, #multiply_vec4, #transform_vec3, and #scale,
+  # respectively.
+  #
+  # When calling multiply with scalar as rhs, scalar is passed as the value to
+  # scale all columns by.
+  #
+  # call-seq:
+  #     multiply(mat4, output = nil) -> output or new mat4
+  #     multiply(vec4, output = nil) -> output or new vec4
+  #     multiply(vec3, output = nil) -> output or new vec3
+  #     multiply(scalar, output = nil) -> output or new mat4
   def multiply(rhs, out = nil)
     raise "Invalid type for output, must be the same as RHS" if !out.nil? && !out.kind_of?(rhs.class)
     case rhs
@@ -49,6 +115,8 @@ class Snow::Mat4
     end
   end
 
+  # Calls #multiply(rhs, self) when rhs is a scalar or Mat4, otherwise calls
+  # #multiply(rhs, rhs).
   def multiply!(rhs)
     multiply rhs, case rhs
       when Mat4, Numeric then self
@@ -57,22 +125,36 @@ class Snow::Mat4
       end
   end
 
+  # Calls #scale(x, y, z, self)
+  #
+  # call-seq: scale!(x, y, z) -> self
   def scale!(x, y, z)
     scale x, y, z, self
   end
 
+  # Calls #translate(*args, self)
+  #
+  # call-seq: translate!(vec3) -> self
+  # call-seq: translate!(x, y, z) -> self
   def translate!(*args)
     translate *args, self
   end
 
+  # Calls #inverse_affine(self)
+  #
+  # call-seq: inverse_affine! -> self
   def inverse_affine!
     inverse_affine self
   end
 
+  # Calls #inverse_general(self)
+  #
+  # call-seq: inverse_general! -> self
   def inverse_general!
     inverse_general self
   end
 
+
   alias_method :*, :multiply
   alias_method :**, :scale
   alias_method :~, :transpose