rubysdl 1.3.1 → 2.0

data/doc-en/general.rsd

@@ -0,0 +1,43 @@
+= Contents
+* ((<"Ruby/SDL Outline">))
+* ((<Initialize>))
+* ((<Video>))
+* ((<OpenGL>))
+* ((<Window Management>))
+* ((<Event>))
+* ((<Joystick>))
+* ((<CD-ROM>))
+* ((<Audio>))
+* ((<Time>))
+* ((<Font>))
+* ((<Collision Detection>))
+* ((<SDLSKK>))
+* ((<MPEG playback>))
+
+= Ruby/SDL Outline
+Ruby/SDL is Ruby extension library for
+ ((<SDL|URL:http://www.libsdl.org/>)).
+This library enables you to create games, demo, or so on.
+
+Ruby/SDL has following functions.
+* ((<access to 2D video framebuffer|Video>))
+* Access ((<Keyboard and mouse|Event>)), ((<Joystick>)) input
+* ((<Audio Playback|Audio>)) with ((<SDL_mixer|URL:http://www.libsdl.org/projects/SDL_mixer/index.html>))
+* ((<Control CD-ROM|CD-ROM>))
+* ((<Font drawing |Font>)) with ((<SDL_ttf|URL:http://www.libsdl.org/projects/SDL_ttf/index.html>)),
+  ((<SDL_kanji|URL:http://shinh.skr.jp/sdlkanji/>)) and
+  ((<SGE|URL:http://www.etek.chalmers.se/~e8cal1/sge/index.html>))
+* ((<Using OpenGL|OpenGL>)) via ((<OpenGL Interface|URL:http://www2.giganet.net/~yoshi/>))
+* ((<Dealing with time|Time>))
+* ((<SKK like Japanese input|SDLSKK>)) with ((<SDLSKK|URL:http://www.kmc.gr.jp/~ohai/sdlskk.html>))
+* ((<MPEG playback>)) with ((<SMPGE|URL:http://www.icculus.org/smpeg/>))
+* ((<Window Management>)) and ((<Collision Detection>))
+
+== SDL::Error
+A Exception class for SDL specific errors.
+This class is subclass of StandardError.
+
+== SDL::VERSION
+Ruby/SDL version string.
+
+

data/doc-en/init.rsd

@@ -0,0 +1,168 @@
+= Initialize
+TOC
+
+Before SDL can be used in a program it must be initialized
+with @[init]. @[init] initializes all the subsystems that
+ the user requests (video, audio, joystick, timers and/or cdrom).
+
+== Methods
+%%%
+NAME init
+TYPE .
+PURPOSE Initializes SDL
+
+PROTO
+init(flags)
+
+DESC
+Initializes SDL. This should be called before all other 
+Ruby/SDL methods. The $[flags] parameter specifies what
+ part(s) of SDL to initialize.
+:SDL::INIT_AUDIO
+  Initialize autio subsystems.
+:SDL::INIT_VIDEO
+  Initialize @[Video] subsystem.
+:SDL::INIT_CDROM
+  Initialize @[CDROM] subsystem.
+:SDL::INIT_JOYSTICK
+  Initialize @[Joystick] subsystem.
+:SDL::INIT_EVERYTHING
+  Initialize all of the avobe.
+
+EXCEPTION *
+
+%%
+NAME quit
+TYPE .
+PURPOSE Shut down SDL
+
+PROTO
+quit
+
+DESC
+This method shots down all SDL subsystem and frees the resources
+allocated to them. Because this method is automatically called 
+when ruby stops, you don't have to call this function normally.
+
+You should know SDL and Ruby/SDL very well when you use
+this method.
+
+%%
+NAME inited_system
+TYPE .
+PURPOSE Check which subsystems are initialized
+RVAL UINT
+
+PROTO
+inited_system(flags)
+initedSystem(flags)
+
+DESC
+This method allows you to see which SDL subsytems have
+ been @[initialized|init]. $[flags] is a bitwise OR'd 
+combination of the subsystems you wish to check 
+(see @[init] for a list of subsystem flags).
+
+RET
+Returns a bitwised OR'd combination of the initialized subsystems.
+
+EXAMPLE
+# Here are several ways you can use SDL.inited_system
+
+# Get init data on all the subsystem
+subsystem_init = SDL.inited_system(SDL::INIT_EVERYTHING)
+
+if subsystem_init & SDL::INIT_VIDEO
+  puts "video is initialized"
+else
+  puts "video is not initialized"
+end
+
+# Just check for one specfic subsystem
+
+if SDL.inited_system(SDL::INIT_VIDEO) != 0
+  puts "Video is initialized"
+else
+  puts "Video is not initialized        "
+end
+
+# Check for two subsystem
+
+subsystem_mask = SDL::INIT_VIDEO|SDL::INIT_AUDIO;
+
+if SDL.inited_system(subsystem_mask) == subsystem_mask
+  puts "Video and Audio initialized."
+else
+  puts "Video and Audio not initialized"
+end
+
+SEEALSO
+init
+
+%%
+NAME getenv
+TYPE .
+PURPOSE Get an environmental variable
+RVAL String
+
+PROTO
+getenv(var)
+
+DESC
+Returns the environment variable string matched by $[var].
+
+
+%%
+NAME putenv
+TYPE .
+PURPOSE Change or add an  environmental variable
+
+PROTO
+putenv(string)
+
+DESC
+Add or Change the value of environmental variables.
+The argument $[string] is of the form "name=value"
+
+If you want to change SDL_WINDOWID or SDL_VIDEODRIVER environmental variable 
+to modify the behavior of SDL in your program, you should use 
+this function instead of ENV.
+
+EXCEPTION *
+
+EXAMPLE
+# from http://moriq.tdiary.net/20051006.html 
+# Apollo with Ruby/SDL
+require 'phi'
+require 'sdl'
+
+# Create form
+form = Phi::Form.new
+$terminated = false
+form.on_close{ $terminated = true }
+form.caption = "Ruby/SDL on Phi::Form"
+# Create a panel on new form
+panel = Phi::Panel.new(form)
+panel.align = Phi::AL_LEFT
+
+# Put SDL window on panel with WINDOWID hack
+SDL.putenv("SDL_VIDEODRIVER=windib")
+SDL.putenv("SDL_WINDOWID=#{panel.handle}")
+form.show
+
+# initialize SDL
+SDL.init(SDL::INIT_VIDEO)
+screen = SDL.setVideoMode(640, 480, 16, SDL::SWSURFACE)
+
+# main loop
+unless $terminated
+  while event = SDL::Event2.poll
+    case event
+    when SDL::Event2::KeyDown, SDL::Event2::Quit
+      exit
+    end
+  end
+
+  sleep 0.05
+end
+

data/doc-en/joystick.rsd

@@ -0,0 +1,401 @@
+= Joystick
+* ((<Joystick Overview>))
+* ((<SDL::Joystick>))
+* Methods for Joystick 
+TOC
+
+== Joystick Overview
+Joysticks, and other similar input devices, have a very 
+strong role
+in game playing and SDL provides comprehensive support for them.
+Axes, Buttons, POV Hats and trackballs are all supported.
+
+Joystick support is initialized
+by passed the SDL::INIT_JOYSTICK flag
+to @[init]. Once initilized joysticks must be opened
+using @[Joystick.open].
+
+While using the functions describe in this secton 
+may seem like the best way
+to access and read from joysticks, in most cases they aren't.
+Ideally joysticks should be read
+using the @[Event] system.
+To enable this, you must set the joystick event processing state
+with @[Joystick.poll=].
+Joysticks must be @[opened|Joystick.open]
+before they can be used of course.
+
+* NOTES
+
+  If you are ((*not*)) handling the joystick
+  via the event queue then you must explicitly 
+  request a joystick update by calling @[Joystick.update_all].
+
+  Force Feedback is not yet support.
+
+== SDL::Joystick
+The class represents one joystick.
+
+METHODS(Joystick)
+
+== Methods
+%%%
+NAME num
+MOD Joystick
+TYPE .
+PURPOSE Count available joysticks.
+RVAL Integer
+
+PROTO
+num
+
+DESC
+Counts the number of joysticks attached to the system.
+
+SEEALSO
+Joystick.index_name
+Joystick.open
+
+%%
+NAME index_name
+MOD Joystick
+TYPE .
+PURPOSE Get joystick name.
+RVAL String
+
+PROTO
+index_name(index)
+indexName(index)
+
+DESC
+Get the implementation dependent name of joystick. 
+The $[index] parameter
+refers to the N'th joystick on the system.
+
+EXAMPLE
+# Print the names of all attached joysticks
+num_joy = SDL::Joystick.num
+printf("%d joysticks found\n", num_joy)
+num_joy.times do |i|
+  puts SDL::Joystick.index_name(i)
+end
+
+SEEALSO
+Joystick.open
+
+%%
+NAME open
+MOD Joystick
+TYPE .
+PURPOSE Opens a joystick for use.
+RVAL SDL::Joystick
+
+PROTO
+open(index)
+
+DESC
+Opens a joystick for use within SDL. The $[index] refers to the N'th
+joystick in the system. A joystick must be opened before it can be
+used.
+
+RET
+Returns a @[Joystick] instance on success.
+
+EXCEPTION *
+
+EXAMPLE
+# Check for joystick
+if SDL::Joystick.num > 0
+  # Open joystick
+  joy = SDL::Joystick.open(0)
+
+  printf("Opened Joystick 0\n");
+  printf("Name: %s\n", SDL::Joystick.name(0))
+  printf("Number of Axes: %d\n", joy.num_axes)
+  printf("Number of Buttons: %d\n", joy.num_buttons)
+  printf("Number of Balls: %d\n", joy.num_balls)
+end  
+
+%%
+NAME open?
+MOD Joystick
+TYPE .
+PURPOSE Determine if a joystick has been opened
+RVAL true/false
+
+PROTO
+open?(index)
+
+DESC
+Determines whether a joystick has already been opened within the
+application. $[index] refers to the N'th joystick on the system.
+
+RET
+Returns true if the joystick has been opened, or false if it has not.
+
+SEEALSO
+Joystick.open
+
+%%
+NAME index
+MOD Joystick
+TYPE #
+PURPOSE Get the index of an joystick.
+RVAL Integer
+
+PROTO
+index
+
+DESC
+Returns the index of $[self].
+
+%%
+NAME num_axes
+MOD Joystick
+TYPE #
+PURPOSE Get the number of joystick axes
+RVAL Integer
+
+PROTO
+num_axes
+numAxes
+
+DESC
+Return the number of axes available.
+
+NOTES
+This method counts two dimensional axes as two axes.
+
+SEEALSO
+Joystick#axis
+
+%%
+NAME num_balls
+MOD Joystick
+TYPE #
+PURPOSE Get the number of joystick trackballs
+RVAL Integer
+
+PROTO
+num_balls
+numBalls
+
+DESC
+Return the number of trackballs available.
+
+SEEALSO
+Joystick#ball
+
+%%
+NAME num_hats
+MOD Joystick
+TYPE #
+PURPOSE Get the number of joystick hats
+RVAL Integer
+
+PROTO
+num_hats
+numHats
+
+DESC
+Return the number of hats available.
+
+SEEALSO
+Joystick#hat
+
+%%
+NAME num_buttons
+MOD Joystick
+TYPE #
+PURPOSE Get the number of joystick buttons
+RVAL Integer
+
+PROTO
+num_buttons
+numButtons
+
+DESC
+Return the number of buttons available.
+
+SEEALSO
+Joystick#button
+
+%%
+NAME poll=
+MOD Joystick
+TYPE .
+PURPOSE Enable/disable joystick event polling
+
+PROTO
+poll=(enable)
+
+DESC
+This function is used to enable or disable joystick event
+processing. With joystick event processing disabled you will have
+to update joystick states with @[Joystick.update_all] and read the
+joystick information manually.
+
+Joystick event polling is enabled by default.
+
+NOTE
+Joystick event handling is preferred.
+
+Even if joystick event processing is enabled,
+individual joysticks must be opened before they generate
+events.
+
+Calling this method may delete all events
+currently in SDL's event queue.
+
+SEEALSO
+Joystick.update_all
+Joystick.poll
+Event2::JoyAxis
+Event2::JoyBall
+Event2::JoyButtonDown
+Event2::JoyButtonUp
+Event2::JoyHat
+
+%%
+NAME poll
+MOD Joystick
+TYPE .
+PURPOSE Gets the current state of joysick event polling
+RVAL true/false
+
+PROTO
+poll
+
+DESC
+Returns true if joysick event polling is enabled, otherwise 
+returns false. You will also read @[Joystick.poll=].
+
+%%
+NAME update_all
+MOD Joystick
+TYPE .
+PURPOSE Updates the state of all joysticks
+
+PROTO
+update_all
+updateAll
+
+DESC
+Updates the state(position, buttons, etc.) of all open joysticks.
+If joystick events have been enabled with @[Joystick.poll=]
+then this is called automatically in the event loop.
+
+%%
+NAME axis
+MOD Joystick
+TYPE #
+PURPOSE Get the current state of an axis
+RVAL Integer
+
+PROTO
+axis(axis_index)
+
+DESC
+Returns the current state of given $[axis_index] on $[self].
+
+On most modern joysticks the X axis is usually represented by
+axis 0 and the Y axis by axis 1. The value returned by
+this method is a signed integer (-32768 to 32767)
+representing the current position of the axis, it may be
+necessary to impose certain tolerances on these values to account
+for jitter.
+
+EXAMPLE
+joy = SDL::Joystick.open(0)
+  .
+  .
+x_move = joy.axis(0)
+y_move = joy.axis(1)
+
+SEEALSO
+Joystick#num_axes
+
+%%
+NAME hat
+MOD Joystick
+TYPE #
+PURPOSE Get the current state of a joystick hat
+RVAL UINT
+
+PROTO
+hat(hat_index)
+
+DESC
+Returns the current state of the given $[hat_index].
+
+RET
+The current state is returned as a unsinged integer
+which is an OR'd combination of one or more of the following
+
+* SDL::Joystick::HAT_CENTERED
+* SDL::Joystick::HAT_UP
+* SDL::Joystick::HAT_RIGHT
+* SDL::Joystick::HAT_DOWN
+* SDL::Joystick::HAT_LEFT
+* SDL::Joystick::HAT_RIGHTUP
+* SDL::Joystick::HAT_RIGHTDOWN
+* SDL::Joystick::HAT_LEFTUP
+* SDL::Joystick::HAT_LEFTDOWN
+
+SEEALSO
+Joystick#num_hats
+
+%%
+NAME button
+MOD Joystick
+TYPE #
+PURPOSE Get the current state of a given button
+RVAL true/false
+
+PROTO
+button(button_index)
+
+DESC
+returns the current state of the given $[button_index].
+Returns true if the button is pressed, otherwise returns false.
+
+SEEALSO
+Joystick#num_buttons
+
+%%
+NAME ball
+MOD Joystick
+TYPE #
+PURPOSE Get relative trackball motion
+RVAL [Integer, Integer]
+
+PROTO
+ball(ball_index)
+
+DESC
+Get the ball axis change.
+Trackballs can only return relative motion since the last call to
+this method, these motion deltas are returned as 
+an array of two elements, [dx, dy].
+
+EXCEPTION *
+
+EXAMPLE
+delta_x, delta_y = joy.ball(0)
+printf("Trackball Delta- X:%d, Y:%d\n", delta_x, delta_y)
+
+%%
+NAME close
+MOD Joystick
+TYPE #
+PURPOSE Closes a previously opened joystick
+
+PROTO
+close
+
+DESC
+Close a joystick that was previously opened with @[Joystick.open].
+
+SEEALSO
+Joystick.open
+Joystick.open?