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