rubygame 2.4.1 → 2.5.0

data/ext/rubygame/{rubygame_time.h → rubygame_clock.h}

@@ -1,6 +1,6 @@
 /*
  * Rubygame -- Ruby code and bindings to SDL to facilitate game creation
- * Copyright (C) 2004-2007  John Croisant
+ * 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
@@ -18,15 +18,15 @@
  *
  */
 
-#ifndef _RUBYGAME_TIME_H
-#define _RUBYGAME_TIME_H
+#ifndef _RUBYGAME_CLOCK_H
+#define _RUBYGAME_CLOCK_H
 
-extern void Rubygame_Init_Time();
+extern void Rubygame_Init_Clock();
 
 extern VALUE cClock;
 
-extern VALUE rbgm_time_wait(VALUE, VALUE);
-extern VALUE rbgm_time_delay(int, VALUE*, VALUE);
-extern VALUE rbgm_time_getticks(VALUE);
+extern VALUE rbgm_clock_wait(int, VALUE*, VALUE);
+extern VALUE rbgm_clock_delay(int, VALUE*, VALUE);
+extern VALUE rbgm_clock_runtime(VALUE);
 
 #endif

data/ext/rubygame/rubygame_main.c

@@ -27,7 +27,7 @@
 #include "rubygame_joystick.h"
 #include "rubygame_screen.h"
 #include "rubygame_surface.h"
-#include "rubygame_time.h"
+#include "rubygame_clock.h"
 
 VALUE rbgm_init(VALUE);
 VALUE rbgm_quit(VALUE);
@@ -127,7 +127,7 @@ void Init_rubygame_core()
                            INT2NUM(SDL_MINOR_VERSION),
                            INT2NUM(SDL_PATCHLEVEL)));
 
-	Rubygame_Init_Time();
+	Rubygame_Init_Clock();
 	Rubygame_Init_Surface();
 	Rubygame_Init_Screen();
 	Rubygame_Init_Event();

data/ext/rubygame/rubygame_screen.c

@@ -32,6 +32,8 @@ VALUE cScreen;
 VALUE rbgm_screen_setmode(int, VALUE*, VALUE);
 VALUE rbgm_screen_getsurface(VALUE);
 
+VALUE rbgm_screen_getresolution(VALUE);
+
 VALUE rbgm_screen_getcaption(VALUE);
 VALUE rbgm_screen_setcaption(VALUE, VALUE);
 
@@ -46,8 +48,8 @@ VALUE rbgm_screen_setshowcursor(VALUE, VALUE);
 
 
 /* call-seq:
- *     new(size, depth=0, flags=[SWSURFACE])  ->  Screen
- *     (aliases: set_mode, instance)
+ *     Screen.new( size, depth=0, flags=[SWSURFACE] )  ->  Screen
+ *     (alias: open)
  *
  *  Create a new Rubygame window if there is none, or modify the existing one.
  *  You cannot create more than one Screen; the existing one will be replaced.
@@ -94,13 +96,13 @@ VALUE rbgm_screen_setshowcursor(VALUE, VALUE);
  *                       OpenGL functions.
  *          RESIZABLE::  Create a resizable window. When the window is 
  *                       resized by the user, a ResizeEvent is
- *                       generated and #set_mode can be called again
+ *                       generated and this method can be called again
  *                       with the new size.
  *          NOFRAME::    If possible, create a window with no title bar or
  *                       frame decoration.
  *                       Fullscreen modes automatically have this flag set.
  */
-VALUE rbgm_screen_setmode(int argc, VALUE *argv, VALUE module)
+VALUE rbgm_screen_new(int argc, VALUE *argv, VALUE module)
 {
   SDL_Surface *screen;
   int w, h, depth;
@@ -133,8 +135,73 @@ VALUE rbgm_screen_setmode(int argc, VALUE *argv, VALUE module)
   return Data_Wrap_Struct( cScreen,0,0,screen ); 
 }
 
+
+/* call-seq:
+ *     Screen.set_mode( size, depth=0, flags=[SWSURFACE] )  ->  Screen
+ *
+ *  Deprecated alias for Screen.new. This method will be REMOVED
+ *  in Rubygame 3.0. You should use Screen.new (or its alias, Screen.open)
+ *  instead.
+ */
+VALUE rbgm_screen_setmode(int argc, VALUE *argv, VALUE module)
+{
+  rg_deprecated("Rubygame::Screen.set_mode", "3.0");
+  return rbgm_screen_new(argc, argv, module);
+}
+
+/* call-seq:
+ *     Screen.instance( size, depth=0, flags=[SWSURFACE] )  ->  Screen
+ *
+ *  Deprecated alias for Screen.new. This method will be REMOVED
+ *  in Rubygame 3.0. You should use Screen.new (or its alias, Screen.open)
+ *  instead.
+ */
+VALUE rbgm_screen_instance(int argc, VALUE *argv, VALUE module)
+{
+  rg_deprecated("Rubygame::Screen.instance", "3.0");
+  return rbgm_screen_new(argc, argv, module);
+}
+
+
+/*
+ *  call-seq:
+ *     Screen.close
+ *
+ *  Close the Screen, making the Rubygame window disappear.
+ *  This method also exits from fullscreen mode, if needed.
+ *
+ *  After calling this method, you should discard any references
+ *  to the old Screen surface, as it is no longer valid, even
+ *  if you call Screen.new again.
+ *
+ *  (Note: You do not need to close the Screen to change its size
+ *  or flags, you can simply call Screen.new while already open.)
+ *
+ */
+VALUE rbgm_screen_close(VALUE module)
+{
+	SDL_QuitSubSystem(SDL_INIT_VIDEO);
+	return Qnil;
+}
+
+
+/*
+ *  call-seq:
+ *     Screen.open?
+ *
+ *  True if there is an open Rubygame window.
+ *  See Screen.new and Screen.close.
+ *
+ */
+VALUE rbgm_screen_openp(VALUE module)
+{
+  return (SDL_GetVideoSurface() == NULL) ? Qfalse : Qtrue;
+}
+
+
+
 /*  call-seq:
- *     get_surface
+ *     Screen.get_surface
  *
  *  Returns the current display window, or raises SDLError if it
  *  fails to get it (for example, if it doesn't exist yet).
@@ -150,7 +217,55 @@ VALUE rbgm_screen_getsurface(VALUE module)
   return Data_Wrap_Struct( cScreen,0,0,surface );
 }
 
-/* Screen methods: */
+
+/*  call-seq:
+ *     Screen.get_resolution  ->  [width, height]
+ *
+ *  Returns the pixel dimensions of the user's display (i.e. monitor).
+ *  (That is not the same as Screen#size, which only measures the
+ *  Rubygame window.) You can use this information to detect
+ *  how large of a Screen can fit on the user's display.
+ *
+ *  This method can _only_ be used when there is no open Screen instance.
+ *  This method raises SDLError if there is a Screen instance (i.e.
+ *  you have done Screen.new before). This is a limitation of the SDL
+ *  function SDL_GetVideoInfo, which behaves differently when a Screen
+ *  is open than when it is closed.
+ *
+ *  This method will also raise SDLError if it cannot get the display
+ *  size for some other reason.
+ *
+ */
+VALUE rbgm_screen_getresolution(VALUE module)
+{
+  VALUE array;
+  const SDL_VideoInfo* hw;
+  init_video_system();
+
+  /* Test for existing Screen */
+  SDL_Surface *surface;
+  surface = SDL_GetVideoSurface();
+  if(surface != NULL)
+	{
+		rb_raise(eSDLError, "You cannot get resolution when there is " \
+             "an open Screen. See the docs for the reason.");
+	}
+
+  hw = SDL_GetVideoInfo();
+  if(hw==NULL)
+	{
+		rb_raise(eSDLError,"Couldn't get video info: %s",SDL_GetError());
+	}
+
+  array = rb_ary_new();
+  rb_ary_push(array, INT2NUM(hw->current_w));
+  rb_ary_push(array, INT2NUM(hw->current_h));
+  return array;
+}
+
+
+/* Screen instance methods: */
+
 
 /*  call-seq:
  *     title  ->  String
@@ -224,7 +339,7 @@ VALUE rbgm_screen_seticon(VALUE self, VALUE data)
  *
  *  Updates (refreshes) all or part of the Rubygame window, revealing to the 
  *  user any changes that have been made since the last update. If you're using
- *  a double-buffered display (see Display.set_mode), you should use
+ *  a double-buffered display (see Screen.new), you should use
  *  Screen#flip instead.
  *
  *  This method takes these arguments:
@@ -347,7 +462,7 @@ VALUE rbgm_screen_updaterects(VALUE self, VALUE array_rects)
 /*  call-seq:
  *     flip()
  *
- *  If the Rubygame display is double-buffered (see #set_mode), flips
+ *  If the Rubygame display is double-buffered (see Screen.new), flips
  *  the buffers and updates the whole screen. Otherwise, just updates the
  *  whole screen.
  */
@@ -402,8 +517,8 @@ VALUE rbgm_screen_setshowcursor(VALUE self, VALUE val)
  *  Surface#set_colorkey and Surface#set_alpha are not inherited.
  *
  *  Please note that only *one* Screen can exist, per application, at a time;
- *  this is a limitation of SDL. You *must* use Screen.set_mode to create the
- *  Screen or modify its properties.
+ *  this is a limitation of SDL. You *must* use Screen.new (or its alias,
+ *  Screen.open) to create or modify the Screen.
  *
  *  Also note that no changes to the Screen will be seen until it is refreshed.
  *  See #update, #update_rects, and #flip for ways to refresh all or part of
@@ -419,10 +534,19 @@ void Rubygame_Init_Screen()
 
   /* Screen class */
   cScreen = rb_define_class_under(mRubygame,"Screen",cSurface);
-  rb_define_singleton_method(cScreen,"new",rbgm_screen_setmode, -1);
-  rb_define_alias(rb_singleton_class(cScreen),"set_mode","new");
-  rb_define_alias(rb_singleton_class(cScreen),"instance","new");
+  rb_define_singleton_method(cScreen,"new",rbgm_screen_new, -1);
+  rb_define_alias(rb_singleton_class(cScreen),"open","new");
+
+  rb_define_singleton_method(cScreen,"close", rbgm_screen_close, 0);
+  rb_define_singleton_method(cScreen,"open?", rbgm_screen_openp, 0);
   rb_define_singleton_method(cScreen,"get_surface",rbgm_screen_getsurface, 0);
+  rb_define_singleton_method(cScreen,"get_resolution",rbgm_screen_getresolution, 0);
+
+  /* Deprecated: */
+  rb_define_singleton_method(cScreen,"set_mode", rbgm_screen_setmode, -1);
+  rb_define_singleton_method(cScreen,"instance", rbgm_screen_instance, -1);
+
+
 
   /* These are inherited from Surface, but should not be called on Screen */
   rb_undef_method(cScreen,"set_alpha"); 

data/ext/rubygame/rubygame_screen.h

@@ -28,6 +28,8 @@ extern VALUE cScreen;
 extern VALUE rbgm_screen_setmode(int, VALUE*, VALUE);
 extern VALUE rbgm_screen_getsurface(VALUE);
 
+extern VALUE rbgm_screen_getresolution(VALUE);
+
 extern VALUE rbgm_screen_getcaption(VALUE);
 extern VALUE rbgm_screen_setcaption(VALUE, VALUE);
 

data/lib/rubygame.rb

@@ -1,6 +1,7 @@
 #--
+#
 #  Rubygame -- Ruby code and bindings to SDL to facilitate game creation
-#  Copyright (C) 2004-2007, 2008  John Croisant
+#  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
@@ -15,6 +16,7 @@
 #  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
+#
 #++
 
 # This file is loaded when you "require 'rubygame'".
@@ -39,6 +41,8 @@ require "rubygame_core"
   end
 end
 
+require "rubygame/shared"
+
 require "rubygame/color"
 require "rubygame/constants"
 

data/lib/rubygame/clock.rb

@@ -1,6 +1,7 @@
 #--
+#
 #	Rubygame -- Ruby code and bindings to SDL to facilitate game creation
-#	Copyright (C) 2004-2007  John Croisant
+#	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
@@ -15,114 +16,295 @@
 #	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/events/clock_events"
+
+
 module Rubygame
-		#  Clock provides class methods for tracking running time and delaying
-		#  execution of the program for specified time periods. This is used to
-		#  provide a consistent framerate, prevent the program from using
-		#  all the processor time, etc.
-		# 
-		#  Clock also provides instance methods to make it convenient to
-		#  monitor and limit application framerate. See #tick.
-		class Clock
-			# The runtime when the Clock was initialized.
-			attr_reader :start        
-			# The number of times #tick has been called.
-			attr_reader :ticks        
-
-			# Create a new Clock instance.
-			def initialize()
-				@start = Clock.runtime()
-				@last_tick = @start
-				@ticks = 0
-				@target_frametime = nil
-				yield self if block_given?
-			end
-
-			# The target frametime (milliseconds/frame). See #tick
-			attr_accessor :target_frametime
-
-			# Returns the current target framerate (frames/second).
-			# This is an alternate way to access @target_frametime.
-			# Same as: 1000.0 / #target_frametime
-			def target_framerate
-				if @target_frametime
-					1000.0 / @target_frametime
-				else
-					nil
-				end
-			rescue ZeroDivisionError
-				return nil
-			end
-
-			# Sets the target number of frames per second to +framerate+.
-			# This is an alternate way to access @target_frametime.
-			# Same as: #target_frametime = 1000.0 / framerate
-			def target_framerate=( framerate )
-				if framerate
-					@target_frametime = 1000.0 / framerate
-				else
-					@target_frametime = nil
-				end
-			rescue ZeroDivisionError
-				@target_frametime = nil
-			end
-
-			# call-seq: lifetime()  ->  Numeric
-			# 
-			# Returns time in milliseconds since this Clock instance was created.
-			def lifetime
-				Clock.runtime() - @start
-			end
-
-			# call-seq: framerate()  ->  Numeric
-			# 
-			# Return the actual framerate (frames per second) recorded by the Clock.
-			# See #tick.
-			# 
-			# TODO: sample only a few seconds in the past, instead of the
-			# entire lifetime of the Clock. 
-			def framerate
-				# below is same as: return @ticks / (lifetime / 1000.0)
-				return 1000.0 * @ticks / lifetime()
-			rescue ZeroDivisionError
-				return 0
-			end
-
-			# Returns the number of milliseconds since you last called this method.
-			# 
-			# You must call this method once per frame (i.e. per iteration of
-			# your main loop) if you want to use the framerate monitoring and/or
-			# framerate limiting features.
-			# 
-			# Framerate monitoring allows you to check the framerate (frames per
-			# second) with the #framerate method.
-			# 
-			# Framerate limiting allows you to prevent the application from running
-			# too fast (and using 100% of processor time) by pausing the program
-			# very briefly each frame. The pause duration is calculated each frame
-			# to maintain a constant framerate.
-			# 
-			# Framerate limiting is only enabled if you have set the
-			# #target_framerate= or #target_frametime=.
-			# If you have done that, this method will automatically perform the
-			# delay each time you call it.
-			# 
-			# (Please note that no effort is made to correct a framerate
-			# which is *slower* than the target framerate. Clock can't
-			# make your code run faster, only slow it down if it is
-			# running too fast.)
-			def tick()
-				passed = Clock.runtime() - @last_tick  # how long since the last tick?
-				if @target_frametime
-					return Clock.delay(@target_frametime - passed) + passed
-				end
-				return passed
-			ensure
-				@last_tick = Clock.runtime()
-				@ticks += 1
-			end
-
-		end # class Clock
-end #module Rubygame
+
+
+  # Clock provides class methods for tracking running time and delaying
+  # execution of the program for specified time periods. This is used to
+  # provide a consistent framerate, prevent the program from using
+  # all the processor time, etc.
+  # 
+  # Clock also provides instance methods to make it convenient to
+  # monitor and limit application framerate. See #tick.
+  # 
+  # An in-depth tutorial on using Clock is available. See
+  # doc/managing_framerate.rdoc[link:files/doc/managing_framerate_rdoc.html]
+  # in the Rubygame source distribution or in the online
+  # documentation.
+  # 
+  class Clock
+
+    # The runtime when the Clock was initialized.
+    attr_reader :start
+
+    # The number of times #tick has been called.
+    attr_reader :ticks
+
+
+    # Granularity used for framerate limiting delays in #tick.
+    # You can calibrate this easily with #calibrate.
+    # See also #tick and Clock.delay.
+    # (Non-negative integer. Default: 12.)
+    attr_accessor :granularity
+
+    # Whether to try to let other ruby threads run during framerate
+    # limiting delays in #tick. See #tick and Clock.delay.
+    # (true or false. Default: false.)
+    attr_accessor :nice
+
+
+    # Create a new Clock instance.
+    def initialize()
+      @start = self.class.runtime()
+      @last_tick = nil
+      @ticks = 0
+
+      @target_frametime = nil
+
+      # Frametime samples for framerate calculation
+      @samples = []
+      @max_samples = 20
+
+      @granularity = 12
+      @nice = false
+
+      # Should #tick return a ClockTicked event?
+      @tick_events = false
+
+      # Cache for past tick events with specific ms values
+      @tick_cache = {}
+
+      yield self if block_given?
+    end
+
+
+    # Calibrate some Clock settings to match the current computer.
+    # This improves efficiency and minimizes CPU usage without
+    # reducing accuracy.
+    # 
+    # As of Rubygame 2.5, this method calibrates @granularity. See
+    # #tick and Clock.delay for more information about the effect of
+    # setting granularity. In future versions of Rubygame, this
+    # method may also calibrate additional Clock attributes.
+    # 
+    # By default, the calibration takes a maximum of 0.5 seconds to
+    # complete. You can specify a different maximum length by passing
+    # a different value for +max_time+. In future versions of
+    # Rubygame, calibration may take less than max_time, but will
+    # not take more. Also, the default max_time may be lowered in
+    # future versions, but will not be raised.
+    # 
+    # You usually only need to call this once, after you create the
+    # Clock instance at the start of your application. You should not
+    # run any other ruby threads at the same time, as doing so will
+    # skew the calibration.
+    # 
+    #--
+    # 
+    # I'm not 100% sure that this is a valid way to measure
+    # granularity, or that the granularity of ruby sleep is
+    # always the same as that of SDL_Delay. But it can be
+    # improved later if needed...
+    #
+    #++
+    def calibrate( max_time = 0.5 )
+      samples = []
+
+      end_time = Time.now + max_time
+
+      while( Time.now < end_time )
+        t = Time.now
+        sleep 0.01
+        samples << (Time.now - t - 0.01)
+      end
+
+      average = samples.inject{|sum,n| sum + n} / samples.length
+
+      # convert to ms, add some padding
+      gran = (average * 1000).to_i + 1
+
+      @granularity = gran
+
+      return nil
+    end
+
+
+    # Enable tick events, so that #tick will return a ClockTicked
+    # instance instead of a number of milliseconds.
+    # 
+    # This option is available starting in Rubygame 2.5, and will
+    # become the default in Rubygame 3.0.
+    # 
+    def enable_tick_events
+      @tick_events = true
+    end
+
+
+    # Returns the current target frametime (milliseconds/frame),
+    # or nil if there is no target.
+    # 
+    # This is another way to access #target_framerate.
+    # Same as: 1000.0 / #target_framerate
+    # 
+    def target_frametime
+      @target_frametime
+    end
+
+
+    # Sets the target milliseconds per frame to +frametime+.
+    # If +frametime+ is nil, the target is unset, and #tick
+    # will no longer apply any delay.
+    # 
+    # This is another way to access #target_framerate.
+    # Same as: #target_framerate = 1000.0 / frametime
+    # 
+    def target_frametime=( frametime )
+      @target_frametime = frametime
+    end
+
+
+    # Returns the current target framerate (frames/second),
+    # or nil if there is no target.
+    # 
+    # This is another to access #target_frametime.
+    # Same as: 1000.0 / #target_frametime
+    # 
+    def target_framerate
+      if @target_frametime
+        1000.0 / @target_frametime
+      else
+        nil
+      end
+    rescue ZeroDivisionError
+      return nil
+    end
+
+
+    # Sets the target number of frames per second to +framerate+.
+    # If +framerate+ is nil, the target is unset, and #tick
+    # will no longer apply any delay.
+    # 
+    # This is another way to access #target_frametime.
+    # Same as: #target_frametime = 1000.0 / framerate
+    # 
+    def target_framerate=( framerate )
+      if framerate
+        @target_frametime = 1000.0 / framerate
+      else
+        @target_frametime = nil
+      end
+    rescue ZeroDivisionError
+      @target_frametime = nil
+    end
+
+
+    # call-seq:
+    #   lifetime  ->  Integer
+    # 
+    # Returns time in milliseconds since this Clock instance was created.
+    # 
+    def lifetime
+      self.class.runtime() - @start
+    end
+
+
+    # call-seq:
+    #   framerate  ->  Float
+    # 
+    # Return the actual framerate (frames per second) recorded by the
+    # Clock. See #tick.
+    # 
+    def framerate
+      1000.0 * @samples.length / @samples.inject(0){|sum, n| sum + n}
+    rescue ZeroDivisionError
+      0.0
+    end
+
+
+    # call-seq:
+    #   frametime  ->  Float
+    # 
+    # Return the actual frametime (milliseconds per frame) recorded by
+    # the Clock. See #tick.
+    # 
+    def frametime
+      @samples.inject(0){|sum, n| sum + n} / (@samples.length)
+    rescue ZeroDivisionError
+      0.0
+    end
+
+
+    # Returns the number of milliseconds since you last called this
+    # method. Or, if you have called #enable_tick_events, this returns
+    # a ClockTicked event representing the time since you last called
+    # this method. (ClockTicked was added in Rubygame 2.5, and will
+    # become the default and only option in Rubygame 3.0.)
+    # 
+    # You must call this method once per frame (i.e. per iteration
+    # of your main loop) if you want to use the framerate monitoring
+    # and/or framerate limiting features.
+    # 
+    # Framerate monitoring allows you to check the #framerate (frames
+    # per second) or #frametime (milliseconds per frame) of your game.
+    # 
+    # Framerate limiting allows you to prevent the application from
+    # running too fast (and using 100% of processor time) by pausing
+    # the program very briefly each frame. The pause duration is
+    # calculated each frame to maintain a stable framerate.
+    # 
+    # Framerate limiting is only enabled if you have set the
+    # #target_framerate= or #target_frametime=. If you have done that,
+    # this method will automatically perform the delay each time you
+    # call it.
+    # 
+    # There are two other attributes which affect framerate limiting,
+    # #granularity and #nice. These are passed as parameters to
+    # Clock.delay for the brief pause each frame. See Clock.delay for
+    # the effects of those parameters on CPU usage and threading.
+    # 
+    # (Please note that no effort is made to correct a framerate which
+    # is *slower* than the target framerate. Clock can't make your
+    # code run faster, only slow it down if it is running too fast.)
+    # 
+    def tick()
+
+      # how long since the last tick?
+      passed = 0
+      if @last_tick
+        passed += self.class.runtime() - @last_tick
+      end
+
+      if @target_frametime
+        extra = @target_frametime - passed
+        if( extra > 0 )
+          passed += self.class.delay( extra, @granularity, @nice )
+        end
+      end
+
+      if @tick_events
+        return (@tick_cache[passed] or 
+                 (@tick_cache[passed] =
+                  Rubygame::Events::ClockTicked.new( passed ) ))
+      else
+        return passed
+      end
+
+    ensure
+      @last_tick = self.class.runtime()
+      @ticks += 1
+
+      # Save the frametime for framerate calculation
+      @samples.push(passed)
+      @samples.shift if @samples.length > @max_samples
+    end
+
+  end
+
+end