[sdl_omap.git] / docs / html / sdladdtimer.html

<HTML
><HEAD
><TITLE
>SDL_AddTimer</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
REL="HOME"
TITLE="SDL Library Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="Time"
HREF="time.html"><LINK
REL="PREVIOUS"
TITLE="SDL_Delay"
HREF="sdldelay.html"><LINK
REL="NEXT"
TITLE="SDL_RemoveTimer"
HREF="sdlremovetimer.html"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFF8DC"
TEXT="#000000"
LINK="#0000ee"
VLINK="#551a8b"
ALINK="#ff0000"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>SDL Library Documentation</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="sdldelay.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="sdlremovetimer.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="SDLADDTIMER"
></A
>SDL_AddTimer</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN8482"
></A
><H2
>Name</H2
>SDL_AddTimer&nbsp;--&nbsp;Add a timer which will call a callback after the specified number of milliseconds has
elapsed.</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN8485"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN8486"
></A
><P
></P
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include "SDL.h"</PRE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>SDL_TimerID <B
CLASS="FSFUNC"
>SDL_AddTimer</B
></CODE
>(Uint32 interval, SDL_NewTimerCallback callback, void *param);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="SDLNEWTIMERCALLBACK"
></A
><H2
>Callback</H2
><PRE
CLASS="PROGRAMLISTING"
>/* type definition for the "new" timer callback function */
typedef Uint32 (*SDL_NewTimerCallback)(Uint32 interval, void *param);</PRE
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8495"
></A
><H2
>Description</H2
><P
>Adds a callback function to be run after the specified number of
milliseconds has elapsed. The callback function is passed the current
timer interval and the user supplied parameter from the
<TT
CLASS="FUNCTION"
>SDL_AddTimer</TT
> call and returns the next timer
interval. If the returned value from the callback is the same as the one
passed in, the periodic alarm continues, otherwise a new alarm is
scheduled.</P
><P
>To cancel a currently running timer call
<A
HREF="sdlremovetimer.html"
>SDL_RemoveTimer</A
> with the
timer ID returned from
<TT
CLASS="FUNCTION"
>SDL_AddTimer</TT
>.</P
><P
>The timer callback function may run in a different thread than your
main program, and so shouldn't call any functions from within itself.
You may always call <A
HREF="sdlpushevent.html"
>SDL_PushEvent</A
>, however.</P
><P
>The granularity of the timer is platform-dependent, but you should count
on it being at least 10 ms as this is the most common number.
This means that if
you request a 16 ms timer, your callback will run approximately 20 ms
later on an unloaded system.  If you wanted to set a flag signaling
a frame update at 30 frames per second (every 33 ms), you might set a
timer for 30 ms (see example below).

If you use this function, you need to pass <TT
CLASS="LITERAL"
>SDL_INIT_TIMER</TT
>
to <A
HREF="sdlinit.html"
>SDL_Init</A
>.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8507"
></A
><H2
>Return Value</H2
><P
>Returns an ID value for the added timer or
<SPAN
CLASS="RETURNVALUE"
>NULL</SPAN
> if there was an error.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8511"
></A
><H2
>Examples</H2
><P
><PRE
CLASS="PROGRAMLISTING"
>my_timer_id = SDL_AddTimer((33/10)*10, my_callbackfunc, my_callback_param);</PRE
></P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8515"
></A
><H2
>See Also</H2
><P
><A
HREF="sdlremovetimer.html"
><TT
CLASS="FUNCTION"
>SDL_RemoveTimer</TT
></A
>,
<A
HREF="sdlpushevent.html"
><TT
CLASS="FUNCTION"
>SDL_PushEvent</TT
></A
></P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="sdldelay.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="sdlremovetimer.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>SDL_Delay</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="time.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>SDL_RemoveTimer</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
Commit	Line	Data
e14743d1	1	<HTML
	2	><HEAD
	3	><TITLE
	4	>SDL_AddTimer</TITLE
	5	><META
	6	NAME="GENERATOR"
	7	CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
	8	"><LINK
	9	REL="HOME"
	10	TITLE="SDL Library Documentation"
	11	HREF="index.html"><LINK
	12	REL="UP"
	13	TITLE="Time"
	14	HREF="time.html"><LINK
	15	REL="PREVIOUS"
	16	TITLE="SDL_Delay"
	17	HREF="sdldelay.html"><LINK
	18	REL="NEXT"
	19	TITLE="SDL_RemoveTimer"
	20	HREF="sdlremovetimer.html"></HEAD
	21	><BODY
	22	CLASS="REFENTRY"
	23	BGCOLOR="#FFF8DC"
	24	TEXT="#000000"
	25	LINK="#0000ee"
	26	VLINK="#551a8b"
	27	ALINK="#ff0000"
	28	><DIV
	29	CLASS="NAVHEADER"
	30	><TABLE
	31	SUMMARY="Header navigation table"
	32	WIDTH="100%"
	33	BORDER="0"
	34	CELLPADDING="0"
	35	CELLSPACING="0"
	36	><TR
	37	><TH
	38	COLSPAN="3"
	39	ALIGN="center"
	40	>SDL Library Documentation</TH
	41	></TR
	42	><TR
	43	><TD
	44	WIDTH="10%"
	45	ALIGN="left"
	46	VALIGN="bottom"
	47	><A
	48	HREF="sdldelay.html"
	49	ACCESSKEY="P"
	50	>Prev</A
	51	></TD
	52	><TD
	53	WIDTH="80%"
	54	ALIGN="center"
	55	VALIGN="bottom"
	56	></TD
	57	><TD
	58	WIDTH="10%"
	59	ALIGN="right"
	60	VALIGN="bottom"
	61	><A
	62	HREF="sdlremovetimer.html"
	63	ACCESSKEY="N"
	64	>Next</A
65	></TD
66	></TR
67	></TABLE
68	><HR
69	ALIGN="LEFT"
70	WIDTH="100%"></DIV
71	><H1
72	><A
73	NAME="SDLADDTIMER"
74	></A
75	>SDL_AddTimer</H1
76	><DIV
77	CLASS="REFNAMEDIV"
78	><A
79	NAME="AEN8482"
80	></A
81	><H2
82	>Name</H2
83	>SDL_AddTimer -- Add a timer which will call a callback after the specified number of milliseconds has
84	elapsed.</DIV
85	><DIV
86	CLASS="REFSYNOPSISDIV"
87	><A
88	NAME="AEN8485"
89	></A
90	><H2
91	>Synopsis</H2
92	><DIV
93	CLASS="FUNCSYNOPSIS"
94	><A
95	NAME="AEN8486"
96	></A
97	><P
98	></P
99	><PRE
100	CLASS="FUNCSYNOPSISINFO"
101	>#include "SDL.h"</PRE
102	><P
103	><CODE
104	><CODE
105	CLASS="FUNCDEF"
106	>SDL_TimerID <B
107	CLASS="FSFUNC"
108	>SDL_AddTimer</B
109	></CODE
110	>(Uint32 interval, SDL_NewTimerCallback callback, void *param);</CODE
111	></P
112	><P
113	></P
114	></DIV
115	></DIV
116	><DIV
117	CLASS="REFSECT1"
118	><A
119	NAME="SDLNEWTIMERCALLBACK"
120	></A
121	><H2
122	>Callback</H2
123	><PRE
124	CLASS="PROGRAMLISTING"
125	>/* type definition for the "new" timer callback function */
126	typedef Uint32 (SDL_NewTimerCallback)(Uint32 interval, void param);</PRE
127	></DIV
128	><DIV
129	CLASS="REFSECT1"
130	><A
131	NAME="AEN8495"
132	></A
133	><H2
134	>Description</H2
135	><P
136	>Adds a callback function to be run after the specified number of
137	milliseconds has elapsed. The callback function is passed the current
138	timer interval and the user supplied parameter from the
139	<TT
140	CLASS="FUNCTION"
141	>SDL_AddTimer</TT
142	> call and returns the next timer
143	interval. If the returned value from the callback is the same as the one
144	passed in, the periodic alarm continues, otherwise a new alarm is
145	scheduled.</P
146	><P
147	>To cancel a currently running timer call
148	<A
149	HREF="sdlremovetimer.html"
150	>SDL_RemoveTimer</A
151	> with the
152	timer ID returned from
153	<TT
154	CLASS="FUNCTION"
155	>SDL_AddTimer</TT
156	>.</P
157	><P
158	>The timer callback function may run in a different thread than your
159	main program, and so shouldn't call any functions from within itself.
160	You may always call <A
161	HREF="sdlpushevent.html"
162	>SDL_PushEvent</A
163	>, however.</P
164	><P
165	>The granularity of the timer is platform-dependent, but you should count
166	on it being at least 10 ms as this is the most common number.
167	This means that if
168	you request a 16 ms timer, your callback will run approximately 20 ms
169	later on an unloaded system. If you wanted to set a flag signaling
170	a frame update at 30 frames per second (every 33 ms), you might set a
171	timer for 30 ms (see example below).
172
173	If you use this function, you need to pass <TT
174	CLASS="LITERAL"
175	>SDL_INIT_TIMER</TT
176	>
177	to <A
178	HREF="sdlinit.html"
179	>SDL_Init</A
180	>.</P
181	></DIV
182	><DIV
183	CLASS="REFSECT1"
184	><A
185	NAME="AEN8507"
186	></A
187	><H2
188	>Return Value</H2
189	><P
190	>Returns an ID value for the added timer or
191	<SPAN
192	CLASS="RETURNVALUE"
193	>NULL</SPAN
194	> if there was an error.</P
195	></DIV
196	><DIV
197	CLASS="REFSECT1"
198	><A
199	NAME="AEN8511"
200	></A
201	><H2
202	>Examples</H2
203	><P
204	><PRE
205	CLASS="PROGRAMLISTING"
206	>my_timer_id = SDL_AddTimer((33/10)*10, my_callbackfunc, my_callback_param);</PRE
207	></P
208	></DIV
209	><DIV
210	CLASS="REFSECT1"
211	><A
212	NAME="AEN8515"
213	></A
214	><H2
215	>See Also</H2
216	><P
217	><A
218	HREF="sdlremovetimer.html"
219	><TT
220	CLASS="FUNCTION"
221	>SDL_RemoveTimer</TT
222	></A
223	>,
224	<A
225	HREF="sdlpushevent.html"
226	><TT
227	CLASS="FUNCTION"
228	>SDL_PushEvent</TT
229	></A
230	></P
231	></DIV
232	><DIV
233	CLASS="NAVFOOTER"
234	><HR
235	ALIGN="LEFT"
236	WIDTH="100%"><TABLE
237	SUMMARY="Footer navigation table"
238	WIDTH="100%"
239	BORDER="0"
240	CELLPADDING="0"
241	CELLSPACING="0"
242	><TR
243	><TD
244	WIDTH="33%"
245	ALIGN="left"
246	VALIGN="top"
247	><A
248	HREF="sdldelay.html"
249	ACCESSKEY="P"
250	>Prev</A
251	></TD
252	><TD
253	WIDTH="34%"
254	ALIGN="center"
255	VALIGN="top"
256	><A
257	HREF="index.html"
258	ACCESSKEY="H"
259	>Home</A
260	></TD
261	><TD
262	WIDTH="33%"
263	ALIGN="right"
264	VALIGN="top"
265	><A
266	HREF="sdlremovetimer.html"
267	ACCESSKEY="N"
268	>Next</A
269	></TD
270	></TR
271	><TR
272	><TD
273	WIDTH="33%"
274	ALIGN="left"
275	VALIGN="top"
276	>SDL_Delay</TD
277	><TD
278	WIDTH="34%"
279	ALIGN="center"
280	VALIGN="top"
281	><A
282	HREF="time.html"
283	ACCESSKEY="U"
284	>Up</A
285	></TD
286	><TD
287	WIDTH="33%"
288	ALIGN="right"
289	VALIGN="top"
290	>SDL_RemoveTimer</TD
291	></TR
292	></TABLE
293	></DIV
294	></BODY
295	></HTML
296	>