rubygame 2.1.0

data/lib/rubygame/event.rb

@@ -0,0 +1,313 @@
+#--
+#	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
+
+	# List of all Rubygame hardware event classes. *Do not modify!*
+	SDL_EVENTS = [ActiveEvent, KeyDownEvent, KeyUpEvent,\
+		MouseMotionEvent,MouseDownEvent,MouseUpEvent,JoyAxisEvent,\
+		JoyBallEvent, JoyHatEvent,JoyDownEvent, JoyUpEvent,\
+		ResizeEvent, QuitEvent]
+  
+	# Converts a keyboard symbol (keysym) into a human-readable text string.
+	# If either Shift key was being pressed, alphanumeric or punctuation keys 
+	# will be made uppercase or alternate, based on U.S. keyboard layout.
+	# E.g. "a" becomes "A", "1" becomes "!", and "/" becomes "?".
+	def Rubygame.key2str( sym, mods )
+		if (mods.include? K_LSHIFT) or (mods.include? K_RSHIFT)
+			return (Rubygame::Key::KEY2UPPER[sym]\
+				or Rubygame::Key::KEY2ASCII[sym] or "")
+		else
+			return (Rubygame::Key::KEY2LOWER[sym]\
+				or Rubygame::Key::KEY2ASCII[sym] or "")
+		end
+	end
+
+	# The parent class for all event classes. You can make custom event classes,
+  # if desired; inheriting this class is not necessary, but makes it easier
+  # to check if an object is an event or not.
+	class Event
+	end
+
+	# Indicates that the Rubygame window has gained or lost focus from the
+	# window manager.
+	# 
+	# This event has these attributes:
+	# gain::  true if the window gained focus, and false if it lost focus.
+	# state:: string indicating what type of focus was gained or lost: 
+	#         "mouse"::    the mouse entered/exited the window
+	#         "keyboard":: the window gained or lost input focus
+	#         "active"::   the window was minimized/iconified.
+	class ActiveEvent < Event
+		attr_accessor :gain, :state
+		def initialize(gain,state)
+			@gain = gain
+			@state = state 
+		end
+	end
+
+	# Indicates that a keyboard key was pressed.
+	# 
+	# This event has these attributes:
+	# string:: a human-readable string telling what key was pressed, or nil.
+	#          See #key2str.
+	# key::    the integer keysym for the key. These can be compared with the
+	#          K_* constants in the Rubygame module, e.g. Rubygame::K_A.
+	# mods::   an Array of zero or more keysyms indicating which modifier keys
+	#          were being pressed when the key was pressed. You can compare
+	#          with these constants in the Rubygame module:
+	#          K_RSHIFT::    shift key (right side)
+	#          K_LSHIFT::    shift key (left side)
+	#          K_RCTRL::     ctrl key (right side)
+	#          K_LCTRL::     ctrl key (left side)
+	#          K_RALT::      alt key (right side)
+	#          K_LALT::      alt key (left side)
+	#          K_RMETA::     meta key (right side)
+	#          K_LMETA::     meta key (left side)
+	#          K_RSUPER::    super key, aka. Windows key (right side)
+	#          K_LSUPER::    super key, aka. Windows key (left side)
+	#          K_RALT::      alt key (right side)
+	#          K_NUMLOCK::   num lock
+	#          K_CAPSLOCK::  caps lock
+	#          K_MODE::      mode key
+	#          
+	#          
+	class KeyDownEvent < Event
+		attr_accessor :string,:key,:mods
+
+		# Create a new KeyDownEvent.
+		# 
+		# key::  either an integer keysym (e.g. Rubygame::K_A) or string (e.g. "a")
+		# mods:: array of modifier keysyms
+		def initialize(key,mods)
+			if key.kind_of? Integer
+				@key = key
+				@string = Rubygame.key2str(key, mods) #a string or nil
+			elsif key.kind_of? String
+				@key = Rubygame::Key::ASCII2KEY[key]
+				if @key != nil
+					@string = key
+				else
+					raise(ArgumentError,"First argument of KeyDownEvent.new() must be an Integer KeySym (like K_A) or a ASCII-like String (like \"a\" or \"A\"). Got %s (%s)"%[key,key.class])
+				end
+			end
+			@mods = mods
+		end
+	end
+
+	# Indicates that a keyboard key was released.
+	# 
+	# See KeyDownEvent.
+	class KeyUpEvent < Event
+		attr_accessor :string,:key,:mods
+		def initialize(key,mods)
+			if key.kind_of? Integer
+				@key = key
+				@string = Rubygame.key2str(key, mods) #a string or nil
+			elsif key.kind_of? String
+				@key = Rubygame::Key::ASCII2KEY[key]
+				if @key != nil
+					@string = key
+				else
+					raise(ArgumentError,"First argument of KeyUpEvent.new() must be an Integer KeySym (like K_A) or a ASCII-like String (like \"a\" or \"A\"). Got %s (%s)"%[key,key.class])
+				end
+			end
+			@mods = mods
+		end
+	end
+
+	# Indicates that the mouse cursor moved.
+	# 
+	# This event has these attributes:
+	# pos::     the new position of the cursor, in the form [x,y].
+	# rel::     the relative movement of the cursor since the last update, [x,y].
+	# buttons:: the mouse buttons that were being held during the movement,
+	#           an Array of zero or more of these constants in module Rubygame
+	#           (or the corresponding button number):
+	#           MOUSE_LEFT::   1; left mouse button
+	#           MOUSE_MIDDLE:: 2; middle mouse button
+	#           MOUSE_RIGHT::  3; right mouse button
+	class MouseMotionEvent < Event
+		attr_accessor :pos,:rel,:buttons
+		def initialize(pos,rel,buttons)
+			@pos, @rel, @buttons = pos, rel, buttons
+		end
+	end
+
+	# Indicates that a mouse button was pressed.
+	# 
+	# This event has these attributes:
+	# string:: string indicating the button that was pressed ("left","middle", or
+	#          "right").
+	# pos::    the position of the mouse cursor when the button was pressed,
+	#          in the form [x,y].
+	# button:: the mouse button that was pressed; one of these constants in
+	#          module Rubygame (or the corresponding button number):
+	#          MOUSE_LEFT::   1; left mouse button
+	#          MOUSE_MIDDLE:: 2; middle mouse button
+	#          MOUSE_RIGHT::  3; right mouse button
+	class MouseDownEvent < Event
+		attr_accessor :string,:pos,:button
+		def initialize(pos,button)
+			@pos = pos
+			if button.kind_of? Integer
+				@button = button
+				@string = Rubygame::Mouse::MOUSE2STR[button] #a string or nil
+			elsif key.kind_of? String
+				@button = Rubygame::Mouse::STR2MOUSE[key]
+				if @button != nil
+					@string = button
+				else
+					raise(ArgumentError,"First argument of MouseDownEvent.new() must be an Integer Mouse button indentifier (like MOUSE_LEFT) or a String (like \"left\"). Got %s (%s)"%[button,button.class])
+				end
+			end
+		end
+	end
+
+	# Indicates that a mouse button was released.
+	# 
+	# See MouseDownEvent.
+	class MouseUpEvent < Event
+		attr_accessor :string,:pos,:button
+		def initialize(pos,button)
+			@pos = pos
+			if button.kind_of? Integer
+				@button = button
+				@string = Rubygame::Mouse::MOUSE2STR[button] #a string or nil
+			elsif key.kind_of? String
+				@button = Rubygame::Mouse::STR2MOUSE[key]
+				if @button != nil
+					@string = button
+				else
+					raise(ArgumentError,"First argument of MouseUpEvent.new() must be an Integer Mouse button indentifier (like MOUSE_LEFT) or a String (like \"left\"). Got %s (%s)"%[button,button.class])
+				end
+			end
+		end
+	end
+
+	# Indicates that a Joystick axis was moved.
+	# 
+	# This event has these attributes:
+	# joynum:: the identifier number of the affected Joystick.
+	# axis::   the identifier number of the axis.
+	# value::  the new value of the axis, between -32768 and 32767
+	class JoyAxisEvent < Event
+		attr_accessor :joynum,:axis,:value
+		def initialize(joy,axis,value)
+			# eventually, joy could be int OR a Rubygame::Joystick instance,
+			# which would be stored as joy or maybe joyinstance?
+			@joynum = joy
+			@axis, @value = axis, value
+		end
+	end
+
+	# Indicates that a Joystick trackball was moved.
+	# 
+	# This event has these attributes:
+	# joynum:: the identifier number of the affected Joystick.
+	# ball::   the identifier number of the trackball.
+	# rel::    the relative movement of the trackball, [x,y].
+	class JoyBallEvent < Event
+		attr_accessor :joynum,:ball,:rel
+		def initialize(joy,ball,rel)
+			# eventually, joy could be int OR a Rubygame::Joystick instance,
+			# which would be stored as joy or maybe joyinstance?
+			@joynum = joy
+			@ball, @rel = ball, rel
+		end
+	end
+
+	# Indicates that a Joystick POV hat was moved.
+	# 
+	# This event has these attributes:
+	# joynum:: the identifier number of the affected Joystick.
+	# hat::    the identifier number of the hat.
+	# value::  the new direction of the hat, one of these constants in module
+	#          Rubygame (or the corresponding number):
+	#          HAT_CENTERED::   0
+	#          HAT_UP::         1 
+	#          HAT_RIGHT::      2
+	#          HAT_DOWN::       4 	
+	#          HAT_LEFT::       8
+	#          HAT_RIGHTUP::    3
+	#          HAT_RIGHTDOWN::  6
+	#          HAT_LEFTUP::     9
+	#          HAT_LEFTDOWN::   12
+	class JoyHatEvent < Event
+		attr_accessor :joynum,:hat,:value
+		def initialize(joy,hat,value)
+			# eventually, joy could be int OR a Rubygame::Joystick instance,
+			# which would be stored as joy or maybe joyinstance?
+			@joynum = joy
+			@hat, @value = hat, value
+		end
+	end
+
+	# Indicates that a Joystick button was pressed.
+	# 
+	# This event has these attributes:
+	# joynum:: the identifier number of the affected Joystick.
+	# hat::    the identifier number of the button.
+	class JoyDownEvent < Event
+		attr_accessor :joynum, :button
+		def initialize(joy,button)
+			# eventually, joy could be int OR a Rubygame::Joystick instance,
+			# which would be stored as joy or maybe joyinstance?
+			@joynum = joy
+			@button = button
+		end
+	end
+
+	# Indicates that a Joystick button was released.
+	# 
+	# See JoyDownEvent.
+	class JoyUpEvent < Event
+		attr_accessor :joynum, :button
+		def initialize(joy,button)
+			# eventually, joy could be int OR a Rubygame::Joystick instance,
+			# which would be stored as joy or maybe joyinstance?
+			@joynum = joy
+			@button = button
+		end
+	end
+
+	# Indicates that the application window was resized. (After this event
+	# occurs, you should use Screen#set_mode to change the display surface to
+	# the new size.)
+	# 
+	# This event has these attributes:
+	# size:: the new size of the window, in pixels [w,h].
+	class ResizeEvent < Event
+		attr_accessor :size
+		def initialize(new_size)
+			@size = new_size
+		end
+	end
+
+	# Indicates that part of the application window was exposed or otherwise
+	# changed, and perhaps the window needs to be refreshed. This event occurs,
+	# for example, when an OpenGL display should be updated.
+	class ExposeEvent < Event
+	end
+	
+	# Indicates that the application has been signaled to quit. (E.g. the user
+	# pressed the close button.)
+	class QuitEvent < Event
+	end
+end # module Rubygame

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