rubygame 2.3.0-x86-mswin32-60

data/lib/rubygame/queue.rb

@@ -0,0 +1,288 @@
+#--
+#	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
+#++
+
+require "rubygame/event"
+
+module Rubygame
+
+	# EventQueue provides a simple way to manage SDL's events, allowing the
+	# application to detect keyboard presses, mouse movements and clicks,
+	# joystick movement, etc. You can also post custom events to the
+  # EventQueue to help manage the game state.
+  # 
+  # This class replaces the old Rubygame::Queue class, which is no longer
+  # available. While EventQueue class serves the same purpose as the old
+  # class, they are somewhat different in behavior. Please note that while
+  # the old class was a Singleton, this class is not; you may have as many
+  # separate instances of EventQueue as you wish (although it is strongly
+  # recommended that only one be used to #fetch_sdl_events).
+  # 
+  # For basic usage, create a #new EventQueue with autofetch, then call the
+  # #each method once per game loop, passing a block which handles events.
+  # See the sample applications for examples of this.
+  #
+  # If you wish to ignore all events of a certain class, append those classes
+  # the instance variable @ignore (accessors are provided). You can ignore as
+  # many classes of events as you want, but make sure you don't ignore ALL
+  # event classes, or the user won't be able to control the game!
+  # 
+  # If the program has to pause and wait for an event (for example, if the
+  # player must press a button to begin playing), you might find the #wait
+  # method to be convenient.
+	# 
+	# For reference, the full list of SDL events is:
+	# - Event (base class, not used by itself)
+	# - ActiveEvent
+	# - JoyAxisEvent
+	# - JoyBallEvent
+	# - JoyDownEvent
+	# - JoyHatEvent
+	# - JoyUpEvent
+	# - KeyDownEvent
+	# - KeyUpEvent
+	# - MouseDownEvent
+	# - MouseMotionEvent
+	# - MouseUpEvent
+	# - QuitEvent
+	# - ResizeEvent
+	# 
+	class EventQueue < Array
+    # Array of classes to be ignored by #push.
+    attr_accessor :ignore
+
+    # Whether to fetch SDL events automatically when #each and #wait are used.
+    # Enabled by default.
+    attr_accessor :autofetch    
+
+    # Create a new EventQueue.
+    def initialize()
+      @autofetch = true
+      @ignore = []
+      yield self if block_given?
+    end
+
+    # Append events to the EventQueue.
+    # Silently ignores events whose class is in @ignore.
+    def push(*events)
+      events = events.flatten.delete_if {|e| @ignore.include?(e.class)}
+      events.each do |e|
+        super( e )
+      end
+    end
+
+    alias post push
+
+    alias peek_each each        # Iterate through all events without removing.
+
+    # Iterate through all events in the EventQueue, yielding them one at a time
+    # to the given block. The EventQueue is flushed after all events have been
+    # yielded. You can use #peek_each if you want to keep the events.
+    #
+    # If the internal variable @autofetch is true, this method will call
+    # #fetch_sdl_events once before iterating.
+    def each(&block)
+      fetch_sdl_events if @autofetch
+      super
+      self.clear
+    end
+
+    # Posts pending SDL hardware events to the EventQueue. Only one EventQueue
+    # should call this method per application, and only if you are not using
+    # Rubygame#fetch_sdl_events to manually process events! Otherwise, some
+    # events may be removed from SDL's event stack before they can be properly
+    # processed!
+		def fetch_sdl_events
+			self.push(Rubygame.fetch_sdl_events())
+		end
+
+    # Wait for an event to be posted, then return that event.
+    # If there is already an event in the queue, this method will immediately
+    # return that event.
+    # Events that are ignored will not trigger the return.
+    #
+    # This method takes this argument:
+    # time:: how long (in milliseconds) to delay between each check for
+    #        new events. Defaults to 10 ms.
+    #
+    # If a block is given to this method, it will be run after each
+    # unsuccessful check for new events. This method will pass to the block the
+    # number of times it has checked for new events.
+    # 
+    # If the internal variable @autofetch is true, this method will call
+    # #fetch_sdl_events before every check for new events.
+    #
+    # Please be cautious when using this method, as it is rather easy to
+    # cause an infinite loop. Two ways an infinite loop might occur are:
+    # 1. Waiting for an SDL event when @autofetch is disabled. (This is
+    #    not a problem if the block will post an event.)
+    # 2. Waiting for any event when all possible event types are ignored.
+    #
+    def wait(delay=10, &block)
+      iterations = 0
+      if block_given?
+        loop do
+          fetch_sdl_events() if @autofetch
+          if self.length >= 1
+            s = self.shift
+            return s unless s == nil
+          end
+          yield iterations
+          iterations += 1
+          Rubygame::Clock.delay(delay)
+        end
+      else
+        loop do 
+          fetch_sdl_events() if @autofetch
+          s = self.shift
+          return s unless s == nil
+          iterations += 1
+          Rubygame::Clock.delay(delay)
+        end
+      end
+    end
+
+	end # class EventQueue
+
+
+  # A mixin module to extend EventQueue with the ability to 'deliver' specific
+  # types of events to subscribed objects, a la a mailing list. Each object
+  # must subscribe for the classes of events it wishes to receive;
+  # when the MailQueue receives an event of that type, it will deliver
+  # it to the subscribers. See #subscribe for more information.
+  # 
+  # Please note that if you extend an already-existing EventQueue object
+  # with this mixin module (rather than including it in a class), you must
+  # call #setup before using the object. This will create the necessary
+  # internal variables for the MailQueue to work.
+  # 
+  module MailQueue
+    # Whether to automatically deliver events as they are received.
+    # Enabled by default.
+    attr_accessor :autodeliver
+
+    # Create a new MailQueue object.
+    # Like EventQueue.new, this method will yield self if a block is given.
+    def initialize()
+      setup()
+      super
+    end
+
+    # Create the necessary internal variables for the MailQueue.
+    def setup
+      @subscribe = Hash.new
+      @autodeliver = true
+    end
+
+    # Returns an Array of all event classes which have at least one subscriber.
+    def list
+      @subscribe.collect { |k, v|  
+        (v.length > 0) ? k : nil  rescue NoMethodError nil
+      }.compact
+    end
+
+    # Subscribe +client+ to receive events that match +klass+.
+    # 
+    # After the client object has been subscribed, the MailQueue will
+    # push along any event for which "klass === event" is true. This usually
+    # means that the event is an instance of klass or one of klass's child
+    # classes; however, note that klass may have changed its own #=== operator
+    # to have different behavior, so this is not always the case.
+    #
+    # Important: the MailQueue uses the client's #push method to deliver
+    # events! If the client does not have such a method, MailQueue will
+    # silently catch the error and move on to the next client.
+    # 
+    # A client object may be subscribed for many different types of events
+    # simultaneously, and more than one client object may be subscribed to
+    # any type of event (in which case each object will receive the event).
+    # A client may also be subscribed multiple times for the same type (in
+    # which case it will receive duplicate events). Likewise, the client will
+    # receive duplicates if it is subscribed to multiple classes which share
+    # ancestry, for example Numeric and Float.
+    # 
+    # If a client wishes to receive ALL types of events, it can subscribe to
+    # Object, which is a parent class of all objects.
+    # 
+    # If the queue's @autodeliver is true, it will deliver events to
+    # subscribers immediately after they are posted, rather than waiting for
+    # #deliver to be called.
+    def subscribe(client,klass)
+      @subscribe[klass] << client
+    rescue NoMethodError
+      @subscribe[klass] = [client] if @subscribe[klass].nil?
+    end
+
+    # Returns true if +client+ is currently subscribed to receive events
+    # of type +klass+.
+    def subscribed?(client,klass)
+      return true if @subscribe[klass].include?(client)  rescue NoMethodError
+      return false
+    end
+
+    # Unsubscribes the client to stop receiving events of type +klass+.
+    # It is safe (has no effect) to unsubscribe for an event type you
+    # are not subscribed to receive.
+    def unsubscribe(client,klass)
+      @subscribe[klass] -= [client]  rescue NoMethodError
+    ensure
+      return
+    end
+
+    # This private method is used by #deliver to do the real work.
+    def deliver_event(event)
+      @subscribe.each_pair { |klass,clients|
+        begin
+          if klass === event
+            clients.each do |client|
+              client.push(event) rescue NoMethodError
+            end 
+          end
+        rescue NoMethodError
+        end
+      }
+    end
+    private :deliver_event
+
+    # Deliver each pending event to all objects which are subscribed to
+    # that event class. Every client object MUST have a #push method, or
+    # events can't be delivered to it, and it will become very lonely!
+    # 
+    # The queue will be cleared of all events after all deliveries are done.
+    def deliver()
+      each() { |event|  deliver_event(event) }
+      clear()
+    end
+
+    # Append events to the queue. If @autodeliver is enabled, all events
+    # on the queue will be delivered to subscribed client objects immediately.
+    def push(*args)
+      # Temporarily disable autofetch to avoid infinite loop
+      a, @autofetch = @autofetch, false
+      # Fetch once to emulate autofetch, if it was enabled before
+      fetch_sdl_events() if a
+
+      super
+      deliver() if @autodeliver
+
+      @autofetch = a
+      return
+    end
+  end
+
+end # module Rubygame

data/lib/rubygame/rect.rb

@@ -0,0 +1,612 @@
+#--
+#	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
+#++
+
+#--
+# Table of Contents:
+#
+# class Rect
+# 	GENERAL:
+# 		initialize
+# 		new_from_object
+# 		to_s
+# 		to_a, to_ary
+# 		[]
+# 	ATTRIBUTES:
+# 		x, y, w, h [<- accessors]
+# 		width, height, size
+# 		left, top, right, bottom
+# 		center, centerx, centery
+# 		topleft, topright
+# 		bottomleft, bottomright
+# 		midleft, midtop, midright, midbottom
+# 	UTILITY METHODS:
+# 		clamp, clamp!
+# 		clip, clip!
+# 		collide_hash, collide_hash_all
+# 		collide_array, collide_array_all
+# 		collide_point?
+# 		collide_rect?
+# 		contain?
+# 		inflate, inflate!
+# 		move, move!
+# 		normalize, normalize!
+# 		union, union!
+# 		union_all, union_all!
+#
+#	class Surface
+#		make_rect
+# 
+#++
+
+module Rubygame
+
+# A Rect is a representation of a rectangle, with four core attributes
+# (x offset, y offset, width, and height) and a variety of functions
+# for manipulating and accessing these attributes.
+#
+# Like all coordinates in Rubygame (and its base library, SDL), x and y
+# offsets are measured from the top-left corner of the screen, with greater
+# y offsets being lower. Thus, specifying the x and y offsets of the Rect
+# is equivalent to setting the location of its top-left corner.
+# 
+# In Rubygame, Rects are used for collision detection and describing 
+# the area of a Surface to operate on.
+class Rect < Array
+
+	#--
+	# GENERAL
+	#++
+
+	# Create a new Rect, attempting to extract its own information from 
+	# the given arguments. The arguments must fall into one of these cases:
+	# 
+	#   - 4 integers +(x, y, w, h)+.
+	#   - 1 Rect or Array containing 4 integers +([x, y, w, h])+.
+	#   - 2 Arrays containing 2 integers each +([x,y], [w,h])+.
+	#   - 1 object with a +rect+ attribute which is a valid Rect object.
+	# 
+	# All rect core attributes (x,y,w,h) must be integers.
+	# 
+	def initialize(*argv)
+		case argv.length
+		when 1
+			if argv[0].kind_of? Array; super(argv[0])
+			elsif argv[0].respond_to? :rect; super(argv[0])
+			end
+		when 2
+			super(argv[0].concat(argv[1]))
+		when 4
+			super(argv)
+		end
+		return self
+	end
+
+	# Extract or generate a Rect from the given object, if possible, using the
+	# following process:
+	# 
+	#  1. If it's a Rect already, return a duplicate Rect.
+	#  2. Elsif it's an Array with at least 4 values, make a Rect from it.
+	#  3. Elsif it has a +rect+ attribute., perform (1) and (2) on that.
+	#  4. Otherwise, raise TypeError.
+	# 
+	# See also Surface#make_rect()
+	def Rect.new_from_object(object)
+		case(object)
+		when Rect
+			return object.dup
+		when Array 
+			if object.length >= 4
+				return Rect.new(object)
+			else
+				raise(ArgumentError,"Array does not have enough indices to be made into a Rect (%d for 4)."%object.length )
+			end
+		else
+			begin
+				case(object.rect)
+				when Rect
+					return object.rect.dup
+				when Array
+					if object.rect.length >= 4
+						return Rect.new(object.rect)
+					else
+						raise(ArgumentError,"Array does not have enough indices to be made into a Rect (%d for 4)."%object.rect.length )
+					end
+				end				# case object.rect
+			rescue NoMethodError # if no rect.rect
+				raise(TypeError,"Object must be a Rect or Array [x,y,w,h], or have an attribute called 'rect'. (Got %s instance.)"%object.class)
+			end
+		end # case object
+	end
+
+
+	# Print the Rect in the form "+#<Rect [x,y,w,h]>+"
+	def to_s; "#<Rect [%s,%s,%s,%s]>"%self; end
+
+	# Print the Rect in the form "+#<Rect:id [x,y,w,h]>+"
+	def inspect; "#<Rect:#{self.object_id} [%s,%s,%s,%s]>"%self; end
+
+	#--
+	# ATTRIBUTES
+	#++
+
+	# Returns self.at(0)
+	def x; return self.at(0); end
+	# Sets self[0] to +val+
+	def x=(val); self[0] = val; end
+
+	alias left x
+	alias left= x=;
+	alias l x
+	alias l= x=;
+
+	# Returns self.at(1)
+	def y; return self.at(1); end
+	# Sets self[1] to +val+
+	def y=(val); self[1] = val; end
+
+	alias top y
+	alias top= y=;
+	alias t y
+	alias t= y=;
+
+	# Returns self.at(2)
+	def w; return self.at(2); end
+	# Sets self[2] to +val+
+	def w=(val); self[2] = val; end
+
+	alias width w
+	alias width= w=;
+
+	# Returns self.at(3)
+	def h; return self.at(3); end
+	# Sets self[3] to +val+
+	def h=(val); self[3] = val; end
+
+	alias height h
+	alias height= h=;
+
+	# Return the width and height of the Rect.
+	def size; return self[2,2]; end
+
+	# Set the width and height of the Rect.
+	def size=(size)
+	 raise ArgumentError, "Rect#size= takes an Array of form [width, height]." if size.size != 2
+	 self[2,2] = size
+	 size
+	end
+
+	# Return the x coordinate of the right side of the Rect.
+	def right; return self.at(0)+self.at(2); end
+
+	# Set the x coordinate of the right side of the Rect by translating the
+	# Rect (adjusting the x offset).
+	def right=(r); self[0] = r - self.at(2); return r; end
+
+	alias r right
+	alias r= right=;
+
+	# Return the y coordinate of the bottom side of the Rect.
+	def bottom; return self.at(1)+self.at(3); end
+
+	# Set the y coordinate of the bottom side of the Rect by translating the
+	# Rect (adjusting the y offset).
+	def bottom=(b); self[1] = b - self.at(3); return b; end
+
+	alias b bottom
+	alias b= bottom=;
+
+	# Return the x and y coordinates of the center of the Rect.
+	def center; return self.centerx, self.centery; end
+
+	# Set the x and y coordinates of the center of the Rect by translating the
+	# Rect (adjusting the x and y offsets).
+	def center=(center)
+	    raise ArgumentError, "Rect#center= takes an Array of the form [x,y]." if center.size != 2
+		self.centerx, self.centery = center
+		center
+	end
+	alias c center
+	alias c= center=;
+
+	# Return the x coordinate of the center of the Rect
+	def centerx; return self.at(0)+(self.at(2).div(2)); end
+
+	# Set the x coordinate of the center of the Rect by translating the
+	# Rect (adjusting the x offset).
+	def centerx=(x); self[0] = x - (self.at(2).div(2)); return x; end
+
+	alias cx centerx
+	alias cx= centerx=;
+
+	# Return the y coordinate of the center of the Rect
+	def centery; return self.at(1)+(self.at(3).div(2)); end
+
+	# Set the y coordinate of the center of the Rect by translating the
+	# Rect (adjusting the y offset).
+	def centery=(y); self[1] = y- (self.at(3).div(2)); return y; end
+
+	alias cy centery
+	alias cy= centery=;
+
+	# Return the x and y coordinates of the top-left corner of the Rect
+	def topleft; return self[0,2].to_a; end
+
+	# Set the x and y coordinates of the top-left corner of the Rect by 
+	# translating the Rect (adjusting the x and y offsets).
+	def topleft=(topleft)
+	    raise ArgumentError, "Rect#topright= takes an Array of form [x, y]." if topleft.size != 2
+		self[0,2] = topleft
+		return topleft
+	end
+
+	alias tl topleft
+	alias tl= topleft=;
+
+	# Return the x and y coordinates of the top-right corner of the Rect
+	def topright; return self.right, self.at(1); end
+
+	# Set the x and y coordinates of the top-right corner of the Rect by 
+	# translating the Rect (adjusting the x and y offsets).
+	def topright=(topright)
+	    raise ArgumentError, "Rect#topright= takes an Array of form [x, y]." if topright.size != 2
+		self.right, self[1] = topright
+		return topright
+	end
+
+	alias tr topright
+	alias tr= topright=;
+
+	# Return the x and y coordinates of the bottom-left corner of the Rect
+	def bottomleft; return self.at(0), self.bottom; end
+
+	# Set the x and y coordinates of the bottom-left corner of the Rect by 
+	# translating the Rect (adjusting the x and y offsets).
+	def bottomleft=(bottomleft)
+		raise ArgumentError, "Rect#bottomleft= takes an Array of form [x, y]." if bottomleft.size != 2
+		self[0], self.bottom = bottomleft
+		return bottomleft
+	end
+
+	alias bl bottomleft
+	alias bl= bottomleft=;
+
+	# Return the x and y coordinates of the bottom-right corner of the Rect
+	def bottomright; return self.right, self.bottom; end
+
+	# Set the x and y coordinates of the bottom-right corner of the Rect by 
+	# translating the Rect (adjusting the x and y offsets).
+	def bottomright=(bottomright)
+		raise ArgumentError, "Rect#bottomright= takes an Array of form [x, y]." if bottomright.size != 2
+		self.right, self.bottom = bottomright
+		return bottomright
+	end
+
+	alias br bottomright
+	alias br= bottomright=;
+
+	# Return the x and y coordinates of the midpoint on the left side of the
+	# Rect.
+	def midleft; return self.at(0), self.centery; end	
+
+	# Set the x and y coordinates of the midpoint on the left side of the Rect
+	# by translating the Rect (adjusting the x and y offsets).
+	def midleft=(midleft)
+    	raise ArgumentError, "Rect#midleft= takes an Array of form [x, y]." if midleft.size != 2
+		self[0], self.centery = midleft
+		return midleft
+	end
+
+	alias ml midleft
+	alias ml= midleft=;
+
+	# Return the x and y coordinates of the midpoint on the left side of the
+	# Rect.
+	def midtop; return self.centerx, self.at(1); end	
+
+	# Set the x and y coordinates of the midpoint on the top side of the Rect
+	# by translating the Rect (adjusting the x and y offsets).
+	def midtop=(midtop)
+    	raise ArgumentError, "Rect#midtop= takes an Array of form [x, y]." if midtop.size != 2
+		self.centerx, self[1] = midtop
+		return midtop
+	end
+
+	alias mt midtop
+	alias mt= midtop=;
+
+	# Return the x and y coordinates of the midpoint on the left side of the
+	# Rect.
+	def midright; return self.right, self.centery; end	
+
+	# Set the x and y coordinates of the midpoint on the right side of the Rect
+	# by translating the Rect (adjusting the x and y offsets).
+	def midright=(midright)
+    	raise ArgumentError, "Rect#midright= takes an Array of form [x, y]." if midright.size != 2
+		self.right, self.centery = midright
+		return midright
+	end
+
+	alias mr midright
+	alias mr= midright=;
+
+	# Return the x and y coordinates of the midpoint on the left side of the
+	# Rect.
+	def midbottom; return self.centerx, self.bottom; end	
+
+	# Set the x and y coordinates of the midpoint on the bottom side of the
+	# Rect by translating the Rect (adjusting the x and y offsets).
+	def midbottom=(midbottom)
+    	raise ArgumentError, "Rect#midbottom= takes an Array of form [x, y]." if midbottom.size != 2
+		self.centerx, self.bottom = midbottom
+		return midbottom
+	end
+
+	alias mb midbottom
+	alias mb= midbottom=;
+
+	#--
+	# UTILITY METHODS
+	#++
+
+
+	# As #clamp!, but the original caller is not changed.
+	def clamp(rect)
+		self.dup.clamp!(rect)
+	end
+
+	# Translate the calling Rect to be entirely inside the given Rect. If 
+	# the caller is too large along either axis to fit in the given rect,
+	# it is centered with respect to the given rect, along that axis.
+	def clamp!(rect)
+		nself = self.normalize
+		rect = Rect.new_from_object(rect)
+		#If self is inside given, there is no need to move self
+		unless rect.contain?(nself)
+
+			#If self is too wide:
+			if nself.at(2) >= rect.at(2)
+				self[0] = rect.centerx - nself.at(2).div(2)
+				#Else self is not too wide
+			else
+				#If self is to the left of arg
+				if nself.at(0) < rect.at(0)
+					self[0] = rect.at(0)
+				#If self is to the right of arg
+				elsif nself.right > rect.right
+					self[0] = rect.right - nself.at(2)
+				#Otherwise, leave x alone
+				end
+			end
+
+			#If self is too tall:
+			if nself.at(3) >= rect.at(3)
+				self[1] = rect.centery - nself.at(3).div(2)
+				#Else self is not too tall
+			else
+				#If self is above arg
+				if nself.at(1) < rect.at(1)
+					self[1] = rect.at(1)
+				#If self below arg
+				elsif nself.bottom > rect.bottom
+					self[1] = rect.bottom - nself.at(3)
+				#Otherwise, leave y alone
+				end
+			end
+		end
+		return self
+	end
+
+	# As #clip!, but the original caller is not changed.
+	def clip(rect)
+		self.dup.clip!(rect)
+	end
+
+	# Crop the calling Rect to be entirely inside the given Rect. If the
+	# caller does not intersect the given Rect at all, its width and height
+	# are set to zero, but its x and y offsets are not changed.
+	# 
+	# As a side effect, the Rect is normalized.
+	def clip!(rect)
+		nself = self.normalize
+		other = Rect.new_from_object(rect).normalize!
+		if self.collide_rect?(other)
+			self[0] = [nself.at(0), other.at(0)].max
+			self[1] = [nself.at(1), other.at(1)].max
+			self[2] = [nself.right, other.right].min - self.at(0)
+			self[3] = [nself.bottom, other.bottom].min - self.at(1)
+		else #if they do not intersect at all:
+			self[0], self[1] = nself.topleft
+			self[2], self[3] = 0, 0
+		end
+		return self
+	end
+
+	# Iterate through all key/value pairs in the given hash table, and
+	# return the first pair whose value is a Rect that collides with the
+	# caller.
+	#
+	# Because a hash table is unordered, you should not expect any 
+	# particular Rect to be returned first.
+	def collide_hash(hash_rects)
+		hash_rects.each { |key,value|
+			if value.collide_rect?+(self); return [key,value]; end
+		}
+		return nil
+	end
+
+	# Iterate through all key/value pairs in the given hash table, and
+	# return an Array of every pair whose value is a Rect that collides
+	# the caller.
+	# 
+	# Because a hash table is unordered, you should not expect the returned
+	# pairs to be in any particular order.
+	def collide_hash_all(hash_rects)
+		hash_rects.select { |key,value|
+			value.collide_rect?+(self)
+		}
+	end
+
+	# Iterate through all elements in the given Array, and return
+	# the *index* of the first element which is a Rect that collides with
+	# the caller.
+	def collide_array(array_rects)
+		for i in (0...(array_rects.length))
+			if array_rects[i].collide_rect?(self)
+				return i
+			end
+		end
+		return nil
+	end
+
+	# Iterate through all elements in the given Array, and return
+	# an Array containing the *indices* of every element that is a Rect
+	# that collides with the caller.
+	def collide_array_all(array_rects)
+		indexes = []
+		for i in (0...(array_rects.length))
+			if array_rects[i].collide_rect?(self)
+				indexes += [i]
+			end
+		end
+		return indexes
+	end
+
+	# True if the point is inside (including on the border) of the caller.
+	# If you have Array of coordinates, you can use collide_point?(*coords).
+	def collide_point?(x,y)
+		nself = normalize()
+		x.between?(nself.left,nself.right) && y.between?(nself.top,nself.bottom)
+	end
+
+	# True if the caller and the given Rect overlap (or touch) at all.
+	def collide_rect?(rect)
+		nself = self.normalize
+		rect  = Rect.new_from_object(rect).normalize!
+		return ((nself.l >= rect.l && nself.l <= rect.r) or (rect.l >= nself.l && rect.l <= nself.r)) &&
+		       ((nself.t >= rect.t && nself.t <= rect.b) or (rect.t >= nself.t && rect.t <= nself.b))
+	end
+
+	# True if the given Rect is totally within the caller. Borders may
+	# overlap.
+	def contain?(rect)
+		nself = self.normalize
+		rect = Rect.new_from_object(rect).normalize!
+		return (nself.left <= rect.left and rect.right <= nself.right and
+					nself.top <= rect.top and rect.bottom <= nself.bottom)
+	end
+
+	# As #inflate!, but the original caller is not changed.
+	def inflate(x,y)
+		return self.class.new(self.at(0) - x.div(2),
+													self.at(1) - y.div(2),
+													self.at(2) + x,
+													self.at(3) + y)
+	end
+
+	# Increase the Rect's size is the x and y directions, while keeping the
+	# same center point. For best results, expand by an even number.
+	# X and y inflation can be given as an Array or as separate values.
+	def inflate!(x,y)
+		self[0] -= x.div(2)
+		self[1] -= y.div(2)
+		self[2] += x
+		self[3] += y
+		return self
+	end
+
+	# As #move!, but the original caller is not changed.
+	def move(x,y)
+		self.dup.move!(x,y)
+	end
+
+	# Translate the Rect by the given amounts in the x and y directions.
+	# Positive values are rightward for x and downward for y.
+	# X and y movement can be given as an Array or as separate values.
+	def move!(x,y)
+		self[0]+=x; self[1]+=y
+		return self
+	end
+
+	# As #normalize!, but the original caller is not changed.
+	def normalize
+		self.dup.normalize!()
+	end
+
+	# Fix Rects that have negative width or height, without changing the
+	# area it represents. Has no effect on Rects with non-negative width
+	# and height. Some Rect methods will automatically normalize the Rect.
+	def normalize!
+		if self.at(2) < 0
+			self[0], self[2] = self.at(0)+self.at(2), -self.at(2)
+		end
+		if self.at(3) < 0
+			self[1], self[3] = self.at(1)+self.at(3), -self.at(3)
+		end
+		self
+	end
+
+	# As #union!, but the original caller is not changed.
+	def union(rect)
+		self.dup.union!(rect)
+	end
+
+	# Expand the caller to also cover the given Rect. The Rect is still a 
+	# rectangle, so it may also cover areas that neither of the original
+	# Rects did, for example areas between the two Rects.
+	def union!(rect)
+		self.normalize!
+    rleft, rtop = self.topleft
+    rright, rbottom = self.bottomright
+		r2 = Rect.new_from_object(rect).normalize!
+
+		rleft = [rleft, r2.left].min
+		rtop = [rtop, r2.top].min
+		rright = [rright, r2.right].max
+		rbottom = [rbottom, r2.bottom].max
+
+		self[0,4] = rleft, rtop, rright - rleft, rbottom - rtop
+		return self
+	end
+
+	# As #union_all!, but the original caller is not changed.
+	def union_all(array_rects)
+		self.dup.union_all!(array_rects)
+	end
+
+	# Expand the caller to cover all of the given Rects. See also #union!
+	def union_all!(array_rects)
+		array_rects.each do |r|
+      self.union!(r)
+		end
+		return self
+	end
+
+
+end # class Rect
+
+
+class Surface
+	# Return a Rect with the same width and height as the Surface, positioned
+	# at (0,0).
+	def make_rect()
+		return Rect.new(0,0,self.width,self.height)
+	end
+end
+
+end # module Rubygame