include/SDL_timer.h
author Ryan C. Gordon <icculus@icculus.org>
Tue, 15 Dec 2009 18:00:16 +0000
changeset 3567 fb9ea4b549c3
parent 3407 d3baf5ac4e37
child 3697 f7b03b6838cb
permissions -rw-r--r--
Added a warning comment to SDL_putenv().

"Fixes" Bugzilla #779.
slouken@0
     1
/*
slouken@0
     2
    SDL - Simple DirectMedia Layer
slouken@2859
     3
    Copyright (C) 1997-2009 Sam Lantinga
slouken@0
     4
slouken@0
     5
    This library is free software; you can redistribute it and/or
slouken@1312
     6
    modify it under the terms of the GNU Lesser General Public
slouken@0
     7
    License as published by the Free Software Foundation; either
slouken@1312
     8
    version 2.1 of the License, or (at your option) any later version.
slouken@0
     9
slouken@0
    10
    This library is distributed in the hope that it will be useful,
slouken@0
    11
    but WITHOUT ANY WARRANTY; without even the implied warranty of
slouken@0
    12
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
slouken@1312
    13
    Lesser General Public License for more details.
slouken@0
    14
slouken@1312
    15
    You should have received a copy of the GNU Lesser General Public
slouken@1312
    16
    License along with this library; if not, write to the Free Software
slouken@1312
    17
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
slouken@0
    18
slouken@0
    19
    Sam Lantinga
slouken@251
    20
    slouken@libsdl.org
slouken@0
    21
*/
slouken@0
    22
slouken@0
    23
#ifndef _SDL_timer_h
slouken@0
    24
#define _SDL_timer_h
slouken@0
    25
slouken@1895
    26
/**
slouken@3407
    27
 *  \file SDL_timer.h
slouken@3407
    28
 *  
slouken@3407
    29
 *  Header for the SDL time management routines.
slouken@1895
    30
 */
slouken@0
    31
slouken@1356
    32
#include "SDL_stdinc.h"
slouken@1358
    33
#include "SDL_error.h"
slouken@0
    34
slouken@0
    35
#include "begin_code.h"
slouken@0
    36
/* Set up for C function definitions, even when using C++ */
slouken@0
    37
#ifdef __cplusplus
slouken@1895
    38
/* *INDENT-OFF* */
slouken@0
    39
extern "C" {
slouken@1895
    40
/* *INDENT-ON* */
slouken@0
    41
#endif
slouken@0
    42
slouken@3407
    43
/**
slouken@3407
    44
 *  This is the OS scheduler timeslice, in milliseconds.
slouken@3407
    45
 */
slouken@0
    46
#define SDL_TIMESLICE		10
slouken@0
    47
slouken@3407
    48
/**
slouken@3407
    49
 *  This is the maximum resolution of the SDL timer on all platforms.
slouken@3407
    50
 */
slouken@3407
    51
#define TIMER_RESOLUTION	10      /**< Experimentally determined */
slouken@0
    52
slouken@3407
    53
/**
slouken@3407
    54
 *  Get the number of milliseconds since the SDL library initialization.
slouken@3407
    55
 *  
slouken@3407
    56
 *  Note that this value wraps if the program runs for more than ~49 days.
slouken@1895
    57
 */
slouken@337
    58
extern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void);
slouken@0
    59
slouken@3407
    60
/**
slouken@3407
    61
 *  Wait a specified number of milliseconds before returning.
slouken@3407
    62
 */
slouken@337
    63
extern DECLSPEC void SDLCALL SDL_Delay(Uint32 ms);
slouken@0
    64
slouken@3407
    65
/**
slouken@3407
    66
 *  Function prototype for the timer callback function.
slouken@3407
    67
 */
slouken@1895
    68
typedef Uint32(SDLCALL * SDL_TimerCallback) (Uint32 interval);
slouken@0
    69
slouken@3407
    70
/**
slouken@3407
    71
 *  Set a callback to run after the specified number of milliseconds has
slouken@3407
    72
 *  elapsed. The callback function is passed the current timer interval
slouken@3407
    73
 *  and returns the next timer interval.  If the returned value is the 
slouken@3407
    74
 *  same as the one passed in, the periodic alarm continues, otherwise a
slouken@3407
    75
 *  new alarm is scheduled.  If the callback returns 0, the periodic alarm
slouken@3407
    76
 *  is cancelled.
slouken@3407
    77
 *  
slouken@3407
    78
 *  To cancel a currently running timer, call 
slouken@3407
    79
 *  \code SDL_SetTimer(0, NULL); \endcode
slouken@3407
    80
 *  
slouken@3407
    81
 *  The timer callback function may run in a different thread than your
slouken@3407
    82
 *  main code, and so shouldn't call any functions from within itself.
slouken@3407
    83
 *  
slouken@3407
    84
 *  The maximum resolution of this timer is 10 ms, which means that if
slouken@3407
    85
 *  you request a 16 ms timer, your callback will run approximately 20 ms
slouken@3407
    86
 *  later on an unloaded system.  If you wanted to set a flag signaling
slouken@3407
    87
 *  a frame update at 30 frames per second (every 33 ms), you might set a 
slouken@3407
    88
 *  timer for 30 ms:
slouken@3407
    89
 *  \code
slouken@3407
    90
 *    SDL_SetTimer((33/10)*10, flag_update);
slouken@3407
    91
 *  \endcode
slouken@3407
    92
 *  
slouken@3407
    93
 *  If you use this function, you need to pass ::SDL_INIT_TIMER to SDL_Init().
slouken@3407
    94
 *  
slouken@3407
    95
 *  Under UNIX, you should not use raise or use SIGALRM and this function
slouken@3407
    96
 *  in the same program, as it is implemented using setitimer().  You also
slouken@3407
    97
 *  should not use this function in multi-threaded applications as signals
slouken@3407
    98
 *  to multi-threaded apps have undefined behavior in some implementations.
slouken@3407
    99
 *  
slouken@3407
   100
 *  \return 0 if successful, or -1 if there was an error.
slouken@0
   101
 */
slouken@1895
   102
extern DECLSPEC int SDLCALL SDL_SetTimer(Uint32 interval,
slouken@1895
   103
                                         SDL_TimerCallback callback);
slouken@0
   104
slouken@3407
   105
/**
slouken@3407
   106
 *  \name Peter timers
slouken@3407
   107
 *  New timer API, supports multiple timers
slouken@3407
   108
 *  Written by Stephane Peter <megastep@lokigames.com>
slouken@0
   109
 */
slouken@3407
   110
/*@{*/
slouken@0
   111
slouken@3407
   112
/**
slouken@3407
   113
 *  Function prototype for the new timer callback function.
slouken@3407
   114
 *  
slouken@3407
   115
 *  The callback function is passed the current timer interval and returns
slouken@3407
   116
 *  the next timer interval.  If the returned value is the same as the one
slouken@3407
   117
 *  passed in, the periodic alarm continues, otherwise a new alarm is
slouken@3407
   118
 *  scheduled.  If the callback returns 0, the periodic alarm is cancelled.
slouken@0
   119
 */
slouken@1895
   120
typedef Uint32(SDLCALL * SDL_NewTimerCallback) (Uint32 interval, void *param);
slouken@0
   121
slouken@3407
   122
/**
slouken@3407
   123
 *  Definition of the timer ID type.
slouken@3407
   124
 */
slouken@0
   125
typedef struct _SDL_TimerID *SDL_TimerID;
slouken@0
   126
slouken@3407
   127
/**
slouken@3407
   128
 *  Add a new timer to the pool of timers already running.
slouken@3407
   129
 *  \return A timer ID, or NULL when an error occurs.
slouken@0
   130
 */
slouken@1895
   131
extern DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval,
slouken@1895
   132
                                                 SDL_NewTimerCallback
slouken@1895
   133
                                                 callback, void *param);
slouken@0
   134
slouken@3407
   135
/**
slouken@3407
   136
 *  Remove one of the multiple timers knowing its ID.
slouken@3407
   137
 *  \return A boolean value indicating success or failure.
slouken@0
   138
 */
slouken@337
   139
extern DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID t);
slouken@0
   140
slouken@3407
   141
/*@}*//*Peter timers*/
slouken@3407
   142
slouken@0
   143
/* Ends C function definitions when using C++ */
slouken@0
   144
#ifdef __cplusplus
slouken@1895
   145
/* *INDENT-OFF* */
slouken@0
   146
}
slouken@1895
   147
/* *INDENT-ON* */
slouken@0
   148
#endif
slouken@0
   149
#include "close_code.h"
slouken@0
   150
slouken@0
   151
#endif /* _SDL_timer_h */
slouken@1895
   152
slouken@1895
   153
/* vi: set ts=4 sw=4 expandtab: */