rubygame 2.5.3 → 2.6.0

data/CREDITS

@@ -5,25 +5,27 @@
   Role::  Creator; primary developer
   Date::  2004 - present
 
+== Past Developers
+
 - <b>Ash Wilson</b> / smashwilson
   Email:: smashwilson at gmail.com
   Role::  Assistant developer
-  Date::  2007 - present
+  Date::  2007 - 2008
 
 - <b>Roger Ostrander</b> / denor
   Email:: atiaxi at gmail.com
   Role::  Assistant developer
-  Date::  2007 - present
+  Date::  2007 - 2008
 
 - <b>Rusterholz Stefan</b> / apeiros
   Email:: apeiros at gmx.net
   Role::  Assistant developer
-  Date::  2007 - present
+  Date::  2007 - 2008
 
 - <b>Bjorn De Meyer</b> / beoran
   Email:: beoran at gmail.com
   Role::  Assistant developer
-  Date::  Nov 2007 - present
+  Date::  Nov 2007 - 2008
 
 == Other Source Contributors
 

data/NEWS

@@ -1,5 +1,84 @@
 = NEWS
 
+== Rubygame 2.6.0
+
+Release focus: Ported to FFI.
+
+=== FFI
+
+Rubygame is now pure Ruby, with no compiled C code. Instead, it uses
+Ruby-FFI (or compatible FFI implementations) to directly access SDL
+and related libraries. That means:
+
+- It is much easier to install. You can install it directly from
+  RubyGems (`gem install rubygame`) on any operating system, and you
+  don't need a C compiler or SDL headers.
+
+- It is now possible to use Rubygame on JRuby, and possibly on
+  Rubinius.
+
+- Rubygame will be slightly slower than before. But, the hard work is
+  still being done by SDL, so the speed decrease is only minor. The
+  increased portability and ease of future development greatly
+  outweighs the small speed loss.
+
+Despite the major architectural change, Rubygame 2.6 API is meant to
+be backwards compatible with Rubygame 2.5 and earlier. If you find an
+API incompatibility, you should report it as a bug.
+
+However, there are a few minor incompatibilities that are already known,
+and most likely cannot or will not be fixed:
+
+- Surface#flip now needs SDL_gfx to run. Before, it needed only plain
+  SDL, but the code for it was too slow when reimplemented in Ruby.
+
+- Rubygame::VERSIONS[:sdl_gfx] now reports [0,0,0] when SDL_gfx is
+  available, instead of its real version number. SDL_gfx does not
+  currently provide any way to detect its version number at run time.
+  (VERSIONS still reports nil when SDL_gfx is not available, the same
+  as in 2.5 and earlier.)
+
+=== Fixes
+
+- Fixed: Surface#set_at() now correctly sets the pixel's opacity for
+  Surfaces with an alpha channel. If no opacity is given for the new
+  color (i.e. only RGB), the pixel will be fully opaque.
+
+  - Note: Due to a long-standing bug, Surface.new cannot create a
+    Surface with an alpha channel. Use Surface#to_display_alpha to
+    create an alpha-channeled copy of the Surface, or load an image
+    file that has an alpha channel already.
+
+- Fixed: Music.load now automatically opens audio if needed. MP3s (and
+  perhaps other file types) would fail to load in some circumstances
+  if audio was not open.
+
+=== Other Changes
+
+- Rubygame now automatically initializes itself when loaded and cleans
+  itself up at exit. So, you no longer need to call Rubygame.init or
+  Rubygame.quit in your code (but it won't hurt if you do).
+
+- Added: New sample application, a basic image viewer.
+  See samples/image_viewer.rb.
+
+- Added: Documentation listing every keyboard symbol used by Rubygame.
+  See doc/keyboard_symbols.rdoc.
+
+- Added: Guide to setting custom load parts for SDL libraries.
+  See doc/custom_sdl_load_paths.rdoc.
+
+- Surface#alpha= is now a true alias for Surface#set_alpha. It was a
+  separate method before. It can still be used in the same way as
+  before.
+
+- Surface#colorkey= is now a true alias for Surface#set_colorkey. It
+  was a separate method before. It can still be used in the same way
+  as before.
+
+
+
+
 == Rubygame 2.5.3
 
 Release focus: Bug fixes.

data/README

@@ -2,126 +2,109 @@
 
  == What is Rubygame?
 
- Rubygame is a cross-platform game-development extension and library for Ruby,
- inspired by Pygame. The purpose of Rubygame is to empower game developers by
- providing them with powerful and flexible high-level concepts. Instead of
- worrying about low-level technical details, you can focus your energy on
- more interesting things (like making a fun game).
-
- Rubygame's core is written in C to bind low-level SDL functions into Ruby.
- On top of that is a pure Ruby library for higher-level behavior like
- event and game object management.
+ Rubygame is a cross-platform game-development library for Ruby,
+ inspired by Pygame. Rubygame strives to empower game developers by
+ providing them with powerful and flexible mid-to-high level tools.
+ Instead of worrying about low-level technical details, you can focus
+ your energy on more interesting things (like making a fun game).
 
  === Relevant Links
  1. Rubygame: http://rubygame.org
  2. Ruby: http://www.ruby-lang.org
  3. Pygame: http://www.pygame.org
- 4. SDL: http://www.libsdl.org
+
 
  == Requirements
 
- You will definitely need these software packages to compile Rubygame:
+ You will definitely need these software packages to use Rubygame:
 
- * ruby        >= 1.8 
- * SDL         >= 1.2.7
- * rake        >= 0.7.0    (for build/install system)
+ * Ruby          >= 1.8 
+ * Ruby-SDL-FFI  >= 0.1
+ * SDL           >= 1.2.7   (1.2.14 on MacOS X 10.6)
+ * (MacOS X only): RSDL  ( http://github.com/knu/rsdl )
 
  It's highly recommended that you have these packages as well, or some
  cool features won't be available!
 
- * SDL_gfx     >= 2.0.10
+ * SDL_gfx     >= 2.0.13
  * SDL_image   >= 1.2.3
  * SDL_mixer   >= 1.2.7
  * SDL_ttf     >= 2.0.6
 
- (If you don't have some of those, you have to disable those features
- by passing some flags to the build process. See "Advanced Install", below.)
-
- If you are compiling source on a binary-based Linux ditribution,
- you will also need the "dev" packages of ruby, SDL, SDL_gfx, SDL_image,
- SDL_mixer, and SDL_ttf. (Really, you just need the header files.)
-
- And of course, if you are compiling the source, you will need a C compiler!
- These versions of gcc worked fine when I tried them; other compilers might
- work too:
-
- * gcc 3.3, 3.4, 4.0, 4.1
-
 
  == Install
 
  === Basic Install
 
- Extract the archive and enter its top directory.
- Then run ($ indicates as user, # as root):
-
-  $ rake build
-  # rake install
-
- === Advanced Install
-
- The build and install tasks can be configured by providing certain commands
- to rake:
-
- no-sdl-gfx::    do not build modules which depend on SDL_gfx
- no-sdl-image::  do not build modules which depend on SDL_image
- no-sdl-mixer::  do not build modules which depend on SDL_mixer
- no-sdl-ttf::    do not build modules which depend on SDL_ttf
- no-opengl::     do not build modules which depend on OpenGL
-
- no-sdl-config:: do not guess compiler/linker flags using `sdl-config'
-
- debug::         build modules with debbugging flags enabled
- universal::     on MacOS X, try to compile for both PPC and Intel
- verbose::       display the build commands as they are run
+ The simplest way to install is with RubyGems:
 
- Additionally, the build process respects certain environmental variables.
- In particular, CFLAGS and LDFLAGS are important for users compiling with
- the no-sdl-config command.
+  $ sudo gem install rubygame
 
- CC::            C compiler command
- CFLAGS::        flags passed to the C compiler
- LDSHARED::      linker command
- LDFLAGS::       flags passed to the linker
- RUBYARCHDIR::   where to install platform-specific compiled extensions
- RUBYLIBDIR::    where to install platform-independent interpreted libs
+ Another way is to install directly from the source:
 
- IMPORTANT: if you are missing any optional SDL_* libraries, you must specify
- "no-*" flags for those libraries. For example, if you don't have SDL_gfx:
+  $ sudo rake install
 
-  $ rake no-sdl-gfx build
+ Or generate and install a gem from the source:
 
- If you don't disable the features, the compile will probably fail when it
- looks for the headers and libraries. (The build system is not smart enough to
- automatically disable missing features.)
+  $ rake gem
+  $ sudo gem install pkg/rubygame-*.gem
 
  === Generating documentation
 
  You can generate documentation for Rubygame's API by running:
 
-  # rake rdoc
+  $ rake rdoc
 
  Documentation will be generated as HTML in the 'html' directory.
  Open 'html/index.html' in a web browser to get started.
 
+
  == Usage
  
  See the documentation (online at http://docs.rubygame.org, or
  generated locally with the 'rake rdoc' command). 
 
  We also recommend that you take a peek at the demo applications in
- the 'samples' directory, especially demo_rubygame.rb and chimp.rb.
+ the 'samples' directory, especially image_viewer.rb,
+ demo_rubygame.rb, and chimp.rb.
+
+
+ == About the version number
+
+ The version number of Rubygame has a strict meaning, to help you
+ decide whether the new version might break your application. The
+ version number has 3 parts: the major number, the minor number, and
+ the patch number. For the example of Rubygame 2.6.0:
+
+     2   .   6   .   0
+   MAJOR . MINOR . PATCH
+
+ When a new release of Rubygame is made, one of the version numbers
+ will go up, and the numbers that come after it will be reset to 0.
+ Which number will go up depends on how much the Rubygame API changed:
+
+ - *MAJOR*: API has changed, and old apps _must_ be updated.
+   An example of this is when a class has been significantly changed,
+   or a method has renamed/moved to another module and the old name is
+   removed.
+
+ - *MINOR*: API has changed, but old apps will still work.
+   An example of this is when a new feature has been added, or a
+   method has been renamed but the old name is still supported.
+
+ - *PATCH*: API has not changed at all.
+   An example of this is when a bug has been fixed, or existing code
+   has been improved beneath the surface.
+
 
  == License
 
  Rubygame is distributed under the terms of the GNU Lesser GPL.
  See LICENSE for more details.
 
- The contents of the file 'Rakefile' is licensed under the terms of the
- MIT license. See that file for more details.
-
- Some of the sample files are distributed under licenses other than the
- GNU Lesser GPL. See 'samples/README' and 'samples/GPL' for more details.
+ Some of the sample files are distributed under licenses other than
+ the GNU Lesser GPL. See 'samples/README' and 'samples/GPL' for more
+ details.
 
 
  John Croisant (jacius at gmail.com)

data/ROADMAP

@@ -1,22 +1,22 @@
 = ROADMAP
 
 This represents the direction Rubygame will be going in, but
-keep in mind that specific details may change over time.
+keep in mind that plans and details may change over time.
 
 
-== 2.X.0 (_possible_ minor releases before 3.0.0)
+== 2.X (_possible_ minor releases before 3.0)
 
 === Focus: Surface & Rect
 
 - Surface improvements
   - Make Surface instances copyable and marshalable
   - Support for palettes on 8-bit Surfaces
+  - Export as OpenGL-ready 32bit pixel data.
   - To Fix: New Surfaces never have alpha channels
-  - To Fix: Surface#set_at doesn't respect alpha
   - To Add: Surface#pixels= (set pixel data directly)
   - To Add: Surface.load_from_pixels (create from pixel data)
 
-- Rewrite Rect class in C for speed
+- Optimize Rect for speed
 
 
 === Focus: Sprites
@@ -24,18 +24,20 @@ keep in mind that specific details may change over time.
 - New sprite system
   - New Sprite, Scene, and Camera classes.
   - More powerful and simpler to use.
-  - Integration with the Chipmunk physics library.
+  - Integration with the Chipmunk physics library?
 
 
 
-== 3.0.0 (next major release)
+== 3.0 (next major release)
 
 - Backwards compatibility is broken:
   - Deprecated classes / methods retired:
     - Rubygame::Mixer module.
     - Rubygame::Mixer::Sample class. Use Rubygame::Sound.
     - Rubygame::Mixer::Music class. Use Rubygame::Music.
-    - Rubygame::Surface.load_image method. User Rubygame::Surface.load.
+    - Rubygame::Surface.load_image method. Use Rubygame::Surface.load.
+    - Rubygame::Ftor class. An alternative class will be provided.
+    - Rubygame::MediaBag class. Use Surface#[], Sound#[], and Music#[].
   - Surface#get_at
   - Sprites::Group#collide_group
 
@@ -44,7 +46,17 @@ keep in mind that specific details may change over time.
 
 
 
-== On the horizon...
+== Possible future developments
+
+- Switch from SDL_gfx to SPriG for graphics primitives.
+  - SPriG provides more functionality and flexibility, and a more
+    consistent interface.
+  - How does speed compare?
+  - Is it buggy?
+
+- Alternative back-ends:
+  - OpenGL (faster rendering, better Mac support)
+  - Allegro?
 
 - Polygon, circle, and other geometric primitives
   - Drawing, with styles?
@@ -65,8 +77,3 @@ keep in mind that specific details may change over time.
   - E.g. moves a sprite from point A to point B over N seconds.
   - Many types of effects, easy to define custom ones.
   - Takes parameters: start/end time, others depending on effect.
-
-- C equivalent of Rect.new_from_object (see rect.rb)
-  - Screen#update (cannot pass object with rect attribute)
-  - Screen#update_rects (same as above)
-  - Why not just call the ruby function from within C?

data/doc/custom_sdl_load_paths.rdoc

@@ -0,0 +1,79 @@
+= Custom SDL Load Paths
+
+In Rubygame 2.6 and later, you can tell Rubygame to look in custom
+locations to find the SDL libraries (e.g. DLL files). This is mostly
+intended for when you are packaging your application in a stand-alone
+package (e.g. with RubyScript2Exe), and want to distribute the SDL
+libraries with your application, so that users do not need to install
+SDL.
+
+== Setting Load Paths
+
+Setting custom load paths is easy: just set the SDL_PATHS constant
+to an Array of directories before you do `require "rubygame"`.
+Note: You really must set SDL_PATHS *before* loading Rubygame!
+
+Rubygame will look first in the paths in SDL_PATHS, in the order they
+are given in the array. If Rubygame can't find a SDL library in any of
+the SDL_PATHS directories, Rubygame will then search for the library
+in some common library paths for the current operating system (e.g.
+"C:\windows\system32\" on Windows, "/usr/lib/" on Linux, etc.).
+
+For example, if the SDL libraries are in "mygame/libs/", and your
+main script is "mygame/mygame.rb", you could do the following in
+"mygame/mygame.rb":
+
+  main_dir = File.dirname(__FILE__)
+  SDL_PATHS = [ File.join( main_dir, "libs" ) ]
+  
+  require "rubygame"
+  
+  # ... the rest of your code ...
+
+== Per-OS Load Paths
+
+If you prefer to split the libraries into a separate directory for
+each operating system, you can set SDL_PATHS to a Hash instead. For
+example:
+
+  main_dir = File.dirname(__FILE__)
+  SDL_PATHS = {
+    /linux/   => File.join( main_dir, "libs", "linux"   ),
+    /bsd/     => File.join( main_dir, "libs", "bsd"     ),
+    /darwin/  => File.join( main_dir, "libs", "mac"     ),
+    /windows/ => File.join( main_dir, "libs", "windows" ),
+  }
+  
+  require "rubygame"
+  
+  # ... the rest of your code ...
+
+Each key in the hash should be a Regexp that matches an OS name. As of
+this writing (October 2009), the list of recognized OS names is:
+
+* "darwin" (MacOS X)
+* "freebsd"
+* "linux"
+* "openbsd"
+* "solaris"
+* "windows"
+
+== Library File Names
+
+Rubygame has certain expectations about the names of library files for
+each operating system ("[NAME]" is replaced with e.g. "SDL"):
+
+'Nix::    lib[NAME].so
+Mac::     lib[NAME].dylib or [NAME].framework/[NAME]
+Windows:: [NAME].dll
+
+The specific libraries used by Rubygame are:
+
+SDL::        libSDL.so; libSDL.dylib or SDL.framework/SDL; SDL.dll
+SDL_gfx::    libSDL_gfx.so; libSDL_gfx.dylib or SDL_gfx.framework/SDL_gfx; SDL_gfx.dll
+SDL_image::  libSDL_image.so; libSDL_image.dylib or SDL_image.framework/SDL_image; SDL_image.dll
+SDL_mixer::  libSDL_mixer.so; libSDL_mixer.dylib or SDL_mixer.framework/SDL_mixer; SDL_mixer.dll
+SDL_ttf::    libSDL_ttf.so; libSDL_ttf.dylib or SDL_ttf.framework/SDL_ttf; SDL_ttf.dll
+
+SDL is absolutely required. The others are optional, but strongly
+recommended, because they provide a lot of extra functionality.