rubygame 2.1.0 → 2.2.0

data/lib/rubygame.rb

@@ -32,6 +32,7 @@ require "rubygame_core"
   end
 end
 
+require "rubygame/color"
 require "rubygame/constants"
 require "rubygame/event"
 require "rubygame/queue"

data/lib/rubygame/color.rb

@@ -0,0 +1,79 @@
+#--
+#	Rubygame -- Ruby code and bindings to SDL to facilitate game creation
+#	Copyright (C) 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/color/models/base'
+require 'rubygame/color/models/rgb'
+require 'rubygame/color/models/hsv'
+require 'rubygame/color/models/hsl'
+
+require 'rubygame/color/palettes/palette'
+require 'rubygame/color/palettes/x11'
+require 'rubygame/color/palettes/css'
+
+module Rubygame
+
+	# The Color module contains classes related to colors.
+	# 
+	# Available color representations:
+	# 
+	# ColorRGB::  color class with red, green, and blue components.
+	# ColorHSV::  color class with hue, saturation, and value components.
+	# ColorHSL::  color class with hue, saturation, and luminosity components.
+	# 
+	# The Palette class allows you to conveniently store and access a
+	# collection of many different colors, with inheritance from
+	# included Palettes.
+	# 
+	# The available predefined palettes are:
+	# 
+	# X11::    palette with the default X11 colors
+	# CSS::    palette used with HTML and CSS, very similar to X11
+	# GLOBAL:: special palette used for automatic lookup (see below)
+	# 
+	# The GLOBAL palette is special; it is used for automatic color lookup
+	# in functions like Surface#draw_circle and TTF#render.It includes the
+	# CSS palette by default; you can include other palettes or define new
+	# custom colors in GLOBAL to make them available for automatic lookup.
+	# 
+	# For convenience, you can access the GLOBAL palette through the
+	# #[] and #[]= methods:
+	# 
+	#     include Rubygame
+	#     player_color = Color[:red]
+	#     Color[:favorite] = Color[:azure]
+	# 
+	module Color
+
+		(GLOBAL = Palette.new()).include(CSS) # :nodoc:
+		
+		# Retrieve a color from the GLOBAL palette.
+		# See Palette#[]
+		def self.[]( name )
+			GLOBAL[name]
+		end
+		
+		# Store a color in the GLOBAL palette.
+		# See Palette#[]=
+		def self.[]=( name, color )
+			GLOBAL[name] = color
+		end
+		
+	end
+end
+

data/lib/rubygame/color/models/base.rb

@@ -0,0 +1,106 @@
+#--
+#	Rubygame -- Ruby code and bindings to SDL to facilitate game creation
+#	Copyright (C) 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
+#++
+
+
+# A mix-in module defining color arithmetic operations.
+module ColorBase
+
+	# Perform color addition with another color of any type.
+	# The alpha of the new color will be equal to the alpha
+	# of the receiver.
+	def +(other)
+		wrap( simple_op(other)  { |a,b| a + b } )
+	end
+	
+	# Perform color subtraction with another color of any type.
+	# The alpha of the new color will be equal to the alpha
+	# of the receiver.
+	def -(other)
+		wrap( simple_op(other)  { |a,b|  a - b } )
+	end
+
+	# Perform color multiplication with another color of any type.
+	# The alpha of the new color will be equal to the alpha
+	# of the receiver.
+	def *(other)
+		wrap( simple_op(other)  { |a,b|  a * b } )
+	end
+	
+	# Perform color division with another color of any type.
+	# The alpha of the new color will be equal to the alpha
+	# of the receiver.
+	def /(other)
+		wrap( simple_op(other)  { |a,b|  a / b } )
+	end
+	
+	# Layer this color over another color.
+	def over(other)
+		c1, c2 = self.to_rgba_ary, other.to_rgba_ary
+		a1, a2 = c1[3], c2[3]
+
+		rgba = [0,1,2].collect do |i| 
+			clamp( a1*c1.at(i) + a2*c2.at(i)*(1-a1) )
+		end
+		
+		rgba << ( a1 + a2*(1-a1) )
+		
+		wrap( rgba )
+	end
+	
+	# Average this color with another color. (Linear weighted average)
+	# 
+	# A weight of 0.0 means 0% of this color, 100% of the other.
+	# A weight of 1.0 means 100% of this color, 0% of the other.
+	# A weight of 0.5 means 50% of each color.
+	# 
+	def average(other, weight=0.5)
+		c1, c2 = self.to_rgba_ary, other.to_rgba_ary
+
+		rgba = [0,1,2,3].collect do |i| 
+			clamp( c1.at(i)*weight + c2.at(i)*(1-weight) )
+		end
+		
+		wrap( rgba )
+	end
+
+	private
+	
+	def wrap( rgba )
+		self.class.new_from_rgba( rgba )
+	end
+	
+	def simple_op(other, &block)
+		c1, c2 = self.to_rgba_ary, other.to_rgba_ary
+		a1, a2 = c1[3], c2[3]
+
+		rgba = [0,1,2].collect do |i| 
+			clamp( block.call( a1*c1.at(i),  a2*c2.at(i) ) )
+		end
+
+		rgba << a1
+
+		return rgba
+	end
+	
+	def clamp(v, min=0.0, max=1.0)
+		v = min if v < min
+		v = max if v > max
+		return v		
+	end
+end

data/lib/rubygame/color/models/hsl.rb

@@ -0,0 +1,153 @@
+#--
+#	Rubygame -- Ruby code and bindings to SDL to facilitate game creation
+#	Copyright (C) 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/color/models/base'
+
+module Rubygame
+	module Color
+
+		# Represents color in the HSL (Hue, Saturation, Luminosity) color space.
+		class ColorHSL
+			include ColorBase
+			
+			attr_reader :h, :s, :l, :a
+
+			# call-seq:
+			#   new( [h,s,l,a] )  ->  ColorHSL
+			#   new( [h,s,l] )  ->  ColorHSL
+			#   new( color )  ->  ColorHSL
+			# 
+			# Create a new instance from an Array or an existing color
+			# (of any type). If the alpha (opacity) component is omitted
+			# from the array, full opacity will be used.
+			# 
+			# All color components range from 0.0 to 1.0.
+			# 
+			def initialize( color )
+				if color.kind_of?(Array)
+					@h, @s, @l, @a = color.collect { |i| i.to_f }
+					@a = 1.0 unless @a
+				elsif color.respond_to?(:to_rgba_ary)
+					@h, @s, @l, @a = self.class.rgba_to_hsla( *color.to_rgba_ary )
+				end
+			end
+
+			# Return an Array with the red, green, blue, and alpha components
+			# of the color (converting the color to the RGBA model first).
+			def to_rgba_ary
+				return self.class.hsla_to_rgba( @h, @s, @l, @a )
+			end
+			
+			def to_s
+				"#<#{self.class} [#{@h}, #{@s}, #{@l}, #{@a}]>"
+			end
+			alias :inspect :to_s
+			
+			class << self
+
+				def new_from_rgba( rgba )
+					new( rgba_to_hsla(*rgba) )
+				end
+				
+				def new_from_sdl_rgba( rgba )
+					new_from_rgba( rgba.collect { |i| i / 255.0 } )
+				end
+				
+				# Convert the red, green, blue, and alpha to the
+				# equivalent hue, saturation, luminosity, and alpha.
+				def rgba_to_hsla( r, g, b, a ) # :nodoc:
+					rgb_arr = [r, g, b]
+					max     = rgb_arr.max
+					min     = rgb_arr.min
+
+					# Calculate lightness.
+					l = (max + min) / 2.0
+
+					# Calculate saturation.
+					if l == 0.0 or max == min
+						s = 0
+					elsif 0 < l and l <= 0.5 
+						s = (max - min) / (max + min)
+					else # l > 0.5
+						s = (max - min) / (2 - (max + min))
+					end
+					
+					# Calculate hue.
+					if min == max 
+						h = 0 
+						# Undefined in this case, but set it to zero
+					elsif max == r and g >= b
+						h = (1.quo(6) * (g - b) / (max - min)) + 0
+					elsif max == r and g < b
+						h = (1.quo(6) * (g - b) / (max - min)) + 1.0
+					elsif max == g
+						h = (1.quo(6) * (b - r) / (max - min)) + 1.quo(3)
+					elsif max == b
+						h = (1.quo(6) * (r - g) / (max - min)) + 2.quo(3)
+					else 
+						raise "Should never happen"
+					end 
+					
+					return [h,s,l,a]
+				end
+				
+				# Convert the hue, saturation, luminosity, and alpha
+				# to the equivalent red, green, blue, and alpha.
+				def hsla_to_rgba( h, s, l, a ) # :nodoc:
+					# If the color is achromatic, return already with the lightness value for all components
+					if s == 0.0
+						return [l, l, l, a]
+					end
+
+					# Otherwise, we have to do the long, hard calculation
+
+					# q helper value
+					q = (l < 0.5) ? (l * (1.0 + s)) : (l + s - l * s)
+
+					# p helper value
+					p = (2.0 * l) - q
+
+					r = calculate_component( p, q, h + 1.quo(3) )
+					g = calculate_component( p, q, h            )
+					b = calculate_component( p, q, h - 1.quo(3) )
+
+					return [r,g,b,a]
+				end
+
+				private
+				
+				# Perform some arcane math to calculate a color component.
+				def calculate_component(p, q, tc) # :nodoc:
+					tc %= 1.0
+					if tc < 1.quo(6)
+						p + (q - p) * tc * 6.0
+					elsif tc < 0.5
+						q
+					elsif tc < 2.quo(3)
+						p + (q - p) * (2.quo(3) - tc) * 6.0
+					else
+						p 
+					end
+				end
+				
+			end
+
+		end
+	end
+end

data/lib/rubygame/color/models/hsv.rb

@@ -0,0 +1,149 @@
+#--
+#	Rubygame -- Ruby code and bindings to SDL to facilitate game creation
+#	Copyright (C) 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/color/models/base'
+
+module Rubygame
+	module Color
+
+		# Represents color in the HSV (Hue, Saturation, Value) color space.
+		class ColorHSV
+			include ColorBase
+
+			attr_reader :h, :s, :v, :a
+
+			# call-seq:
+			#   new( [h,s,v,a] )  ->  ColorHSV
+			#   new( [h,s,v] )  ->  ColorHSV
+			#   new( color )  ->  ColorHSV
+			# 
+			# Create a new instance from an Array or an existing color
+			# (of any type). If the alpha (opacity) component is omitted
+			# from the array, full opacity will be used.
+			# 
+			# All color components range from 0.0 to 1.0.
+			# 
+			def initialize( color )
+				if color.kind_of?(Array)
+					@h, @s, @v, @a = color.collect { |i| i.to_f }
+					@a = 1.0 unless @a
+				elsif color.respond_to?(:to_rgba_ary)
+					@h, @s, @v, @a = self.class.rgba_to_hsva( *color.to_rgba_ary )
+				end
+			end
+			
+			# Return an Array with the red, green, blue, and alpha components
+			# of the color (converting the color to the RGBA model first).
+			def to_rgba_ary
+				return self.class.hsva_to_rgba( @h, @s, @v, @a )
+			end
+			
+			def to_s
+				"#<#{self.class} [#{@h}, #{@s}, #{@v}, #{@a}]>"
+			end
+			alias :inspect :to_s
+			
+			class << self
+				
+				def new_from_rgba( rgba )
+					new( rgba_to_hsva(*rgba) )
+				end
+				
+				def new_from_sdl_rgba( rgba )
+					new_from_rgba( rgba.collect { |i| i / 255.0 } )
+				end
+				
+				# Convert the red, green, blue, and alpha to the
+				# equivalent hue, saturation, value, and alpha.
+				def rgba_to_hsva( r, g, b, a ) # :nodoc:
+					rgb_arr = [r, g, b]
+					max     = rgb_arr.max
+					min     = rgb_arr.min
+
+					# Calculate hue.
+					if min == max 
+						h = 0 
+						# Undefined in this case, but set it to zero
+					elsif max == r and g >= b
+						h = (1.quo(6) * (g - b) / (max - min)) + 0
+					elsif max == r and g < b
+						h = (1.quo(6) * (g - b) / (max - min)) + 1.0
+					elsif max == g
+						h = (1.quo(6) * (b - r) / (max - min)) + 1.quo(3)
+					elsif max == b
+						h = (1.quo(6) * (r - g) / (max - min)) + 2.quo(3)
+					else 
+						raise "Should never happen"
+					end
+
+					# Calulate value.
+					v = max
+
+					# Calculate saturation.
+					if max == 0.0
+						s = 0.0
+					else
+						s = 1.0 - (min / max)
+					end  
+					
+					return [h,s,v,a]
+				end
+
+				# Convert the hue, saturation, value, and alpha
+				# to the equivalent red, green, blue, and alpha.
+				def hsva_to_rgba( h, s, v, a ) # :nodoc:
+					# Determine what part of the "color hexagon" the hue is in.
+					hi = (h * 6).floor % 6
+
+					# Fractional part
+					f  = (h * 6) - hi
+
+					# Helper values
+					p  = v * (1.0 - s)
+					q  = v * (1.0 - (f * s))
+					t  = v * (1.0 - ((1.0 - f) * s))
+
+					# Finally calculate the rgb values
+					r, g, b = calculate_rgb(hi, v, p, t, q)
+
+					return [r, g, b, a]
+				end
+
+				private
+				
+				def calculate_rgb(hi, v, p, t, q) # :nodoc:
+					case hi
+					when 0
+						return v, t, p
+					when 1
+						return q, v, p
+					when 2
+						return p, v, t
+					when 3
+						return p, q, v
+					when 4
+						return t, p, v
+					when 5
+						return v, p, q
+					end
+				end
+			end
+		end
+	end
+end