1b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet/* 2b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet SDL - Simple DirectMedia Layer 34458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall Copyright (C) 1997-2012 Sam Lantinga 4b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet 5b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet This library is free software; you can redistribute it and/or 6b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet modify it under the terms of the GNU Lesser General Public 7b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet License as published by the Free Software Foundation; either 8b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet version 2.1 of the License, or (at your option) any later version. 9b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet 10b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet This library is distributed in the hope that it will be useful, 11b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet but WITHOUT ANY WARRANTY; without even the implied warranty of 12b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet Lesser General Public License for more details. 14b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet 15b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet You should have received a copy of the GNU Lesser General Public 16b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet License along with this library; if not, write to the Free Software 17b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 18b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet 19b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet Sam Lantinga 20b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet slouken@libsdl.org 21b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet*/ 22b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet 23b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet#ifndef _SDL_timer_h 24b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet#define _SDL_timer_h 25b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet 264458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall/** @file SDL_timer.h 274458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall * Header for the SDL time management routines 284458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall */ 29b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet 30b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet#include "SDL_stdinc.h" 31b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet#include "SDL_error.h" 32b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet 33b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet#include "begin_code.h" 34b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet/* Set up for C function definitions, even when using C++ */ 35b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet#ifdef __cplusplus 36b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohetextern "C" { 37b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet#endif 38b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet 394458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall/** This is the OS scheduler timeslice, in milliseconds */ 40b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet#define SDL_TIMESLICE 10 41b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet 424458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall/** This is the maximum resolution of the SDL timer on all platforms */ 434458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall#define TIMER_RESOLUTION 10 /**< Experimentally determined */ 44b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet 454458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall/** 464458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall * Get the number of milliseconds since the SDL library initialization. 47b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * Note that this value wraps if the program runs for more than ~49 days. 48b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet */ 49b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohetextern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void); 50b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet 514458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall/** Wait a specified number of milliseconds before returning */ 52b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohetextern DECLSPEC void SDLCALL SDL_Delay(Uint32 ms); 53b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet 544458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall/** Function prototype for the timer callback function */ 55b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohettypedef Uint32 (SDLCALL *SDL_TimerCallback)(Uint32 interval); 56b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet 574458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall/** 584458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall * Set a callback to run after the specified number of milliseconds has 59b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * elapsed. The callback function is passed the current timer interval 60b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * and returns the next timer interval. If the returned value is the 61b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * same as the one passed in, the periodic alarm continues, otherwise a 62b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * new alarm is scheduled. If the callback returns 0, the periodic alarm 63b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * is cancelled. 64b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * 65b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * To cancel a currently running timer, call SDL_SetTimer(0, NULL); 66b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * 67b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * The timer callback function may run in a different thread than your 68b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * main code, and so shouldn't call any functions from within itself. 69b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * 70b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * The maximum resolution of this timer is 10 ms, which means that if 71b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * you request a 16 ms timer, your callback will run approximately 20 ms 72b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * later on an unloaded system. If you wanted to set a flag signaling 73b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * a frame update at 30 frames per second (every 33 ms), you might set a 74b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * timer for 30 ms: 754458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall * @code SDL_SetTimer((33/10)*10, flag_update); @endcode 76b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * 77b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * If you use this function, you need to pass SDL_INIT_TIMER to SDL_Init(). 78b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * 79b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * Under UNIX, you should not use raise or use SIGALRM and this function 80b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * in the same program, as it is implemented using setitimer(). You also 81b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * should not use this function in multi-threaded applications as signals 82b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * to multi-threaded apps have undefined behavior in some implementations. 83b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * 84b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * This function returns 0 if successful, or -1 if there was an error. 85b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet */ 86b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohetextern DECLSPEC int SDLCALL SDL_SetTimer(Uint32 interval, SDL_TimerCallback callback); 87b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet 884458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall/** @name New timer API 894458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall * New timer API, supports multiple timers 90b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * Written by Stephane Peter <megastep@lokigames.com> 91b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet */ 924458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall/*@{*/ 93b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet 944458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall/** 954458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall * Function prototype for the new timer callback function. 96b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * The callback function is passed the current timer interval and returns 97b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * the next timer interval. If the returned value is the same as the one 98b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * passed in, the periodic alarm continues, otherwise a new alarm is 99b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * scheduled. If the callback returns 0, the periodic alarm is cancelled. 100b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet */ 101b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohettypedef Uint32 (SDLCALL *SDL_NewTimerCallback)(Uint32 interval, void *param); 102b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet 1034458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall/** Definition of the timer ID type */ 104b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohettypedef struct _SDL_TimerID *SDL_TimerID; 105b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet 1064458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall/** Add a new timer to the pool of timers already running. 1074458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall * Returns a timer ID, or NULL when an error occurs. 108b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet */ 109b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohetextern DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval, SDL_NewTimerCallback callback, void *param); 110b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet 1114458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall/** 1124458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall * Remove one of the multiple timers knowing its ID. 113b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet * Returns a boolean value indicating success. 114b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet */ 115b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohetextern DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID t); 116b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet 1174458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall/*@}*/ 1184458c4364a99c5d8d124b19eec146b0998c4895aJesse Hall 119b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet/* Ends C function definitions when using C++ */ 120b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet#ifdef __cplusplus 121b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet} 122b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet#endif 123b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet#include "close_code.h" 124b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet 125b565d46b836401fa5dac23f9f8f0841c7a41e58eXavier Ducrohet#endif /* _SDL_timer_h */ 126