From: kthakore Date: Sun, 24 Oct 2010 15:11:07 +0000 (+0000) Subject: Updated docs X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=sdlgit%2FSDL-Site.git;a=commitdiff_plain;h=4769fd1282e2d4cb10aecefc8478e18b6c7635df Updated docs --- diff --git a/pages/SDL.html-inc b/pages/SDL.html-inc index c5147c2..75f9b1f 100644 --- a/pages/SDL.html-inc +++ b/pages/SDL.html-inc @@ -240,7 +240,7 @@ The actual delay may be longer than specified depending on the underlying OS.

See the impact graph on our github repository.

Andy Bakun <sdlperl@thwartedefforts.org>

Benedikt Meurer <bmeurer@fwdn.de>

-

Blaise Roth (Blaizer) <blaiseroth@gmail.com>

+

Blaise Roth (Blaizer) <blaizer@cpan.org>

Breno G. de Oliveira (garu)

Brian Cassidy (bricas)

chromatic <chromatic@wgz.org>

diff --git a/pages/SDLx-App.html-inc b/pages/SDLx-App.html-inc index a8127cf..df87986 100644 --- a/pages/SDLx-App.html-inc +++ b/pages/SDLx-App.html-inc @@ -106,6 +106,8 @@ Screen depth. Defaults to 16. Shortcut: 'd'. Any flags you want to pass to SDL::Video upon initialization. Defaults to SDL_ANYFORMAT. Flags should be or'ed together if you're passing more than one (flags => FOO|BAR). Shortcut: 'f'.
* resizeable Set this to a true value to make the window resizeable by the user. Default is off.
+
* exit_on_quit +Set this to a true value to make the app exit if a SDL_QUIT event is triggered. Shortcut: 'eoq'.
diff --git a/pages/SDLx-Controller.html-inc b/pages/SDLx-Controller.html-inc index 7b2256a..7cf82d5 100644 --- a/pages/SDLx-Controller.html-inc +++ b/pages/SDLx-Controller.html-inc @@ -48,28 +48,29 @@

SYNOPSIS

Top

-
  use SDLx::Controller;
+
 use SDLx::Controller;
 
-  # create our controller object
-  my $app = SDLx::Controller->new;
-
-  # register some callbacks
-  $app->add_event_handler( \&on_event );
-  $app->add_move_handler( \&on_move );
-  $app->add_show_handler( \&on_show );
-
-  # run our game loop
-  $app->run;
+ # create our controller object
+ my $app = SDLx::Controller->new;
 
+ # we could also do:
+ my $app = SDLx::App->new;
+ # because App is also a controller
 
+ # register some callbacks
+ $app->add_event_handler( \&on_event );
+ $app->add_move_handler( \&on_move );
+ $app->add_show_handler( \&on_show );
 
+ # run our game loop
+ $app->run;

DESCRIPTION

-

The core of a SDL application/game is the main loop, where you handle events +

The core of an SDL application/game is the main loop, where you handle events and display your elements on the screen until something signals the end of the program. This usually goes in the form of:

  while (1) {
@@ -109,10 +110,10 @@ It is only when you change the dt without changing all the things i
 If you lower the dt, everything will move faster than it did with it set higher, and vice-versa.
 This is useful to add slo-mo and fast-forward features to the game, all you would have to do is change the dt.

 
min_t specifies the minimum time, in seconds, that has to accumulate before any move or show handlers are called, and defaults to 1 / 60.
-Having the min_t to 1 / 60 ensures that the controller can update the screen at a maximum of 60 times per second.
+Having the min_t at 1 / 60 ensures that the controller can update the screen at a maximum of 60 times per second.
 A "V-Sync" such as this is necessary to prevent video "tear", which occurs when the app is updating faster than the monitor can display.
-Setting it to 0, as in the example, will let the app run as fast as it possibly can.

-
event is a SDL::Event object that events going to the event callbacks are polled in to. Defaults to SDL::Event->new().

+Setting it to 0, as seen above, will let the app run as fast as it possibly can.

+
event is a SDL::Event object that events going to the event callbacks are polled in to. It defaults to SDL::Event->new().

 
All parameters are optional.

 
Returns the new object.

 
@@ -142,17 +143,22 @@ Note that the second argument every callback recieves is the SDLx::Control
 
Takes 1 argument which is a callback. The application waits for the next event with wait_event.
 When one is recieved, it is passed to the callback as the first argument, along with the SDLx::Controller object as the second argument.
 If the callback then returns a true value, pause will return.
-If the callback returns a false value, pause will indefinitely wait for more events, repeating the process, until the callback returns true.

+If the callback returns a false value, pause will repeat the process.

 
This can be used to easily implement a pause when the app loses focus:

-
 sub focus {
-     my ($e, $controller) = @_;
-     if($e->type == SDL_ACTIVEEVENT) {
+
 sub window {
+     my ($e, $app) = @_;
+     if($e->type == SDL_QUIT) {
+		 $app->stop;
+         # quit handling is here so that the app
+         # can be stopped while paused
+     }
+     elsif($e->type == SDL_ACTIVEEVENT) {
          if($e->active_state & SDL_APPINPUTFOCUS) {
              if($e->active_gain) {
                  return 1;
              }
              else {
-                 $controller->pause(\&focus);
+                 $app->pause(\&window);
                  # recursive, but only once since the window
                  # can't lose focus again without gaining is first
              }
@@ -178,10 +184,10 @@ The second is the SDLx::Controller object.

 
 sub stop {
     my ($event, $app) = @_;
     if($event->type == SDL_QUIT) {
-        $controller->stop;
+        $app->stop;
     }
  }
- $controller->add_event_handler(\&stop);
+ $app->add_event_handler(\&stop);
 
 

 
@@ -195,7 +201,7 @@ and once more for any remaining time less than dt.
 The first argument passed to the callbacks is the portion of the step, which will be 1 for a full step, and less than 1 for a partial step.
 Movement values should be multiplied by this value.
 The full steps correspond to the amount of dt passed between calls, and the partial step corresponds to the call with the remaining time less than dt.
-The argument can be 0 if no time has passed since the last cycle. Set a min_t if you need to protect against this.

+The argument can be 0 if no time has passed since the last cycle. If you need to protect against this, set a min_t, or put a return unless $_[0] at the start of every move handler.

 
The second argument passed to the callbacks is the SDLx::Controller object.
 The third is the total amount of time passed since the call of run.

 
You should use these handlers to update your in-game objects, check collisions, etc.
@@ -214,7 +220,7 @@ so you can check and/or update it as necessary.

 
Register a callback to render objects. You can add as many subs as you need.
 Returns the order queue number of the added callback.
 All registered callbacks will be triggered in order, once per run of the run loop.

-
The first argument passed is the number of ticks since the previous call.
+
The first argument passed is the time, in seconds, since the previous call.
 The second is the SDLx::Controller object.

 
 sub show_ball {
      my ($delta, $app) = @_;
diff --git a/pages/documentation.html-inc b/pages/documentation.html-inc
index 317ade7..8a9e770 100644
--- a/pages/documentation.html-inc
+++ b/pages/documentation.html-inc
@@ -1,2 +1,2 @@
 

-
Documentation (latest development branch)
Core
thumbSDL- Simple DirectMedia Layer for Perl
thumbSDL::Credits- Authors and contributors of the SDL Perl project
thumbSDL::Deprecated- Log of Deprecated items per release
thumbSDL::Time- An SDL Perl extension for managing timers
Audio
thumbSDL::Audio- SDL Bindings for Audio
Structure
thumbSDL::AudioCVT- Audio Conversion Structure
thumbSDL::AudioSpec- SDL Bindings for structure SDL::AudioSpec
CDROM
thumbSDL::CDROM- SDL Bindings for the CDROM device
Structure
thumbSDL::CD- SDL Bindings for structure SDL_CD
thumbSDL::CDTrack- SDL Bindings for structure SDL_CDTrack
Events
thumbSDL::Events- Bindings to the Events Category in SDL API
Structure
thumbSDL::Event- General event structure
Joystick
thumbSDL::Joystick- SDL Bindings for the Joystick device
Mouse
thumbSDL::Mouse- SDL Bindings for the Mouse device
Structure
thumbSDL::Cursor- Mouse cursor structure
Structure
thumbSDL::Version- SDL Bindings for structure SDL_Version
Video
thumbSDL::Video- Bindings to the video category in SDL API
Structure
thumbSDL::Color- Format independent color description
thumbSDL::Overlay- YUV Video overlay
thumbSDL::Palette- Color palette for 8-bit pixel formats 
thumbSDL::PixelFormat- Stores surface format information
thumbSDL::Rect- Defines a rectangular area
thumbSDL::Surface- Graphic surface structure
thumbSDL::VideoInfo- Video Target Information 

Cookbook
thumbSDL::Cookbook
thumbSDL::Cookbook::OpenGL- Using SDL with OpenGL
thumbSDL::Cookbook::PDL

Extension
thumbSDLx::App- a SDL perl extension
thumbSDLx::Layer- Storage object for surface and position information
thumbSDLx::LayerManager- Extension for managing layers in a 2D world
thumbSDLx::Rect- SDL extension for storing and manipulating rectangular coordinates
thumbSDLx::SFont- Extension making fonts out of images and printing them
thumbSDLx::Sound
thumbSDLx::Sprite- interact with images quick and easily in SDL
thumbSDLx::Sprite::Animated- create animated SDL sprites easily!
thumbSDLx::Surface- Graphic surface matrix extension
Controller
thumbSDLx::Controller- Handles the loops for events, movement and rendering
thumbSDLx::Controller::Interface- Interface Physics and Rendering with the Controller with callbacks
thumbSDLx::Controller::State- the state of a SDLx::Controller::Interface

GFX
thumbSDL::GFX::Framerate- framerate calculating functions
thumbSDL::GFX::Primitives- basic drawing functions
Structure
thumbSDL::GFX::FPSManager- data structure used by SDL::GFX::Framerate

Image
thumbSDL::Image- Bindings for the SDL_Image library

Mixer
thumbSDL::Mixer- Sound and music functions
thumbSDL::Mixer::Channels- SDL::Mixer channel functions and bindings
thumbSDL::Mixer::Effects- sound effect functions
thumbSDL::Mixer::Groups- Audio channel group functions
thumbSDL::Mixer::Music- functions for music
thumbSDL::Mixer::Samples- functions for loading sound samples
Structure
thumbSDL::Mixer::MixChunk- SDL Bindings for structure SDL_MixChunk
thumbSDL::Mixer::MixMusic- SDL Bindings for structure SDL_MixMusic

Pango
thumbSDL::Pango- Text rendering engine
Structure
thumbSDL::Pango::Context- Context object for SDL::Pango

TODO
thumbSDL::MPEG- a SDL perl extension
thumbSDL::SMPEG- a SDL perl extension
MultiThread
thumbSDL::MultiThread- Bindings to the MultiThread category in SDL API
Structure
thumbSDL::RWOps- SDL Bindings to SDL_RWOPs
GFX
thumbSDL::GFX::BlitFunc- blitting functions
thumbSDL::GFX::ImageFilter- image filtering functions
thumbSDL::GFX::Rotozoom- rotation and zooming functions for surfaces

TTF
thumbSDL::TTF- True Type Font functions (libfreetype)
Structure
thumbSDL::TTF::Font- Font object type for SDL_ttf

Tutorials
thumbSDL::Tutorial- introduction to Perl SDL
thumbSDL::Tutorial::Animation
thumbSDL::Tutorial::LunarLander- a small tutorial on Perl SDL

+
Documentation (latest development branch)
Core
thumbSDL- Simple DirectMedia Layer for Perl
thumbSDL::Credits- Authors and contributors of the SDL Perl project
thumbSDL::Deprecated- Log of Deprecated items per release
thumbSDL::Time- An SDL Perl extension for managing timers
Audio
thumbSDL::Audio- SDL Bindings for Audio
Structure
thumbSDL::AudioCVT- Audio Conversion Structure
thumbSDL::AudioSpec- SDL Bindings for structure SDL::AudioSpec
CDROM
thumbSDL::CDROM- SDL Bindings for the CDROM device
Structure
thumbSDL::CD- SDL Bindings for structure SDL_CD
thumbSDL::CDTrack- SDL Bindings for structure SDL_CDTrack
Events
thumbSDL::Events- Bindings to the Events Category in SDL API
Structure
thumbSDL::Event- General event structure
Joystick
thumbSDL::Joystick- SDL Bindings for the Joystick device
Mouse
thumbSDL::Mouse- SDL Bindings for the Mouse device
Structure
thumbSDL::Cursor- Mouse cursor structure
Structure
thumbSDL::Version- SDL Bindings for structure SDL_Version
Video
thumbSDL::Video- Bindings to the video category in SDL API
Structure
thumbSDL::Color- Format independent color description
thumbSDL::Overlay- YUV Video overlay
thumbSDL::Palette- Color palette for 8-bit pixel formats 
thumbSDL::PixelFormat- Stores surface format information
thumbSDL::Rect- Defines a rectangular area
thumbSDL::Surface- Graphic surface structure
thumbSDL::VideoInfo- Video Target Information 

Cookbook
thumbSDL::Cookbook
thumbSDL::Cookbook::OpenGL- Using SDL with OpenGL
thumbSDL::Cookbook::PDL

Extension
thumbSDLx::App- a SDL perl extension
thumbSDLx::Layer- Storage object for surface and position information
thumbSDLx::LayerManager- Extension for managing layers in a 2D world
thumbSDLx::Rect- SDL extension for storing and manipulating rectangular coordinates
thumbSDLx::SFont- Extension making fonts out of images and printing them
thumbSDLx::Sound
thumbSDLx::Sprite- interact with images quick and easily in SDL
thumbSDLx::Sprite::Animated- create animated SDL sprites easily!
thumbSDLx::Surface- Graphic surface matrix extension
Controller
thumbSDLx::Controller- Handles the loops for events, movement and rendering
thumbSDLx::Controller::Interface- Interface Physics and Rendering with the Controller with callbacks
thumbSDLx::Controller::State- the state of a SDLx::Controller::Interface

GFX
thumbSDL::GFX::Framerate- framerate calculating functions
thumbSDL::GFX::Primitives- basic drawing functions
Structure
thumbSDL::GFX::FPSManager- data structure used by SDL::GFX::Framerate

Image
thumbSDL::Image- Bindings for the SDL_Image library

Mixer
thumbSDL::Mixer- Sound and music functions
thumbSDL::Mixer::Channels- SDL::Mixer channel functions and bindings
thumbSDL::Mixer::Effects- sound effect functions
thumbSDL::Mixer::Groups- Audio channel group functions
thumbSDL::Mixer::Music- functions for music
thumbSDL::Mixer::Samples- functions for loading sound samples
Structure
thumbSDL::Mixer::MixChunk- SDL Bindings for structure SDL_MixChunk
thumbSDL::Mixer::MixMusic- SDL Bindings for structure SDL_MixMusic

Pango
thumbSDL::Pango- Text rendering engine
Structure
thumbSDL::Pango::Context- Context object for SDL::Pango

TODO
thumbSDL::MPEG- a SDL perl extension
thumbSDL::SMPEG- a SDL perl extension
MultiThread
thumbSDL::MultiThread- Bindings to the MultiThread category in SDL API
Structure
thumbSDL::RWOps- SDL Bindings to SDL_RWOPs
GFX
thumbSDL::GFX::BlitFunc- blitting functions
thumbSDL::GFX::ImageFilter- image filtering functions
thumbSDL::GFX::Rotozoom- rotation and zooming functions for surfaces

TTF
thumbSDL::TTF- True Type Font functions (libfreetype)
Structure
thumbSDL::TTF::Font- Font object type for SDL_ttf

Tutorials
thumbSDL::Tutorial- introduction to Perl SDL
thumbSDL::Tutorial::Animation
thumbSDL::Tutorial::LunarLander- a small tutorial on Perl SDL