Commit | Line | Data |
807ae0cd |
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 => 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->new; |
46 | |
47 | # register some callbacks |
48 | $app->add_event_handler( \&on_event ); |
49 | $app->add_move_handler( \&on_move ); |
50 | $app->add_show_handler( \&on_show ); |
51 | |
52 | # run our game loop |
53 | $app->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 => 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->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 "run" 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> |
505f308d |
170 | <p>You can also pass a coderef. |
171 | The first coderef in the handler list that this matches will be removed.</p> |
807ae0cd |
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 | |
193 | |
194 | |
195 | |
196 | </div> |
197 | <h1 id="AUTHORS">AUTHORS</h1><p><a href="#TOP" class="toplink">Top</a></p> |
198 | <div id="AUTHORS_CONTENT"> |
199 | <p>Kartik Thakore</p> |
200 | <p>Breno G. de Oliveira</p> |
201 | |
202 | </div> |
203 | <h2 id="ACKNOWLEGDEMENTS">ACKNOWLEGDEMENTS</h2> |
204 | <div id="ACKNOWLEGDEMENTS_CONTENT"> |
205 | <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, |
206 | and Glenn Fiedler's <a href="http://gafferongames.com/game-physics/fix-your-timestep/">Fix Your Timestep</a> article on timing.</p> |
207 | |
208 | |
209 | |
210 | |
211 | |
212 | |
213 | |
214 | |
215 | |
216 | |
217 | |
218 | </div> |
219 | </div> |