X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pages%2FSDLx-Controller.html-inc;h=3851fa24685029fe2e3dd06a8220d065d803baa6;hb=a3de848879a5553418ed11fb193c4bf286ca7120;hp=ecfccd09913727df09033303759e740be4bb8a2a;hpb=c7e8d3c612049580c9a96b3006c4c89a00410643;p=sdlgit%2FSDL-Site.git diff --git a/pages/SDLx-Controller.html-inc b/pages/SDLx-Controller.html-inc index ecfccd0..3851fa2 100644 --- a/pages/SDLx-Controller.html-inc +++ b/pages/SDLx-Controller.html-inc @@ -3,18 +3,19 @@
SDLx::Controller - Handles the loops for event, movement and rendering
+SDLx::Controller - Handles the loops for events, movement and rendering
+ +Extension, Controller
use SDLx::Controller +use SDLx::Controller; # create our controller object my $app = SDLx::Controller->new; @@ -76,7 +85,7 @@ MS-DOS games, anyone?). matter what, but this is not the right way to do it as it penalizes better hardware.This module provides an industry-proven standard for frame independent -movement. It calls the movement handlers based on time (tick counts) rather +movement. It calls the movement handlers based on time (hi-res seconds) rather than frame rate. You can add/remove handlers and control your main loop with ease.
@@ -87,27 +96,76 @@ ease.
SDLx::Controller->new( + dt => 0.5, + min_t => 0, + event => $event_object, + ); -
Controller construction. Optional dt
parameter indicates delta t times
-in which to call the movement handlers, and defaults to 0.1.
The dt
parameter specifies the length, in seconds, of a full movement step, and defaults to 0.1.
+The dt
can be anything and the game can still look the same.
+It is only when you change the dt
without changing all the things in the movement step that are being multiplied by the first move argument that it will make a difference.
+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.
+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()
.
All parameters are optional.
Returns the new object.
After creating and setting up your handlers (see below), call this method to -activate the main loop. The main loop will run until an event handler returns -undef.
+activate the main loop. The main loop will run untilstop
is called.
All hooked functions will be called during the main loop, in this order:
Please refer to each handler below for information on received arguments.
+Please refer to each handler below for information on received arguments.
+Note that the second argument every callback recieves is the SDLx::Controller
object.
Returns from the run
loop.
Attempts to pause the application with a call to SDL::Events::wait_event
. See SDL::Events.
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.
This can be used to easily implement a pause when the app loses focus:
+sub focus { + my ($e, $controller) = @_; + if($e->type == SDL_ACTIVEEVENT) { + if($e->active_state & SDL_APPINPUTFOCUS) { + if($e->active_gain) { + return 1; + } + else { + $controller->pause(\&focus); + # recursive, but only once since the window + # can't lose focus again without gaining is first + } + } + } + return 0; + } + ++
Note: if you implement your own pause function, remember to update current_time
to the current time when the application unpauses.
+This should be done with Time::HiRes::time
.
+Otherwise, time will accumulate while the application is paused, and many movement steps will be called all at once when it unpauses.
Note 2: a pause will be potentially dangerous to the run
cycle (even if you implement your own) unless called by an event
callback.
Register a callback to handle events. You can add as many subs as you need. Whenever a SDL::Event occurs, all registered callbacks will be triggered in order. Returns the order queue number of the added callback.
-The first (and only) argument passed to registered callbacks is the
-SDL::Event object itself, so you can test for $event->type
, etc.
Each event handler is required to return a defined value for the main loop
-to continue. To exit the main loop (see "run" above), return undef
or
-nothing at all.
The first argument passed to registered callbacks is the SDL::Event object.
+The second is the SDLx::Controller
object.
sub stop { + my ($event, $app) = @_; + if($event->type == SDL_QUIT) { + $controller->stop; + } + } + $controller->add_event_handler(\&stop); +
Register a callback to update your 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 for as many
-dt
as have happened between calls. You should use these handlers to update
-your in-game objects, check collisions, etc.
The first (and only) argument passed is a reference to the dt value itself, +
All registered callbacks will be triggered in order for as many dt
as have happened between calls,
+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 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. so you can check and/or update it as necessary.
-Any returned values are ignored.
- - - +sub move_ball { + my ($step, $app, $t) = @_; + $ball->move_x( $ball->x_vel * $step ); + $ball->move_y( $ball->y_vel * $step ); + } +
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 main -loop. The first (and only) argument passed is the number of ticks since -the previous round.
+Returns the order queue number of the added callback. +All registered callbacks will be triggered in order, once per run of therun
loop.
+The first argument passed is the number of ticks since the previous call.
+The second is the SDLx::Controller
object.
sub show_ball { + my ($delta, $app) = @_; + $app->draw_rect( + [ $ball->x, $ball->y, $ball->size, $ball->size ], + $ball->colour + ); + } -
Exits the main loop. Calling this method will cause run
to return.
Quick access to removing all handlers at once.
+If an argument is passed, modifies the corresponding value to the argument.
+dt
and min_t
will keep their old value until the beginning of the next run
cycle.
Returns the corresponding value.
+ +See AUTHORS in SDL.