rubygame 2.3.0-x86-linux

data/ext/rubygame/rubygame_screen.h

@@ -0,0 +1,43 @@
+/*
+ * 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
+ *
+ */
+
+#ifndef _RUBYGAME_SCREEN_H
+#define _RUBYGAME_SCREEN_H
+
+extern void Rubygame_Init_Screen();
+
+extern VALUE cScreen;
+
+extern VALUE rbgm_screen_setmode(int, VALUE*, VALUE);
+extern VALUE rbgm_screen_getsurface(VALUE);
+
+extern VALUE rbgm_screen_getcaption(VALUE);
+extern VALUE rbgm_screen_setcaption(VALUE, VALUE);
+
+extern VALUE rbgm_screen_seticon(VALUE, VALUE);
+
+extern VALUE rbgm_screen_update(int, VALUE*, VALUE);
+extern VALUE rbgm_screen_updaterects(VALUE, VALUE);
+extern VALUE rbgm_screen_flip(VALUE);
+
+extern VALUE rbgm_screen_getshowcursor(VALUE);
+extern VALUE rbgm_screen_setshowcursor(VALUE, VALUE);
+
+#endif

data/ext/rubygame/rubygame_shared.c

@@ -0,0 +1,272 @@
+/*
+ *  Code that is common to all Rubygame modules.
+ *--
+ * 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
+ *++
+ */
+
+#include "rubygame_shared.h"
+
+VALUE mRubygame;
+VALUE cSurface;
+VALUE cRect;
+VALUE eSDLError;
+VALUE mNamedResource;
+
+
+SDL_Rect *make_rect(int, int, int, int);
+SDL_Color make_sdl_color(VALUE);
+int init_video_system();
+void Init_rubygame_shared();
+
+SDL_Rect *make_rect(int x, int y, int w, int h)
+{
+	SDL_Rect *rect;
+	rect = (SDL_Rect *) malloc(sizeof(SDL_Rect));
+	rect->x = x;
+	rect->y = y;
+	rect->w = w;
+	rect->h = h;
+	return rect;
+}
+
+/* Returns a symbol from the given char* string */
+VALUE make_symbol(char *string)
+{
+	return ID2SYM(rb_intern(string));
+}
+
+/* Returns a char* string from the given symbol */
+char *unmake_symbol(VALUE symbol)
+{
+	return rb_id2name( SYM2ID(symbol) );
+}
+
+
+/* Lowercase, change spaces to underscores, and convert to symbol.
+ * Equivalent to: str.downcase!.gsub!(" ","_").intern
+ */
+VALUE sanitized_symbol(char *string)
+{
+	VALUE str = rb_str_new2(string);
+
+	rb_funcall( str, rb_intern("downcase!"), 0 );
+	rb_funcall( str, rb_intern("gsub!"), 2, rb_str_new2(" "), rb_str_new2("_") );
+	return rb_funcall( str, rb_intern("intern"), 0 );
+}
+
+/* Take either nil, Numeric or an Array of Numerics, returns Uint32. */
+Uint32 collapse_flags(VALUE vflags)
+{
+	Uint32 flags = 0;
+	int i;
+
+	if( RTEST(vflags) )
+	{
+    switch( TYPE(vflags) ){
+			case T_ARRAY: {
+				int len = RARRAY(vflags)->len;
+				for(i=0;  i < len;  i++)
+        {
+          flags |= NUM2UINT(  rb_ary_entry( vflags,i )  );
+        }
+				break;
+			}
+			case T_BIGNUM: {
+				flags = rb_big2uint( vflags );
+				break;
+            }
+			case T_FIXNUM: {
+				flags = NUM2UINT( vflags );
+				break;
+			}
+			default: {
+				rb_raise(rb_eArgError,"Wrong type for argument `flags' (wanted Number or Array).");
+			}
+    }
+	}
+
+	return flags;
+}
+
+VALUE convert_to_array(VALUE val)
+{
+	VALUE v = rb_check_array_type(val);
+	if( TYPE(v) != T_ARRAY )
+	{
+		rb_raise(rb_eTypeError, "can't convert %s into Array",
+						 rb_obj_classname(val));
+	}
+	return v;
+}
+
+/* Takes a Color, Array, or color name (Symbol or String).
+ * Returns an RGBA Array, or raises eTypeError if it can't.
+ */
+VALUE convert_color(VALUE color)
+{
+	if( rb_respond_to(color, rb_intern("to_sdl_rgba_ary")) )
+	{
+		return rb_funcall( color, rb_intern("to_sdl_rgba_ary"), 0 );
+	}
+	else if( rb_respond_to(color, rb_intern("to_ary")) )
+	{
+		return convert_to_array( color );
+	}
+	else if( TYPE(color) == T_SYMBOL || TYPE(color) == T_STRING )
+	{
+		VALUE mColor = rb_const_get( mRubygame, rb_intern("Color") );
+		return convert_color( rb_funcall( mColor, rb_intern("[]"), 1, color) );
+	}
+	else
+	{
+		rb_raise(rb_eTypeError, "unsupported type %s for color",
+						 rb_obj_classname(color));
+	}
+}
+
+SDL_Color make_sdl_color(VALUE vcolor)
+{
+	SDL_Color color;
+	vcolor = convert_color(vcolor);
+	extract_rgb_u8_as_u8(vcolor, &(color.r), &(color.g), &(color.b));
+	return color;
+}
+
+void extract_rgb_u8_as_u8(VALUE color, Uint8 *r, Uint8 *g, Uint8 *b)
+{
+	*r = NUM2UINT(rb_ary_entry(color, 0));
+	*g = NUM2UINT(rb_ary_entry(color, 1));
+	*b = NUM2UINT(rb_ary_entry(color, 2));
+}
+
+void extract_rgba_u8_as_u8(VALUE color, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a)
+{
+	*r = NUM2UINT(rb_ary_entry(color, 0));
+	*g = NUM2UINT(rb_ary_entry(color, 1));
+	*b = NUM2UINT(rb_ary_entry(color, 2));
+
+	if( RARRAY(color)->len > 3 )
+	{
+		*a = NUM2UINT(rb_ary_entry(color, 3));
+	}
+	else
+	{
+		*a = 255;
+	}
+}
+
+
+
+/* --
+ *
+ * Issues a deprecation warning for the given feature/method.
+ *
+ * ++
+ */
+void rg_deprecated( char *feature, char *version )
+{
+  rb_warning( "%s is DEPRECATED and will be removed in Rubygame %s! "
+              "Please see the docs for more information.",
+              feature, version );
+}
+
+
+
+/* --
+ *
+ *  call-seq:
+ *     init_video_system()  ->  int
+ *
+ *  Initialize SDL's video subsystem.
+ *  Return 0 (zero) on success, non-zero on failure.
+ *
+ *  If it has already been initialized, return 0 immediately.
+ *
+ * ++
+ */
+int init_video_system()
+{
+	if( SDL_WasInit(SDL_INIT_VIDEO) == 0 )
+	{
+		return SDL_Init(SDL_INIT_VIDEO);
+	}
+	else
+	{
+		return 0;
+	}
+}
+
+/* --
+ *
+ * Includes the Rubygame::NamedResource mixin in the given class
+ * and performs the `included' callback.
+ *
+ * ++
+ */
+void rg_include_named_resource( VALUE klass )
+{
+  /* Include the mixin, and manually perform the 'included' callback. */
+	rb_include_module( klass, mNamedResource );
+  rb_funcall( mNamedResource, rb_intern("included"), 1, klass );
+}
+
+
+void Init_rubygame_shared()
+{
+
+	mRubygame = rb_define_module("Rubygame");
+
+	/* Rubygame::Surface class */
+	if( !rb_const_defined(mRubygame,rb_intern("Surface")) )
+	{
+		cSurface = rb_define_class_under(mRubygame,"Surface",rb_cObject);
+	}
+	else
+	{
+		cSurface = rb_const_get(mRubygame,rb_intern("Surface"));
+	}
+
+	/* Rubygame::SDLError class */
+	if( !rb_const_defined(mRubygame,rb_intern("SDLError")))
+	{
+		/* Indicates that an SDL function did not execute properly. */
+		eSDLError = rb_define_class_under(mRubygame,"SDLError",rb_eStandardError);
+	}
+	else
+	{
+		eSDLError = rb_const_get(mRubygame,rb_intern("SDLError"));
+	}
+
+	/* Rubygame::VERSIONS hash table */
+	if( !rb_const_defined(mRubygame, rb_intern("VERSIONS")))
+	{
+		/* A Hash containing the version	s of rubygame and it's 
+		 *	 compile-time dependencies. */
+		rb_define_const(mRubygame,"VERSIONS",rb_hash_new());
+	}
+
+
+  /* Rubygame::NamedResource mixin. See named_resource.rb. */
+  if( mNamedResource == (int)NULL )
+  {
+    rb_require("rubygame/named_resource");
+    mNamedResource = rb_const_get(mRubygame, rb_intern("NamedResource"));
+  }
+
+}

data/ext/rubygame/rubygame_shared.h

@@ -0,0 +1,68 @@
+/*
+ * 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
+ *
+ */
+
+#ifndef _RUBYGAME_SHARED_H
+#define _RUBYGAME_SHARED_H
+
+#include <SDL.h>
+#include <ruby.h>
+#include <stdio.h>
+
+/* General */
+extern VALUE mRubygame;
+extern VALUE eSDLError;
+extern VALUE cSurface;
+extern VALUE cRect;
+extern VALUE mNamedResource;
+
+extern SDL_Rect *make_rect(int, int, int, int);
+extern VALUE make_symbol(char *);
+extern char *unmake_symbol(VALUE);
+extern VALUE sanitized_symbol(char *);
+extern Uint32 collapse_flags(VALUE);
+extern VALUE convert_to_array(VALUE);
+
+extern SDL_Color make_sdl_color(VALUE);
+extern void extract_rgb_u8_as_u8(VALUE, Uint8*, Uint8*, Uint8*);
+extern void extract_rgba_u8_as_u8(VALUE, Uint8*, Uint8*, Uint8*, Uint8*);
+
+extern void rg_deprecated( char *feature, char *version );
+
+/* Properly includes the Rubygame::NamedResource mixin in the klass */
+extern void rg_include_named_resource( VALUE klass );
+
+extern int init_video_system();
+extern void Init_rubygame_shared();
+
+/* Apparently it is not desirable to define these functions when
+ * using Micrsoft Visual C.
+ */
+#ifndef _MSC_VER
+
+static inline int max(int a, int b) {
+	return a > b ? a : b;
+}
+static inline int min(int a, int b) {
+	return a > b ? b : a;
+}
+
+#endif
+
+#endif

data/ext/rubygame/rubygame_sound.c

@@ -0,0 +1,863 @@
+/*
+ *  Interface to SDL_mixer sound playback and mixing.
+ *--
+ *  Rubygame -- Ruby code and bindings to SDL to facilitate game creation
+ *  Copyright (C) 2004-2008  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
+ *++
+ */
+
+#include "SDL_mixer.h"
+#include "rubygame_shared.h"
+#include "rubygame_mixer.h"
+
+VALUE cSound;
+
+/* A pointer to a Mix_Chunk, with a reference count.
+ * Allows re-use of sound data, then freeing memory when
+ * there are no references to it.
+ */
+typedef struct RG_WrapChunk {
+	/* 'private' */
+	Mix_Chunk *chunk;
+	int ref_count;
+} RG_WrapChunk;
+
+
+/* The struct that the Sound class wraps. Stores a 
+ * pointer to a RG_WrapChunk and important attributes
+ * of the Sound like its volume and channel it's
+ * playing on.
+ */
+typedef struct RG_Sound {
+	/* 'public' */
+	float volume;
+
+	/* 'private' */
+	RG_WrapChunk *wrap;
+	int channel;
+} RG_Sound;
+
+
+
+
+/* Allocate/initialize the memory for a RG_WrapChunk and return a pointer. */
+static RG_WrapChunk* _rg_wrapchunk_alloc()
+{
+	RG_WrapChunk *wrap;
+	wrap = ALLOC(RG_WrapChunk);
+
+	wrap->chunk = NULL;
+	wrap->ref_count = 0;
+
+	return wrap;
+}
+
+/* Load a Mix_Chunk from a file and assign it to the RG_WrapChunk. */
+static int _rg_wrapchunk_load( RG_WrapChunk *wrap, char *file )
+{
+	/* Open audio if it's not already. Return -1 if it failed. */
+	if( ensure_open_audio() != 0 )
+	{
+		return -1;
+	}
+
+	wrap->chunk = Mix_LoadWAV( file );
+
+	if( !(wrap->chunk) )
+		return -1;
+	else
+		return 0;
+}
+
+/* Make a copy of the other's Mix_Chunk audio data, and assign
+ * it to the RG_WrapChunk.
+ */
+static void _rg_wrapchunk_deepcopy( RG_WrapChunk *wrap, RG_WrapChunk *other )
+{
+	*(wrap->chunk) = *(other->chunk);
+}
+
+
+/* Free the memory used by the RG_WrapChunk */
+static void _rg_wrapchunk_free( RG_WrapChunk *wrap )
+{
+	Mix_FreeChunk( wrap->chunk );
+	wrap->chunk = NULL;
+	free(wrap);
+}
+
+
+
+
+/* Associate a RG_WrapChunk with a RG_Sound. Handles reference counts. */
+static inline void _rg_sound_associate( RG_Sound *sound, RG_WrapChunk *wrap )
+{
+	sound->wrap = wrap;
+	sound->wrap->ref_count += 1;
+}
+
+/* Deassociate the RG_Sound's WrapChunk. Handles reference counts. */
+static inline void _rg_sound_deassociate( RG_Sound *sound )
+{
+	sound->wrap->ref_count -= 1;
+	sound->wrap = NULL;
+}
+
+/* Allocate/initialize the memory for a RG_Sound return a pointer. */
+static RG_Sound* _rg_sound_alloc()
+{
+	RG_Sound *sound;
+	sound = ALLOC(RG_Sound);
+
+	sound->wrap = NULL;
+	sound->volume = 1.f;
+	sound->channel = -1;
+
+	return sound;
+}
+
+
+/* Free the memory used by the Sound, and possibly the memory
+ * used by the WrapChunk it refers to.
+ */
+static void _rg_sound_free( RG_Sound *sound )
+{
+	RG_WrapChunk *wrap = sound->wrap;
+
+	_rg_sound_deassociate( sound );
+
+	free(sound);
+
+	/* If the WrapChunk has no more referrers, free it too. */
+	if( wrap->ref_count <= 0 )
+	{
+		_rg_wrapchunk_free( wrap );
+	}
+}
+
+
+/* Load a new Sound from a file. */
+static int _rg_sound_load( RG_Sound *sound, char *file )
+{
+	RG_WrapChunk *wrap = _rg_wrapchunk_alloc();
+
+	int result = _rg_wrapchunk_load( wrap, file );
+
+	_rg_sound_associate( sound, wrap );
+
+	return result;
+}
+
+
+/* Make a shallow copy of the given Sound; the new Sound points to
+ * the same audio data in memory as the old one. Also copies
+ * user-visible attributes (e.g. volume).
+ */
+static void _rg_sound_copy( RG_Sound *sound, RG_Sound *other )
+{
+	_rg_sound_associate( sound, other->wrap );
+
+	sound->volume = other->volume;
+	sound->channel = -1;
+}
+
+
+/* Make a new Sound with a copy of the audio from an existing Sound */
+static void _rg_sound_deepcopy( RG_Sound *sound, RG_Sound *other )
+{
+	RG_WrapChunk *wrap = _rg_wrapchunk_alloc();
+	_rg_wrapchunk_deepcopy( wrap, other->wrap );
+
+	_rg_sound_associate( sound, wrap );
+
+	sound->volume = other->volume;
+	sound->channel = -1;
+}
+
+
+/* Check that the given channel is (still) loaded with the given chunk. */
+static int _rg_sound_channel_check( RG_Sound *sound )
+{
+	/* channel is unset, so it doesn't belong. */
+	if( sound->channel == -1 )
+	{
+		return 0;
+	}
+
+	Mix_Chunk *chan_chunk = Mix_GetChunk(sound->channel);	
+
+	/* Check that the channel chunk is the same as the given one */
+	return ( sound->wrap->chunk == chan_chunk );
+}
+
+
+/* Play the sound, fading in, repeating, and stopping as specified.
+ * fade_in and stop_after are in milliseconds!
+ */
+static int _rg_sound_play( RG_Sound *sound, 
+                            int fade_in, int repeats, int stop_after )
+{
+
+	/* Open audio if it's not already. Return -1 if it failed. */
+	if( ensure_open_audio() != 0 )
+	{
+		return -1;
+	}
+
+	/* If it's already playing on a channel, stop it first. */
+	if( _rg_sound_channel_check(sound) )
+	{
+		Mix_HaltChannel( sound->channel );
+	}
+
+	/* Find first available channel */
+	sound->channel = Mix_GroupAvailable(-1);
+
+	if( sound->channel == -1 )
+	{
+		/* No channels were available, so make one more than there are now.
+		 * (Mix_AllocateChannels(-1) returns the current number of channels)
+		 */
+		Mix_AllocateChannels( Mix_AllocateChannels(-1) + 1 );
+
+		/* Try again. */
+		sound->channel = Mix_GroupAvailable(-1);
+	}
+	
+	/* Set its volume before we play */
+	Mix_Volume( sound->channel, (int)(MIX_MAX_VOLUME * sound->volume) );
+
+
+	if( fade_in <= 0 )
+	{
+		/* Play sound without fading in */
+		return Mix_PlayChannelTimed( sound->channel, sound->wrap->chunk,
+		                             repeats, stop_after );
+	}
+	else
+	{
+		/* Play sound with fading in */
+		return Mix_FadeInChannelTimed( sound->channel, sound->wrap->chunk,
+		                               repeats, fade_in, stop_after );
+	}
+}
+
+
+/* Ruby allocation function. */
+static VALUE rg_sound_alloc( VALUE klass )
+{
+	RG_Sound *sound = _rg_sound_alloc();
+	return Data_Wrap_Struct(klass, 0, _rg_sound_free, sound);
+}
+
+
+
+/*
+ *  call-seq:
+ *    load( filename )  ->  sound
+ *
+ *  Load the given audio file.
+ *  Supported file formats are WAV, AIFF, RIFF, OGG (Ogg Vorbis), and
+ *  VOC (SoundBlaster).
+ *
+ *  filename::    Full or relative path to the file. (String, required)
+ *
+ *  Returns::     The new Sound instance. (Sound)
+ *  May raise::   SDLError, if the sound file could not be loaded.
+ *
+ */
+static VALUE rg_sound_load( VALUE klass, VALUE filename )
+{
+	RG_Sound *sound;
+
+	VALUE s = rg_sound_alloc( cSound );
+
+	Data_Get_Struct( s, RG_Sound, sound );
+
+	char *file = StringValuePtr( filename );
+
+	int result = _rg_sound_load( sound, file );
+
+	if( result == -1 )
+	{
+		rb_raise(eSDLError, "Could not load Sound file '%s': %s",
+		                    file, Mix_GetError());
+	}
+
+	return s;
+}
+
+
+/*
+ *  call-seq:
+ *    Sound.autoload( filename )  ->  Surface or nil
+ *
+ *  Searches each directory in Sound.autoload_dirs for a file with
+ *  the given filename. If it finds that file, loads it and returns
+ *  a Sound instance. If it doesn't find the file, returns nil.
+ *
+ *  See Rubygame::NamedResource for more information about this
+ *  functionality.
+ *
+ */
+VALUE rg_sound_autoload( VALUE klass, VALUE namev )
+{
+  VALUE pathv = rb_funcall( klass, rb_intern("find_file"), 1, namev );
+
+  if( RTEST(pathv) )
+  {
+    return rg_sound_load( klass, pathv );
+  }
+  else
+  {
+    return Qnil;
+  }
+}
+
+
+/*
+ *
+ *  call-seq:
+ *    new
+ *
+ *  **NOTE**: Don't use this method. Use Sound.load.
+ *
+ *  This method is not implemented. (In the future, it might be
+ *  used to create a new Sound with blank audio data.)
+ *
+ *  Raises NotImplementedError.
+ *
+ */
+static VALUE rg_sound_new( int argc, VALUE *ARGV, VALUE self )
+{
+	rb_raise(rb_eNotImpError, "Sound.new is not implemented yet. Use Sound.load to load a sound file.");
+}
+
+
+/*
+ *  call-seq:
+ *    clone( other )  ->  sound
+ *    dup( other )  ->  sound
+ *
+ *  Create a copy of the given Sound instance. Much more memory-efficient
+ *  than using #load to load the sound file again.
+ *
+ *  other::       An existing Sound instance. (Sound, required)
+ *
+ *  Returns::     The new Sound instance. (Sound)
+ *
+ *  **NOTE**: #clone and #dup do slightly different things; #clone will copy
+ *  the 'frozen' state of the object, while #dup will create a fresh, un-frozen
+ *  object.
+ *
+ */
+static VALUE rg_sound_initialize_copy( VALUE self, VALUE other )
+{
+	RG_Sound *soundA, *soundB;
+	Data_Get_Struct(self,  RG_Sound, soundA);
+	Data_Get_Struct(other, RG_Sound, soundB);
+
+	_rg_sound_copy( soundA, soundB );
+
+	return self;
+}
+
+
+
+
+/*
+ *  call-seq:
+ *    play( options={} )  ->  self
+ *
+ *  Play the Sound, optionally fading in, repeating a certain number of
+ *  times (or forever), and/or stopping automatically after a certain time.
+ *
+ *  See also #pause and #stop.
+ *
+ *  options::     Hash of options, listed below. (Hash, required)
+ *
+ *    :fade_in::     Fade in from silence over the given number of seconds.
+ *                   (Numeric)
+ *    :repeats::     Repeat the sound the given number of times, or forever
+ *                   (or until stopped) if -1. (Integer)
+ *    :stop_after::  Automatically stop playing after playing for the given
+ *                   number of seconds. (Numeric)
+ *
+ *  Returns::     The receiver (self).
+ *  May raise::   SDLError, if the sound file could not be played.
+ *
+ *	**NOTE**: If the sound is already playing (or paused), it will be stopped
+ *  and played again from the beginning.
+ *
+ *  Example:
+ *    # Fade in over 2 seconds, play 4 times (1 + 3 repeats),
+ *    # but stop playing after 5 seconds.
+ *    sound.play( :fade_in => 2, :repeats => 3, :stop_after => 5 );
+ *
+ */
+static VALUE rg_sound_play( int argc, VALUE *argv, VALUE self )
+{
+	RG_Sound *sound;
+	Data_Get_Struct(self,  RG_Sound, sound);
+
+	VALUE options;
+	rb_scan_args(argc, argv, "01", &options);
+
+	int fade_in    =  0;
+	int repeats    =  0;
+	int stop_after = -1;
+
+	/* If we got some options */
+	if( RTEST(options) )
+	{
+		/* Make sure options is a Hash table */
+		if( TYPE(options) != T_HASH )
+		{
+			rb_raise(rb_eTypeError, "wrong argument type %s (expected Hash)",
+			         rb_obj_classname(options));
+		}
+
+		VALUE temp;
+
+		temp = rb_hash_aref(options, make_symbol("fade_in"));
+		if( RTEST(temp) )
+		{
+			fade_in = (int)(1000 * NUM2DBL( temp ));
+		}
+
+		temp = rb_hash_aref(options, make_symbol("repeats"));
+		if( RTEST(temp) )
+		{
+			repeats = NUM2INT(temp);
+		}
+
+		temp = rb_hash_aref(options, make_symbol("stop_after"));
+		if( RTEST(temp) )
+		{
+			stop_after = (int)(1000 * NUM2DBL( temp ));
+		}
+
+	}
+
+	int result = _rg_sound_play( sound, fade_in, repeats, stop_after );
+
+	if( result == -1 )
+	{
+		rb_raise(eSDLError, "Could not play Sound: %s", Mix_GetError());
+	}
+
+	return self;
+}
+
+
+/*
+ *  call-seq:
+ *    playing?  ->  true or false
+ *
+ *  True if the Sound is currently playing (not paused or stopped).
+ *  See also #paused? and #stopped?.
+ *
+ */
+static VALUE rg_sound_playingp( VALUE self )
+{
+	RG_Sound *sound;
+	Data_Get_Struct(self,  RG_Sound, sound);
+
+	int channel = sound->channel;
+
+	/* Make sure the sound actually belongs to the channel */
+	if( _rg_sound_channel_check(sound) )
+	{
+		/* Return true if it's playing, but not paused. */
+		if( Mix_Playing(channel) && !Mix_Paused(channel) )
+		{
+			return Qtrue;
+		}
+		else
+		{
+			return Qfalse;
+		}
+	}
+	else
+	{
+		return Qfalse;
+	}
+}
+
+
+
+/*
+ *  call-seq:
+ *    pause  ->  self
+ *
+ *  Pause the Sound. Unlike #stop, it can be unpaused later to resume
+ *  from where it was paused. See also #unpause and #paused?.
+ *
+ *  Returns::     The receiver (self).
+ *
+ *  **NOTE**: Does nothing if the sound is not currently playing.
+ *
+ */
+static VALUE rg_sound_pause( VALUE self )
+{
+	RG_Sound *sound;
+	Data_Get_Struct(self,  RG_Sound, sound);
+
+	int channel = sound->channel;
+
+	/* Make sure the sound actually belongs to the channel */
+	if( _rg_sound_channel_check(sound) )
+	{
+		Mix_Pause( channel );
+	}
+
+	return self;
+}
+
+
+/*
+ *  call-seq:
+ *    unpause  ->  self
+ *
+ *  Unpause the Sound, if it is currently paused. Resumes from
+ *  where it was paused. See also #pause and #paused?.
+ *
+ *  Returns::     The receiver (self).
+ *
+ *  **NOTE**: Does nothing if the sound is not currently paused.
+ *
+ */
+static VALUE rg_sound_unpause( VALUE self )
+{
+	RG_Sound *sound;
+	Data_Get_Struct(self,  RG_Sound, sound);
+
+	int channel = sound->channel;
+
+	/* Make sure the sound actually belongs to the channel */
+	if( _rg_sound_channel_check(sound) )
+	{
+		Mix_Resume( channel );
+	}
+
+	return self;
+}
+
+
+/*
+ *  call-seq:
+ *    paused?  ->  true or false
+ *
+ *  True if the Sound is currently paused (not playing or stopped).
+ *  See also #playing? and #stopped?.
+ *
+ */
+static VALUE rg_sound_pausedp( VALUE self )
+{
+	RG_Sound *sound;
+	Data_Get_Struct(self,  RG_Sound, sound);
+
+	int channel = sound->channel;
+
+	/* Make sure the sound actually belongs to the channel */
+	if( _rg_sound_channel_check(sound) )
+	{
+		/* Return true if it's "playing" (not stopped), as well as paused. */
+		if( Mix_Playing(channel) && Mix_Paused(channel) )
+		{
+			return Qtrue;
+		}
+		else
+		{
+			return Qfalse;
+		}
+	}
+	else
+	{
+		return Qfalse;
+	}
+}
+
+
+
+/*
+ *  call-seq:
+ *    stop  ->  self
+ *
+ *  Stop the Sound. Unlike #pause, the sound must be played again from
+ *  the beginning, it cannot be resumed from it was stopped.
+ *
+ *  Returns::     The receiver (self).
+ *
+ *  **NOTE**: Does nothing if the sound is not currently playing or paused.
+ *
+ */
+static VALUE rg_sound_stop( VALUE self )
+{
+	RG_Sound *sound;
+	Data_Get_Struct(self,  RG_Sound, sound);
+
+	int channel = sound->channel;
+
+	/* Make sure the sound actually belongs to the channel */
+	if( _rg_sound_channel_check(sound) )
+	{
+		Mix_HaltChannel( channel );
+	}
+
+	return self;
+}
+
+
+/*
+ *  call-seq:
+ *    stopped?  ->  true or false
+ *
+ *  True if the Sound is currently stopped (not playing or paused).
+ *  See also #playing? and #paused?.
+ *
+ */
+static VALUE rg_sound_stoppedp( VALUE self )
+{
+	RG_Sound *sound;
+	Data_Get_Struct(self,  RG_Sound, sound);
+
+	int channel = sound->channel;
+
+	/* Make sure the sound actually belongs to the channel */
+	if( _rg_sound_channel_check(sound) )
+	{
+		/* Return true if it's not playing. */
+		if( !Mix_Playing(channel) )
+		{
+			return Qtrue;
+		}
+		else
+		{
+			return Qfalse;
+		}
+	}
+	else
+	{
+		/* If it's not on a channel... it can't be playing! */
+		return Qtrue;
+	}
+}
+
+
+/*
+ *  call-seq:
+ *    fade_out( fade_time )  ->  self
+ *
+ *  Fade out to silence over the given number of seconds. Once the sound
+ *  is silent, it is automatically stopped.
+ *
+ *  Returns::     The receiver (self).
+ *
+ *  **NOTE**: If the sound is currently paused, the fade will start,
+ *  but you won't be able to hear it happening unless you #unpause during
+ *  the fade. Does nothing if the sound is currently stopped.
+ *
+ */
+static VALUE rg_sound_fadeout( VALUE self, VALUE fade_time )
+{
+	RG_Sound *sound;
+	Data_Get_Struct(self,  RG_Sound, sound);
+
+	int channel = sound->channel;
+	int fade_ms = (int)(1000 * NUM2DBL(fade_time));
+
+	/* Make sure the sound actually belongs to the channel */
+	if( _rg_sound_channel_check(sound) )
+	{
+		Mix_FadeOutChannel( channel, fade_ms );
+	}
+
+	return self;
+}
+
+
+/*
+ *  call-seq:
+ *    fading?( direction=:either )  ->  true or false
+ *
+ *  True if the Sound is currently fading in or out.
+ *  See also #play and #fade_out.
+ *
+ *  direction::  Check if it is fading :in, :out, or :either.
+ *               (Symbol, required)
+ *
+ */
+static VALUE rg_sound_fadingp( int argc, VALUE *argv, VALUE self )
+{
+	RG_Sound *sound;
+	Data_Get_Struct(self,  RG_Sound, sound);
+
+	VALUE vdirection;
+	rb_scan_args(argc, argv, "01", &vdirection);
+	
+	int direction;
+	int channel = sound->channel;
+
+	/* If it's not actually on a channel, return false right away. */
+	if( !(_rg_sound_channel_check(sound)) )
+	{
+		return Qfalse;
+	}
+
+	if( RTEST(vdirection) )
+	{
+		if( make_symbol("in") == vdirection )
+		{
+			return ( (Mix_FadingChannel(channel) == MIX_FADING_IN)  ? Qtrue : Qfalse );
+		}
+		
+		else if( make_symbol("out") == vdirection )
+		{
+			return ( (Mix_FadingChannel(channel) == MIX_FADING_OUT) ? Qtrue : Qfalse );
+		}
+		
+		else if( make_symbol("either") == vdirection )
+		{
+			return ( (Mix_FadingChannel(channel) != MIX_NO_FADING)  ? Qtrue : Qfalse );
+		}
+	}
+
+	/* default */
+	return ( (Mix_FadingChannel(channel) != MIX_NO_FADING)  ? Qtrue : Qfalse );
+}
+
+
+
+/*
+ *  call-seq:
+ *    volume  -> vol
+ *
+ *  Return the volume level of the sound.
+ *  0.0 is totally silent, 1.0 is full volume.
+ *
+ *  **NOTE**: Ignores fading in or out.
+ *	
+ */
+static VALUE rg_sound_getvolume( VALUE self )
+{
+	RG_Sound *sound;
+	Data_Get_Struct(self,  RG_Sound, sound);
+
+	return rb_float_new(sound->volume);
+}
+
+
+/*
+ *  call-seq:
+ *    volume = new_vol
+ *
+ *  Set the new #volume level of the sound.
+ *  0.0 is totally silent, 1.0 is full volume.
+ * 
+ *  Volume cannot be set while the sound is fading in or out.
+ *  Be sure to check #fading? or rescue from SDLError when
+ *  using this method.
+ *
+ *  May raise::  SDLError if the sound is fading in or out.
+ *	
+ */
+static VALUE rg_sound_setvolume( VALUE self, VALUE volume )
+{
+	RG_Sound *sound;
+	Data_Get_Struct(self,  RG_Sound, sound);
+
+	/* Change channel volume if Sound is currently assigned to a channel */
+	if( _rg_sound_channel_check(sound) )
+	{
+		/* But only if it's not fading right now. */
+		if( Mix_FadingChannel(sound->channel) == MIX_NO_FADING )
+		{
+			sound->volume = NUM2DBL(volume);
+			Mix_Volume( sound->channel, (int)(MIX_MAX_VOLUME * sound->volume) );
+		}
+		else
+		{
+			rb_raise(eSDLError, "cannot set Sound volume while fading");
+		}
+	}
+	else
+	{
+		/* Save it for later. */
+		sound->volume = NUM2DBL(volume);
+	}
+
+	return volume;
+}
+
+
+void Rubygame_Init_Sound()
+{
+#if 0
+  mRubygame = rb_define_module("Rubygame");
+#endif
+
+	/*
+	 *  **IMPORTANT**: Sound is only available if Rubygame was compiled
+	 *  with SDL_mixer support!
+	 *
+	 *  Sound holds a sound effect, loaded from an audio file (see #load for
+	 *  supported formats).
+	 *
+	 *  Sound can #play, #pause/#unpause, #stop, adjust #volume,
+	 *  and #fade_out (you can fade in by passing an option to #play).
+	 *
+	 *  Sound can create duplicates (with #dup or #clone) in a memory-efficient
+	 *  way -- the new Sound instance refers back to the same audio data,
+	 *  so having 100 duplicates of a sound uses only slightly more memory
+	 *  than having the first sound. Duplicates can different volume levels,
+	 *  too!
+	 *
+   *  Sound includes the Rubygame::NamedResource mixin module, which
+   *  can perform autoloading of sounds on demand, among other things.
+   *
+	 */
+  cSound = rb_define_class_under(mRubygame,"Sound",rb_cObject);
+
+	/* Include the Rubygame::NamedResource mixin module. */
+	rg_include_named_resource(cSound);
+
+	rb_define_alloc_func( cSound, rg_sound_alloc );
+
+	rb_define_singleton_method( cSound, "new",  rg_sound_new,  -1 );
+	rb_define_singleton_method( cSound, "load", rg_sound_load,  1 );
+
+	rb_define_singleton_method( cSound, "autoload", rg_sound_autoload,  1 );
+
+	rb_define_method( cSound, "initialize_copy", rg_sound_initialize_copy,  1 );
+
+	rb_define_method( cSound, "play",            rg_sound_play,            -1 );
+	rb_define_method( cSound, "playing?",        rg_sound_playingp,         0 );
+
+	rb_define_method( cSound, "pause",           rg_sound_pause,            0 );
+	rb_define_method( cSound, "unpause",         rg_sound_unpause,          0 );
+	rb_define_method( cSound, "paused?",         rg_sound_pausedp,          0 );
+
+	rb_define_method( cSound, "stop",            rg_sound_stop,             0 );
+	rb_define_method( cSound, "stopped?",        rg_sound_stoppedp,         0 );
+
+	rb_define_method( cSound, "fade_out",        rg_sound_fadeout,          1 );
+	rb_define_method( cSound, "fading?",         rg_sound_fadingp,         -1 );
+
+	rb_define_method( cSound, "volume",          rg_sound_getvolume,        0 );
+	rb_define_method( cSound, "volume=",         rg_sound_setvolume,        1 );
+}