SDLx::Controller - Handles the loops for event, movement and rendering
+SDLx::Controller - Handles the loops for events, movement and rendering
use SDLx::Controller +use SDLx::Controller; # create our controller object my $app = SDLx::Controller->new; @@ -76,7 +79,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 +90,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.