rubygame 2.5.3 → 2.6.0

data/doc/windows_install.rdoc

@@ -1,123 +1,51 @@
-= Compiling Rubygame on Windows
+Note: You can view the latest version of this guide online at the
+Rubygame wiki: http://rubygame.org/wiki/Windows_Installation_Guide
 
-(For the most up-to-date version of this document, see the Rubygame wiki:
-http://rubygame.wiki.sourceforge.net/win32_compile)
+== Gather Dependencies
 
-This document gives some helpful guidelines to for compiling and installing
-Rubygame on Microsoft Windows. However, these instructions are not perfect,
-so they might not work for you. If you use this guide, we'd love to hear about
-what worked and what didn't; just send a message to the {rubygame-users mailing
-list}[https://sourceforge.net/mail/?group_id=172781]!
+* {Ruby}[http://www.ruby-lang.org/en/downloads/], the language itself.
+  The easiest option here is the one-click installer. This will
+  install Ruby and a number of useful libraries without any hassle.
 
-The usual caveats apply: follow these instructions at your own risk and so
-forth.  Please direct comments or questions to the {Rubygame user's mailing
-list}[http://sourceforge.net/mail/?group_id=172781].
+* {SDL}[http://www.libsdl.org/download-1.2.php].
+  Download the Win32 binary package, e.g. "SDL-1.2.14-win32.zip".
 
-== Step 1: Gather Dependencies
+The rest are optional dependencies, but highly recommended. If you
+don't have them, you won't be able to use certain features of
+Rubygame.
 
-- You'll need a build environment for Windows. In this guide, we'll use 
-  {MinGW}[http://www.mingw.org/MinGWiki/index.php/GettingStarted].  
-  - Grab MinGW-NNN.exe (e.g. MinGW-5.12.exe) from the {downloads page}[http://sourceforge.net/project/showfiles.php?group_id=2435&package_id=82721]
-    and install it. (Note: you might need to expand the "MinGW" section to see
-    the MinGW-NNN.exe files.)
-  - Optional, but recommended: install MSYS-NNNN.exe (e.g. MSYS-1.0.10.exe)
-    from the same page as above. (You might have to expand the MSYS section.)
-  - Add the full path to the compiler executible to your system PATH if it 
-    isn't there already.  You should be able to type <code>gcc -v</code> at a
-    command line and see a version number.
+* {SDL_image}[http://www.libsdl.org/projects/SDL_image/].
+  Grab the Win32 binary package, e.g. "SDL_image-1.2.8-win32.zip".
 
-- {Download Ruby}[http://www.ruby-lang.org/en/downloads/], the language itself.
-  The easiest option here is the one-click installer.  This will install
-  Ruby and a number of useful libraries without any hassle.
+* {SDL_mixer}[http://www.libsdl.org/projects/SDL_mixer/].
+  Just like before, grab the Win32 binary package, e.g.
+  "SDL_mixer-1.2.9-win32.zip".
 
-- {SDL}[http://www.libsdl.org/download-1.2.php]. In the <b>Development 
-  Libraries</b> section (near the bottom of the page), grab the 
-  SDL-devel-1.2.??-VC6.zip file. (The VC6 package is just fine, even though
-  we're using with MinGW to compile.)
+* {SDL_ttf}[http://www.libsdl.org/projects/SDL_ttf/].
+  Again, get the Win32 binary package, e.g. "SDL_ttf-2.0.9-win32.zip".
 
-The rest are optional dependencies, but highly recommended. If you don't have
-them, you won't be able to use certain features of Rubygame.
+* {SDL_gfx}[http://www.ferzkopp.net/joomla/content/view/19/14/]
+  ({compiled version}[http://download.rubygame.org/files/extras/]).
+  Many thanks to a generous Rubygame user (bmatthew1) for providing a
+  compiled Windows DLL for SDL_gfx!
 
-- {SDL_image}[http://www.libsdl.org/projects/SDL_image/]. Grab the Win32 
-  binary package with 'devel' in the name.
-- {SDL_mixer}[http://www.libsdl.org/projects/SDL_mixer/]. Just like before,
-  grab the Win32 binary package with 'devel' in the name.
-- {SDL_ttf}[http://www.libsdl.org/projects/SDL_ttf/]. Again, get the
-  Win32 binary package with 'devel' in the name
-- {SDL_gfx}[http://www.ferzkopp.net/joomla/content/view/19/14/].  This is
-  the trickiest dependency, because there is currently no official package for
-  a precompiled version of SDL_gfx. If you are able to compile this yourself,
-  great! Otherwise, some nice features of Rubygame have to be disabled;
-  make sure you add the --no-gfx flag when you get to the "Set up environment
-  variables" section, below.
+Once you have downloaded everything, unzip them and copy the *.dll
+files into the <code>C:\windows\system32\</code> directory. This will
+allow the libraries to be detected and loaded by Rubygame.
 
-Once you have downloaded everything, extract each archive into a convenient
-location on your hard drive.  You'll thank yourself later if you use a short
-path with no spaces in it.  For this example, we'll unzip everything under 
-<code>C:\\src\\</code>.
+== Install Rubygame
 
-Next, copy the *.dll file from each library's folder into 
-<code>C:\\windows\\system32\\</code>.
-This will allow the libraries to be detected properly later on.
+The simplest way to install Rubygame is: <code>gem install rubygame</code>
 
-== Step 2: Get Rubygame
+Or you can {download the source from
+Github}[http://github.com/jacius/rubygame/] and follow the
+installation instructions in README.
 
-If you haven't already, download the latest Rubygame source from the 
-{download page}[http://rubyforge.org/frs/?group_id=5089]. 
-If you're feeling adventurous, you could try the in-development code from
-the {Git repository}[http://github.com/jacius/rubygame].  
-You can decompress the .tar.bz2 file with either MSYS' <code>tar</code>
-(<code>tar xvjf rubygame-2.0.0.tar.bz2</code>) or a program like 
-{7zip}[http://www.7-zip.org].
+== Conclusion
 
-Extract the source into another folder of your choice, such as 
-<code>C:\\src\\rubygame</code>.
+If all goes well, you have successfully installed Rubygame. Try to
+execute <code>require 'rubygame'</code> in an irb session and run the
+provided samples to ensure that everything is acceptable.
 
-== Step 3: Set up environment variables
-
-Environment variables are used to configure the build process for your
-system; it helps the compiler to locate the headers and libraries it needs to
-compile Rubygame. 
-
-Create a text file in your Rubygame directory called "envsetup.bat".
-In it, use code based on the following to set your variables.
-Be sure to replace '\src\' (lines 3-7) with the path to where you unpacked
-the libraries.
-
- set CC=gcc
- set CFLAGS=-DHAVE_ISINF -D_MSC_VER=1200 
- set CFLAGS=%CFLAGS% -I \src\SDL-1.2.11\include
- set CFLAGS=%CFLAGS% -I \src\SDL_gfx-2.0.15
- set CFLAGS=%CFLAGS% -I \src\SDL_image-1.2.5\include
- set CFLAGS=%CFLAGS% -I \src\SDL_mixer-1.2.7\include
- set CFLAGS=%CFLAGS% -I \src\SDL_ttf-2.0.8\include
- 
- set LDSHARED=gcc -shared
- set LINK_FLAGS=-L \windows\system32 -lSDL
- set LIBRUBYARG_SHARED=-L \ruby\bin -lmsvcrt-ruby18
-
-The -L parameter for LIBRUBYARG_SHARED may be different if you installed
-Ruby to a path other than C:/ruby.
-
-== Step 4: Compile and install Rubygame
-
-Open a command prompt and navigate to the root of your Rubygame source
-directory.  Type:
-
- envsetup.bat
- rake install
-
-IMPORTANT: If you are missing an optional library (such as SDL_gfx), you must
-disable optional features by passing a "no-???" command to rake before the word
-"install". For example, to disable features that depend on SDL_gfx, you would
-type this instead of the above:
-
- envsetup.bat
- rake no-sdl-gfx install
-
-If all goes well, you have built and installed Rubygame.
-Try to execute <code>require 'rubygame'</code> in an irb session and run
-the provided samples to ensure that everything is acceptable.
-
-(Thanks to Ash Wilson (smashwilson) for contributing the original version of 
-these instructions.)
+If you have any trouble installing Rubygame, please post in the
+{forums}[http://rubygame.org/forums/].

data/lib/rubygame.rb

@@ -19,38 +19,76 @@
 #
 #++
 
-# This file is loaded when you "require 'rubygame'".
-# It loads up the compiled C extensions and the rest of
-# the Rubygame library modules.
 
+this_dir = File.expand_path( File.dirname(__FILE__) )
 
-# Prefer local library over global installed version.
-$:.unshift( File.join( File.dirname(__FILE__), "..", "lib" ) )
-$:.unshift( File.join( File.dirname(__FILE__), "..", "ext", "rubygame" ) )
+
+# Require Rubygame files. If these fail, don't rescue.
+# Note: screen.rb is intentionally loaded late.
+%w{ main
+    shared
+    audio
+    clock
+    constants
+    color
+    event
+    events
+    event_handler
+    gl
+    joystick
+    named_resource
+    queue
+    rect
+    surface
+    sprite
+}.each do |f|
+  require File.join( this_dir, "rubygame", f )
+end
+
+
+# SDL_gfx is optional, rescue if it fails.
+begin
+  require File.join( this_dir, "rubygame", "gfx" )
+rescue LoadError => e
+  puts( "Warning: Could not load SDL_gfx! " +
+        "Continuing anyway, but some Surface methods will be missing.\n" +
+        "Error message was: #{e.message.inspect}" )
+end
 
 
-require "rbconfig"
+# SDL_image is optional, rescue if it fails.
+begin
+  require File.join( this_dir, "rubygame", "image" )
+rescue LoadError => e
+  puts( "Warning: Could not load SDL_image! " +
+        "Continuing anyway, but image loading will be missing.\n" +
+        "Error message was: #{e.message.inspect}" )
+end
+
+
+# SDL_mixer is optional, rescue if it fails.
+begin
+  require File.join( this_dir, "rubygame", "mixer" )
+rescue LoadError => e
+  puts( "Warning: Could not load SDL_mixer! " +
+        "Continuing anyway, but audio features will be missing.\n" +
+        "Error message was: #{e.message.inspect}" )
+end
 
-require "rubygame_core"
 
-%W{ rubygame_gfx rubygame_image rubygame_ttf rubygame_mixer }.each do |mod|
-  begin
-    require mod
-  rescue LoadError
-    warn( "Warning: Unable to require optional module: #{mod}.") if $VERBOSE
-  end
+# SDL_ttf is optional, rescue if it fails.
+begin
+  require File.join( this_dir, "rubygame", "ttf" )
+rescue LoadError => e
+  puts( "Warning: Could not load SDL_ttf! " +
+        "Continuing anyway, but the TTF class will be missing.\n" +
+        "Error message was: #{e.message.inspect}" )
 end
 
-require "rubygame/shared"
 
-require "rubygame/color"
-require "rubygame/constants"
+# Loaded late so Screen can undefine some inherited Surface methods.
+require File.join( this_dir, "rubygame", "screen" )
 
-require "rubygame/event"
-require "rubygame/events"
-require "rubygame/queue"
-require "rubygame/event_handler"
 
-require "rubygame/rect"
-require "rubygame/sprite"
-require "rubygame/clock"
+Rubygame.init
+at_exit { Rubygame.quit }

data/lib/rubygame/audio.rb

@@ -0,0 +1,147 @@
+#--
+#	Rubygame -- Ruby code and bindings to SDL to facilitate game creation
+#	Copyright (C) 2004-2009  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
+
+  # call-seq:
+  #   open_audio( options={:buffer=>1024, :channels=>2, :frequency=>22050} )
+  #
+  # Initializes the audio device using the given settings.
+  #
+  # NOTE: Audio will be automatically opened when Rubygame::Sound or
+  # Rubygame::Music are first used. You only need to open audio
+  # manually if you want settings different from the default, or if
+  # you are using the older, deprecated Music and Sample classes from
+  # the Rubygame::Mixer module.
+  #
+  # If audio is already open, this method has no effect, and returns false.
+  # If you want to change audio settings, you must #close_audio() and
+  # then open it again.
+  #
+  # options::    A Hash of any of the following options. (Hash, optional)
+  #
+  #    :frequency::  output sample rate in audio samples per second
+  #                  (Hz). Affects the quality of the sound output, at
+  #                  the expense of CPU usage. If omitted, the default
+  #                  (22050) is used. The default is recommended for
+  #                  most games.
+  #
+  #    :channels::   output sound channels. Use 2 for stereo, 1 for mono.
+  #                  If omitted, the default (2) is used.
+  #
+  #    :buffer::     size of the sound buffer, in bytes. Must be a
+  #                  power of 2 (e.g. 512, 1024, 2048). If omitted,
+  #                  the default (1024) is used. If your game is
+  #                  fast-paced, you may want to use a smaller value
+  #                  to reduce audio delay, the time between when you
+  #                  play a sound and when it is heard.
+  #
+  # Returns::    true if the audio was newly opened by this action, or
+  #              false if it was already open before this action.
+  #
+  # May raise::  SDLError, if initialization fails.
+  #              ArgumentError, if an invalid value is given for any option.
+  #
+  def self.open_audio( options={} )
+    return false if audio_open?
+
+    unless options.kind_of? Hash
+      raise TypeError, "invalid options Hash: #{options.inspect}"
+    end
+
+    buff = (options[:buffer] or 1024)
+    chan = (options[:channels] or 2)
+    freq = (options[:frequency] or SDL::Mixer::DEFAULT_FREQUENCY)
+
+    # In general, format should always be the default.
+    frmt = SDL::Mixer::DEFAULT_FORMAT
+
+
+    buff = if( buff <= 0 )
+             raise ArgumentError, "buffer size must be positive (got #{buff})"
+           elsif( buff & (buff - 1) != 0 )
+             raise( ArgumentError, "buffer size must be a power of 2 "+
+                    "(e.g. 512, 1024) (got #{buff})" )
+           else
+             buff.to_i
+           end
+
+
+    chan = if( chan != 1 && chan != 2 )
+             raise( ArgumentError, 
+                    "channels must be 1 (mono) or 2 (stereo) (got #{chan})" )
+           else
+             chan.to_i
+           end
+
+
+    freq = if( freq <= 0 )
+             raise ArgumentError, "frequency must be positive (got #{freq})"
+           else
+             freq.to_i
+           end
+
+    result = SDL::Mixer.OpenAudio(freq, frmt, chan, buff)
+
+    if( result < 0 )
+      raise Rubygame::SDLError, "Could not open audio: #{SDL.GetError()}"
+    end
+
+    return true
+  end
+
+
+
+  # Deinitializes and closes the audio device. If audio was not open,
+  # this method does nothing, and returns false. See also #open_audio().
+  # 
+  # NOTE: The audio will be automatically closed when the program
+  # exits. You only need to close audio manually if you want to
+  # call #open_audio with different settings.
+  # 
+  # Returns::  true if the audio was open before this action.
+  #
+  def self.close_audio
+    if audio_open?
+      SDL::Mixer.CloseAudio()
+      return true
+    else
+      return false
+    end
+  end
+
+
+  def self.audio_open?          # :nodoc:
+    SDL::Mixer.QuerySpec(nil,nil,nil) > 0
+  end
+
+
+  # Returns the name of the audio driver that SDL is using.
+  # This method opens the audio device if it is not open already.
+  #
+  # May raise an SDLError if the audio device could not be opened.
+  #
+  def self.audio_driver
+    open_audio
+    return SDL.AudioDriverName
+  end
+
+end

data/lib/rubygame/clock.rb

@@ -20,7 +20,8 @@
 #++
 
 
-require "rubygame/events/clock_events"
+
+require( File.join( File.dirname(__FILE__), "events", "clock_events" ) )
 
 
 module Rubygame
@@ -41,6 +42,168 @@ module Rubygame
   # 
   class Clock
 
+    class << self
+
+      # time::  The target delay time, in milliseconds.
+      #         (Non-negative integer. Required.)
+      # gran::  The assumed granularity (in ms) of the system clock.
+      #         (Non-negative integer. Optional. Default: 12.)
+      # nice::  If true, try to let other ruby threads run during the delay.
+      #         (true or false. Optional. Default: false.)
+      #
+      # Returns:: The actual delay time, in milliseconds.
+      #
+      # Pause the program for +time+ milliseconds. This function is more
+      # accurate than Clock.wait, but uses slightly more CPU time. Both
+      # this function and Clock.wait can be used to slow down the
+      # framerate so that the application doesn't use too much CPU time.
+      # See also Clock#tick for a good and easy way to limit the
+      # framerate.
+      #
+      # This function uses "busy waiting" during the last part
+      # of the delay, for increased accuracy. The value of +gran+ affects
+      # how many milliseconds of the delay are spent in busy waiting, and thus
+      # how much CPU it uses. A smaller +gran+ value uses less CPU, but if
+      # it's smaller than the true system granularity, this function may
+      # delay a few milliseconds too long. The default value (12ms) is very
+      # safe, but a value of approximately 5ms would give a better balance
+      # between accuracy and CPU usage on most modern computers.
+      # A granularity of 0ms makes this method act the same as Clock.wait
+      # (i.e. no busy waiting at all, very low CPU usage).
+      #
+      # If +nice+ is true, this function will try to allow other ruby
+      # threads to run during this function. Otherwise, other ruby threads
+      # will probably also be paused. Setting +nice+ to true is only
+      # useful if your application is multithreaded. It's safe (but
+      # pointless) to use this feature for single threaded applications.
+      #
+      # The Rubygame timer system will be initialized when you call this
+      # function, if it has not been already. See Clock.runtime.
+      #
+      def delay( time, gran=12, nice=false )
+        _init_sdl_timer
+        time = 0 if time < 0
+        gran = 0 if gran < 0
+        _accurate_delay( time, gran, nice )
+      end
+
+
+      # time::  The target wait time, in milliseconds.
+      #         (Non-negative Integer. Required.)
+      # nice::  If true, try to let other ruby threads run during the delay.
+      #         (true or false. Optional.)
+      #
+      # Returns:: The actual wait time, in milliseconds.
+      #
+      # Pause the program for approximately +time+ milliseconds. Both this
+      # function and Clock.delay can be used to slow down the framerate so
+      # that the application doesn't use too much CPU time. See also
+      # Clock#tick for a good and easy way to limit the framerate.
+      #
+      # The accuracy of this function depends on processor scheduling,
+      # which varies with operating system and hardware. The actual delay
+      # time may be up to 10ms longer than +time+. If you need more
+      # accuracy use Clock.delay, which is more accurate but uses slightly
+      # more CPU time.
+      #
+      # If +nice+ is true, this function will try to allow other ruby
+      # threads to run during this function. Otherwise, other ruby threads
+      # will probably also be paused. Setting +nice+ to true is only
+      # useful if your application is multithreaded. It's safe (but
+      # pointless) to use this feature for single threaded applications.
+      #
+      # The Rubygame timer system will be initialized when you call this
+      # function, if it has not been already. See Clock.runtime.
+      #
+      def wait( time, nice=false )
+        _init_sdl_timer
+        time = 0 if time < 0
+        _threaded_delay( time, nice )
+      end
+
+
+      # Return the number of milliseconds since the Rubygame timer
+      # system was initialized.
+      #
+      # The Rubygame timer system will be initialized when you call
+      # this function, if it has not been already.
+      #
+      def runtime
+        SDL.GetTicks().to_i
+      end
+
+
+
+      private
+
+
+      # Initialize the SDL timer system, if it hasn't been already.
+      def _init_sdl_timer
+        if( SDL.WasInit( SDL::INIT_TIMER ) == 0 )
+          if( SDL.InitSubSystem( SDL::INIT_TIMER ) != 0)
+            raise( Rubygame::SDLError,
+                   "Could not initialize timer system: #{SDL.GetError()}" )
+          end
+        end
+      end
+
+
+      # Delays for the given amount of time, but possibly split into
+      # small parts. Control is given to ruby between each part, so
+      # that other threads can run.
+      #
+      # delay: How many milliseconds to delay.
+      # nice:  If true, split the delay into smaller parts and
+      #        allow other ruby threads to run between each part.
+      #
+      def _threaded_delay( delay, nice )
+        start = SDL.GetTicks()
+        stop = start + delay
+
+        if nice
+          while( SDL.GetTicks() < stop )
+            SDL.Delay(1)
+          end
+        else
+          SDL.Delay( delay.to_i )
+        end
+
+        return (SDL.GetTicks() - start).to_i
+      end
+
+
+      # Based on pygame code, with a few modifications:
+      #   - takes 'accuracy' argument
+      #   - ruby syntax for raising exceptions
+      #   - uses rg_threaded_delay
+      #
+      def _accurate_delay( ticks, accuracy, nice )
+        return _threaded_delay( ticks, nice ) if( accuracy <= 0 )
+
+        start = SDL.GetTicks()
+
+        if( ticks >= accuracy )
+          delay = ticks - (ticks % accuracy)
+          delay -= 2  # Aim low so we don't overshoot.
+
+          if( delay >= accuracy and delay > 0 )
+            _threaded_delay( delay, nice )
+          end
+        end
+
+        delay = ticks - (SDL.GetTicks() - start)
+        while( delay > 0 )
+          delay = ticks - (SDL.GetTicks() - start)
+        end
+
+        return (SDL.GetTicks() - start).to_i
+      end
+
+    end
+
+
+
+
     # The runtime when the Clock was initialized.
     attr_reader :start