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

<HTML
><HEAD
><TITLE
>SDL_SetTimer</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_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="sdlremovetimer.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
>&nbsp;</TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="SDLSETTIMER"
></A
>SDL_SetTimer</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN8557"
></A
><H2
>Name</H2
>SDL_SetTimer&nbsp;--&nbsp;Set a callback to run after the specified number of milliseconds has
elapsed.</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN8560"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN8561"
></A
><P
></P
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include "SDL.h"</PRE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int <B
CLASS="FSFUNC"
>SDL_SetTimer</B
></CODE
>(Uint32 interval, SDL_TimerCallback callback);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="SDLTIMERCALLBACK"
></A
><H2
>Callback</H2
><P
>/* Function prototype for the timer callback function */
typedef Uint32 (*SDL_TimerCallback)(Uint32 interval);</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8570"
></A
><H2
>Description</H2
><P
>Set a callback to run after the specified number of milliseconds has
elapsed. The callback function is passed the current timer interval
and returns the next timer interval.  If the returned value 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
<TT
CLASS="FUNCTION"
>SDL_SetTimer(0, NULL);</TT
></P
><P
>The timer callback function may run in a different thread than your
main constant, and so shouldn't call any functions from within itself.</P
><P
>The maximum resolution of this timer is 10 ms, which 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).</P
><P
>If you use this function, you need to pass <TT
CLASS="LITERAL"
>SDL_INIT_TIMER</TT
>
to <TT
CLASS="FUNCTION"
>SDL_Init()</TT
>.</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>This function is kept for compatibility but has been superseded
by the new timer functions
<A
HREF="sdladdtimer.html"
>SDL_AddTimer</A
> and
<A
HREF="sdlremovetimer.html"
>SDL_RemoveTimer</A
> which support
multiple timers.</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8584"
></A
><H2
>Examples</H2
><P
><PRE
CLASS="PROGRAMLISTING"
>SDL_SetTimer((33/10)*10, my_callback);</PRE
></P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8588"
></A
><H2
>See Also</H2
><P
><A
HREF="sdladdtimer.html"
><TT
CLASS="FUNCTION"
>SDL_AddTimer</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="sdlremovetimer.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"
>&nbsp;</TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>SDL_RemoveTimer</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="time.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>&nbsp;</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
Commit	Line	Data
e14743d1	1	<HTML
	2	><HEAD
	3	><TITLE
	4	>SDL_SetTimer</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_RemoveTimer"
	17	HREF="sdlremovetimer.html"></HEAD
	18	><BODY
	19	CLASS="REFENTRY"
	20	BGCOLOR="#FFF8DC"
	21	TEXT="#000000"
	22	LINK="#0000ee"
	23	VLINK="#551a8b"
	24	ALINK="#ff0000"
	25	><DIV
	26	CLASS="NAVHEADER"
	27	><TABLE
	28	SUMMARY="Header navigation table"
	29	WIDTH="100%"
	30	BORDER="0"
	31	CELLPADDING="0"
	32	CELLSPACING="0"
	33	><TR
	34	><TH
	35	COLSPAN="3"
	36	ALIGN="center"
	37	>SDL Library Documentation</TH
	38	></TR
	39	><TR
	40	><TD
	41	WIDTH="10%"
	42	ALIGN="left"
	43	VALIGN="bottom"
	44	><A
	45	HREF="sdlremovetimer.html"
	46	ACCESSKEY="P"
	47	>Prev</A
	48	></TD
	49	><TD
	50	WIDTH="80%"
	51	ALIGN="center"
	52	VALIGN="bottom"
	53	></TD
	54	><TD
	55	WIDTH="10%"
	56	ALIGN="right"
	57	VALIGN="bottom"
	58	> </TD
	59	></TR
	60	></TABLE
	61	><HR
	62	ALIGN="LEFT"
	63	WIDTH="100%"></DIV
	64	><H1
65	><A
66	NAME="SDLSETTIMER"
67	></A
68	>SDL_SetTimer</H1
69	><DIV
70	CLASS="REFNAMEDIV"
71	><A
72	NAME="AEN8557"
73	></A
74	><H2
75	>Name</H2
76	>SDL_SetTimer -- Set a callback to run after the specified number of milliseconds has
77	elapsed.</DIV
78	><DIV
79	CLASS="REFSYNOPSISDIV"
80	><A
81	NAME="AEN8560"
82	></A
83	><H2
84	>Synopsis</H2
85	><DIV
86	CLASS="FUNCSYNOPSIS"
87	><A
88	NAME="AEN8561"
89	></A
90	><P
91	></P
92	><PRE
93	CLASS="FUNCSYNOPSISINFO"
94	>#include "SDL.h"</PRE
95	><P
96	><CODE
97	><CODE
98	CLASS="FUNCDEF"
99	>int <B
100	CLASS="FSFUNC"
101	>SDL_SetTimer</B
102	></CODE
103	>(Uint32 interval, SDL_TimerCallback callback);</CODE
104	></P
105	><P
106	></P
107	></DIV
108	></DIV
109	><DIV
110	CLASS="REFSECT1"
111	><A
112	NAME="SDLTIMERCALLBACK"
113	></A
114	><H2
115	>Callback</H2
116	><P
117	>/* Function prototype for the timer callback function */
118	typedef Uint32 (*SDL_TimerCallback)(Uint32 interval);</P
119	></DIV
120	><DIV
121	CLASS="REFSECT1"
122	><A
123	NAME="AEN8570"
124	></A
125	><H2
126	>Description</H2
127	><P
128	>Set a callback to run after the specified number of milliseconds has
129	elapsed. The callback function is passed the current timer interval
130	and returns the next timer interval. If the returned value is the
131	same as the one passed in, the periodic alarm continues, otherwise a
132	new alarm is scheduled.</P
133	><P
134	>To cancel a currently running timer, call
135	<TT
136	CLASS="FUNCTION"
137	>SDL_SetTimer(0, NULL);</TT
138	></P
139	><P
140	>The timer callback function may run in a different thread than your
141	main constant, and so shouldn't call any functions from within itself.</P
142	><P
143	>The maximum resolution of this timer is 10 ms, which means that if
144	you request a 16 ms timer, your callback will run approximately 20 ms
145	later on an unloaded system. If you wanted to set a flag signaling
146	a frame update at 30 frames per second (every 33 ms), you might set a
147	timer for 30 ms (see example below).</P
148	><P
149	>If you use this function, you need to pass <TT
150	CLASS="LITERAL"
151	>SDL_INIT_TIMER</TT
152	>
153	to <TT
154	CLASS="FUNCTION"
155	>SDL_Init()</TT
156	>.</P
157	><DIV
158	CLASS="NOTE"
159	><BLOCKQUOTE
160	CLASS="NOTE"
161	><P
162	><B
163	>Note: </B
164	>This function is kept for compatibility but has been superseded
165	by the new timer functions
166	<A
167	HREF="sdladdtimer.html"
168	>SDL_AddTimer</A
169	> and
170	<A
171	HREF="sdlremovetimer.html"
172	>SDL_RemoveTimer</A
173	> which support
174	multiple timers.</P
175	></BLOCKQUOTE
176	></DIV
177	></DIV
178	><DIV
179	CLASS="REFSECT1"
180	><A
181	NAME="AEN8584"
182	></A
183	><H2
184	>Examples</H2
185	><P
186	><PRE
187	CLASS="PROGRAMLISTING"
188	>SDL_SetTimer((33/10)*10, my_callback);</PRE
189	></P
190	></DIV
191	><DIV
192	CLASS="REFSECT1"
193	><A
194	NAME="AEN8588"
195	></A
196	><H2
197	>See Also</H2
198	><P
199	><A
200	HREF="sdladdtimer.html"
201	><TT
202	CLASS="FUNCTION"
203	>SDL_AddTimer</TT
204	></A
205	></P
206	></DIV
207	><DIV
208	CLASS="NAVFOOTER"
209	><HR
210	ALIGN="LEFT"
211	WIDTH="100%"><TABLE
212	SUMMARY="Footer navigation table"
213	WIDTH="100%"
214	BORDER="0"
215	CELLPADDING="0"
216	CELLSPACING="0"
217	><TR
218	><TD
219	WIDTH="33%"
220	ALIGN="left"
221	VALIGN="top"
222	><A
223	HREF="sdlremovetimer.html"
224	ACCESSKEY="P"
225	>Prev</A
226	></TD
227	><TD
228	WIDTH="34%"
229	ALIGN="center"
230	VALIGN="top"
231	><A
232	HREF="index.html"
233	ACCESSKEY="H"
234	>Home</A
235	></TD
236	><TD
237	WIDTH="33%"
238	ALIGN="right"
239	VALIGN="top"
240	> </TD
241	></TR
242	><TR
243	><TD
244	WIDTH="33%"
245	ALIGN="left"
246	VALIGN="top"
247	>SDL_RemoveTimer</TD
248	><TD
249	WIDTH="34%"
250	ALIGN="center"
251	VALIGN="top"
252	><A
253	HREF="time.html"
254	ACCESSKEY="U"
255	>Up</A
256	></TD
257	><TD
258	WIDTH="33%"
259	ALIGN="right"
260	VALIGN="top"
261	> </TD
262	></TR
263	></TABLE
264	></DIV
265	></BODY
266	></HTML
267	>