
=head1 NAME

SDLx::Controller - Handles the loops for event, movement and rendering

=head1 SYNOPSIS

  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;


=head2 DESCRIPTION

The core of a 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) {
      ...
  }

The problem most developers face, besides the repetitive work, is to ensure
the screen update is independent of the frame rate. Otherwise, your game will
run at different speeds on different machines and this is never good (old
MS-DOS games, anyone?).

One way to circumveint this is by capping the frame rate so it's the same no
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
than frame rate. You can add/remove handlers and control your main loop with
ease.

=head1 METHODS

=head2 new

=head2 new( dt => 0.5 )

Controller construction. Optional C<dt> parameter indicates delta t times
in which to call the movement handlers, and defaults to 0.1.

Returns the new object.

=head2 run

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.

All hooked functions will be called during the main loop, in this order:

=over 4

=item 1. Events

=item 2. Movements

=item 3. Displaying

=back

Please refer to each handler below for information on received arguments.

=head2 add_event_handler

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
L<< SDL::Event >> object itself, so you can test for C<< $event->type >>, etc.

Each event handler is B<required> to return a defined value for the main loop
to continue. To exit the main loop (see "run" above), return C<undef> or
nothing at all.


=head2 add_move_handler

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
C<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,
so you can check and/or update it as necessary.

Any returned values are ignored.


=head2 add_show_handler

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.

=head2 quit

Exits the main loop. Calling this method will cause C<< run >> to return.

=head2 remove_move_handler( $index )

=head2 remove_event_handler( $index )

=head2 remove_show_handler( $index )

Removes the handler with the given index from the respective calling queue.

You can also pass a coderef.
The first coderef in the handler list that this matches will be removed.

Returns the removed handler.

=head2 remove_all_move_handlers

=head2 remove_all_event_handlers

=head2 remove_all_show_handlers

Removes all handlers from the respective calling queue.

=head2 remove_all_handlers

Quick access to removing all handlers at once.

=head1 AUTHORS

See L<SDL/AUTHORS>.

=head2 ACKNOWLEGDEMENTS

The idea and base for this module comes from Lazy Foo's L<< Frame Independent
Movement|http://www.lazyfoo.net/SDL_tutorials/lesson32/index.php >> tutorial,
and Glenn Fiedler's L<< Fix Your Timestep|http://gafferongames.com/game-physics/fix-your-timestep/ >> article on timing.




