[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
	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	>