pages/SDLx-Controller.html-inc

   1 <div class="pod">
   2 <!-- INDEX START -->
   3 <h3 id="TOP">Index</h3>
   4
   5 <ul><li><a href="#NAME">NAME</a></li>
   6 <li><a href="#SYNOPSIS">SYNOPSIS</a>
   7 <ul><li><a href="#DESCRIPTION">DESCRIPTION</a></li>
   8 </ul>
   9 </li>
  10 <li><a href="#METHODS">METHODS</a>
  11 <ul><li><a href="#new">new</a></li>
  12 <li><a href="#new_dt_gt_0_5">new( dt =&gt; 0.5 )</a></li>
  13 <li><a href="#run">run</a></li>
  14 <li><a href="#add_event_handler">add_event_handler</a></li>
  15 <li><a href="#add_move_handler">add_move_handler</a></li>
  16 <li><a href="#add_show_handler">add_show_handler</a></li>
  17 <li><a href="#quit">quit</a></li>
  18 <li><a href="#remove_move_handler_index">remove_move_handler( $index )</a></li>
  19 <li><a href="#remove_event_handler_index">remove_event_handler( $index )</a></li>
  20 <li><a href="#remove_show_handler_index">remove_show_handler( $index )</a></li>
  21 <li><a href="#remove_all_move_handlers">remove_all_move_handlers</a></li>
  22 <li><a href="#remove_all_event_handlers">remove_all_event_handlers</a></li>
  23 <li><a href="#remove_all_show_handlers">remove_all_show_handlers</a></li>
  24 <li><a href="#remove_all_handlers">remove_all_handlers</a></li>
  25 </ul>
  26 </li>
  27 <li><a href="#AUTHORS">AUTHORS</a>
  28 <ul><li><a href="#ACKNOWLEGDEMENTS">ACKNOWLEGDEMENTS</a>
  29 </li>
  30 </ul>
  31 </li>
  32 </ul><hr />
  33 <!-- INDEX END -->
  34
  35 <h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
  36 <div id="NAME_CONTENT">
  37 <p>SDLx::Controller - Handles the loops for event, movement and rendering</p>
  38
  39 </div>
  40 <h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
  41 <div id="SYNOPSIS_CONTENT">
  42 <pre>  use SDLx::Controller
  43
  44   # create our controller object
  45   my $app = SDLx::Controller-&gt;new;
  46
  47   # register some callbacks
  48   $app-&gt;add_event_handler( \&amp;on_event );
  49   $app-&gt;add_move_handler( \&amp;on_move );
  50   $app-&gt;add_show_handler( \&amp;on_show );
  51
  52   # run our game loop
  53   $app-&gt;run;
  54
  55
  56
  57
  58 </pre>
  59
  60 </div>
  61 <h2 id="DESCRIPTION">DESCRIPTION</h2>
  62 <div id="DESCRIPTION_CONTENT">
  63 <p>The core of a SDL application/game is the main loop, where you handle events
  64 and display your elements on the screen until something signals the end of
  65 the program. This usually goes in the form of:</p>
  66 <pre>  while (1) {
  67       ...
  68   }
  69
  70 </pre>
  71 <p>The problem most developers face, besides the repetitive work, is to ensure
  72 the screen update is independent of the frame rate. Otherwise, your game will
  73 run at different speeds on different machines and this is never good (old
  74 MS-DOS games, anyone?).</p>
  75 <p>One way to circumveint this is by capping the frame rate so it's the same no
  76 matter what, but this is not the right way to do it as it penalizes better
  77 hardware.</p>
  78 <p>This module provides an industry-proven standard for frame independent
  79 movement. It calls the movement handlers based on time (tick counts) rather
  80 than frame rate. You can add/remove handlers and control your main loop with
  81 ease.</p>
  82
  83 </div>
  84 <h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
  85 <div id="METHODS_CONTENT">
  86
  87 </div>
  88 <h2 id="new">new</h2>
  89 <div id="new_CONTENT">
  90
  91 </div>
  92 <h2 id="new_dt_gt_0_5">new( dt =&gt; 0.5 )</h2>
  93 <div id="new_dt_gt_0_5_CONTENT">
  94 <p>Controller construction. Optional <code>dt</code> parameter indicates delta t times
  95 in which to call the movement handlers, and defaults to 0.1.</p>
  96 <p>Returns the new object.</p>
  97
  98 </div>
  99 <h2 id="run">run</h2>
 100 <div id="run_CONTENT">
 101 <p>After creating and setting up your handlers (see below), call this method to
 102 activate the main loop. The main loop will run until an event handler returns
 103 undef.</p>
 104 <p>All hooked functions will be called during the main loop, in this order:</p>
 105 <dl>
 106         <dt>1. Events</dt>
 107         <dt>2. Movements</dt>
 108         <dt>3. Displaying</dt>
 109 </dl>
 110 <p>Please refer to each handler below for information on received arguments.</p>
 111
 112 </div>
 113 <h2 id="add_event_handler">add_event_handler</h2>
 114 <div id="add_event_handler_CONTENT">
 115 <p>Register a callback to handle events. You can add as many subs as you need.
 116 Whenever a SDL::Event occurs, all registered callbacks will be triggered in
 117 order. Returns the order queue number of the added callback.</p>
 118 <p>The first (and only) argument passed to registered callbacks is the
 119 <a href="SDL-Event.html">SDL::Event</a> object itself, so you can test for <code>$event-&gt;type</code>, etc.</p>
 120 <p>Each event handler is <strong>required</strong> to return a defined value for the main loop
 121 to continue. To exit the main loop (see &quot;run&quot; above), return <code>undef</code> or
 122 nothing at all.</p>
 123
 124
 125
 126
 127
 128 </div>
 129 <h2 id="add_move_handler">add_move_handler</h2>
 130 <div id="add_move_handler_CONTENT">
 131 <p>Register a callback to update your objects. You can add as many subs as
 132 you need. Returns the order queue number of the added callback.</p>
 133 <p>All registered callbacks will be triggered in order for as many
 134 <code>dt</code> as have happened between calls. You should use these handlers to update
 135 your in-game objects, check collisions, etc.</p>
 136 <p>The first (and only) argument passed is a reference to the dt value itself,
 137 so you can check and/or update it as necessary.</p>
 138 <p>Any returned values are ignored.</p>
 139
 140
 141
 142
 143
 144 </div>
 145 <h2 id="add_show_handler">add_show_handler</h2>
 146 <div id="add_show_handler_CONTENT">
 147 <p>Register a callback to render objects. You can add as many subs as you need.
 148 Returns the order queue number of the added callback.</p>
 149 <p>All registered callbacks will be triggered in order, once per run of the main
 150 loop. The first (and only) argument passed is the number of ticks since
 151 the previous round.</p>
 152
 153 </div>
 154 <h2 id="quit">quit</h2>
 155 <div id="quit_CONTENT">
 156 <p>Exits the main loop. Calling this method will cause <code>run</code> to return.</p>
 157
 158 </div>
 159 <h2 id="remove_move_handler_index">remove_move_handler( $index )</h2>
 160 <div id="remove_move_handler_index_CONTENT">
 161
 162 </div>
 163 <h2 id="remove_event_handler_index">remove_event_handler( $index )</h2>
 164 <div id="remove_event_handler_index_CONTENT">
 165
 166 </div>
 167 <h2 id="remove_show_handler_index">remove_show_handler( $index )</h2>
 168 <div id="remove_show_handler_index_CONTENT">
 169 <p>Removes the handler with the given index from the respective calling queue.</p>
 170 <p>You can also pass a coderef.
 171 The first coderef in the handler list that this matches will be removed.</p>
 172 <p>Returns the removed handler.</p>
 173
 174 </div>
 175 <h2 id="remove_all_move_handlers">remove_all_move_handlers</h2>
 176 <div id="remove_all_move_handlers_CONTENT">
 177
 178 </div>
 179 <h2 id="remove_all_event_handlers">remove_all_event_handlers</h2>
 180 <div id="remove_all_event_handlers_CONTENT">
 181
 182 </div>
 183 <h2 id="remove_all_show_handlers">remove_all_show_handlers</h2>
 184 <div id="remove_all_show_handlers_CONTENT">
 185 <p>Removes all handlers from the respective calling queue.</p>
 186
 187 </div>
 188 <h2 id="remove_all_handlers">remove_all_handlers</h2>
 189 <div id="remove_all_handlers_CONTENT">
 190 <p>Quick access to removing all handlers at once.</p>
 191
 192 </div>
 193 <h1 id="AUTHORS">AUTHORS</h1><p><a href="#TOP" class="toplink">Top</a></p>
 194 <div id="AUTHORS_CONTENT">
 195 <p>See <b>AUTHORS</b> in <cite>SDL</cite>.</p>
 196
 197 </div>
 198 <h2 id="ACKNOWLEGDEMENTS">ACKNOWLEGDEMENTS</h2>
 199 <div id="ACKNOWLEGDEMENTS_CONTENT">
 200 <p>The idea and base for this module comes from Lazy Foo's <a href="http://www.lazyfoo.net/SDL_tutorials/lesson32/index.php">Frame Independent Movement</a> tutorial,
 201 and Glenn Fiedler's <a href="http://gafferongames.com/game-physics/fix-your-timestep/">Fix Your Timestep</a> article on timing.</p>
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213 </div>
 214 </div>