rubygame 2.2.0-mswin32

data/lib/rubygame/ftor.rb

@@ -0,0 +1,370 @@
+# Ftor ("Fake vecTOR"), a vector-like class for 2D position/movement.
+#--
+#	Rubygame -- Ruby code and bindings to SDL to facilitate game creation
+#	Copyright (C) 2004-2007  John Croisant
+#
+#	This library is free software; you can redistribute it and/or
+#	modify it under the terms of the GNU Lesser General Public
+#	License as published by the Free Software Foundation; either
+#	version 2.1 of the License, or (at your option) any later version.
+#
+#	This library is distributed in the hope that it will be useful,
+#	but WITHOUT ANY WARRANTY; without even the implied warranty of
+#	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+#	Lesser General Public License for more details.
+#
+#	You should have received a copy of the GNU Lesser General Public
+#	License along with this library; if not, write to the Free Software
+#	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+#++
+
+module Rubygame
+
+# *NOTE*: you must require 'rubygame/ftor' manually to gain access to
+# Rubygame::Ftor. It is not imported with Rubygame by default!
+# 
+# Ftor ("Fake vecTOR"), a vector-like class for 2D position/movement.
+# 
+# (NB: See #angle for an important note about why angles appear to be the
+# opposite of what you may expect.)
+# 
+# Ftor is useful for storing 2D coordinates (x,y) as well as
+# vector quantities such as velocity and acceleration (representationally,
+# points and vectors are equivalent.) Although Ftors are always represented
+# internally as Cartesian coordinates (x, y), it is possible to deal with an
+# Ftor as polar coordinates (#angle, #magnitude) instead.
+# See #new_am and #set_am!, for example.
+# 
+# Ftor is a "fake" vector because it has certain convenient properties which
+# differ from "true" vectors (i.e. vectors in a strict mathematical sense).
+#
+# Unlike vectors, Ftors may be multiplied or divided to another Ftor. This is
+# equivalent to multiplying or dividing each component by the corresponding
+# component in the second Ftor. If you like, you can think of this feature as
+# scaling each component of the Ftor by a separate factor:
+# 
+#   Ftor(a,b) * Ftor(c,d)  =  Ftor(a*c, b*d)
+# 
+# Of course, Ftors also have the usual vector behavior for addition/subraction
+# between two Ftors, and multiplication/division of an Ftor by a scalar:
+# 
+#   Ftor(a,b) + Ftor(c,d) = Ftor(a+c, b+d)
+#   Ftor(a,b) * n = Ftor(a*n, b*n)
+# 
+# Additionally, Ftor contains functions for manipulating itself.
+# You can both get and set such properties as #angle, #magnitude, #unit,
+# and #normal, and the Ftor will change in-place as needed. For example,
+# if you set #angle=, the vector will change to have the new angle,
+# but keeps the same magnitude as before.
+# 
+# Ftor attempts to save processing time (at the expense of memory) by 
+# storing secondary properties (angle, magnitude, etc.) whenever they are
+# calculated,so that they need not be calculated repeatedly. If the vector
+# changes, the properties will be calculated again the next time they
+# are needed.
+# (In future versions, it may be possible to disable this feature for
+# certain Ftors, for example if they will change very often, to save memory.)
+# 
+class Ftor
+  PI = Math::PI
+  HALF_PI = PI*0.5
+  THREE_HALF_PI = PI*1.5
+  TWO_PI = PI*2
+
+	# Create a new Ftor by specifying its x and y components. See also #new_am
+  # and #new_from_to.
+	def initialize(x,y)
+    @x, @y = x, y
+	end
+
+	# Create a new Ftor by specifying its #angle (in radians) and #magnitude.
+  # See also #new.
+	def self.new_am(a,m)
+		v = Ftor.new(1,0)
+    v.a, v.m = a, m
+		return v
+	end
+
+  # Returns a new Ftor which represents the difference in position of two
+  # points +p1+ and +p2+. (+p1+ and +p2+ can be Ftors, size-2 Arrays, or
+  # anything else which has two numerical components and responds to #[].)
+  # 
+  # In other words, assuming +v+ is the Ftor returned by this function:
+  #   p1 + v = p2
+  def self.new_from_to(p1,p2)
+    return self.class.new(p2[0]-p1[0],p2[1]-p1[1])
+  end
+
+	attr_reader :x                # The x component of the Ftor.
+  # Set the x component of the Ftor.
+	def x=(value)
+    @x = value
+    _clear()
+	end
+
+  attr_reader :y                # The y component of the Ftor.
+  # Set the y component of the Ftor.
+	def y=(value)
+    @y = value
+    _clear()
+	end
+
+	# Modify the x and y components of the Ftor in-place
+	def set!(x,y)
+    @x, @y = x,y
+		_clear()
+	end
+
+	# Modify the #angle (in radians) and #magnitude of the Ftor in-place
+	def set_am!(a,m)
+    self.angle, self.magnitude = a, m
+  end
+
+  # Same as #to_s, but this Ftor's #object_id is also displayed.
+	def inspect
+		"#<#{self.class}:#{object_id}: %f, %f>"%[@x,@y]
+	end
+
+  # Display this Ftor in the format: "#<Ftor: [x, y]>". x and y are displayed
+  # as floats at full precision. See also #pp.
+	def to_s
+		"#<#{self.class}: [%f, %f]>"%[@x,@y]
+	end
+
+  # "Pretty print". Same as #to_s, but components are displayed as rounded
+  # floats to 3 decimal places, for easy viewing.
+	def pretty
+		"#<#{self.class}: [%0.3f, %0.3f]>"%[@x,@y]
+	end
+
+  # Same as #to_s_am, but this Ftor's #object_id is also displayed.
+	def inspect_am
+		"#<#{self.class}:AM:#{object_id}: %f, %f>"%[angle(),magnitude()]
+	end
+
+  # Display this Ftor in the format: "#<Ftor:AM: [angle, magnitude]>". 
+  # angle and magnitude are displayed as floats at full precision.
+  # See also #to_s and #pp_am.
+  def to_s_am
+		"#<#{self.class}:AM: [%f, %f]>"%[angle(),magnitude()]
+  end
+
+  # "Pretty print" with angle and magnitude. 
+  # Same as #to_s_am, but components are displayed as rounded floats to 3
+  # decimal places, for easy viewing.
+	def pretty_am
+		"#<#{self.class}:AM: [%0.3f, %0.3f]>"%[angle(),magnitude()]
+	end
+
+  # Returns an Array of this Ftor's components, [x,y].
+	def to_a
+		[@x,@y]
+	end
+	alias :to_ary :to_a
+
+  # Return the +i+th component of this Ftor, as if it were the Array
+  # returned by #to_a.
+	def [](i)
+		[@x,@y][i]
+	end
+
+  # True if this Ftor is equal to +other+, when both have been converted to
+  # Arrays via #to_a. In other words, a component-by-component equality check.
+	def ==(other)
+		to_a() == other.to_a
+	end
+
+  # The reverse of this Ftor. I.e., all components are negated. See also
+  # #reverse!.
+  def -@
+    self.class.new(-@x,-@y)
+  end
+
+  # Like #-@, but reverses this Ftor in-place.
+  def reverse!
+    set!(-@x,-@y)
+  end
+
+  # Perform vector addition with this Ftor and +other+, adding them on a
+  # component-by-component basis, like so:
+  #   Ftor(a,b) + Ftor(c,d)  =  Ftor(a+c, b+d)
+	def +(other)
+    return self.class.new(@x+other[0],@y+other[1])
+	end
+
+  # Like #+, but performs subtraction instead of addition.
+	def -(other)
+    return self.class.new(@x-other[0],@y-other[1])
+	end
+
+  # Perform multiplication of this Ftor by the scalar +other+, like so:
+  #   Ftor(a,b) * n = Ftor(a*n, b*n)
+  # 
+  # However, if this causes TypeError, attempt to extract indices 0 and 1
+  # with +other+'s #[] operator, and multiply them into the corresponding
+  # components of this Ftor, like so:
+  #   Ftor(a,b) * Ftor(c,d) = Ftor(a*c, b*d)
+  #   Ftor(a,b) * [c,d]     = Ftor(a*c, b*d)
+	def *(other)
+    return self.class.new(@x*other,@y*other)
+  rescue TypeError
+    return self.class.new(@x*other[0],@y*other[1])
+	end
+
+  # Like #*, but performs division instead of multiplication.
+	def /(other)
+		x, y = @x.to_f, @y.to_f
+    return self.class.new(x/other,y/other)
+  rescue TypeError
+    return self.class.new(x/other[0],y/other[1])
+	end
+
+	# Return the angle (radians) this Ftor forms with the positive X axis.
+  # This is the same as the Ftor's angle in a polar coordinate system.
+  # 
+  # *IMPORTANT*: Because the positive Y axis on the Rubygame::Screen points
+  # *downwards*, an angle in the range 0..PI will appear to point *downwards*,
+  # rather than upwards!
+  # This also means that positive rotation will appear *clockwise*, and
+  # negative rotation will appear *counterclockwise*!
+  # This is the opposite of what you would expect in geometry class!
+	def angle
+		@angle or @angle = Math.atan2(@y,@x)
+	end
+
+	# Set the angle (radians) of this Ftor from the positive X axis.
+	# Magnitude is preserved.
+	def angle=(a)
+		m = magnitude()
+		set!( Math.cos(a)*m, Math.sin(a)*m )
+	end
+
+	alias :a  :angle
+	alias :a= :angle= ;
+
+	# Returns the magnitude of the Ftor, i.e. its length from tail to head.
+  # This is the same as the Ftor's magnitude in a polar coordinate system.
+	def magnitude
+		@magnitude or @magnitude = Math.hypot(@x,@y)
+	end
+
+	# Modifies the #magnitude of the Ftor, preserving its #angle.
+  # 
+  # In other words, the Ftor will point in the same direction, but it will
+  # be a different length from tail to head.
+	def magnitude=(m)
+		new = unit() * m
+		set!(new.x, new.y)
+	end
+
+	alias :m  :magnitude
+	alias :m= :magnitude= ;
+
+	# Return a new unit Ftor which is perpendicular to this Ftor (rotated by
+  # pi/2 radians, to be specific).
+	def normal
+		@normal or @normal = unit().rotate(HALF_PI)
+	end
+
+  # Rotate this Ftor in-place, so that it is perpendicular to +other+.
+  # This Ftor will be at an angle of -pi/2 to +other+.
+	def normal=(other)
+    set!( *(self.class.new(*other).unit().rotate(-HALF_PI) * magnitude()) )
+	end
+
+	alias :n  :normal
+	alias :n= :normal= ;
+
+	# Return the unit vector of the Ftor, i.e. an Ftor with the same direction,
+  # but a #magnitude of 1. (This is sometimes called a "normalized" vector,
+  # not to be confused with a vector's #normal.)
+	def unit
+		m = magnitude().to_f
+		@unit or @unit = Ftor.new(@x/m, @y/m)
+	end
+
+	# Rotates this Ftor in-place, so that its #unit vector matches the unit
+  # vector of the given Ftor.
+  # 
+  # In other words, changes the #angle of this Ftor to be the same as the angle
+  # of the given Ftor, but this Ftor's #magnitude does not change.
+  #--
+  # TODO: investigate efficiency of using `self.angle = other.angle` instead
+  #++
+	def unit=(other)
+		set!( *(self.class.new(*other).unit() * magnitude()) )
+	end
+
+	alias :u  :unit
+	alias :u= :unit=
+  alias :align! :unit=;
+
+	# Return the dot product (aka inner product) of this Ftor and +other+.
+  # The dot product of two vectors +v1+ and +v2+ is:
+  #   v1.x * v2.x + v1.y * v2.y
+	def dot(other)
+		@x*other[0] + @y*other[1]
+	end
+
+	# Return the #dot product of #unit vectors of this Ftor and +other+.
+	def udot(other)
+		unit().dot(self.class.new(*other).unit)
+	end
+
+	#Return the difference in angles (radians) between this Ftor and +other+.
+	def angle_with(other)
+		Math.acos( self.udot(other) )
+	end
+
+  # Rotate this Ftor in-place by +angle+ (radians). This is the same as
+  # adding +angle+ to this Ftor's #angle.
+  # 
+  #--
+  # , with one important difference: 
+  # This method will be much more efficient when rotating at a right angle,
+  # i.e.rotating by any multiple of PI/2 radians from -2*PI to 2*PI radians.
+  # 
+  # For convenience, and to ensure exactitude, several numerical constants
+  # have been defined for multiples of PI/2:
+  # * Ftor::PI::             (same as Math::PI)
+  # * Ftor::HALF_PI::        PI * 0.5 (or PI/2)
+  # * Ftor::THREE_HALF_PI::  PI * 1.5 (or 3*PI/2)
+  # * Ftor::TWO_PI::         PI * 2
+  #++
+  # 
+  # *IMPORTANT*: Positive rotation will appear *clockwise*, and negative
+  # rotation will appear *counterclockwise*! See #angle for the reason.
+	def rotate!(angle)
+# 		case(angle)
+# 		when HALF_PI, -THREE_HALF_PI
+# 			self.set!(@y,-@x)
+# 		when THREE_HALF_PI, -HALF_PI
+# 			self.set!(-@y,@x)
+# 		when PI, -PI
+# 			self.set!(@y,-@x)
+# 		when 0, TWO_PI, -TWO_PI
+# 			self.set!(@y,-@x)
+# 		else
+			self.a += angle
+# 		end
+		return self
+	end
+
+  # Like #rotate!, but returns a duplicate instead of rotating this Ftor
+  # in-place.
+	def rotate(radians)
+		self.dup.rotate!(radians)
+	end
+
+	# Clears stored values for #angle, #magnitude, #normal, and #unit,
+  # so that they will be recalculated the next time they are needed.
+  # Intended for internal use, but might be useful in other situations.
+	def _clear
+		@angle = nil
+		@magnitude = nil
+		@normal = nil
+		@unit = nil
+		return self
+	end
+end
+end

data/lib/rubygame/hotspot.rb

@@ -0,0 +1,265 @@
+# Hotspot, a mixin module to extend an object with custom, named, relative 
+# position offsets.
+#--
+#	Rubygame -- Ruby code and bindings to SDL to facilitate game creation
+#	Copyright (C) 2004-2007  John Croisant
+#
+#	This library is free software; you can redistribute it and/or
+#	modify it under the terms of the GNU Lesser General Public
+#	License as published by the Free Software Foundation; either
+#	version 2.1 of the License, or (at your option) any later version.
+#
+#	This library is distributed in the hope that it will be useful,
+#	but WITHOUT ANY WARRANTY; without even the implied warranty of
+#	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+#	Lesser General Public License for more details.
+#
+#	You should have received a copy of the GNU Lesser General Public
+#	License along with this library; if not, write to the Free Software
+#	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+#++
+
+module Rubygame
+
+  # *NOTE*: you must require 'rubygame/hotspot' manually to gain access to
+  # Rubygame::Hotspot. It is not imported with Rubygame by default!
+  # 
+  # Hotspot is a mixin module to extend an object with "hotspots": custom,
+  # named, relative position offsets. Hotspots can be defined relative to the
+  # origin, to another hotspot, or to the results of a method (via a 
+  # 'smart' hotspot).
+  # 
+  # There are two types of hotspots, simple and 'smart'.
+  # 
+  # Simple hotspots are an Array of three values, an x offset, a y offset,
+  # and the label of another hotspot relative to which this hotspot is defined.
+  # If the last argument is omitted or nil, the hotspot is defined relative
+  # to the true origin (i.e. (0,0), the top-left corner of the Screen).
+  # See #new_hotspot.
+  # 
+  # Smart hotspots, or 'smartspots' for short, act as a proxy to the object's
+  # methods. Each time a smartspot is evaluated, it calls the object's method
+  # of the same name as the smartspot, and uses the results of the method as
+  # x and y offsets. Therefore, smartspots only work for methods which:
+  #  1. take no arguments
+  #  2. return an Array with 2 Numeric values (or something else that responds
+  #     to #[]
+  #
+  # By adding a smartspot to a Rect, for example, you could define simple 
+  # hotspots relative to its Rect#center; then, even if the Rect moves or
+  # changes size, the smartspot will always to evaluate to its true center.
+  # See #new_smartspot.
+  # 
+  #--
+  # ((Old documentation/brainstorming))
+  # As an example, consider an object which represents a person's face: eyes, 
+  # ears, nose, mouth, etc. You might make a face and define several hotspots
+  # like so:
+  # 
+  #  myface = Face.new()                # Create a new face, with no hotspots.
+  #  myface.extend(Hotspot)             # Extend myface with hotspot ability.
+  #  myface.new_hotspot \               # Define some new hotspots: ...
+  #   :nose => [10,5, :center],        # the nose, relative to face's center,
+  #   :left_eye => [-5,-2, :nose],     # the left eye, left and above the nose,
+  #   :left_brow => [0,-5, :left_eye], # the left eye-brow, above the left eye.
+  # 
+  # Please note that +:center+ is a "virtual" hotspot. When the coordinates of
+  # +:center+ are requested, +myface+'s #center method is called* and the
+  # results used as the coordinates. (* Technically, +myface+ is sent
+  # +:center+, which is not exactly the same as calling #center.)
+  # 
+  # Now, suppose we want to find out where :left_brow is, in absolute
+  # coordinates (i.e. relative to the origin). We can do this, even if +myface+
+  # has moved, or the hotspots have been changed:
+  # 
+  #  myface.left_brow                   # => [5,-2]
+  #  myface.move(20,-12)                # moves the face right and up
+  #  myface.left_brow                   # => [25,-14]
+  #  myface.new_hotspot \
+  #    :left_eye => [-10,3]             # redefine the left_eye hotspot
+  #  myface.left_brow                   # => [20,-9]
+  # 
+  # Where do [5,-2], [25,-24], and [20,-9] come from? They are the vector sums
+  # of each hotspot in the chain: left_brow, left_eye, nose, and center. See
+  # #hotspot for more information.
+  #++
+  # 
+  module Hotspot
+    # :call-seq: def_hotspot label => [x,y,parent]
+    # 
+    # Define +label+ as a simple hotspot, a custom reference coordinate 
+    # point +x+ pixels to the right and +y+ pixels below the hotspot whose
+    # label is +parent+.
+    # You may omit +parent+, in which case the hotspot will evaluate relative
+    # to the origin, i.e. the top-left corner of the Screen.
+    # 
+    # See also #def_smartspot to create a 'smart hotspot'.
+    # 
+    # +label+ must be usable as a key in a Hash table. Additionally, if you
+    # want <code>myobject.{label}</code> to work like 
+    # <code>myobject.hotspot({label})</code>, +label+ must be a :symbol.
+    # 
+    # *IMPORTANT*: Do NOT create circular hotspot chains (e.g. a -> b -> a).
+    # Doing so will raise SystemStackError when #hotspot is asked to evaluate
+    # any hotspot in that chain. Hotspots are not yet smart enough to detect
+    # circular chains.
+    # 
+    # Hotspots can be defined in any order, as long as you define all the
+    # hotspots in a chain before that chain is evaluated with #hotspot.
+    #
+    # You may define multiple hotspots simultaneously by separating the 
+    # definitions by commas. For example:
+    # 
+    #   def_hotspot label => [x,y,parent], label2 => [x,y,parent]
+    # 
+    # Users of the Rake library will recognize this style of syntax.
+    # It is simply constructing a Hash object and passing it as the
+    # only argument to #new_hotspot. The above code is equivalent to:
+    # 
+    #   def_hotspot( { label => [x,y,parent], label2 => [x,y,parent] } )
+    def def_hotspot(dfn)
+      @hotspots.update(dfn)
+    rescue NoMethodError => e
+      unless defined? @hotspots
+        @hotspots = Hash.new
+        retry
+      else raise e
+      end
+    end
+
+    # Remove all simple hotspots whose label is included in +*labels+.
+    def undef_hotspot(*labels)
+      labels.flatten.each do |l|
+        @hotspots.delete(l)
+      end
+    end
+
+    # True if +label+ has been defined as a simple hotspot.
+    def defined_hotspot?(label)
+      @hotspots.include? label
+    rescue NoMethodError => e
+      unless defined? @hotspots
+        false
+      else raise e
+      end
+    end
+
+    # :call-seq: hotspot(label)
+    # 
+    # Returns the absolute coordinates represented by the hotspot +label+.
+    # Will return nil if the hotspot (or one of its ancestors) does not exist.
+    # 
+    # This method will recursively evaluate the hotspot, it's parent hotspot
+    # (if any), and so on, until a parent-less hotspot or a smartspot is found.
+    # 
+    # (*NOTE*: this means that a circular chains (e.g. a -> b -> a)
+    # will keep going around and around until the ruby interpreter
+    # raises SystemStackError!)
+    #
+    # The final value returned by this method will be the vector component sum
+    # of all the hotspots in the chain. For example, if you have this chain:
+    # 
+    #   :a => [1, 2, :b]
+    #   :b => [4, 8, :c]
+    #   :c => [16,32]
+    # 
+    # the value returned for +:a+ would be [21,42], i.e. [1+4+16, 2+8+32]
+    #--
+    # The x and y arguments are used for recursive accumulation, although
+    # I suppose you could use them to create a temporary offset by giving
+    # something besides zero when you look up a hotspot.
+    #++
+    def hotspot(label,x=0,y=0)
+      a = @hotspots[label]
+      if a[2].nil?              # has no parent
+        [x+a[0],y+a[1]]
+      else                      # has a parent
+        hotspot(a[2],x+a[0],y+a[1])
+      end
+    rescue NoMethodError => e
+      if not(defined? @hotspots)
+        return nil
+      elsif a.nil?
+        smartspot(label,x,y)
+      else raise e
+      end
+    end
+
+    # Define each label in +*labels+ as a smartspot ('smart hotspot').
+    # 
+    # To prevent outside objects from abusing hotspots to call arbitrary 
+    # methods, a smartspot must be defined for each method before it can be 
+    # used as a parent to a hotspot.
+    # 
+    # The label must be a :symbol, and it must be identical to the name of the
+    # method to be called.
+    def def_smartspot(*labels)
+      @smartspots += labels.flatten
+      @smartspots.uniq!
+    rescue NoMethodError => e
+      unless defined? @smartspots
+        @smartspots = Array.new
+        retry
+      else raise e
+      end
+    end
+
+    # Remove all smartspots whose label is included in +*labels+.
+    def undef_smartspot(*labels)
+      @smartspots -= labels.flatten
+    end
+
+    # True if +label+ has been defined as a smartspot.
+    def defined_smartspot?(label)
+      @smartspots.include? label
+    rescue NoMethodError => e
+      unless defined? @smartspots
+        false
+      else raise e
+      end
+    end
+
+    # :call-seq: smartspot(label)
+    # 
+    # Evaluate the smartspot +label+, calling the method of the same name as
+    # +label+. Will return nil if no such smartspot has been defined.
+    #--
+    # The x and y arguments are used for recursive accumulation.
+    #++
+    def smartspot(label,x=0,y=0)
+      if @smartspots.include? label
+        a = self.send(label)
+        [x+a[0],y+a[1]]
+      else
+        nil
+      end
+    rescue NoMethodError => e
+      unless defined? @smartspots
+        nil
+      else raise e
+      end
+    end
+
+    #--
+    # 
+    # TODO:
+    # Methods for changing the position of the object indirectly, 
+    # by saying where the hotspot should be.
+    # You could do this: my_object.foot = [5,3], and if foot was defined
+    # relative to, say, #center, it would set center = [5-x_offset, 3-y_offset]
+    # 
+    # It should be recursive to work with chains of hotspots too.
+    # 
+    #++ 
+
+    alias :old_method_missing :method_missing
+
+    def method_missing(symbol,*args)
+      if have_hotspot?(symbol) 
+        hotspot(symbol)
+      else old_method_missing(symbol,*args)
+      end
+    end
+    
+  end
+end