Partial fix for bug #859
authorSam Lantinga <slouken@libsdl.org>
Mon, 19 Oct 2009 13:31:58 +0000
changeset 3407d3baf5ac4e37
parent 3406 8ae607392409
child 3408 55541ddf13e3
Partial fix for bug #859

Header file update from Ken for improved doxygen output
include/SDL.h
include/SDL_atomic.h
include/SDL_audio.h
include/SDL_compat.h
include/SDL_config.h.default
include/SDL_config.h.in
include/SDL_config_minimal.h
include/SDL_cpuinfo.h
include/SDL_endian.h
include/SDL_error.h
include/SDL_events.h
include/SDL_haptic.h
include/SDL_joystick.h
include/SDL_keyboard.h
include/SDL_keysym.h
include/SDL_loadso.h
include/SDL_main.h
include/SDL_mouse.h
include/SDL_mutex.h
include/SDL_opengl.h
include/SDL_opengles.h
include/SDL_pixels.h
include/SDL_platform.h
include/SDL_power.h
include/SDL_quit.h
include/SDL_rect.h
include/SDL_rwops.h
include/SDL_scancode.h
include/SDL_stdinc.h
include/SDL_surface.h
include/SDL_syswm.h
include/SDL_thread.h
include/SDL_timer.h
include/SDL_types.h
include/SDL_version.h
include/SDL_video.h
include/begin_code.h
include/close_code.h
     1.1 --- a/include/SDL.h	Sun Oct 18 23:21:15 2009 +0000
     1.2 +++ b/include/SDL.h	Mon Oct 19 13:31:58 2009 +0000
     1.3 @@ -21,54 +21,55 @@
     1.4  */
     1.5  
     1.6  /**
     1.7 - * \file SDL.h
     1.8 - *
     1.9 - * Main include header for the SDL library
    1.10 + *  \file SDL.h
    1.11 + *  
    1.12 + *  Main include header for the SDL library
    1.13   */
    1.14 +
    1.15  /**
    1.16 - * \mainpage Simple DirectMedia Layer (SDL)
    1.17 -
    1.18 -http://www.libsdl.org/
    1.19 -
    1.20 -* \section intro_sec Introduction
    1.21 -
    1.22 -This is the Simple DirectMedia Layer, a general API that provides low
    1.23 -level access to audio, keyboard, mouse, joystick, 3D hardware via OpenGL,
    1.24 -and 2D framebuffer across multiple platforms.
    1.25 -
    1.26 -The current version supports Linux, Windows, Windows CE, BeOS, MacOS,
    1.27 -Mac OS X, FreeBSD, NetBSD, OpenBSD, BSD/OS, Solaris, IRIX, and QNX.
    1.28 -The code contains support for AIX, OSF/Tru64, RISC OS, and SymbianOS,
    1.29 -but these are not officially supported.
    1.30 -
    1.31 -SDL is written in C, but works with C++ natively, and has bindings to
    1.32 -several other languages, including Ada, C#, Eiffel, Erlang, Euphoria,
    1.33 -Guile, Haskell, Java, Lisp, Lua, ML, Objective C, Pascal, Perl, PHP,
    1.34 -Pike, Pliant, Python, Ruby, and Smalltalk.
    1.35 -
    1.36 -This library is distributed under GNU LGPL version 2, which can be
    1.37 -found in the file  "COPYING".  This license allows you to use SDL
    1.38 -freely in commercial programs as long as you link with the dynamic
    1.39 -library.
    1.40 -
    1.41 -The best way to learn how to use SDL is to check out the header files in
    1.42 -the "include" subdirectory and the programs in the "test" subdirectory.
    1.43 -The header files and test programs are well commented and always up to date.
    1.44 -More documentation is available in HTML format in "docs/index.html", and
    1.45 -a documentation wiki is available online at:
    1.46 -	http://www.libsdl.org/cgi/docwiki.cgi
    1.47 -
    1.48 -The test programs in the "test" subdirectory are in the public domain.
    1.49 -
    1.50 -Frequently asked questions are answered online:
    1.51 -	http://www.libsdl.org/faq.php
    1.52 -
    1.53 -If you need help with the library, or just want to discuss SDL related
    1.54 -issues, you can join the developers mailing list:
    1.55 -	http://www.libsdl.org/mailing-list.php
    1.56 -
    1.57 -Enjoy!
    1.58 -	Sam Lantinga				(slouken@libsdl.org)
    1.59 + *  \mainpage Simple DirectMedia Layer (SDL)
    1.60 + *  
    1.61 + *  http://www.libsdl.org/
    1.62 + *  
    1.63 + *  \section intro_sec Introduction
    1.64 + *  
    1.65 + *  This is the Simple DirectMedia Layer, a general API that provides low
    1.66 + *  level access to audio, keyboard, mouse, joystick, 3D hardware via OpenGL,
    1.67 + *  and 2D framebuffer across multiple platforms.
    1.68 + *  
    1.69 + *  The current version supports Linux, Windows, Windows CE, BeOS, MacOS,
    1.70 + *  Mac OS X, FreeBSD, NetBSD, OpenBSD, BSD/OS, Solaris, IRIX, and QNX.
    1.71 + *  The code contains support for AIX, OSF/Tru64, RISC OS, and SymbianOS,
    1.72 + *  but these are not officially supported.
    1.73 + *  
    1.74 + *  SDL is written in C, but works with C++ natively, and has bindings to
    1.75 + *  several other languages, including Ada, C#, Eiffel, Erlang, Euphoria,
    1.76 + *  Guile, Haskell, Java, Lisp, Lua, ML, Objective C, Pascal, Perl, PHP,
    1.77 + *  Pike, Pliant, Python, Ruby, and Smalltalk.
    1.78 + *  
    1.79 + *  This library is distributed under GNU LGPL version 2, which can be
    1.80 + *  found in the file  "COPYING".  This license allows you to use SDL
    1.81 + *  freely in commercial programs as long as you link with the dynamic
    1.82 + *  library.
    1.83 + *  
    1.84 + *  The best way to learn how to use SDL is to check out the header files in
    1.85 + *  the "include" subdirectory and the programs in the "test" subdirectory.
    1.86 + *  The header files and test programs are well commented and always up to date.
    1.87 + *  More documentation is available in HTML format in "docs/index.html", and
    1.88 + *  a documentation wiki is available online at:
    1.89 + *  	http://www.libsdl.org/cgi/docwiki.cgi
    1.90 + *  
    1.91 + *  The test programs in the "test" subdirectory are in the public domain.
    1.92 + *  
    1.93 + *  Frequently asked questions are answered online:
    1.94 + *  	http://www.libsdl.org/faq.php
    1.95 + *  
    1.96 + *  If you need help with the library, or just want to discuss SDL related
    1.97 + *  issues, you can join the developers mailing list:
    1.98 + *  	http://www.libsdl.org/mailing-list.php
    1.99 + *  
   1.100 + *  Enjoy!
   1.101 + *  	Sam Lantinga				(slouken@libsdl.org)
   1.102   */
   1.103  
   1.104  #ifndef _SDL_H
   1.105 @@ -102,44 +103,52 @@
   1.106  
   1.107  /* As of version 0.5, SDL is loaded dynamically into the application */
   1.108  
   1.109 -/* These are the flags which may be passed to SDL_Init() -- you should
   1.110 -   specify the subsystems which you will be using in your application.
   1.111 -*/
   1.112 +/**
   1.113 + *  \name SDL_INIT_*
   1.114 + *  
   1.115 + *  These are the flags which may be passed to SDL_Init().  You should
   1.116 + *  specify the subsystems which you will be using in your application.
   1.117 + */
   1.118 +/*@{*/
   1.119  #define SDL_INIT_TIMER          0x00000001
   1.120  #define SDL_INIT_AUDIO          0x00000010
   1.121  #define SDL_INIT_VIDEO          0x00000020
   1.122  #define SDL_INIT_JOYSTICK       0x00000200
   1.123  #define SDL_INIT_HAPTIC         0x00001000
   1.124 -#define SDL_INIT_NOPARACHUTE    0x00100000      /* Don't catch fatal signals */
   1.125 -#define SDL_INIT_EVENTTHREAD    0x01000000      /* Not supported on all OS's */
   1.126 +#define SDL_INIT_NOPARACHUTE    0x00100000      /**< Don't catch fatal signals */
   1.127 +#define SDL_INIT_EVENTTHREAD    0x01000000      /**< Not supported on all OS's */
   1.128  #define SDL_INIT_EVERYTHING     0x0000FFFF
   1.129 +/*@}*/
   1.130  
   1.131  /**
   1.132 - * This function loads the SDL dynamically linked library and initializes 
   1.133 - * the subsystems specified by 'flags' (and those satisfying dependencies)
   1.134 - * Unless the SDL_INIT_NOPARACHUTE flag is set, it will install cleanup
   1.135 - * signal handlers for some commonly ignored fatal signals (like SIGSEGV)
   1.136 + *  This function loads the SDL dynamically linked library and initializes 
   1.137 + *  the subsystems specified by \c flags (and those satisfying dependencies).
   1.138 + *  Unless the ::SDL_INIT_NOPARACHUTE flag is set, it will install cleanup
   1.139 + *  signal handlers for some commonly ignored fatal signals (like SIGSEGV).
   1.140   */
   1.141  extern DECLSPEC int SDLCALL SDL_Init(Uint32 flags);
   1.142  
   1.143  /**
   1.144 - * This function initializes specific SDL subsystems
   1.145 + *  This function initializes specific SDL subsystems
   1.146   */
   1.147  extern DECLSPEC int SDLCALL SDL_InitSubSystem(Uint32 flags);
   1.148  
   1.149 -/** This function cleans up specific SDL subsystems */
   1.150 +/**
   1.151 + *  This function cleans up specific SDL subsystems
   1.152 + */
   1.153  extern DECLSPEC void SDLCALL SDL_QuitSubSystem(Uint32 flags);
   1.154  
   1.155  /**
   1.156 -   This function returns mask of the specified subsystems which have
   1.157 -   been initialized.
   1.158 -   If 'flags' is 0, it returns a mask of all initialized subsystems.
   1.159 -*/
   1.160 + *  This function returns mask of the specified subsystems which have
   1.161 + *  been initialized.
   1.162 + *  
   1.163 + *  If \c flags is 0, it returns a mask of all initialized subsystems.
   1.164 + */
   1.165  extern DECLSPEC Uint32 SDLCALL SDL_WasInit(Uint32 flags);
   1.166  
   1.167  /**
   1.168 - * This function cleans up all initialized subsystems and unloads the
   1.169 - * dynamically linked library.  You should call it upon all exit conditions.
   1.170 + *  This function cleans up all initialized subsystems and unloads the
   1.171 + *  dynamically linked library.  You should call it upon all exit conditions.
   1.172   */
   1.173  extern DECLSPEC void SDLCALL SDL_Quit(void);
   1.174  
     2.1 --- a/include/SDL_atomic.h	Sun Oct 18 23:21:15 2009 +0000
     2.2 +++ b/include/SDL_atomic.h	Mon Oct 19 13:31:58 2009 +0000
     2.3 @@ -23,9 +23,19 @@
     2.4   */
     2.5  
     2.6  /**
     2.7 - * \file SDL_atomic.h
     2.8 - *
     2.9 - * Atomic operations.
    2.10 + *  \file SDL_atomic.h
    2.11 + *  
    2.12 + *  Atomic operations.
    2.13 + *  
    2.14 + *  These operations may, or may not, actually be implemented using
    2.15 + *  processor specific atomic operations. When possible they are
    2.16 + *  implemented as true processor specific atomic operations. When that
    2.17 + *  is not possible the are implemented using locks that *do* use the
    2.18 + *  available atomic operations.
    2.19 + *  
    2.20 + *  At the very minimum spin locks must be implemented. Without spin
    2.21 + *  locks it is not possible (AFAICT) to emulate the rest of the atomic
    2.22 + *  operations.
    2.23   */
    2.24  
    2.25  #ifndef _SDL_atomic_h_
    2.26 @@ -43,176 +53,139 @@
    2.27  /* *INDENT-ON* */
    2.28  #endif
    2.29  
    2.30 -/**
    2.31 - * These operations may, or may not, actually be implemented using
    2.32 - * processor specific atomic operations. When possible they are
    2.33 - * implemented as true processor specific atomic operations. When that
    2.34 - * is not possible the are implemented using locks that *do* use the
    2.35 - * available atomic operations.
    2.36 - *
    2.37 - * At the very minimum spin locks must be implemented. Without spin
    2.38 - * locks it is not possible (AFAICT) to emulate the rest of the atomic
    2.39 - * operations.
    2.40 - */
    2.41 -
    2.42  /* Function prototypes */
    2.43  
    2.44  /**
    2.45 - * SDL AtomicLock.
    2.46 - * 
    2.47 - * The spin lock functions and type are required and can not be
    2.48 - * emulated because they are used in the emulation code.
    2.49 + *  \name SDL AtomicLock
    2.50 + *  
    2.51 + *  The spin lock functions and type are required and can not be
    2.52 + *  emulated because they are used in the emulation code.
    2.53   */
    2.54 +/*@{*/
    2.55  
    2.56  typedef volatile Uint32 SDL_SpinLock;
    2.57  
    2.58  /**
    2.59 - * \fn  void SDL_AtomicLock(SDL_SpinLock *lock);
    2.60 - *
    2.61 - * \brief Lock a spin lock by setting it to a none zero value.
    2.62 - *
    2.63 - * \param lock points to the lock.
    2.64 - *
    2.65 + *  \brief Lock a spin lock by setting it to a none zero value.
    2.66 + *  
    2.67 + *  \param lock Points to the lock.
    2.68   */
    2.69  extern DECLSPEC void SDLCALL SDL_AtomicLock(SDL_SpinLock *lock);
    2.70  
    2.71  /**
    2.72 - * \fn  void SDL_AtomicUnlock(SDL_SpinLock *lock);
    2.73 + *  \brief Unlock a spin lock by setting it to 0. Always returns immediately
    2.74   *
    2.75 - * \brief Unlock a spin lock by setting it to 0. Always returns immediately
    2.76 - *
    2.77 - * \param lock points to the lock.
    2.78 - *
    2.79 + *  \param lock Points to the lock.
    2.80   */
    2.81  extern DECLSPEC void SDLCALL SDL_AtomicUnlock(SDL_SpinLock *lock);
    2.82  
    2.83 -/* 32 bit atomic operations */
    2.84 +/*@}*//*SDL AtomicLock*/
    2.85  
    2.86  /**
    2.87 - * \fn  SDL_bool SDL_AtomicTestThenSet32(volatile Uint32 * ptr);
    2.88 - *
    2.89 - * \brief Check to see if *ptr == 0 and set it to 1.
    2.90 - *
    2.91 - * \return SDL_True if the value pointed to by ptr was zero and
    2.92 - * SDL_False if it was not zero
    2.93 - *
    2.94 - * \param ptr points to the value to be tested and set.
    2.95 - *
    2.96 + *  \name 32 bit atomic operations
    2.97 + */
    2.98 +/*@{*/
    2.99 +
   2.100 +/**
   2.101 + *  \brief Check to see if \c *ptr == 0 and set it to 1.
   2.102 + *  
   2.103 + *  \return SDL_True if the value pointed to by \c ptr was zero and
   2.104 + *          SDL_False if it was not zero
   2.105 + *  
   2.106 + *  \param ptr Points to the value to be tested and set.
   2.107   */
   2.108  extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTestThenSet32(volatile Uint32 * ptr);
   2.109  
   2.110  /**
   2.111 - * \fn  void SDL_AtomicClear32(volatile Uint32 * ptr);
   2.112 - *
   2.113 - * \brief set the value pointed to by ptr to be zero.
   2.114 - *
   2.115 - * \param ptr address of the value to be set to zero
   2.116 - *
   2.117 + *  \brief Set the value pointed to by \c ptr to be zero.
   2.118 + *  
   2.119 + *  \param ptr Address of the value to be set to zero
   2.120   */
   2.121  extern DECLSPEC void SDLCALL SDL_AtomicClear32(volatile Uint32 * ptr);
   2.122  
   2.123  /**
   2.124 - * \fn  Uint32 SDL_AtomicFetchThenIncrement32(volatile Uint32 * ptr);
   2.125 - *
   2.126 - * \brief fetch the current value of *ptr and then increment that
   2.127 - * value in place.
   2.128 - *
   2.129 - * \return the value before it was incremented.
   2.130 - *
   2.131 - * \param ptr address of the value to fetch and increment
   2.132 - *
   2.133 + *  \brief Fetch the current value of \c *ptr and then increment that
   2.134 + *         value in place.
   2.135 + *  
   2.136 + *  \return The value before it was incremented.
   2.137 + *  
   2.138 + *  \param ptr Address of the value to fetch and increment
   2.139   */
   2.140  extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenIncrement32(volatile Uint32 * ptr);
   2.141  
   2.142  /**
   2.143 - * \fn  Uint32 SDL_AtomicFetchThenDecrement32(volatile Uint32 * ptr);
   2.144 - *
   2.145 - * \brief fetch *ptr and then decrement the value in place.
   2.146 - *
   2.147 - * \return the value before it was decremented.
   2.148 - *
   2.149 - * \param ptr address of the value to fetch and drement
   2.150 - *
   2.151 + *  \brief Fetch \c *ptr and then decrement the value in place.
   2.152 + *  
   2.153 + *  \return The value before it was decremented.
   2.154 + *  
   2.155 + *  \param ptr Address of the value to fetch and drement
   2.156   */
   2.157  extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenDecrement32(volatile Uint32 * ptr);
   2.158  
   2.159  /**
   2.160 - * \fn  Uint32 SDL_AtomicFetchThenAdd32(volatile Uint32 * ptr, Uint32 value);
   2.161 - *
   2.162 - * \brief fetch the current value at ptr and then add value to *ptr.
   2.163 - *
   2.164 - * \return *ptr before the addition took place.
   2.165 - *
   2.166 - * \param ptr the address of data we are changing.
   2.167 - * \param value the value to add to *ptr. 
   2.168 - *
   2.169 + *  \brief Fetch the current value at \c ptr and then add \c value to \c *ptr.
   2.170 + *  
   2.171 + *  \return \c *ptr before the addition took place.
   2.172 + *  
   2.173 + *  \param ptr The address of data we are changing.
   2.174 + *  \param value The value to add to \c *ptr. 
   2.175   */
   2.176  extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenAdd32(volatile Uint32 * ptr, Uint32 value);
   2.177  
   2.178  /**
   2.179 - * \fn  Uint32 SDL_AtomicFetchThenSubtract32(volatile Uint32 * ptr, Uint32 value);
   2.180 - *
   2.181 - * \brief Fetch *ptr and then subtract value from it.
   2.182 - *
   2.183 - * \return *ptr before the subtraction took place.
   2.184 - *
   2.185 - * \param ptr the address of the data being changed.
   2.186 - * \param value the value to subtract from *ptr.
   2.187 - *
   2.188 + *  \brief Fetch \c *ptr and then subtract \c value from it.
   2.189 + *  
   2.190 + *  \return \c *ptr before the subtraction took place.
   2.191 + *  
   2.192 + *  \param ptr The address of the data being changed.
   2.193 + *  \param value The value to subtract from \c *ptr.
   2.194   */
   2.195  extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenSubtract32(volatile Uint32 * ptr, Uint32 value);
   2.196  
   2.197  /**
   2.198 - * \fn  Uint32 SDL_AtomicIncrementThenFetch32(volatile Uint32 * ptr);
   2.199 - *
   2.200 - * \brief Add one to the data pointed to by ptr and return that value.
   2.201 - *
   2.202 - * \return the incremented value.
   2.203 - *
   2.204 - * \param ptr address of the data to increment.
   2.205 - *
   2.206 + *  \brief Add one to the data pointed to by \c ptr and return that value.
   2.207 + *  
   2.208 + *  \return The incremented value.
   2.209 + *  
   2.210 + *  \param ptr The address of the data to increment.
   2.211   */
   2.212  extern DECLSPEC Uint32 SDLCALL SDL_AtomicIncrementThenFetch32(volatile Uint32 * ptr);
   2.213  
   2.214  /**
   2.215 - * \fn  Uint32 SDL_AtomicDecrementThenFetch32(volatile Uint32 * ptr);
   2.216 - *
   2.217 - * \brief Subtract one from data pointed to by ptr and return the new value.
   2.218 - *
   2.219 - * \return The decremented value.
   2.220 - *
   2.221 - * \param ptr The address of the data to decrement.
   2.222 - *
   2.223 + *  \brief Subtract one from data pointed to by \c ptr and return the new value.
   2.224 + *  
   2.225 + *  \return The decremented value.
   2.226 + *  
   2.227 + *  \param ptr The address of the data to decrement.
   2.228   */
   2.229  extern DECLSPEC Uint32 SDLCALL SDL_AtomicDecrementThenFetch32(volatile Uint32 * ptr);
   2.230  
   2.231  /**
   2.232 - * \fn  Uint32 SDL_AtomicAddThenFetch32(volatile Uint32 * ptr, Uint32 value);
   2.233 - *
   2.234 - * \brief Add value to the data pointed to by ptr and return result.
   2.235 - *
   2.236 - * \return The sum of *ptr and value.
   2.237 - *
   2.238 - * \param ptr The address of the data to be modified.
   2.239 - * \param value The value to be added.
   2.240 - *
   2.241 + *  \brief Add \c value to the data pointed to by \c ptr and return result.
   2.242 + *  
   2.243 + *  \return The sum of \c *ptr and \c value.
   2.244 + *  
   2.245 + *  \param ptr The address of the data to be modified.
   2.246 + *  \param value The value to be added.
   2.247   */
   2.248  extern DECLSPEC Uint32 SDLCALL SDL_AtomicAddThenFetch32(volatile Uint32 * ptr, Uint32 value);
   2.249  
   2.250  /**
   2.251 - * \fn  Uint32 SDL_AtomicSubtractThenFetch32(volatile Uint32 * ptr, Uint32 value);
   2.252 - *
   2.253 - * \brief Subtract value from the data pointed to by ptr and return the result.
   2.254 - *
   2.255 - * \return the difference between *ptr and value.
   2.256 - *
   2.257 - * \param ptr The address of the data to be modified.
   2.258 - * \param value The value to be subtracted.
   2.259 - *
   2.260 + *  \brief Subtract \c value from the data pointed to by \c ptr and return the result.
   2.261 + *  
   2.262 + *  \return The difference between \c *ptr and \c value.
   2.263 + *  
   2.264 + *  \param ptr The address of the data to be modified.
   2.265 + *  \param value The value to be subtracted.
   2.266   */
   2.267  extern DECLSPEC Uint32 SDLCALL SDL_AtomicSubtractThenFetch32(volatile Uint32 * ptr, Uint32 value);
   2.268  
   2.269 -/* 64 bit atomic operations */
   2.270 +/*@}*//*32 bit atomic operations*/
   2.271 +
   2.272 +/**
   2.273 + *  \name 64 bit atomic operations
   2.274 + */
   2.275 +/*@{*/
   2.276  #ifdef SDL_HAS_64BIT_TYPE
   2.277  
   2.278  extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTestThenSet64(volatile Uint64 * ptr);
   2.279 @@ -227,6 +200,8 @@
   2.280  extern DECLSPEC Uint64 SDLCALL SDL_AtomicSubtractThenFetch64(volatile Uint64 * ptr, Uint64 value);
   2.281  #endif /*  SDL_HAS_64BIT_TYPE */
   2.282  
   2.283 +/*@}*//*64 bit atomic operations*/
   2.284 +
   2.285  /* Ends C function definitions when using C++ */
   2.286  #ifdef __cplusplus
   2.287  /* *INDENT-OFF* */
     3.1 --- a/include/SDL_audio.h	Sun Oct 18 23:21:15 2009 +0000
     3.2 +++ b/include/SDL_audio.h	Mon Oct 19 13:31:58 2009 +0000
     3.3 @@ -21,9 +21,9 @@
     3.4  */
     3.5  
     3.6  /**
     3.7 - * \file SDL_audio.h
     3.8 - *
     3.9 - * Access to the raw audio mixing buffer for the SDL library
    3.10 + *  \file SDL_audio.h
    3.11 + *  
    3.12 + *  Access to the raw audio mixing buffer for the SDL library.
    3.13   */
    3.14  
    3.15  #ifndef _SDL_audio_h
    3.16 @@ -44,45 +44,32 @@
    3.17  /* *INDENT-ON* */
    3.18  #endif
    3.19  
    3.20 +/**
    3.21 + *  \brief Audio format flags.
    3.22 + *  
    3.23 + *  These are what the 16 bits in SDL_AudioFormat currently mean...
    3.24 + *  (Unspecified bits are always zero).
    3.25 + *  
    3.26 + *  \verbatim
    3.27 +    ++-----------------------sample is signed if set
    3.28 +    ||
    3.29 +    ||       ++-----------sample is bigendian if set
    3.30 +    ||       ||
    3.31 +    ||       ||          ++---sample is float if set
    3.32 +    ||       ||          ||
    3.33 +    ||       ||          || +---sample bit size---+
    3.34 +    ||       ||          || |                     |
    3.35 +    15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00
    3.36 +    \endverbatim
    3.37 + *  
    3.38 + *  There are macros in SDL 1.3 and later to query these bits.
    3.39 + */
    3.40  typedef Uint16 SDL_AudioFormat;
    3.41  
    3.42 -/* The calculated values in this structure are calculated by SDL_OpenAudio() */
    3.43 -typedef struct SDL_AudioSpec
    3.44 -{
    3.45 -    int freq;                   /* DSP frequency -- samples per second */
    3.46 -    SDL_AudioFormat format;     /* Audio data format */
    3.47 -    Uint8 channels;             /* Number of channels: 1 mono, 2 stereo */
    3.48 -    Uint8 silence;              /* Audio buffer silence value (calculated) */
    3.49 -    Uint16 samples;             /* Audio buffer size in samples (power of 2) */
    3.50 -    Uint16 padding;             /* Necessary for some compile environments */
    3.51 -    Uint32 size;                /* Audio buffer size in bytes (calculated) */
    3.52 -    /* This function is called when the audio device needs more data.
    3.53 -       'stream' is a pointer to the audio data buffer
    3.54 -       'len' is the length of that buffer in bytes.
    3.55 -       Once the callback returns, the buffer will no longer be valid.
    3.56 -       Stereo samples are stored in a LRLRLR ordering.
    3.57 -     */
    3.58 -    void (SDLCALL * callback) (void *userdata, Uint8 * stream, int len);
    3.59 -    void *userdata;
    3.60 -} SDL_AudioSpec;
    3.61 -
    3.62 -
    3.63 -/*
    3.64 - These are what the 16 bits in SDL_AudioFormat currently mean...
    3.65 - (Unspecified bits are always zero.)
    3.66 -
    3.67 - ++-----------------------sample is signed if set
    3.68 - ||
    3.69 - ||       ++-----------sample is bigendian if set
    3.70 - ||       ||
    3.71 - ||       ||          ++---sample is float if set
    3.72 - ||       ||          ||
    3.73 - ||       ||          || +---sample bit size---+
    3.74 - ||       ||          || |                     |
    3.75 - 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00
    3.76 -
    3.77 - There are macros in SDL 1.3 and later to query these bits.
    3.78 -*/
    3.79 +/**
    3.80 + *  \name Audio flags
    3.81 + */
    3.82 +/*@{*/
    3.83  
    3.84  #define SDL_AUDIO_MASK_BITSIZE       (0xFF)
    3.85  #define SDL_AUDIO_MASK_DATATYPE      (1<<8)
    3.86 @@ -96,27 +83,48 @@
    3.87  #define SDL_AUDIO_ISLITTLEENDIAN(x)  (!SDL_AUDIO_ISBIGENDIAN(x))
    3.88  #define SDL_AUDIO_ISUNSIGNED(x)      (!SDL_AUDIO_ISSIGNED(x))
    3.89  
    3.90 -/* Audio format flags (defaults to LSB byte order) */
    3.91 -#define AUDIO_U8	0x0008  /* Unsigned 8-bit samples */
    3.92 -#define AUDIO_S8	0x8008  /* Signed 8-bit samples */
    3.93 -#define AUDIO_U16LSB	0x0010  /* Unsigned 16-bit samples */
    3.94 -#define AUDIO_S16LSB	0x8010  /* Signed 16-bit samples */
    3.95 -#define AUDIO_U16MSB	0x1010  /* As above, but big-endian byte order */
    3.96 -#define AUDIO_S16MSB	0x9010  /* As above, but big-endian byte order */
    3.97 +/** 
    3.98 + *  \name Audio format flags
    3.99 + *
   3.100 + *  Defaults to LSB byte order.
   3.101 + */
   3.102 +/*@{*/
   3.103 +#define AUDIO_U8	0x0008  /**< Unsigned 8-bit samples */
   3.104 +#define AUDIO_S8	0x8008  /**< Signed 8-bit samples */
   3.105 +#define AUDIO_U16LSB	0x0010  /**< Unsigned 16-bit samples */
   3.106 +#define AUDIO_S16LSB	0x8010  /**< Signed 16-bit samples */
   3.107 +#define AUDIO_U16MSB	0x1010  /**< As above, but big-endian byte order */
   3.108 +#define AUDIO_S16MSB	0x9010  /**< As above, but big-endian byte order */
   3.109  #define AUDIO_U16	AUDIO_U16LSB
   3.110  #define AUDIO_S16	AUDIO_S16LSB
   3.111 +/*@}*/
   3.112  
   3.113 -/* int32 support new to SDL 1.3 */
   3.114 -#define AUDIO_S32LSB	0x8020  /* 32-bit integer samples */
   3.115 -#define AUDIO_S32MSB	0x9020  /* As above, but big-endian byte order */
   3.116 +/**
   3.117 + *  \name int32 support
   3.118 + *  
   3.119 + *  New to SDL 1.3.
   3.120 + */
   3.121 +/*@{*/
   3.122 +#define AUDIO_S32LSB	0x8020  /**< 32-bit integer samples */
   3.123 +#define AUDIO_S32MSB	0x9020  /**< As above, but big-endian byte order */
   3.124  #define AUDIO_S32	AUDIO_S32LSB
   3.125 +/*@}*/
   3.126  
   3.127 -/* float32 support new to SDL 1.3 */
   3.128 -#define AUDIO_F32LSB	0x8120  /* 32-bit floating point samples */
   3.129 -#define AUDIO_F32MSB	0x9120  /* As above, but big-endian byte order */
   3.130 +/**
   3.131 + *  \name float32 support
   3.132 + *  
   3.133 + *  New to SDL 1.3.
   3.134 + */
   3.135 +/*@{*/
   3.136 +#define AUDIO_F32LSB	0x8120  /**< 32-bit floating point samples */
   3.137 +#define AUDIO_F32MSB	0x9120  /**< As above, but big-endian byte order */
   3.138  #define AUDIO_F32	AUDIO_F32LSB
   3.139 +/*@}*/
   3.140  
   3.141 -/* Native audio byte ordering */
   3.142 +/**
   3.143 + *  \name Native audio byte ordering
   3.144 + */
   3.145 +/*@{*/
   3.146  #if SDL_BYTEORDER == SDL_LIL_ENDIAN
   3.147  #define AUDIO_U16SYS	AUDIO_U16LSB
   3.148  #define AUDIO_S16SYS	AUDIO_S16LSB
   3.149 @@ -128,101 +136,151 @@
   3.150  #define AUDIO_S32SYS	AUDIO_S32MSB
   3.151  #define AUDIO_F32SYS	AUDIO_F32MSB
   3.152  #endif
   3.153 +/*@}*/
   3.154  
   3.155 -/* Which audio format changes are allowed when opening a device */
   3.156 +/** 
   3.157 + *  \name Allow change flags
   3.158 + *  
   3.159 + *  Which audio format changes are allowed when opening a device.
   3.160 + */
   3.161 +/*@{*/
   3.162  #define SDL_AUDIO_ALLOW_FREQUENCY_CHANGE    0x00000001
   3.163  #define SDL_AUDIO_ALLOW_FORMAT_CHANGE       0x00000002
   3.164  #define SDL_AUDIO_ALLOW_CHANNELS_CHANGE     0x00000004
   3.165  #define SDL_AUDIO_ALLOW_ANY_CHANGE          (SDL_AUDIO_ALLOW_FREQUENCY_CHANGE|SDL_AUDIO_ALLOW_FORMAT_CHANGE|SDL_AUDIO_ALLOW_CHANNELS_CHANGE)
   3.166 +/*@}*/
   3.167  
   3.168 -/* A structure to hold a set of audio conversion filters and buffers */
   3.169 +/*@}*//*Audio flags*/
   3.170 +
   3.171 +/**
   3.172 + *  The calculated values in this structure are calculated by SDL_OpenAudio().
   3.173 + */
   3.174 +typedef struct SDL_AudioSpec
   3.175 +{
   3.176 +    int freq;                   /**< DSP frequency -- samples per second */
   3.177 +    SDL_AudioFormat format;     /**< Audio data format */
   3.178 +    Uint8 channels;             /**< Number of channels: 1 mono, 2 stereo */
   3.179 +    Uint8 silence;              /**< Audio buffer silence value (calculated) */
   3.180 +    Uint16 samples;             /**< Audio buffer size in samples (power of 2) */
   3.181 +    Uint16 padding;             /**< Necessary for some compile environments */
   3.182 +    Uint32 size;                /**< Audio buffer size in bytes (calculated) */
   3.183 +    /**
   3.184 +     *  This function is called when the audio device needs more data.
   3.185 +     *
   3.186 +     *  \param stream A pointer to the audio data buffer.
   3.187 +     *  \param len    The length of that buffer in bytes.
   3.188 +     *
   3.189 +     *  Once the callback returns, the buffer will no longer be valid.
   3.190 +     *  Stereo samples are stored in a LRLRLR ordering.
   3.191 +     */
   3.192 +    void (SDLCALL * callback) (void *userdata, Uint8 * stream, int len);
   3.193 +    void *userdata;
   3.194 +} SDL_AudioSpec;
   3.195 +
   3.196 +
   3.197  struct SDL_AudioCVT;
   3.198  typedef void (SDLCALL * SDL_AudioFilter) (struct SDL_AudioCVT * cvt,
   3.199                                            SDL_AudioFormat format);
   3.200  
   3.201 +/**
   3.202 + *  A structure to hold a set of audio conversion filters and buffers.
   3.203 + */
   3.204  typedef struct SDL_AudioCVT
   3.205  {
   3.206 -    int needed;                 /* Set to 1 if conversion possible */
   3.207 -    SDL_AudioFormat src_format; /* Source audio format */
   3.208 -    SDL_AudioFormat dst_format; /* Target audio format */
   3.209 -    double rate_incr;           /* Rate conversion increment */
   3.210 -    Uint8 *buf;                 /* Buffer to hold entire audio data */
   3.211 -    int len;                    /* Length of original audio buffer */
   3.212 -    int len_cvt;                /* Length of converted audio buffer */
   3.213 -    int len_mult;               /* buffer must be len*len_mult big */
   3.214 -    double len_ratio;           /* Given len, final size is len*len_ratio */
   3.215 -    SDL_AudioFilter filters[10];        /* Filter list */
   3.216 -    int filter_index;           /* Current audio conversion function */
   3.217 +    int needed;                 /**< Set to 1 if conversion possible */
   3.218 +    SDL_AudioFormat src_format; /**< Source audio format */
   3.219 +    SDL_AudioFormat dst_format; /**< Target audio format */
   3.220 +    double rate_incr;           /**< Rate conversion increment */
   3.221 +    Uint8 *buf;                 /**< Buffer to hold entire audio data */
   3.222 +    int len;                    /**< Length of original audio buffer */
   3.223 +    int len_cvt;                /**< Length of converted audio buffer */
   3.224 +    int len_mult;               /**< buffer must be len*len_mult big */
   3.225 +    double len_ratio;           /**< Given len, final size is len*len_ratio */
   3.226 +    SDL_AudioFilter filters[10];        /**< Filter list */
   3.227 +    int filter_index;           /**< Current audio conversion function */
   3.228  } SDL_AudioCVT;
   3.229  
   3.230  
   3.231  /* Function prototypes */
   3.232  
   3.233 -/* These functions return the list of built in audio drivers, in the
   3.234 - * order that they are normally initialized by default.
   3.235 +/**
   3.236 + *  \name Driver discovery functions
   3.237 + *  
   3.238 + *  These functions return the list of built in audio drivers, in the
   3.239 + *  order that they are normally initialized by default.
   3.240   */
   3.241 +/*@{*/
   3.242  extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
   3.243  extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index);
   3.244 +/*@}*/
   3.245  
   3.246 -/* These functions are used internally, and should not be used unless you
   3.247 - * have a specific need to specify the audio driver you want to use.
   3.248 - * You should normally use SDL_Init() or SDL_InitSubSystem().
   3.249 +/**
   3.250 + *  \name Initialization and cleanup
   3.251 + *  
   3.252 + *  \internal These functions are used internally, and should not be used unless
   3.253 + *            you have a specific need to specify the audio driver you want to 
   3.254 + *            use.  You should normally use SDL_Init() or SDL_InitSubSystem().
   3.255   */
   3.256 +/*@{*/
   3.257  extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name);
   3.258  extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
   3.259 +/*@}*/
   3.260  
   3.261 -/* This function returns the name of the current audio driver, or NULL
   3.262 - * if no driver has been initialized.
   3.263 +/**
   3.264 + *  This function returns the name of the current audio driver, or NULL
   3.265 + *  if no driver has been initialized.
   3.266   */
   3.267  extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
   3.268  
   3.269 -/*
   3.270 - * This function opens the audio device with the desired parameters, and
   3.271 - * returns 0 if successful, placing the actual hardware parameters in the
   3.272 - * structure pointed to by 'obtained'.  If 'obtained' is NULL, the audio
   3.273 - * data passed to the callback function will be guaranteed to be in the
   3.274 - * requested format, and will be automatically converted to the hardware
   3.275 - * audio format if necessary.  This function returns -1 if it failed 
   3.276 - * to open the audio device, or couldn't set up the audio thread.
   3.277 - *
   3.278 - * When filling in the desired audio spec structure,
   3.279 - *  'desired->freq' should be the desired audio frequency in samples-per-second.
   3.280 - *  'desired->format' should be the desired audio format.
   3.281 - *  'desired->samples' is the desired size of the audio buffer, in samples.
   3.282 - *     This number should be a power of two, and may be adjusted by the audio
   3.283 - *     driver to a value more suitable for the hardware.  Good values seem to
   3.284 - *     range between 512 and 8096 inclusive, depending on the application and
   3.285 - *     CPU speed.  Smaller values yield faster response time, but can lead
   3.286 - *     to underflow if the application is doing heavy processing and cannot
   3.287 - *     fill the audio buffer in time.  A stereo sample consists of both right
   3.288 - *     and left channels in LR ordering.
   3.289 - *     Note that the number of samples is directly related to time by the
   3.290 - *     following formula:  ms = (samples*1000)/freq
   3.291 - *  'desired->size' is the size in bytes of the audio buffer, and is
   3.292 - *     calculated by SDL_OpenAudio().
   3.293 - *  'desired->silence' is the value used to set the buffer to silence,
   3.294 - *     and is calculated by SDL_OpenAudio().
   3.295 - *  'desired->callback' should be set to a function that will be called
   3.296 - *     when the audio device is ready for more data.  It is passed a pointer
   3.297 - *     to the audio buffer, and the length in bytes of the audio buffer.
   3.298 - *     This function usually runs in a separate thread, and so you should
   3.299 - *     protect data structures that it accesses by calling SDL_LockAudio()
   3.300 - *     and SDL_UnlockAudio() in your code.
   3.301 - *  'desired->userdata' is passed as the first parameter to your callback
   3.302 - *     function.
   3.303 - *
   3.304 - * The audio device starts out playing silence when it's opened, and should
   3.305 - * be enabled for playing by calling SDL_PauseAudio(0) when you are ready
   3.306 - * for your audio callback function to be called.  Since the audio driver
   3.307 - * may modify the requested size of the audio buffer, you should allocate
   3.308 - * any local mixing buffers after you open the audio device.
   3.309 +/**
   3.310 + *  This function opens the audio device with the desired parameters, and
   3.311 + *  returns 0 if successful, placing the actual hardware parameters in the
   3.312 + *  structure pointed to by \c obtained.  If \c obtained is NULL, the audio
   3.313 + *  data passed to the callback function will be guaranteed to be in the
   3.314 + *  requested format, and will be automatically converted to the hardware
   3.315 + *  audio format if necessary.  This function returns -1 if it failed 
   3.316 + *  to open the audio device, or couldn't set up the audio thread.
   3.317 + *  
   3.318 + *  When filling in the desired audio spec structure,
   3.319 + *    - \c desired->freq should be the desired audio frequency in samples-per-
   3.320 + *      second.
   3.321 + *    - \c desired->format should be the desired audio format.
   3.322 + *    - \c desired->samples is the desired size of the audio buffer, in 
   3.323 + *      samples.  This number should be a power of two, and may be adjusted by 
   3.324 + *      the audio driver to a value more suitable for the hardware.  Good values
   3.325 + *      seem to range between 512 and 8096 inclusive, depending on the 
   3.326 + *      application and CPU speed.  Smaller values yield faster response time, 
   3.327 + *      but can lead to underflow if the application is doing heavy processing 
   3.328 + *      and cannot fill the audio buffer in time.  A stereo sample consists of 
   3.329 + *      both right and left channels in LR ordering.
   3.330 + *      Note that the number of samples is directly related to time by the
   3.331 + *      following formula:  \code ms = (samples*1000)/freq \endcode
   3.332 + *    - \c desired->size is the size in bytes of the audio buffer, and is
   3.333 + *      calculated by SDL_OpenAudio().
   3.334 + *    - \c desired->silence is the value used to set the buffer to silence,
   3.335 + *      and is calculated by SDL_OpenAudio().
   3.336 + *    - \c desired->callback should be set to a function that will be called
   3.337 + *      when the audio device is ready for more data.  It is passed a pointer
   3.338 + *      to the audio buffer, and the length in bytes of the audio buffer.
   3.339 + *      This function usually runs in a separate thread, and so you should
   3.340 + *      protect data structures that it accesses by calling SDL_LockAudio()
   3.341 + *      and SDL_UnlockAudio() in your code.
   3.342 + *    - \c desired->userdata is passed as the first parameter to your callback
   3.343 + *      function.
   3.344 + *  
   3.345 + *  The audio device starts out playing silence when it's opened, and should
   3.346 + *  be enabled for playing by calling \c SDL_PauseAudio(0) when you are ready
   3.347 + *  for your audio callback function to be called.  Since the audio driver
   3.348 + *  may modify the requested size of the audio buffer, you should allocate
   3.349 + *  any local mixing buffers after you open the audio device.
   3.350   */
   3.351  extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
   3.352                                            SDL_AudioSpec * obtained);
   3.353  
   3.354 -/*
   3.355 - * SDL Audio Device IDs.
   3.356 - * A successful call to SDL_OpenAudio() is always device id 1, and legacy
   3.357 +/**
   3.358 + *  SDL Audio Device IDs.
   3.359 + *  
   3.360 + *  A successful call to SDL_OpenAudio() is always device id 1, and legacy
   3.361   *  SDL audio APIs assume you want this device ID. SDL_OpenAudioDevice() calls
   3.362   *  always returns devices >= 2 on success. The legacy calls are good both
   3.363   *  for backwards compatibility and when you don't care about multiple,
   3.364 @@ -230,28 +288,29 @@
   3.365   */
   3.366  typedef Uint32 SDL_AudioDeviceID;
   3.367  
   3.368 -/*
   3.369 - * Get the number of available devices exposed by the current driver.
   3.370 +/**
   3.371 + *  Get the number of available devices exposed by the current driver.
   3.372   *  Only valid after a successfully initializing the audio subsystem.
   3.373   *  Returns -1 if an explicit list of devices can't be determined; this is
   3.374   *  not an error. For example, if SDL is set up to talk to a remote audio
   3.375   *  server, it can't list every one available on the Internet, but it will
   3.376   *  still allow a specific host to be specified to SDL_OpenAudioDevice().
   3.377 - * In many common cases, when this function returns a value <= 0, it can still
   3.378 + *  
   3.379 + *  In many common cases, when this function returns a value <= 0, it can still
   3.380   *  successfully open the default device (NULL for first argument of
   3.381   *  SDL_OpenAudioDevice()).
   3.382   */
   3.383  extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture);
   3.384  
   3.385 -/*
   3.386 - * Get the human-readable name of a specific audio device.
   3.387 +/**
   3.388 + *  Get the human-readable name of a specific audio device.
   3.389   *  Must be a value between 0 and (number of audio devices-1).
   3.390   *  Only valid after a successfully initializing the audio subsystem.
   3.391   *  The values returned by this function reflect the latest call to
   3.392   *  SDL_GetNumAudioDevices(); recall that function to redetect available
   3.393   *  hardware.
   3.394 - *
   3.395 - * The string returned by this function is UTF-8 encoded, read-only, and
   3.396 + *  
   3.397 + *  The string returned by this function is UTF-8 encoded, read-only, and
   3.398   *  managed internally. You are not to free it. If you need to keep the
   3.399   *  string for any length of time, you should make your own copy of it, as it
   3.400   *  will be invalid next time any of several other SDL functions is called.
   3.401 @@ -260,14 +319,17 @@
   3.402                                                             int iscapture);
   3.403  
   3.404  
   3.405 -/*
   3.406 - * Open a specific audio device. Passing in a device name of NULL requests
   3.407 +/**
   3.408 + *  Open a specific audio device. Passing in a device name of NULL requests
   3.409   *  the most reasonable default (and is equivalent to calling SDL_OpenAudio()).
   3.410 - * The device name is a UTF-8 string reported by SDL_GetAudioDevice(), but
   3.411 + *  
   3.412 + *  The device name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but
   3.413   *  some drivers allow arbitrary and driver-specific strings, such as a
   3.414   *  hostname/IP address for a remote audio server, or a filename in the
   3.415   *  diskaudio driver.
   3.416 - * Returns 0 on error, a valid device ID that is >= 2 on success.
   3.417 + *  
   3.418 + *  \return 0 on error, a valid device ID that is >= 2 on success.
   3.419 + *  
   3.420   *  SDL_OpenAudio(), unlike this function, always acts on device ID 1.
   3.421   */
   3.422  extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(const char
   3.423 @@ -283,9 +345,12 @@
   3.424  
   3.425  
   3.426  
   3.427 -/*
   3.428 - * Get the current audio state:
   3.429 +/**
   3.430 + *  \name Audio state
   3.431 + *  
   3.432 + *  Get the current audio state.
   3.433   */
   3.434 +/*@{*/
   3.435  typedef enum
   3.436  {
   3.437      SDL_AUDIO_STOPPED = 0,
   3.438 @@ -296,34 +361,41 @@
   3.439  
   3.440  extern DECLSPEC SDL_audiostatus SDLCALL
   3.441  SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
   3.442 +/*@}*//*Audio State*/
   3.443  
   3.444 -/*
   3.445 - * This function pauses and unpauses the audio callback processing.
   3.446 - * It should be called with a parameter of 0 after opening the audio
   3.447 - * device to start playing sound.  This is so you can safely initialize
   3.448 - * data for your callback function after opening the audio device.
   3.449 - * Silence will be written to the audio device during the pause.
   3.450 +/**
   3.451 + *  \name Pause audio functions
   3.452 + *  
   3.453 + *  These functions pause and unpause the audio callback processing.
   3.454 + *  They should be called with a parameter of 0 after opening the audio
   3.455 + *  device to start playing sound.  This is so you can safely initialize
   3.456 + *  data for your callback function after opening the audio device.
   3.457 + *  Silence will be written to the audio device during the pause.
   3.458   */
   3.459 +/*@{*/
   3.460  extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
   3.461  extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
   3.462                                                    int pause_on);
   3.463 +/*@}*//*Pause audio functions*/
   3.464  
   3.465 -/*
   3.466 - * This function loads a WAVE from the data source, automatically freeing
   3.467 - * that source if 'freesrc' is non-zero.  For example, to load a WAVE file,
   3.468 - * you could do:
   3.469 - *	SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...);
   3.470 +/**
   3.471 + *  This function loads a WAVE from the data source, automatically freeing
   3.472 + *  that source if \c freesrc is non-zero.  For example, to load a WAVE file,
   3.473 + *  you could do:
   3.474 + *  \code
   3.475 + *  	SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...);
   3.476 + *  \endcode
   3.477   *
   3.478 - * If this function succeeds, it returns the given SDL_AudioSpec,
   3.479 - * filled with the audio data format of the wave data, and sets
   3.480 - * 'audio_buf' to a malloc()'d buffer containing the audio data,
   3.481 - * and sets 'audio_len' to the length of that audio buffer, in bytes.
   3.482 - * You need to free the audio buffer with SDL_FreeWAV() when you are 
   3.483 - * done with it.
   3.484 + *  If this function succeeds, it returns the given SDL_AudioSpec,
   3.485 + *  filled with the audio data format of the wave data, and sets
   3.486 + *  \c *audio_buf to a malloc()'d buffer containing the audio data,
   3.487 + *  and sets \c *audio_len to the length of that audio buffer, in bytes.
   3.488 + *  You need to free the audio buffer with SDL_FreeWAV() when you are 
   3.489 + *  done with it.
   3.490   *
   3.491 - * This function returns NULL and sets the SDL error message if the 
   3.492 - * wave file cannot be opened, uses an unknown data format, or is 
   3.493 - * corrupt.  Currently raw and MS-ADPCM WAVE files are supported.
   3.494 + *  This function returns NULL and sets the SDL error message if the 
   3.495 + *  wave file cannot be opened, uses an unknown data format, or is 
   3.496 + *  corrupt.  Currently raw and MS-ADPCM WAVE files are supported.
   3.497   */
   3.498  extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
   3.499                                                        int freesrc,
   3.500 @@ -331,21 +403,25 @@
   3.501                                                        Uint8 ** audio_buf,
   3.502                                                        Uint32 * audio_len);
   3.503  
   3.504 -/* Compatibility convenience function -- loads a WAV from a file */
   3.505 +/** 
   3.506 + *  Loads a WAV from a file.
   3.507 + *  Compatibility convenience function.
   3.508 + */
   3.509  #define SDL_LoadWAV(file, spec, audio_buf, audio_len) \
   3.510  	SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
   3.511  
   3.512 -/*
   3.513 - * This function frees data previously allocated with SDL_LoadWAV_RW()
   3.514 +/**
   3.515 + *  This function frees data previously allocated with SDL_LoadWAV_RW()
   3.516   */
   3.517  extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf);
   3.518  
   3.519 -/*
   3.520 - * This function takes a source format and rate and a destination format
   3.521 - * and rate, and initializes the 'cvt' structure with information needed
   3.522 - * by SDL_ConvertAudio() to convert a buffer of audio data from one format
   3.523 - * to the other.
   3.524 - * Returns -1 if the format conversion is not supported, 0 if there's
   3.525 +/**
   3.526 + *  This function takes a source format and rate and a destination format
   3.527 + *  and rate, and initializes the \c cvt structure with information needed
   3.528 + *  by SDL_ConvertAudio() to convert a buffer of audio data from one format
   3.529 + *  to the other.
   3.530 + *  
   3.531 + *  \return -1 if the format conversion is not supported, 0 if there's
   3.532   *  no conversion needed, or 1 if the audio filter is set up.
   3.533   */
   3.534  extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
   3.535 @@ -356,29 +432,31 @@
   3.536                                                Uint8 dst_channels,
   3.537                                                int dst_rate);
   3.538  
   3.539 -/* Once you have initialized the 'cvt' structure using SDL_BuildAudioCVT(),
   3.540 - * created an audio buffer cvt->buf, and filled it with cvt->len bytes of
   3.541 - * audio data in the source format, this function will convert it in-place
   3.542 - * to the desired format.
   3.543 - * The data conversion may expand the size of the audio data, so the buffer
   3.544 - * cvt->buf should be allocated after the cvt structure is initialized by
   3.545 - * SDL_BuildAudioCVT(), and should be cvt->len*cvt->len_mult bytes long.
   3.546 +/**
   3.547 + *  Once you have initialized the \c cvt structure using SDL_BuildAudioCVT(),
   3.548 + *  created an audio buffer \c cvt->buf, and filled it with \c cvt->len bytes of
   3.549 + *  audio data in the source format, this function will convert it in-place
   3.550 + *  to the desired format.
   3.551 + *  
   3.552 + *  The data conversion may expand the size of the audio data, so the buffer
   3.553 + *  \c cvt->buf should be allocated after the \c cvt structure is initialized by
   3.554 + *  SDL_BuildAudioCVT(), and should be \c cvt->len*cvt->len_mult bytes long.
   3.555   */
   3.556  extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt);
   3.557  
   3.558 -/*
   3.559 - * This takes two audio buffers of the playing audio format and mixes
   3.560 - * them, performing addition, volume adjustment, and overflow clipping.
   3.561 - * The volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
   3.562 - * for full audio volume.  Note this does not change hardware volume.
   3.563 - * This is provided for convenience -- you can mix your own audio data.
   3.564 +#define SDL_MIX_MAXVOLUME 128
   3.565 +/**
   3.566 + *  This takes two audio buffers of the playing audio format and mixes
   3.567 + *  them, performing addition, volume adjustment, and overflow clipping.
   3.568 + *  The volume ranges from 0 - 128, and should be set to ::SDL_MIX_MAXVOLUME
   3.569 + *  for full audio volume.  Note this does not change hardware volume.
   3.570 + *  This is provided for convenience -- you can mix your own audio data.
   3.571   */
   3.572 -#define SDL_MIX_MAXVOLUME 128
   3.573  extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
   3.574                                            Uint32 len, int volume);
   3.575  
   3.576 -/*
   3.577 - * This works like SDL_MixAudio, but you specify the audio format instead of
   3.578 +/**
   3.579 + *  This works like SDL_MixAudio(), but you specify the audio format instead of
   3.580   *  using the format of audio device 1. Thus it can be used when no audio
   3.581   *  device is open at all.
   3.582   */
   3.583 @@ -387,25 +465,29 @@
   3.584                                                  SDL_AudioFormat format,
   3.585                                                  Uint32 len, int volume);
   3.586  
   3.587 -/*
   3.588 - * The lock manipulated by these functions protects the callback function.
   3.589 - * During a LockAudio/UnlockAudio pair, you can be guaranteed that the
   3.590 - * callback function is not running.  Do not call these from the callback
   3.591 - * function or you will cause deadlock.
   3.592 +/**
   3.593 + *  \name Audio lock functions
   3.594 + *  
   3.595 + *  The lock manipulated by these functions protects the callback function.
   3.596 + *  During a SDL_LockAudio()/SDL_UnlockAudio() pair, you can be guaranteed that 
   3.597 + *  the callback function is not running.  Do not call these from the callback
   3.598 + *  function or you will cause deadlock.
   3.599   */
   3.600 +/*@{*/
   3.601  extern DECLSPEC void SDLCALL SDL_LockAudio(void);
   3.602  extern DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev);
   3.603  extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
   3.604  extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev);
   3.605 +/*@}*//*Audio lock functions*/
   3.606  
   3.607 -/*
   3.608 - * This function shuts down audio processing and closes the audio device.
   3.609 +/**
   3.610 + *  This function shuts down audio processing and closes the audio device.
   3.611   */
   3.612  extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
   3.613  extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
   3.614  
   3.615 -/*
   3.616 - * Returns 1 if audio device is still functioning, zero if not, -1 on error.
   3.617 +/**
   3.618 + * \return 1 if audio device is still functioning, zero if not, -1 on error.
   3.619   */
   3.620  extern DECLSPEC int SDLCALL SDL_AudioDeviceConnected(SDL_AudioDeviceID dev);
   3.621  
     4.1 --- a/include/SDL_compat.h	Sun Oct 18 23:21:15 2009 +0000
     4.2 +++ b/include/SDL_compat.h	Mon Oct 19 13:31:58 2009 +0000
     4.3 @@ -20,13 +20,26 @@
     4.4      slouken@libsdl.org
     4.5  */
     4.6  
     4.7 -/* This file contains functions for backwards compatibility with SDL 1.2 */
     4.8 + /**
     4.9 + *  \defgroup Compatibility SDL 1.2 Compatibility API
    4.10 + */
    4.11 +/*@{*/
    4.12  
    4.13 -/* 
    4.14 -   #define SDL_NO_COMPAT to prevent SDL_compat.h from being included.
    4.15 -   SDL_NO_COMPAT is intended to make it easier to covert SDL 1.2 code to
    4.16 -   SDL 1.3/2.0
    4.17 -*/
    4.18 +/**
    4.19 + *  \file SDL_compat.h
    4.20 + *
    4.21 + *  This file contains functions for backwards compatibility with SDL 1.2.
    4.22 + */
    4.23 +
    4.24 +/**
    4.25 + *  \def SDL_NO_COMPAT
    4.26 + *
    4.27 + *  #define SDL_NO_COMPAT to prevent SDL_compat.h from being included.
    4.28 + *  SDL_NO_COMPAT is intended to make it easier to covert SDL 1.2 code to
    4.29 + *  SDL 1.3/2.0.
    4.30 + */
    4.31 +
    4.32 + /*@}*/
    4.33  
    4.34  #ifdef SDL_NO_COMPAT
    4.35  #define _SDL_compat_h
    4.36 @@ -46,7 +59,16 @@
    4.37  /* *INDENT-ON* */
    4.38  #endif
    4.39  
    4.40 -#define SDL_SWSURFACE       0x00000000  /* Not used */
    4.41 +/**
    4.42 + *  \addtogroup Compatibility
    4.43 + */
    4.44 +/*@{*/
    4.45 +
    4.46 +/**
    4.47 + *  \name Surface flags
    4.48 + */
    4.49 +/*@{*/
    4.50 +#define SDL_SWSURFACE       0x00000000  /**< \note Not used */
    4.51  #define SDL_SRCALPHA        0x00010000
    4.52  #define SDL_SRCCOLORKEY     0x00020000
    4.53  #define SDL_ANYFORMAT       0x00100000
    4.54 @@ -56,10 +78,11 @@
    4.55  #define SDL_RESIZABLE       0x01000000
    4.56  #define SDL_NOFRAME         0x02000000
    4.57  #define SDL_OPENGL          0x04000000
    4.58 -#define SDL_HWSURFACE       0x08000001  /* Not used */
    4.59 -#define SDL_ASYNCBLIT       0x08000000  /* Not used */
    4.60 -#define SDL_RLEACCELOK      0x08000000  /* Not used */
    4.61 -#define SDL_HWACCEL         0x08000000  /* Not used */
    4.62 +#define SDL_HWSURFACE       0x08000001  /**< \note Not used */
    4.63 +#define SDL_ASYNCBLIT       0x08000000  /**< \note Not used */
    4.64 +#define SDL_RLEACCELOK      0x08000000  /**< \note Not used */
    4.65 +#define SDL_HWACCEL         0x08000000  /**< \note Not used */
    4.66 +/*@}*//*Surface flags*/
    4.67  
    4.68  #define SDL_APPMOUSEFOCUS	0x01
    4.69  #define SDL_APPINPUTFOCUS	0x02
    4.70 @@ -103,35 +126,51 @@
    4.71      int current_h;
    4.72  } SDL_VideoInfo;
    4.73  
    4.74 -/* The most common video overlay formats.
    4.75 -   For an explanation of these pixel formats, see:
    4.76 -   http://www.webartz.com/fourcc/indexyuv.htm
    4.77 +/**
    4.78 + *  \name Overlay formats
    4.79 + *
    4.80 + *  The most common video overlay formats.
    4.81 + *  
    4.82 + *  For an explanation of these pixel formats, see:
    4.83 + *  http://www.webartz.com/fourcc/indexyuv.htm
    4.84 + *  
    4.85 + *  For information on the relationship between color spaces, see:
    4.86 + *  http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html
    4.87 + */
    4.88 +/*@{*/
    4.89 +#define SDL_YV12_OVERLAY  0x32315659    /**< Planar mode: Y + V + U  (3 planes) */
    4.90 +#define SDL_IYUV_OVERLAY  0x56555949    /**< Planar mode: Y + U + V  (3 planes) */
    4.91 +#define SDL_YUY2_OVERLAY  0x32595559    /**< Packed mode: Y0+U0+Y1+V0 (1 plane) */
    4.92 +#define SDL_UYVY_OVERLAY  0x59565955    /**< Packed mode: U0+Y0+V0+Y1 (1 plane) */
    4.93 +#define SDL_YVYU_OVERLAY  0x55595659    /**< Packed mode: Y0+V0+Y1+U0 (1 plane) */
    4.94 +/*@}*//*Overlay formats*/
    4.95  
    4.96 -   For information on the relationship between color spaces, see:
    4.97 -   http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html
    4.98 +/**
    4.99 + *  The YUV hardware video overlay.
   4.100   */
   4.101 -#define SDL_YV12_OVERLAY  0x32315659    /* Planar mode: Y + V + U  (3 planes) */
   4.102 -#define SDL_IYUV_OVERLAY  0x56555949    /* Planar mode: Y + U + V  (3 planes) */
   4.103 -#define SDL_YUY2_OVERLAY  0x32595559    /* Packed mode: Y0+U0+Y1+V0 (1 plane) */
   4.104 -#define SDL_UYVY_OVERLAY  0x59565955    /* Packed mode: U0+Y0+V0+Y1 (1 plane) */
   4.105 -#define SDL_YVYU_OVERLAY  0x55595659    /* Packed mode: Y0+V0+Y1+U0 (1 plane) */
   4.106 -
   4.107 -/* The YUV hardware video overlay */
   4.108  typedef struct SDL_Overlay
   4.109  {
   4.110 -    Uint32 format;              /* Read-only */
   4.111 -    int w, h;                   /* Read-only */
   4.112 -    int planes;                 /* Read-only */
   4.113 -    Uint16 *pitches;            /* Read-only */
   4.114 -    Uint8 **pixels;             /* Read-write */
   4.115 +    Uint32 format;              /**< Read-only */
   4.116 +    int w, h;                   /**< Read-only */
   4.117 +    int planes;                 /**< Read-only */
   4.118 +    Uint16 *pitches;            /**< Read-only */
   4.119 +    Uint8 **pixels;             /**< Read-write */
   4.120  
   4.121 -    /* Hardware-specific surface info */
   4.122 +    /** 
   4.123 +     *  \name Hardware-specific surface info
   4.124 +     */
   4.125 +    /*@{*/
   4.126      struct private_yuvhwfuncs *hwfuncs;
   4.127      struct private_yuvhwdata *hwdata;
   4.128 +    /*@}*//*Hardware-specific surface info*/
   4.129  
   4.130 -    /* Special flags */
   4.131 -    Uint32 hw_overlay:1;        /* Flag: This overlay hardware accelerated? */
   4.132 +    /** 
   4.133 +     *  \name Special flags
   4.134 +     */
   4.135 +    /*@{*/
   4.136 +    Uint32 hw_overlay:1;        /**< Flag: This overlay hardware accelerated? */
   4.137      Uint32 UnusedBits:31;
   4.138 +    /*@}*//*Special flags*/
   4.139  } SDL_Overlay;
   4.140  
   4.141  typedef enum
   4.142 @@ -143,9 +182,17 @@
   4.143  
   4.144  struct SDL_SysWMinfo;
   4.145  
   4.146 -/* Obsolete or renamed key codes */
   4.147 +/**
   4.148 + *  \name Obsolete or renamed key codes
   4.149 + */
   4.150 +/*@{*/
   4.151  
   4.152 -/* These key constants were renamed for clarity or consistency. */
   4.153 +/** 
   4.154 + *  \name Renamed keys
   4.155 + *
   4.156 + *  These key constants were renamed for clarity or consistency. 
   4.157 + */
   4.158 +/*@{*/
   4.159  #define SDLK_0	'0'
   4.160  #define SDLK_1	'1'
   4.161  #define SDLK_2	'2'
   4.162 @@ -214,19 +261,35 @@
   4.163  #define SDLK_NUMLOCK SDLK_NUMLOCKCLEAR
   4.164  #define SDLK_SCROLLOCK SDLK_SCROLLLOCK
   4.165  #define SDLK_PRINT SDLK_PRINTSCREEN
   4.166 +/*@}*//*Renamed keys*/
   4.167  
   4.168 -/* The META modifier is equivalent to the GUI modifier from the USB standard */
   4.169 +/**
   4.170 + *  \name META modifier
   4.171 + *  
   4.172 + *  The META modifier is equivalent to the GUI modifier from the USB standard.
   4.173 + */
   4.174 +/*@{*/
   4.175  #define KMOD_LMETA KMOD_LGUI
   4.176  #define KMOD_RMETA KMOD_RGUI
   4.177  #define KMOD_META KMOD_GUI
   4.178 +/*@}*//*META modifier*/
   4.179  
   4.180 -/* These keys don't appear in the USB specification (or at least not under those names). I'm unsure if the following assignments make sense or if these codes should be defined as actual additional SDLK_ constants. */
   4.181 +/** 
   4.182 + *  \name Not in USB
   4.183 + *
   4.184 + *  These keys don't appear in the USB specification (or at least not under 
   4.185 + *  those names). I'm unsure if the following assignments make sense or if these
   4.186 + *  codes should be defined as actual additional SDLK_ constants.
   4.187 + */
   4.188 +/*@{*/
   4.189  #define SDLK_LSUPER SDLK_LMETA
   4.190  #define SDLK_RSUPER SDLK_RMETA
   4.191  #define SDLK_COMPOSE SDLK_APPLICATION
   4.192  #define SDLK_BREAK SDLK_STOP
   4.193  #define SDLK_EURO SDLK_2
   4.194 +/*@}*//*Not in USB*/
   4.195  
   4.196 +/*@}*//*Obsolete or renamed key codes*/
   4.197  
   4.198  #define SDL_SetModuleHandle(x)
   4.199  #define SDL_AllocSurface    SDL_CreateRGBSurface
   4.200 @@ -287,6 +350,8 @@
   4.201  extern DECLSPEC void SDLCALL SDL_GetKeyRepeat(int *delay, int *interval);
   4.202  extern DECLSPEC int SDLCALL SDL_EnableUNICODE(int enable);
   4.203  
   4.204 +/*@}*//*Compatibility*/
   4.205 +
   4.206  /* Ends C function definitions when using C++ */
   4.207  #ifdef __cplusplus
   4.208  /* *INDENT-OFF* */
     5.1 --- a/include/SDL_config.h.default	Sun Oct 18 23:21:15 2009 +0000
     5.2 +++ b/include/SDL_config.h.default	Mon Oct 19 13:31:58 2009 +0000
     5.3 @@ -25,7 +25,13 @@
     5.4  
     5.5  #include "SDL_platform.h"
     5.6  
     5.7 -/* Add any platform that doesn't build using the configure system */
     5.8 +/**
     5.9 + *  \file SDL_config.h.default
    5.10 + *
    5.11 + *  SDL_config.h for any platform that doesn't build using the configure system.
    5.12 + */
    5.13 + 
    5.14 +/* Add any platform that doesn't build using the configure system. */
    5.15  #if defined(__NINTENDODS__)
    5.16  #include "SDL_config_nintendods.h"
    5.17  #elif defined(__IPHONEOS__) 
     6.1 --- a/include/SDL_config.h.in	Sun Oct 18 23:21:15 2009 +0000
     6.2 +++ b/include/SDL_config.h.in	Mon Oct 19 13:31:58 2009 +0000
     6.3 @@ -23,7 +23,11 @@
     6.4  #ifndef _SDL_config_h
     6.5  #define _SDL_config_h
     6.6  
     6.7 -/* This is a set of defines to configure the SDL features */
     6.8 +/**
     6.9 + *  \file SDL_config.h.in
    6.10 + *
    6.11 + *  This is a set of defines to configure the SDL features
    6.12 + */
    6.13  
    6.14  /* General platform specific identifiers */
    6.15  #include "SDL_platform.h"
     7.1 --- a/include/SDL_config_minimal.h	Sun Oct 18 23:21:15 2009 +0000
     7.2 +++ b/include/SDL_config_minimal.h	Mon Oct 19 13:31:58 2009 +0000
     7.3 @@ -25,7 +25,11 @@
     7.4  
     7.5  #include "SDL_platform.h"
     7.6  
     7.7 -/* This is the minimal configuration that can be used to build SDL */
     7.8 +/**
     7.9 + *  \file SDL_config_minimal.h
    7.10 + *  
    7.11 + *  This is the minimal configuration that can be used to build SDL.
    7.12 + */
    7.13  
    7.14  #include <stdarg.h>
    7.15  
     8.1 --- a/include/SDL_cpuinfo.h	Sun Oct 18 23:21:15 2009 +0000
     8.2 +++ b/include/SDL_cpuinfo.h	Mon Oct 19 13:31:58 2009 +0000
     8.3 @@ -21,9 +21,9 @@
     8.4  */
     8.5  
     8.6  /**
     8.7 - * \file SDL_cpuinfo.h
     8.8 - *
     8.9 - * CPU feature detection for SDL
    8.10 + *  \file SDL_cpuinfo.h
    8.11 + *  
    8.12 + *  CPU feature detection for SDL.
    8.13   */
    8.14  
    8.15  #ifndef _SDL_cpuinfo_h
    8.16 @@ -39,35 +39,43 @@
    8.17  /* *INDENT-ON* */
    8.18  #endif
    8.19  
    8.20 -/* This function returns true if the CPU has the RDTSC instruction
    8.21 +/**
    8.22 + *  This function returns true if the CPU has the RDTSC instruction.
    8.23   */
    8.24  extern DECLSPEC SDL_bool SDLCALL SDL_HasRDTSC(void);
    8.25  
    8.26 -/* This function returns true if the CPU has MMX features
    8.27 +/**
    8.28 + *  This function returns true if the CPU has MMX features.
    8.29   */
    8.30  extern DECLSPEC SDL_bool SDLCALL SDL_HasMMX(void);
    8.31  
    8.32 -/* This function returns true if the CPU has MMX Ext. features
    8.33 +/**
    8.34 + *  This function returns true if the CPU has MMX Ext.\ features.
    8.35   */
    8.36  extern DECLSPEC SDL_bool SDLCALL SDL_HasMMXExt(void);
    8.37  
    8.38 -/* This function returns true if the CPU has 3DNow features
    8.39 +/**
    8.40 + *  This function returns true if the CPU has 3DNow!\ features.
    8.41   */
    8.42  extern DECLSPEC SDL_bool SDLCALL SDL_Has3DNow(void);
    8.43  
    8.44 -/* This function returns true if the CPU has 3DNow! Ext. features
    8.45 +/**
    8.46 + *  This function returns true if the CPU has 3DNow!\ Ext.\ features.
    8.47   */
    8.48  extern DECLSPEC SDL_bool SDLCALL SDL_Has3DNowExt(void);
    8.49  
    8.50 -/* This function returns true if the CPU has SSE features
    8.51 +/**
    8.52 + *  This function returns true if the CPU has SSE features.
    8.53   */
    8.54  extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE(void);
    8.55  
    8.56 -/* This function returns true if the CPU has SSE2 features
    8.57 +/**
    8.58 + *  This function returns true if the CPU has SSE2 features.
    8.59   */
    8.60  extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE2(void);
    8.61  
    8.62 -/* This function returns true if the CPU has AltiVec features
    8.63 +/**
    8.64 + *  This function returns true if the CPU has AltiVec features.
    8.65   */
    8.66  extern DECLSPEC SDL_bool SDLCALL SDL_HasAltiVec(void);
    8.67  
     9.1 --- a/include/SDL_endian.h	Sun Oct 18 23:21:15 2009 +0000
     9.2 +++ b/include/SDL_endian.h	Mon Oct 19 13:31:58 2009 +0000
     9.3 @@ -21,9 +21,9 @@
     9.4  */
     9.5  
     9.6  /**
     9.7 - * \file SDL_endian.h
     9.8 - *
     9.9 - * Functions for reading and writing endian-specific values
    9.10 + *  \file SDL_endian.h
    9.11 + *  
    9.12 + *  Functions for reading and writing endian-specific values
    9.13   */
    9.14  
    9.15  #ifndef _SDL_endian_h
    9.16 @@ -31,9 +31,13 @@
    9.17  
    9.18  #include "SDL_stdinc.h"
    9.19  
    9.20 -/* The two types of endianness */
    9.21 +/**
    9.22 + *  \name The two types of endianness
    9.23 + */
    9.24 +/*@{*/
    9.25  #define SDL_LIL_ENDIAN	1234
    9.26  #define SDL_BIG_ENDIAN	4321
    9.27 +/*@}*/
    9.28  
    9.29  #ifndef SDL_BYTEORDER           /* Not defined in SDL_config.h? */
    9.30  #if defined(__hppa__) || \
    9.31 @@ -56,11 +60,14 @@
    9.32  /* *INDENT-ON* */
    9.33  #endif
    9.34  
    9.35 -/* Use inline functions for compilers that support them, and static
    9.36 -   functions for those that do not.  Because these functions become
    9.37 -   static for compilers that do not support inline functions, this
    9.38 -   header should only be included in files that actually use them.
    9.39 -*/
    9.40 +/**
    9.41 + *  \file SDL_endian.h
    9.42 + *  
    9.43 + *  Uses inline functions for compilers that support them, and static
    9.44 + *  functions for those that do not.  Because these functions become
    9.45 + *  static for compilers that do not support inline functions, this
    9.46 + *  header should only be included in files that actually use them.
    9.47 + */
    9.48  #if defined(__GNUC__) && defined(__i386__) && \
    9.49     !(__GNUC__ == 2 && __GNUC_MINOR__ == 95 /* broken gcc version */)
    9.50  static __inline__ Uint16
    9.51 @@ -184,10 +191,11 @@
    9.52  }
    9.53  #endif
    9.54  #else
    9.55 -/* This is mainly to keep compilers from complaining in SDL code.
    9.56 -   If there is no real 64-bit datatype, then compilers will complain about
    9.57 -   the fake 64-bit datatype that SDL provides when it compiles user code.
    9.58 -*/
    9.59 +/**
    9.60 + *  This is mainly to keep compilers from complaining in SDL code.
    9.61 + *  If there is no real 64-bit datatype, then compilers will complain about
    9.62 + *  the fake 64-bit datatype that SDL provides when it compiles user code.
    9.63 + */
    9.64  #define SDL_Swap64(X)	(X)
    9.65  #endif /* SDL_HAS_64BIT_TYPE */
    9.66  
    9.67 @@ -206,7 +214,11 @@
    9.68  }
    9.69  
    9.70  
    9.71 -/* Byteswap item from the specified endianness to the native endianness */
    9.72 +/**
    9.73 + *  \name Swap to native
    9.74 + *  Byteswap item from the specified endianness to the native endianness.
    9.75 + */
    9.76 +/*@{*/
    9.77  #if SDL_BYTEORDER == SDL_LIL_ENDIAN
    9.78  #define SDL_SwapLE16(X)	(X)
    9.79  #define SDL_SwapLE32(X)	(X)
    9.80 @@ -226,6 +238,7 @@
    9.81  #define SDL_SwapBE64(X)	(X)
    9.82  #define SDL_SwapFloatBE(X)	(X)
    9.83  #endif
    9.84 +/*@}*//*Swap to native*/
    9.85  
    9.86  /* Ends C function definitions when using C++ */
    9.87  #ifdef __cplusplus
    10.1 --- a/include/SDL_error.h	Sun Oct 18 23:21:15 2009 +0000
    10.2 +++ b/include/SDL_error.h	Mon Oct 19 13:31:58 2009 +0000
    10.3 @@ -21,8 +21,9 @@
    10.4  */
    10.5  
    10.6  /**
    10.7 - * \file SDL_error.h
    10.8 - * Simple error message routines for SDL
    10.9 + *  \file SDL_error.h
   10.10 + *  
   10.11 + *  Simple error message routines for SDL.
   10.12   */
   10.13  
   10.14  #ifndef _SDL_error_h
   10.15 @@ -43,7 +44,13 @@
   10.16  extern DECLSPEC char *SDLCALL SDL_GetError(void);
   10.17  extern DECLSPEC void SDLCALL SDL_ClearError(void);
   10.18  
   10.19 -/* Private error message function - used internally */
   10.20 +/**
   10.21 + *  \name Internal error functions
   10.22 + *  
   10.23 + *  \internal 
   10.24 + *  Private error message function - used internally.
   10.25 + */
   10.26 +/*@{*/
   10.27  #define SDL_OutOfMemory()	SDL_Error(SDL_ENOMEM)
   10.28  #define SDL_Unsupported()	SDL_Error(SDL_UNSUPPORTED)
   10.29  typedef enum
   10.30 @@ -56,7 +63,7 @@
   10.31      SDL_LASTERROR
   10.32  } SDL_errorcode;
   10.33  extern DECLSPEC void SDLCALL SDL_Error(SDL_errorcode code);
   10.34 -
   10.35 +/*@}*//*Internal error functions*/
   10.36  
   10.37  /* Ends C function definitions when using C++ */
   10.38  #ifdef __cplusplus
    11.1 --- a/include/SDL_events.h	Sun Oct 18 23:21:15 2009 +0000
    11.2 +++ b/include/SDL_events.h	Mon Oct 19 13:31:58 2009 +0000
    11.3 @@ -21,9 +21,9 @@
    11.4  */
    11.5  
    11.6  /**
    11.7 - * \file SDL_events.h
    11.8 - *
    11.9 - * Include file for SDL event handling
   11.10 + *  \file SDL_events.h
   11.11 + *  
   11.12 + *  Include file for SDL event handling.
   11.13   */
   11.14  
   11.15  #ifndef _SDL_events_h
   11.16 @@ -50,9 +50,7 @@
   11.17  #define SDL_PRESSED	1
   11.18  
   11.19  /**
   11.20 - * \enum SDL_EventType
   11.21 - *
   11.22 - * \brief The types of events that can be delivered
   11.23 + * \brief The types of events that can be delivered.
   11.24   */
   11.25  typedef enum
   11.26  {
   11.27 @@ -76,22 +74,22 @@
   11.28      SDL_PROXIMITYIN,            /**< Proximity In event */
   11.29      SDL_PROXIMITYOUT,           /**< Proximity Out event */
   11.30      SDL_EVENT_RESERVED1,        /**< Reserved for future use... */
   11.31 -    SDL_EVENT_RESERVED2,
   11.32 -    SDL_EVENT_RESERVED3,
   11.33 -    /* Events SDL_USEREVENT through SDL_MAXEVENTS-1 are for your use */
   11.34 +    SDL_EVENT_RESERVED2,        /**< Reserved for future use... */
   11.35 +    SDL_EVENT_RESERVED3,        /**< Reserved for future use... */
   11.36 +    /** Events ::SDL_USEREVENT through ::SDL_MAXEVENTS-1 are for your use */
   11.37      SDL_USEREVENT = 24,
   11.38 -    /* This last event is only for bounding internal arrays
   11.39 -       It is the number of bits in the event mask datatype -- Uint32
   11.40 +    /**
   11.41 +     *  This last event is only for bounding internal arrays
   11.42 +     *  It is the number of bits in the event mask datatype -- Uint32
   11.43       */
   11.44      SDL_NUMEVENTS = 32
   11.45  } SDL_EventType;
   11.46  
   11.47 +/*@{*/
   11.48 +#define SDL_EVENTMASK(X)	(1<<(X))
   11.49  /**
   11.50 - * \enum SDL_EventMask
   11.51 - *
   11.52   * \brief Predefined event masks
   11.53   */
   11.54 -#define SDL_EVENTMASK(X)	(1<<(X))
   11.55  typedef enum
   11.56  {
   11.57      SDL_WINDOWEVENTMASK = SDL_EVENTMASK(SDL_WINDOWEVENT),
   11.58 @@ -121,71 +119,63 @@
   11.59      SDL_PROXIMITYOUTMASK = SDL_EVENTMASK(SDL_PROXIMITYOUT)
   11.60  } SDL_EventMask;
   11.61  #define SDL_ALLEVENTS		0xFFFFFFFF
   11.62 +/*@}*/
   11.63  
   11.64  /**
   11.65 - * \struct SDL_WindowEvent
   11.66 - *
   11.67 - * \brief Window state change event data (event.window.*)
   11.68 + *  \brief Window state change event data (event.window.*)
   11.69   */
   11.70  typedef struct SDL_WindowEvent
   11.71  {
   11.72 -    Uint8 type;             /**< SDL_WINDOWEVENT */
   11.73 +    Uint8 type;             /**< ::SDL_WINDOWEVENT */
   11.74      SDL_WindowID windowID;  /**< The associated window */
   11.75 -    Uint8 event;            /**< SDL_WindowEventID */
   11.76 +    Uint8 event;            /**< ::SDL_WindowEventID */
   11.77      int data1;              /**< event dependent data */
   11.78      int data2;              /**< event dependent data */
   11.79  } SDL_WindowEvent;
   11.80  
   11.81  /**
   11.82 - * \struct SDL_KeyboardEvent
   11.83 - *
   11.84 - * \brief Keyboard button event structure (event.key.*)
   11.85 + *  \brief Keyboard button event structure (event.key.*)
   11.86   */
   11.87  typedef struct SDL_KeyboardEvent
   11.88  {
   11.89 -    Uint8 type;             /**< SDL_KEYDOWN or SDL_KEYUP */
   11.90 +    Uint8 type;             /**< ::SDL_KEYDOWN or ::SDL_KEYUP */
   11.91      SDL_WindowID windowID;  /**< The window with keyboard focus, if any */
   11.92      Uint8 which;            /**< The keyboard device index */
   11.93 -    Uint8 state;            /**< SDL_PRESSED or SDL_RELEASED */
   11.94 +    Uint8 state;            /**< ::SDL_PRESSED or ::SDL_RELEASED */
   11.95      SDL_keysym keysym;      /**< The key that was pressed or released */
   11.96  } SDL_KeyboardEvent;
   11.97  
   11.98 +#define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32)
   11.99  /**
  11.100 - * \struct SDL_TextEditingEvent
  11.101 - *
  11.102 - * \brief Keyboard text editing event structure (event.edit.*)
  11.103 + *  \brief Keyboard text editing event structure (event.edit.*)
  11.104   */
  11.105 -#define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32)
  11.106  typedef struct SDL_TextEditingEvent
  11.107  {
  11.108 -    Uint8 type;                                 /**< SDL_TEXTEDITING */
  11.109 +    Uint8 type;                                 /**< ::SDL_TEXTEDITING */
  11.110      char text[SDL_TEXTEDITINGEVENT_TEXT_SIZE];  /**< The editing text */
  11.111      int start;                                  /**< The start cursor of selected editing text */
  11.112      int length;                                 /**< The length of selected editing text */
  11.113  } SDL_TextEditingEvent;
  11.114  
  11.115 +
  11.116 +#define SDL_TEXTINPUTEVENT_TEXT_SIZE (32)
  11.117  /**
  11.118 - * \struct SDL_TextInputEvent
  11.119 - *
  11.120 - * \brief Keyboard text input event structure (event.text.*)
  11.121 + *  \brief Keyboard text input event structure (event.text.*)
  11.122   */
  11.123 -#define SDL_TEXTINPUTEVENT_TEXT_SIZE (32)
  11.124  typedef struct SDL_TextInputEvent
  11.125  {
  11.126 -    Uint8 type;                               /**< SDL_TEXTINPUT */
  11.127 +    Uint8 type;                               /**< ::SDL_TEXTINPUT */
  11.128      SDL_WindowID windowID;                    /**< The window with keyboard focus, if any */
  11.129      Uint8 which;                              /**< The keyboard device index */
  11.130      char text[SDL_TEXTINPUTEVENT_TEXT_SIZE];  /**< The input text */
  11.131  } SDL_TextInputEvent;
  11.132  
  11.133  /**
  11.134 - * \struct SDL_MouseMotionEvent
  11.135 - *
  11.136 - * \brief Mouse motion event structure (event.motion.*)
  11.137 + *  \brief Mouse motion event structure (event.motion.*)
  11.138   */
  11.139  typedef struct SDL_MouseMotionEvent
  11.140  {
  11.141 -    Uint8 type;             /**< SDL_MOUSEMOTION */
  11.142 +    Uint8 type;             /**< ::SDL_MOUSEMOTION */
  11.143      SDL_WindowID windowID;  /**< The window with mouse focus, if any */
  11.144      Uint8 which;            /**< The mouse device index */
  11.145      Uint8 state;            /**< The current button state */
  11.146 @@ -203,29 +193,25 @@
  11.147  } SDL_MouseMotionEvent;
  11.148  
  11.149  /**
  11.150 - * \struct SDL_MouseButtonEvent
  11.151 - *
  11.152 - * \brief Mouse button event structure (event.button.*)
  11.153 + *  \brief Mouse button event structure (event.button.*)
  11.154   */
  11.155  typedef struct SDL_MouseButtonEvent
  11.156  {
  11.157 -    Uint8 type;             /**< SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */
  11.158 +    Uint8 type;             /**< ::SDL_MOUSEBUTTONDOWN or ::SDL_MOUSEBUTTONUP */
  11.159      SDL_WindowID windowID;  /**< The window with mouse focus, if any */
  11.160      Uint8 which;            /**< The mouse device index */
  11.161      Uint8 button;           /**< The mouse button index */
  11.162 -    Uint8 state;            /**< SDL_PRESSED or SDL_RELEASED */
  11.163 +    Uint8 state;            /**< ::SDL_PRESSED or ::SDL_RELEASED */
  11.164      int x;                  /**< X coordinate, relative to window */
  11.165      int y;                  /**< Y coordinate, relative to window */
  11.166  } SDL_MouseButtonEvent;
  11.167  
  11.168  /**
  11.169 - * \struct SDL_MouseWheelEvent
  11.170 - *
  11.171 - * \brief Mouse wheel event structure (event.wheel.*)
  11.172 + *  \brief Mouse wheel event structure (event.wheel.*)
  11.173   */
  11.174  typedef struct SDL_MouseWheelEvent
  11.175  {
  11.176 -    Uint8 type;             /**< SDL_MOUSEWHEEL */
  11.177 +    Uint8 type;             /**< ::SDL_MOUSEWHEEL */
  11.178      SDL_WindowID windowID;  /**< The window with mouse focus, if any */
  11.179      Uint8 which;            /**< The mouse device index */
  11.180      int x;                  /**< The amount scrolled horizontally */
  11.181 @@ -233,26 +219,22 @@
  11.182  } SDL_MouseWheelEvent;
  11.183  
  11.184  /**
  11.185 - * \struct SDL_JoyAxisEvent
  11.186 - *
  11.187 - * \brief Joystick axis motion event structure (event.jaxis.*)
  11.188 + *  \brief Joystick axis motion event structure (event.jaxis.*)
  11.189   */
  11.190  typedef struct SDL_JoyAxisEvent
  11.191  {
  11.192 -    Uint8 type;         /**< SDL_JOYAXISMOTION */
  11.193 +    Uint8 type;         /**< ::SDL_JOYAXISMOTION */
  11.194      Uint8 which;        /**< The joystick device index */
  11.195      Uint8 axis;         /**< The joystick axis index */
  11.196      int value;          /**< The axis value (range: -32768 to 32767) */
  11.197  } SDL_JoyAxisEvent;
  11.198  
  11.199  /**
  11.200 - * \struct SDL_JoyBallEvent
  11.201 - *
  11.202 - * \brief Joystick trackball motion event structure (event.jball.*)
  11.203 + *  \brief Joystick trackball motion event structure (event.jball.*)
  11.204   */
  11.205  typedef struct SDL_JoyBallEvent
  11.206  {
  11.207 -    Uint8 type;         /**< SDL_JOYBALLMOTION */
  11.208 +    Uint8 type;         /**< ::SDL_JOYBALLMOTION */
  11.209      Uint8 which;        /**< The joystick device index */
  11.210      Uint8 ball;         /**< The joystick trackball index */
  11.211      int xrel;           /**< The relative motion in the X direction */
  11.212 @@ -260,72 +242,64 @@
  11.213  } SDL_JoyBallEvent;
  11.214  
  11.215  /**
  11.216 - * \struct SDL_JoyHatEvent
  11.217 - *
  11.218 - * \brief Joystick hat position change event structure (event.jhat.*)
  11.219 + *  \brief Joystick hat position change event structure (event.jhat.*)
  11.220   */
  11.221  typedef struct SDL_JoyHatEvent
  11.222  {
  11.223 -    Uint8 type;         /**< SDL_JOYHATMOTION */
  11.224 +    Uint8 type;         /**< ::SDL_JOYHATMOTION */
  11.225      Uint8 which;        /**< The joystick device index */
  11.226      Uint8 hat;          /**< The joystick hat index */
  11.227 -    Uint8 value;        /**< The hat position value:
  11.228 -                             SDL_HAT_LEFTUP   SDL_HAT_UP       SDL_HAT_RIGHTUP
  11.229 -                             SDL_HAT_LEFT     SDL_HAT_CENTERED SDL_HAT_RIGHT
  11.230 -                             SDL_HAT_LEFTDOWN SDL_HAT_DOWN     SDL_HAT_RIGHTDOWN
  11.231 -                             Note that zero means the POV is centered.
  11.232 +    Uint8 value;        /**< The hat position value.
  11.233 +                         *   \sa ::SDL_HAT_LEFTUP ::SDL_HAT_UP ::SDL_HAT_RIGHTUP
  11.234 +                         *   \sa ::SDL_HAT_LEFT ::SDL_HAT_CENTERED ::SDL_HAT_RIGHT
  11.235 +                         *   \sa ::SDL_HAT_LEFTDOWN ::SDL_HAT_DOWN ::SDL_HAT_RIGHTDOWN
  11.236 +                         *   
  11.237 +                         *   Note that zero means the POV is centered.
  11.238                           */
  11.239  } SDL_JoyHatEvent;
  11.240  
  11.241  /**
  11.242 - * \struct SDL_JoyButtonEvent
  11.243 - *
  11.244 - * \brief Joystick button event structure (event.jbutton.*)
  11.245 + *  \brief Joystick button event structure (event.jbutton.*)
  11.246   */
  11.247  typedef struct SDL_JoyButtonEvent
  11.248  {
  11.249 -    Uint8 type;         /**< SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP */
  11.250 +    Uint8 type;         /**< ::SDL_JOYBUTTONDOWN or ::SDL_JOYBUTTONUP */
  11.251      Uint8 which;        /**< The joystick device index */
  11.252      Uint8 button;       /**< The joystick button index */
  11.253 -    Uint8 state;        /**< SDL_PRESSED or SDL_RELEASED */
  11.254 +    Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
  11.255  } SDL_JoyButtonEvent;
  11.256  
  11.257  /**
  11.258 - * \struct SDL_QuitEvent
  11.259 - *
  11.260 - * \brief The "quit requested" event
  11.261 + *  \brief The "quit requested" event
  11.262   */
  11.263  typedef struct SDL_QuitEvent
  11.264  {
  11.265 -    Uint8 type;         /**< SDL_QUIT */
  11.266 +    Uint8 type;         /**< ::SDL_QUIT */
  11.267  } SDL_QuitEvent;
  11.268  
  11.269  /**
  11.270 - * \struct SDL_UserEvent
  11.271 - *
  11.272 - * \brief A user-defined event type (event.user.*)
  11.273 + *  \brief A user-defined event type (event.user.*)
  11.274   */
  11.275  typedef struct SDL_UserEvent
  11.276  {
  11.277 -    Uint8 type;             /**< SDL_USEREVENT through SDL_NUMEVENTS-1 */
  11.278 +    Uint8 type;             /**< ::SDL_USEREVENT through ::SDL_NUMEVENTS-1 */
  11.279      SDL_WindowID windowID;  /**< The associated window if any*/
  11.280      int code;               /**< User defined event code */
  11.281      void *data1;            /**< User defined data pointer */
  11.282      void *data2;            /**< User defined data pointer */
  11.283  } SDL_UserEvent;
  11.284  
  11.285 -/**
  11.286 - * \struct SDL_SysWMEvent
  11.287 - *
  11.288 - * \brief A video driver dependent system event (event.syswm.*)
  11.289 - *
  11.290 - * \note If you want to use this event, you should include SDL_syswm.h
  11.291 - */
  11.292  struct SDL_SysWMmsg;
  11.293  typedef struct SDL_SysWMmsg SDL_SysWMmsg;
  11.294 +
  11.295 +/**
  11.296 + *  \brief A video driver dependent system event (event.syswm.*)
  11.297 + *  
  11.298 + *  \note If you want to use this event, you should include SDL_syswm.h.
  11.299 + */
  11.300  typedef struct SDL_SysWMEvent
  11.301  {
  11.302 -    Uint8 type;         /**< SDL_SYSWMEVENT */
  11.303 +    Uint8 type;         /**< ::SDL_SYSWMEVENT */
  11.304      SDL_SysWMmsg *msg;  /**< driver dependent data, defined in SDL_syswm.h */
  11.305  } SDL_SysWMEvent;
  11.306  
  11.307 @@ -339,8 +313,16 @@
  11.308      int y;
  11.309  } SDL_ProximityEvent;
  11.310  
  11.311 -/* Typedefs for backwards compatibility */
  11.312  #ifndef SDL_NO_COMPAT
  11.313 +/**
  11.314 + *  \addtogroup Compatibility 
  11.315 + */
  11.316 +/*@{*/
  11.317 +
  11.318 +/**
  11.319 + *  \name Typedefs for backwards compatibility
  11.320 + */
  11.321 +/*@{*/
  11.322  typedef struct SDL_ActiveEvent
  11.323  {
  11.324      Uint8 type;
  11.325 @@ -354,12 +336,13 @@
  11.326      int w;
  11.327      int h;
  11.328  } SDL_ResizeEvent;
  11.329 +/*@}*/
  11.330 +
  11.331 +/*@}*//*Compatibility*/
  11.332  #endif
  11.333  
  11.334  /**
  11.335 - * \union SDL_Event
  11.336 - *
  11.337 - * \brief General event structure
  11.338 + *  \brief General event structure
  11.339   */
  11.340  typedef union SDL_Event
  11.341  {
  11.342 @@ -380,129 +363,164 @@
  11.343      SDL_SysWMEvent syswm;           /**< System dependent window event data */
  11.344      SDL_ProximityEvent proximity;   /**< Proximity In or Out event */
  11.345  
  11.346 -    /* Temporarily here for backwards compatibility */
  11.347 +    /** Temporarily here for backwards compatibility */
  11.348 +    /*@{*/
  11.349  #ifndef SDL_NO_COMPAT
  11.350      SDL_ActiveEvent active;
  11.351      SDL_ResizeEvent resize;
  11.352  #endif
  11.353 +    /*@}*/
  11.354  } SDL_Event;
  11.355  
  11.356  
  11.357  /* Function prototypes */
  11.358  
  11.359 -/* Pumps the event loop, gathering events from the input devices.
  11.360 -   This function updates the event queue and internal input device state.
  11.361 -   This should only be run in the thread that sets the video mode.
  11.362 -*/
  11.363 +/**
  11.364 + *  Pumps the event loop, gathering events from the input devices.
  11.365 + *  
  11.366 + *  This function updates the event queue and internal input device state.
  11.367 + *  
  11.368 + *  This should only be run in the thread that sets the video mode.
  11.369 + */
  11.370  extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
  11.371  
  11.372 -/* Checks the event queue for messages and optionally returns them.
  11.373 -   If 'action' is SDL_ADDEVENT, up to 'numevents' events will be added to
  11.374 -   the back of the event queue.
  11.375 -   If 'action' is SDL_PEEKEVENT, up to 'numevents' events at the front
  11.376 -   of the event queue, matching 'mask', will be returned and will not
  11.377 -   be removed from the queue.
  11.378 -   If 'action' is SDL_GETEVENT, up to 'numevents' events at the front 
  11.379 -   of the event queue, matching 'mask', will be returned and will be
  11.380 -   removed from the queue.
  11.381 -   This function returns the number of events actually stored, or -1
  11.382 -   if there was an error.  This function is thread-safe.
  11.383 -*/
  11.384 +/*@{*/
  11.385  typedef enum
  11.386  {
  11.387      SDL_ADDEVENT,
  11.388      SDL_PEEKEVENT,
  11.389      SDL_GETEVENT
  11.390  } SDL_eventaction;
  11.391 -/* */
  11.392 +
  11.393 +/**
  11.394 + *  Checks the event queue for messages and optionally returns them.
  11.395 + *  
  11.396 + *  If \c action is ::SDL_ADDEVENT, up to \c numevents events will be added to
  11.397 + *  the back of the event queue.
  11.398 + *  
  11.399 + *  If \c action is ::SDL_PEEKEVENT, up to \c numevents events at the front
  11.400 + *  of the event queue, matching \c mask, will be returned and will not
  11.401 + *  be removed from the queue.
  11.402 + *  
  11.403 + *  If \c action is ::SDL_GETEVENT, up to \c numevents events at the front 
  11.404 + *  of the event queue, matching \c mask, will be returned and will be
  11.405 + *  removed from the queue.
  11.406 + *  
  11.407 + *  \return The number of events actually stored, or -1 if there was an error.
  11.408 + *  
  11.409 + *  This function is thread-safe.
  11.410 + */
  11.411  extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
  11.412                                             SDL_eventaction action,
  11.413                                             Uint32 mask);
  11.414 +/*@}*/
  11.415  
  11.416 -/* Checks to see if certain event types are in the event queue.
  11.417 +/**
  11.418 + *  Checks to see if certain event types are in the event queue.
  11.419   */
  11.420  extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 mask);
  11.421  
  11.422 -/* Polls for currently pending events, and returns 1 if there are any pending
  11.423 -   events, or 0 if there are none available.  If 'event' is not NULL, the next
  11.424 -   event is removed from the queue and stored in that area.
  11.425 +/**
  11.426 + *  \brief Polls for currently pending events.
  11.427 + *  
  11.428 + *  \return 1 if there are any pending events, or 0 if there are none available.
  11.429 + *  
  11.430 + *  \param event If not NULL, the next event is removed from the queue and 
  11.431 + *               stored in that area.
  11.432   */
  11.433  extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
  11.434  
  11.435 -/* Waits indefinitely for the next available event, returning 1, or 0 if there
  11.436 -   was an error while waiting for events.  If 'event' is not NULL, the next
  11.437 -   event is removed from the queue and stored in that area.
  11.438 +/**
  11.439 + *  \brief Waits indefinitely for the next available event.
  11.440 + *  
  11.441 + *  \return 1, or 0 if there was an error while waiting for events.
  11.442 + *   
  11.443 + *  \param event If not NULL, the next event is removed from the queue and 
  11.444 + *               stored in that area.
  11.445   */
  11.446  extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
  11.447  
  11.448 -/* Waits until the specified timeout (in milliseconds) for the next available
  11.449 -   event, returning 1, or 0 if there was an error while waiting for events. If
  11.450 -   'event' is not NULL, the next event is removed from the queue and stored in
  11.451 -   that area.
  11.452 +/**
  11.453 + *  \brief Waits until the specified timeout (in milliseconds) for the next 
  11.454 + *         available event.
  11.455 + *  
  11.456 + *  \return 1, or 0 if there was an error while waiting for events.
  11.457 + *  
  11.458 + *  \param event If not NULL, the next event is removed from the queue and 
  11.459 + *               stored in that area.
  11.460   */
  11.461  extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event,
  11.462                                                   int timeout);
  11.463  
  11.464 -/* Add an event to the event queue.
  11.465 -   This function returns 1 on success, 0 if the event was filtered,
  11.466 -   or -1 if the event queue was full or there was some other error.
  11.467 +/**
  11.468 + *  \brief Add an event to the event queue.
  11.469 + *  
  11.470 + *  \return 1 on success, 0 if the event was filtered, or -1 if the event queue 
  11.471 + *          was full or there was some other error.
  11.472   */
  11.473  extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
  11.474  
  11.475 -/*
  11.476 -  This function sets up a filter to process all events before they
  11.477 -  change internal state and are posted to the internal event queue.
  11.478 +typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
  11.479  
  11.480 -  The filter is protypted as:
  11.481 -*/
  11.482 -typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
  11.483 -/*
  11.484 -  If the filter returns 1, then the event will be added to the internal queue.
  11.485 -  If it returns 0, then the event will be dropped from the queue, but the 
  11.486 -  internal state will still be updated.  This allows selective filtering of
  11.487 -  dynamically arriving events.
  11.488 -
  11.489 -  WARNING:  Be very careful of what you do in the event filter function, as 
  11.490 -            it may run in a different thread!
  11.491 -
  11.492 -  There is one caveat when dealing with the SDL_QUITEVENT event type.  The
  11.493 -  event filter is only called when the window manager desires to close the
  11.494 -  application window.  If the event filter returns 1, then the window will
  11.495 -  be closed, otherwise the window will remain open if possible.
  11.496 -  If the quit event is generated by an interrupt signal, it will bypass the
  11.497 -  internal queue and be delivered to the application at the next event poll.
  11.498 -*/
  11.499 +/**
  11.500 + *  Sets up a filter to process all events before they change internal state and
  11.501 + *  are posted to the internal event queue.
  11.502 + *  
  11.503 + *  The filter is protypted as:
  11.504 + *  \code
  11.505 + *      int SDL_EventFilter(void *userdata, SDL_Event * event);
  11.506 + *  \endcode
  11.507 + *
  11.508 + *  If the filter returns 1, then the event will be added to the internal queue.
  11.509 + *  If it returns 0, then the event will be dropped from the queue, but the 
  11.510 + *  internal state will still be updated.  This allows selective filtering of
  11.511 + *  dynamically arriving events.
  11.512 + *  
  11.513 + *  \warning  Be very careful of what you do in the event filter function, as 
  11.514 + *            it may run in a different thread!
  11.515 + *  
  11.516 + *  There is one caveat when dealing with the ::SDL_QUITEVENT event type.  The
  11.517 + *  event filter is only called when the window manager desires to close the
  11.518 + *  application window.  If the event filter returns 1, then the window will
  11.519 + *  be closed, otherwise the window will remain open if possible.
  11.520 + *
  11.521 + *  If the quit event is generated by an interrupt signal, it will bypass the
  11.522 + *  internal queue and be delivered to the application at the next event poll.
  11.523 + */
  11.524  extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
  11.525                                                  void *userdata);
  11.526  
  11.527 -/*
  11.528 -  Return the current event filter - can be used to "chain" filters.
  11.529 -  If there is no event filter set, this function returns SDL_FALSE.
  11.530 -*/
  11.531 +/**
  11.532 + *  Return the current event filter - can be used to "chain" filters.
  11.533 + *  If there is no event filter set, this function returns SDL_FALSE.
  11.534 + */
  11.535  extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
  11.536                                                      void **userdata);
  11.537  
  11.538 -/*
  11.539 -  Run the filter function on the current event queue, removing any
  11.540 -  events for which the filter returns 0.
  11.541 -*/
  11.542 +/**
  11.543 + *  Run the filter function on the current event queue, removing any
  11.544 + *  events for which the filter returns 0.
  11.545 + */
  11.546  extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
  11.547                                                void *userdata);
  11.548  
  11.549 -/*
  11.550 -  This function allows you to set the state of processing certain events.
  11.551 -  If 'state' is set to SDL_IGNORE, that event will be automatically dropped
  11.552 -  from the event queue and will not event be filtered.
  11.553 -  If 'state' is set to SDL_ENABLE, that event will be processed normally.
  11.554 -  If 'state' is set to SDL_QUERY, SDL_EventState() will return the 
  11.555 -  current processing state of the specified event.
  11.556 -*/
  11.557 +/*@{*/
  11.558  #define SDL_QUERY	-1
  11.559  #define SDL_IGNORE	 0
  11.560  #define SDL_DISABLE	 0
  11.561  #define SDL_ENABLE	 1
  11.562 +
  11.563 +/**
  11.564 + *  This function allows you to set the state of processing certain events.
  11.565 + *   - If \c state is set to ::SDL_IGNORE, that event will be automatically 
  11.566 + *     dropped from the event queue and will not event be filtered.
  11.567 + *   - If \c state is set to ::SDL_ENABLE, that event will be processed 
  11.568 + *     normally.
  11.569 + *   - If \c state is set to ::SDL_QUERY, SDL_EventState() will return the 
  11.570 + *     current processing state of the specified event.
  11.571 + */
  11.572  extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint8 type, int state);
  11.573 -
  11.574 +/*@}*/
  11.575  
  11.576  /* Ends C function definitions when using C++ */
  11.577  #ifdef __cplusplus
    12.1 --- a/include/SDL_haptic.h	Sun Oct 18 23:21:15 2009 +0000
    12.2 +++ b/include/SDL_haptic.h	Mon Oct 19 13:31:58 2009 +0000
    12.3 @@ -21,24 +21,23 @@
    12.4  */
    12.5  
    12.6  /**
    12.7 - * \file SDL_haptic.h
    12.8 + *  \file SDL_haptic.h
    12.9 + *  
   12.10 + *  \brief The SDL Haptic subsystem allows you to control haptic (force feedback)
   12.11 + *         devices.
   12.12 + *  
   12.13 + *  The basic usage is as follows:
   12.14 + *   - Initialize the Subsystem (::SDL_INIT_HAPTIC).
   12.15 + *   - Open a Haptic Device.
   12.16 + *    - SDL_HapticOpen() to open from index.
   12.17 + *    - SDL_HapticOpenFromJoystick() to open from an existing joystick.
   12.18 + *   - Create an effect (::SDL_HapticEffect).
   12.19 + *   - Upload the effect with SDL_HapticNewEffect().
   12.20 + *   - Run the effect with SDL_HapticRunEffect().
   12.21 + *   - (optional) Free the effect with SDL_HapticDestroyEffect().
   12.22 + *   - Close the haptic device with SDL_HapticClose().
   12.23   *
   12.24 - * \brief The SDL Haptic subsystem allows you to control haptic (force feedback)
   12.25 - *  devices.
   12.26 - *
   12.27 - * The basic usage is as follows:
   12.28 - *   - Initialize the Subsystem (SDL_INIT_HAPTIC).
   12.29 - *   - Open a Haptic Device.
   12.30 - *     - SDL_HapticOpen(...) to open from index.
   12.31 - *     - SDL_HapticOpenFromJoystick(...) to open from an existing joystick.
   12.32 - *   - Create an effect (SDL_HapticEffect).
   12.33 - *   - Upload the effect with SDL_HapticNewEffect(...).
   12.34 - *   - Run the effect with SDL_HapticRunEffect(...).
   12.35 - *   - (optional) Free the effect with SDL_HapticDestroyEffect(...).
   12.36 - *   - Close the haptic device with SDL_HapticClose(...).
   12.37 - *
   12.38 - * Example:
   12.39 - *
   12.40 + * \par Example:
   12.41   * \code
   12.42   * int test_haptic( SDL_Joystick * joystick ) {
   12.43   *    SDL_Haptic *haptic;
   12.44 @@ -82,7 +81,6 @@
   12.45   *    return 0; // Success
   12.46   * }
   12.47   * \endcode
   12.48 - *
   12.49   * \author Edgar Simo Serra
   12.50   */
   12.51  
   12.52 @@ -102,190 +100,215 @@
   12.53  #endif /* __cplusplus */
   12.54  
   12.55  /**
   12.56 - * \typedef SDL_Haptic
   12.57 - *
   12.58 - * \brief The haptic structure used to identify an SDL haptic.
   12.59 - *
   12.60 - * \sa SDL_HapticOpen
   12.61 - * \sa SDL_HapticOpenFromJoystick
   12.62 - * \sa SDL_HapticClose
   12.63 + *  \typedef SDL_Haptic
   12.64 + *  
   12.65 + *  \brief The haptic structure used to identify an SDL haptic.
   12.66 + *  
   12.67 + *  \sa SDL_HapticOpen
   12.68 + *  \sa SDL_HapticOpenFromJoystick
   12.69 + *  \sa SDL_HapticClose
   12.70   */
   12.71  struct _SDL_Haptic;
   12.72  typedef struct _SDL_Haptic SDL_Haptic;
   12.73  
   12.74  
   12.75 -/*
   12.76 - * Different haptic features a device can have.
   12.77 +/**
   12.78 + *  \name Haptic features
   12.79 + *  
   12.80 + *  Different haptic features a device can have.
   12.81   */
   12.82 +/*@{*/
   12.83 +
   12.84  /**
   12.85 - * \def SDL_HAPTIC_CONSTANT
   12.86 + *  \name Haptic effects
   12.87 + */
   12.88 +/*@{*/
   12.89 +
   12.90 +/**
   12.91 + *  \brief Constant effect supported.
   12.92   *
   12.93 - * \brief Constant haptic effect.
   12.94 + *  Constant haptic effect.
   12.95 + *  
   12.96 + *  \sa SDL_HapticCondition
   12.97 + */
   12.98 +#define SDL_HAPTIC_CONSTANT   (1<<0)
   12.99 +
  12.100 +/**
  12.101 + *  \brief Sine wave effect supported.
  12.102 + *  
  12.103 + *  Periodic haptic effect that simulates sine waves.
  12.104 + *  
  12.105 + *  \sa SDL_HapticPeriodic
  12.106 + */
  12.107 +#define SDL_HAPTIC_SINE       (1<<1)
  12.108 +
  12.109 +/**
  12.110 + *  \brief Square wave effect supported.
  12.111 + *  
  12.112 + *  Periodic haptic effect that simulates square waves.
  12.113 + * 
  12.114 + *  \sa SDL_HapticPeriodic
  12.115 + */
  12.116 +#define SDL_HAPTIC_SQUARE     (1<<2)
  12.117 +
  12.118 +/**
  12.119 + *  \brief Triangle wave effect supported.
  12.120 + *  
  12.121 + *  Periodic haptic effect that simulates triangular waves.
  12.122 + *  
  12.123 + *  \sa SDL_HapticPeriodic
  12.124 + */
  12.125 +#define SDL_HAPTIC_TRIANGLE   (1<<3)
  12.126 +
  12.127 +/**
  12.128 + *  \brief Sawtoothup wave effect supported.
  12.129 + *  
  12.130 + *  Periodic haptic effect that simulates saw tooth up waves.
  12.131 + *  
  12.132 + *  \sa SDL_HapticPeriodic
  12.133 + */
  12.134 +#define SDL_HAPTIC_SAWTOOTHUP (1<<4)
  12.135 +
  12.136 +/**
  12.137 + *  \brief Sawtoothdown wave effect supported.
  12.138 + *  
  12.139 + *  Periodic haptic effect that simulates saw tooth down waves.
  12.140 + *  
  12.141 + *  \sa SDL_HapticPeriodic
  12.142 + */
  12.143 +#define SDL_HAPTIC_SAWTOOTHDOWN (1<<5)
  12.144 +
  12.145 +/**
  12.146 + *  \brief Ramp effect supported.
  12.147 + *  
  12.148 + *  Ramp haptic effect.
  12.149 + *  
  12.150 + *  \sa SDL_HapticRamp
  12.151 + */
  12.152 +#define SDL_HAPTIC_RAMP       (1<<6)
  12.153 +
  12.154 +/**
  12.155 + *  \brief Spring effect supported - uses axes position.
  12.156 + *  
  12.157 + *  Condition haptic effect that simulates a spring.  Effect is based on the
  12.158 + *  axes position.
  12.159   *
  12.160 - * \sa SDL_HapticCondition
  12.161 + *  \sa SDL_HapticCondition
  12.162   */
  12.163 -#define SDL_HAPTIC_CONSTANT   (1<<0)    /* Constant effect supported */
  12.164 +#define SDL_HAPTIC_SPRING     (1<<7)
  12.165 +
  12.166  /**
  12.167 - * \def SDL_HAPTIC_SINE
  12.168 + *  \brief Damper effect supported - uses axes velocity.
  12.169 + *  
  12.170 + *  Condition haptic effect that simulates dampening.  Effect is based on the
  12.171 + *  axes velocity.
  12.172 + *  
  12.173 + *  \sa SDL_HapticCondition
  12.174 + */
  12.175 +#define SDL_HAPTIC_DAMPER     (1<<8)
  12.176 +
  12.177 +/**
  12.178 + *  \brief Inertia effect supported - uses axes acceleration.
  12.179 + *  
  12.180 + *  Condition haptic effect that simulates inertia.  Effect is based on the axes
  12.181 + *  acceleration.
  12.182   *
  12.183 - * \brief Periodic haptic effect that simulates sine waves.
  12.184 - *
  12.185 - * \sa SDL_HapticPeriodic
  12.186 + *  \sa SDL_HapticCondition
  12.187   */
  12.188 -#define SDL_HAPTIC_SINE       (1<<1)    /* Sine wave effect supported */
  12.189 +#define SDL_HAPTIC_INERTIA    (1<<9)
  12.190 +
  12.191  /**
  12.192 - * \def SDL_HAPTIC_SQUARE
  12.193 - *
  12.194 - * \brief Periodic haptic effect that simulates square waves.
  12.195 - * 
  12.196 - * \sa SDL_HapticPeriodic
  12.197 + *  \brief Friction effect supported - uses axes movement.
  12.198 + *  
  12.199 + *  Condition haptic effect that simulates friction.  Effect is based on the 
  12.200 + *  axes movement.
  12.201 + *  
  12.202 + *  \sa SDL_HapticCondition
  12.203   */
  12.204 -#define SDL_HAPTIC_SQUARE     (1<<2)    /* Square wave effect supported */
  12.205 +#define SDL_HAPTIC_FRICTION   (1<<10)
  12.206 +
  12.207  /**
  12.208 - * \def SDL_HAPTIC_TRIANGLE
  12.209 - *
  12.210 - * \brief Periodic haptic effect that simulates triangular waves.
  12.211 - *
  12.212 - * \sa SDL_HapticPeriodic
  12.213 + *  \brief Custom effect is supported.
  12.214 + *  
  12.215 + *  User defined custom haptic effect.
  12.216   */
  12.217 -#define SDL_HAPTIC_TRIANGLE   (1<<3)    /* Triangle wave effect supported */
  12.218 +#define SDL_HAPTIC_CUSTOM     (1<<11)
  12.219 +
  12.220 +/*@}*//*Haptic effects*/
  12.221 +
  12.222 +/* These last few are features the device has, not effects */
  12.223 +
  12.224  /**
  12.225 - * \def SDL_HAPTIC_SAWTOOTHUP
  12.226 - *
  12.227 - * \brief Periodic haptic effect that simulates saw tooth up waves.
  12.228 - *
  12.229 - * \sa SDL_HapticPeriodic
  12.230 + *  \brief Device can set global gain.
  12.231 + *  
  12.232 + *  Device supports setting the global gain.
  12.233 + *  
  12.234 + *  \sa SDL_HapticSetGain
  12.235   */
  12.236 -#define SDL_HAPTIC_SAWTOOTHUP (1<<4)    /* Sawtoothup wave effect supported */
  12.237 +#define SDL_HAPTIC_GAIN       (1<<12)
  12.238 +
  12.239  /**
  12.240 - * \def SDL_HAPTIC_SAWTOOTHDOWN
  12.241 - *
  12.242 - * \brief Periodic haptic effect that simulates saw tooth down waves.
  12.243 - *
  12.244 - * \sa SDL_HapticPeriodic
  12.245 + *  \brief Device can set autocenter.
  12.246 + *  
  12.247 + *  Device supports setting autocenter.
  12.248 + *  
  12.249 + *  \sa SDL_HapticSetAutocenter
  12.250   */
  12.251 -#define SDL_HAPTIC_SAWTOOTHDOWN (1<<5)  /* Sawtoothdown wave effect supported */
  12.252 +#define SDL_HAPTIC_AUTOCENTER (1<<13)
  12.253 +
  12.254  /**
  12.255 - * \def SDL_HAPTIC_RAMP
  12.256 - *
  12.257 - * \brief Ramp haptic effect.
  12.258 - *
  12.259 - * \sa SDL_HapticRamp
  12.260 + *  \brief Device can be queried for effect status.
  12.261 + *  
  12.262 + *  Device can be queried for effect status.
  12.263 + *  
  12.264 + *  \sa SDL_HapticGetEffectStatus
  12.265   */
  12.266 -#define SDL_HAPTIC_RAMP       (1<<6)    /* Ramp effect supported */
  12.267 +#define SDL_HAPTIC_STATUS     (1<<14)
  12.268 +
  12.269  /**
  12.270 - * \def SDL_HAPTIC_SPRING
  12.271 - *
  12.272 - * \brief Condition haptic effect that simulates a spring.  Effect is based on the
  12.273 - * axes position.
  12.274 - *
  12.275 - * \sa SDL_HapticCondition
  12.276 + *  \brief Device can be paused.
  12.277 + *  
  12.278 + *  \sa SDL_HapticPause
  12.279 + *  \sa SDL_HapticUnpause
  12.280   */
  12.281 -#define SDL_HAPTIC_SPRING     (1<<7)    /* Spring effect supported - uses axes position */
  12.282 +#define SDL_HAPTIC_PAUSE      (1<<15)
  12.283 +
  12.284 +
  12.285  /**
  12.286 - * \def SDL_HAPTIC_DAMPER
  12.287 - *
  12.288 - * \brief Condition haptic effect that simulates dampening.  Effect is based on the
  12.289 - * axes velocity.
  12.290 - *
  12.291 - * \sa SDL_HapticCondition
  12.292 + * \name Direction encodings
  12.293   */
  12.294 -#define SDL_HAPTIC_DAMPER     (1<<8)    /* Damper effect supported - uses axes velocity */
  12.295 +/*@{*/
  12.296 +
  12.297  /**
  12.298 - * \def SDL_HAPTIC_INERTIA
  12.299 - *
  12.300 - * \brief Condition haptic effect that simulates inertia.  Effect is based on the axes
  12.301 - * acceleration.
  12.302 - *
  12.303 - * \sa SDL_HapticCondition
  12.304 - */
  12.305 -#define SDL_HAPTIC_INERTIA    (1<<9)    /* Inertia effect supported - uses axes acceleration */
  12.306 -/**
  12.307 - * \def SDL_HAPTIC_FRICTION
  12.308 - *
  12.309 - * \brief Condition haptic effect that simulates friction.  Effect is based on the axes
  12.310 - * movement.
  12.311 - *
  12.312 - * \sa SDL_HapticCondition
  12.313 - */
  12.314 -#define SDL_HAPTIC_FRICTION   (1<<10)   /* Friction effect supported - uses axes movement */
  12.315 -/**
  12.316 - * \def SDL_HAPTIC_CUSTOM
  12.317 - *
  12.318 - * \brief User defined custom haptic effect.
  12.319 - */
  12.320 -#define SDL_HAPTIC_CUSTOM     (1<<11)   /* Custom effect is supported */
  12.321 -/* These last two are features the device has, not effects */
  12.322 -/**
  12.323 - * \def SDL_HAPTIC_GAIN
  12.324 - *
  12.325 - * \brief Device supports setting the global gain.
  12.326 - *
  12.327 - * \sa SDL_HapticSetGain
  12.328 - */
  12.329 -#define SDL_HAPTIC_GAIN       (1<<12)   /* Device can set global gain */
  12.330 -/**
  12.331 - * \def SDL_HAPTIC_AUTOCENTER
  12.332 - *
  12.333 - * \brief Device supports setting autocenter.
  12.334 - *
  12.335 - * \sa SDL_HapticSetAutocenter
  12.336 - */
  12.337 -#define SDL_HAPTIC_AUTOCENTER (1<<13)   /* Device can set autocenter */
  12.338 -/**
  12.339 - * \def SDL_HAPTIC_STATUS
  12.340 - *
  12.341 - * \brief Device can be queried for effect status.
  12.342 - *
  12.343 - * \sa SDL_HapticGetEffectStatus
  12.344 - */
  12.345 -#define SDL_HAPTIC_STATUS     (1<<14)   /* Device can be queried for effect status */
  12.346 -/**
  12.347 - * \def SDL_HAPTIC_PAUSE
  12.348 - *
  12.349 - * \brief Device can be paused.
  12.350 - *
  12.351 - * \sa SDL_HapticPause
  12.352 - * \sa SDL_HapticUnpause
  12.353 - */
  12.354 -#define SDL_HAPTIC_PAUSE      (1<<15)   /* Device can be paused. */
  12.355 -
  12.356 -
  12.357 -/*
  12.358 - * Direction encodings
  12.359 - */
  12.360 -/**
  12.361 - * \def SDL_HAPTIC_POLAR
  12.362 - *
  12.363 - * \brief Uses polar coordinates for the direction.
  12.364 - *
  12.365 - * \sa SDL_HapticDirection
  12.366 + *  \brief Uses polar coordinates for the direction.
  12.367 + *  
  12.368 + *  \sa SDL_HapticDirection
  12.369   */
  12.370  #define SDL_HAPTIC_POLAR      0
  12.371 +
  12.372  /**
  12.373 - * \def SDL_HAPTIC_CARTESIAN
  12.374 - *
  12.375 - * \brief Uses cartesian coordinates for the direction.
  12.376 - *
  12.377 - * \sa SDL_HapticDirection
  12.378 + *  \brief Uses cartesian coordinates for the direction.
  12.379 + *  
  12.380 + *  \sa SDL_HapticDirection
  12.381   */
  12.382  #define SDL_HAPTIC_CARTESIAN  1
  12.383 +
  12.384  /**
  12.385 - * \def SDL_HAPTIC_SPHERICAL
  12.386 - *
  12.387 - * \brief Uses spherical coordinates for the direction.
  12.388 - *
  12.389 - * \sa SDL_HapticDirection
  12.390 + *  \brief Uses spherical coordinates for the direction.
  12.391 + *  
  12.392 + *  \sa SDL_HapticDirection
  12.393   */
  12.394  #define SDL_HAPTIC_SPHERICAL  2
  12.395  
  12.396 +/*@}*//*Direction encodings*/
  12.397 +
  12.398 +/*@}*//*Haptic features*/
  12.399  
  12.400  /*
  12.401   * Misc defines.
  12.402   */
  12.403 +
  12.404  /**
  12.405 - * \def SDL_HAPTIC_INFINITY
  12.406 - *
  12.407   * \brief Used to play a device an infinite number of times.
  12.408   *
  12.409   * \sa SDL_HapticRunEffect
  12.410 @@ -294,97 +317,96 @@
  12.411  
  12.412  
  12.413  /**
  12.414 - * \struct SDL_HapticDirection
  12.415 + *  \brief Structure that represents a haptic direction.
  12.416 + *  
  12.417 + *  Directions can be specified by:
  12.418 + *   - ::SDL_HAPTIC_POLAR : Specified by polar coordinates.
  12.419 + *   - ::SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
  12.420 + *   - ::SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates.
  12.421   *
  12.422 - * \brief Structure that represents a haptic direction.
  12.423 - *
  12.424 - * Directions can be specified by:
  12.425 - *   - SDL_HAPTIC_POLAR : Specified by polar coordinates.
  12.426 - *   - SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
  12.427 - *   - SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates.
  12.428 - *
  12.429 - * Cardinal directions of the haptic device are relative to the positioning
  12.430 + *  Cardinal directions of the haptic device are relative to the positioning
  12.431   *  of the device.  North is considered to be away from the user.
  12.432   *
  12.433 - * The following diagram represents the cardinal directions:
  12.434 - * \code
  12.435 - *              .--.
  12.436 - *              |__| .-------.
  12.437 - *              |=.| |.-----.|
  12.438 - *              |--| ||     ||
  12.439 - *              |  | |'-----'|
  12.440 - *              |__|~')_____('
  12.441 - *                [ COMPUTER ]
  12.442 - *
  12.443 - *
  12.444 - *                  North (0,-1)
  12.445 - *                      ^
  12.446 - *                      |
  12.447 - *                      |
  12.448 - * (1,0)  West <----[ HAPTIC ]----> East (-1,0)
  12.449 - *                      |
  12.450 - *                      |
  12.451 - *                      v
  12.452 - *                   South (0,1)
  12.453 - *
  12.454 - *
  12.455 - *                   [ USER ]
  12.456 - *                     \|||/
  12.457 - *                     (o o)
  12.458 - *               ---ooO-(_)-Ooo---
  12.459 - * \endcode
  12.460 - *
  12.461 - * If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a 
  12.462 - *  degree starting north and turning clockwise.  SDL_HAPTIC_POLAR only uses
  12.463 - *  the first dir parameter.  The cardinal directions would be:
  12.464 + *  The following diagram represents the cardinal directions:
  12.465 + *  \verbatim
  12.466 +                 .--.
  12.467 +                 |__| .-------.
  12.468 +                 |=.| |.-----.|
  12.469 +                 |--| ||     ||
  12.470 +                 |  | |'-----'|
  12.471 +                 |__|~')_____('
  12.472 +                   [ COMPUTER ]
  12.473 +    
  12.474 +    
  12.475 +                     North (0,-1)
  12.476 +                         ^
  12.477 +                         |
  12.478 +                         |
  12.479 +    (1,0)  West <----[ HAPTIC ]----> East (-1,0)
  12.480 +                         |
  12.481 +                         |
  12.482 +                         v
  12.483 +                      South (0,1)
  12.484 +    
  12.485 +    
  12.486 +                      [ USER ]
  12.487 +                        \|||/
  12.488 +                        (o o)
  12.489 +                  ---ooO-(_)-Ooo---
  12.490 +    \endverbatim
  12.491 + *  
  12.492 + *  If type is ::SDL_HAPTIC_POLAR, direction is encoded by hundredths of a 
  12.493 + *  degree starting north and turning clockwise.  ::SDL_HAPTIC_POLAR only uses
  12.494 + *  the first \c dir parameter.  The cardinal directions would be:
  12.495   *   - North: 0 (0 degrees)
  12.496   *   - East: 9000 (90 degrees)
  12.497   *   - South: 18000 (180 degrees)
  12.498   *   - West: 27000 (270 degrees)
  12.499 - *
  12.500 - * If type is SDL_HAPTIC_CARTESIAN, direction is encoded by three positions
  12.501 - *  (X axis, Y axis and Z axis (with 3 axes)).  SDL_HAPTIC_CARTESIAN uses
  12.502 - *  the first three dir parameters.  The cardinal directions would be:
  12.503 + *  
  12.504 + *  If type is ::SDL_HAPTIC_CARTESIAN, direction is encoded by three positions
  12.505 + *  (X axis, Y axis and Z axis (with 3 axes)).  ::SDL_HAPTIC_CARTESIAN uses
  12.506 + *  the first three \c dir parameters.  The cardinal directions would be:
  12.507   *   - North:  0,-1, 0
  12.508   *   - East:  -1, 0, 0
  12.509   *   - South:  0, 1, 0
  12.510   *   - West:   1, 0, 0
  12.511 + *  
  12.512   *  The Z axis represents the height of the effect if supported, otherwise
  12.513 - *  it's unused.  In cartesian encoding (1,2) would be the same as (2,4), you
  12.514 + *  it's unused.  In cartesian encoding (1, 2) would be the same as (2, 4), you
  12.515   *  can use any multiple you want, only the direction matters.
  12.516 + *  
  12.517 + *  If type is ::SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations.
  12.518 + *  The first two \c dir parameters are used.  The \c dir parameters are as 
  12.519 + *  follows (all values are in hundredths of degrees):
  12.520 + *   - Degrees from (1, 0) rotated towards (0, 1).
  12.521 + *   - Degrees towards (0, 0, 1) (device needs at least 3 axes).
  12.522   *
  12.523 - * If type is SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations.
  12.524 - *  The first two  dir parameters are used.  The dir parameters are as follows
  12.525 - *  (all values are in hundredths of degrees):
  12.526 - *    1) Degrees from (1, 0) rotated towards (0, 1).
  12.527 - *    2) Degrees towards (0, 0, 1) (device needs at least 3 axes).
  12.528   *
  12.529 + *  Example of force coming from the south with all encodings (force coming
  12.530 + *  from the south means the user will have to pull the stick to counteract):
  12.531 + *  \code
  12.532 + *  SDL_HapticDirection direction;
  12.533 + *  
  12.534 + *  // Cartesian directions
  12.535 + *  direction.type = SDL_HAPTIC_CARTESIAN; // Using cartesian direction encoding.
  12.536 + *  direction.dir[0] = 0; // X position
  12.537 + *  direction.dir[1] = 1; // Y position
  12.538 + *  // Assuming the device has 2 axes, we don't need to specify third parameter.
  12.539 + *  
  12.540 + *  // Polar directions
  12.541 + *  direction.type = SDL_HAPTIC_POLAR; // We'll be using polar direction encoding.
  12.542 + *  direction.dir[0] = 18000; // Polar only uses first parameter
  12.543 + *  
  12.544 + *  // Spherical coordinates
  12.545 + *  direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding
  12.546 + *  direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters.
  12.547 + *  \endcode
  12.548   *
  12.549 - * Example of force coming from the south with all encodings (force coming
  12.550 - *  from the south means the user will have to pull the stick to counteract):
  12.551 - * \code
  12.552 - * SDL_HapticDirection direction;
  12.553 - *
  12.554 - * // Cartesian directions
  12.555 - * direction.type = SDL_HAPTIC_CARTESIAN; // Using cartesian direction encoding.
  12.556 - * direction.dir[0] = 0; // X position
  12.557 - * direction.dir[1] = 1; // Y position
  12.558 - * // Assuming the device has 2 axes, we don't need to specify third parameter.
  12.559 - *
  12.560 - * // Polar directions
  12.561 - * direction.type = SDL_HAPTIC_POLAR; // We'll be using polar direction encoding.
  12.562 - * direction.dir[0] = 18000; // Polar only uses first parameter
  12.563 - *
  12.564 - * // Spherical coordinates
  12.565 - * direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding
  12.566 - * direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters.
  12.567 - * \endcode
  12.568 - *
  12.569 - * \sa SDL_HAPTIC_POLAR
  12.570 - * \sa SDL_HAPTIC_CARTESIAN
  12.571 - * \sa SDL_HAPTIC_SPHERICAL
  12.572 - * \sa SDL_HapticEffect
  12.573 - * \sa SDL_HapticNumAxes
  12.574 + *  \sa SDL_HAPTIC_POLAR
  12.575 + *  \sa SDL_HAPTIC_CARTESIAN
  12.576 + *  \sa SDL_HAPTIC_SPHERICAL
  12.577 + *  \sa SDL_HapticEffect
  12.578 + *  \sa SDL_HapticNumAxes
  12.579   */
  12.580  typedef struct SDL_HapticDirection
  12.581  {
  12.582 @@ -394,22 +416,20 @@
  12.583  
  12.584  
  12.585  /**
  12.586 - * \struct SDL_HapticConstant
  12.587 - *
  12.588 - * \brief A structure containing a template for a Constant effect.
  12.589 - *
  12.590 - * The struct is exclusive to the SDL_HAPTIC_CONSTANT effect.
  12.591 - *
  12.592 - * A constant effect applies a constant force in the specified direction
  12.593 + *  \brief A structure containing a template for a Constant effect.
  12.594 + *  
  12.595 + *  The struct is exclusive to the ::SDL_HAPTIC_CONSTANT effect.
  12.596 + *  
  12.597 + *  A constant effect applies a constant force in the specified direction
  12.598   *  to the joystick.
  12.599 - *
  12.600 - * \sa SDL_HAPTIC_CONSTANT
  12.601 - * \sa SDL_HapticEffect
  12.602 + *  
  12.603 + *  \sa SDL_HAPTIC_CONSTANT
  12.604 + *  \sa SDL_HapticEffect
  12.605   */
  12.606  typedef struct SDL_HapticConstant
  12.607  {
  12.608      /* Header */
  12.609 -    Uint16 type;            /**< SDL_HAPTIC_CONSTANT */
  12.610 +    Uint16 type;            /**< ::SDL_HAPTIC_CONSTANT */
  12.611      SDL_HapticDirection direction;  /**< Direction of the effect. */
  12.612  
  12.613      /* Replay */
  12.614 @@ -429,71 +449,70 @@
  12.615      Uint16 fade_length;     /**< Duration of the fade. */
  12.616      Uint16 fade_level;      /**< Level at the end of the fade. */
  12.617  } SDL_HapticConstant;
  12.618 +
  12.619  /**
  12.620 - * \struct SDL_HapticPeriodic
  12.621 - *
  12.622 - * \brief A structure containing a template for a Periodic effect.
  12.623 - *
  12.624 - * The struct handles the following effects:
  12.625 - *   - SDL_HAPTIC_SINE
  12.626 - *   - SDL_HAPTIC_SQUARE
  12.627 - *   - SDL_HAPTIC_TRIANGLE
  12.628 - *   - SDL_HAPTIC_SAWTOOTHUP
  12.629 - *   - SDL_HAPTIC_SAWTOOTHDOWN
  12.630 - *
  12.631 - * A periodic effect consists in a wave-shaped effect that repeats itself
  12.632 + *  \brief A structure containing a template for a Periodic effect.
  12.633 + *  
  12.634 + *  The struct handles the following effects:
  12.635 + *   - ::SDL_HAPTIC_SINE
  12.636 + *   - ::SDL_HAPTIC_SQUARE
  12.637 + *   - ::SDL_HAPTIC_TRIANGLE
  12.638 + *   - ::SDL_HAPTIC_SAWTOOTHUP
  12.639 + *   - ::SDL_HAPTIC_SAWTOOTHDOWN
  12.640 + *  
  12.641 + *  A periodic effect consists in a wave-shaped effect that repeats itself
  12.642   *  over time.  The type determines the shape of the wave and the parameters
  12.643   *  determine the dimensions of the wave.
  12.644 + *  
  12.645 + *  Phase is given by hundredth of a cyle meaning that giving the phase a value
  12.646 + *  of 9000 will displace it 25% of it's period.  Here are sample values:
  12.647 + *   -     0: No phase displacement.
  12.648 + *   -  9000: Displaced 25% of it's period.
  12.649 + *   - 18000: Displaced 50% of it's period.
  12.650 + *   - 27000: Displaced 75% of it's period.
  12.651 + *   - 36000: Displaced 100% of it's period, same as 0, but 0 is preffered.
  12.652   *
  12.653 - * Phase is given by hundredth of a cyle meaning that giving the phase a value
  12.654 - *  of 9000 will displace it 25% of it's period.  Here are sample values:
  12.655 - *    -     0: No phase displacement.
  12.656 - *    -  9000: Displaced 25% of it's period.
  12.657 - *    - 18000: Displaced 50% of it's period.
  12.658 - *    - 27000: Displaced 75% of it's period.
  12.659 - *    - 36000: Displaced 100% of it's period, same as 0, but 0 is preffered.
  12.660 - *
  12.661 - * Examples:
  12.662 - * \code
  12.663 - * SDL_HAPTIC_SINE
  12.664 - *   __      __      __      __
  12.665 - *  /  \    /  \    /  \    /
  12.666 - * /    \__/    \__/    \__/
  12.667 - *
  12.668 - * SDL_HAPTIC_SQUARE
  12.669 - *  __    __    __    __    __
  12.670 - * |  |  |  |  |  |  |  |  |  |
  12.671 - * |  |__|  |__|  |__|  |__|  |
  12.672 - *
  12.673 - * SDL_HAPTIC_TRIANGLE
  12.674 - *   /\    /\    /\    /\    /\
  12.675 - *  /  \  /  \  /  \  /  \  /
  12.676 - * /    \/    \/    \/    \/
  12.677 - *
  12.678 - * SDL_HAPTIC_SAWTOOTHUP
  12.679 - *   /|  /|  /|  /|  /|  /|  /|
  12.680 - *  / | / | / | / | / | / | / |
  12.681 - * /  |/  |/  |/  |/  |/  |/  |
  12.682 - *
  12.683 - * SDL_HAPTIC_SAWTOOTHDOWN
  12.684 - * \  |\  |\  |\  |\  |\  |\  |
  12.685 - *  \ | \ | \ | \ | \ | \ | \ |
  12.686 - *   \|  \|  \|  \|  \|  \|  \|
  12.687 - * \endcode
  12.688 - *
  12.689 - * \sa SDL_HAPTIC_SINE
  12.690 - * \sa SDL_HAPTIC_SQUARE
  12.691 - * \sa SDL_HAPTIC_TRIANGLE
  12.692 - * \sa SDL_HAPTIC_SAWTOOTHUP
  12.693 - * \sa SDL_HAPTIC_SAWTOOTHDOWN
  12.694 - * \sa SDL_HapticEffect
  12.695 + *  Examples:
  12.696 + *  \verbatim
  12.697 +    SDL_HAPTIC_SINE
  12.698 +      __      __      __      __
  12.699 +     /  \    /  \    /  \    /
  12.700 +    /    \__/    \__/    \__/
  12.701 +    
  12.702 +    SDL_HAPTIC_SQUARE
  12.703 +     __    __    __    __    __
  12.704 +    |  |  |  |  |  |  |  |  |  |
  12.705 +    |  |__|  |__|  |__|  |__|  |
  12.706 +    
  12.707 +    SDL_HAPTIC_TRIANGLE
  12.708 +      /\    /\    /\    /\    /\
  12.709 +     /  \  /  \  /  \  /  \  /
  12.710 +    /    \/    \/    \/    \/
  12.711 +    
  12.712 +    SDL_HAPTIC_SAWTOOTHUP
  12.713 +      /|  /|  /|  /|  /|  /|  /|
  12.714 +     / | / | / | / | / | / | / |
  12.715 +    /  |/  |/  |/  |/  |/  |/  |
  12.716 +    
  12.717 +    SDL_HAPTIC_SAWTOOTHDOWN
  12.718 +    \  |\  |\  |\  |\  |\  |\  |
  12.719 +     \ | \ | \ | \ | \ | \ | \ |
  12.720 +      \|  \|  \|  \|  \|  \|  \|
  12.721 +    \endverbatim
  12.722 + *  
  12.723 + *  \sa SDL_HAPTIC_SINE
  12.724 + *  \sa SDL_HAPTIC_SQUARE
  12.725 + *  \sa SDL_HAPTIC_TRIANGLE
  12.726 + *  \sa SDL_HAPTIC_SAWTOOTHUP
  12.727 + *  \sa SDL_HAPTIC_SAWTOOTHDOWN
  12.728 + *  \sa SDL_HapticEffect
  12.729   */
  12.730  typedef struct SDL_HapticPeriodic
  12.731  {
  12.732      /* Header */
  12.733 -    Uint16 type;        /**< SDL_HAPTIC_SINE, SDL_HAPTIC_SQUARE,
  12.734 -                             SDL_HAPTIC_TRIANGLE, SDL_HAPTIC_SAWTOOTHUP or
  12.735 -                             SDL_HAPTIC_SAWTOOTHDOWN */
  12.736 +    Uint16 type;        /**< ::SDL_HAPTIC_SINE, ::SDL_HAPTIC_SQUARE,
  12.737 +                             ::SDL_HAPTIC_TRIANGLE, ::SDL_HAPTIC_SAWTOOTHUP or
  12.738 +                             ::SDL_HAPTIC_SAWTOOTHDOWN */
  12.739      SDL_HapticDirection direction;  /**< Direction of the effect. */
  12.740  
  12.741      /* Replay */
  12.742 @@ -516,37 +535,36 @@
  12.743      Uint16 fade_length; /**< Duration of the fade. */
  12.744      Uint16 fade_level;  /**< Level at the end of the fade. */
  12.745  } SDL_HapticPeriodic;
  12.746 +
  12.747  /**
  12.748 - * \struct SDL_HapticCondition
  12.749 - *
  12.750 - * \brief A structure containing a template for a Condition effect.
  12.751 - *
  12.752 - * The struct handles the following effects:
  12.753 - *   - SDL_HAPTIC_SPRING: Effect based on axes position.
  12.754 - *   - SDL_HAPTIC_DAMPER: Effect based on axes velocity.
  12.755 - *   - SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
  12.756 - *   - SDL_HAPTIC_FRICTION: Effect based on axes movement.
  12.757 - *
  12.758 - * Direction is handled by condition internals instead of a direction member.
  12.759 + *  \brief A structure containing a template for a Condition effect.
  12.760 + *  
  12.761 + *  The struct handles the following effects:
  12.762 + *   - ::SDL_HAPTIC_SPRING: Effect based on axes position.
  12.763 + *   - ::SDL_HAPTIC_DAMPER: Effect based on axes velocity.
  12.764 + *   - ::SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
  12.765 + *   - ::SDL_HAPTIC_FRICTION: Effect based on axes movement.
  12.766 + *  
  12.767 + *  Direction is handled by condition internals instead of a direction member.
  12.768   *  The condition effect specific members have three parameters.  The first
  12.769   *  refers to the X axis, the second refers to the Y axis and the third
  12.770   *  refers to the Z axis.  The right terms refer to the positive side of the
  12.771   *  axis and the left terms refer to the negative side of the axis.  Please 
  12.772 - *  refer to the SDL_HapticDirection  diagram for which side is positive and
  12.773 + *  refer to the ::SDL_HapticDirection diagram for which side is positive and
  12.774   *  which is negative.
  12.775 - *
  12.776 - * \sa SDL_HapticDirection
  12.777 - * \sa SDL_HAPTIC_SPRING
  12.778 - * \sa SDL_HAPTIC_DAMPER
  12.779 - * \sa SDL_HAPTIC_INERTIA
  12.780 - * \sa SDL_HAPTIC_FRICTION
  12.781 - * \sa SDL_HapticEffect
  12.782 + *  
  12.783 + *  \sa SDL_HapticDirection
  12.784 + *  \sa SDL_HAPTIC_SPRING
  12.785 + *  \sa SDL_HAPTIC_DAMPER
  12.786 + *  \sa SDL_HAPTIC_INERTIA
  12.787 + *  \sa SDL_HAPTIC_FRICTION
  12.788 + *  \sa SDL_HapticEffect
  12.789   */
  12.790  typedef struct SDL_HapticCondition
  12.791  {
  12.792      /* Header */
  12.793 -    Uint16 type;            /**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER,
  12.794 -                                 SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION */
  12.795 +    Uint16 type;            /**< ::SDL_HAPTIC_SPRING, ::SDL_HAPTIC_DAMPER,
  12.796 +                                 ::SDL_HAPTIC_INERTIA or ::SDL_HAPTIC_FRICTION */
  12.797      SDL_HapticDirection direction;  /**< Direction of the effect - Not used ATM. */
  12.798  
  12.799      /* Replay */
  12.800 @@ -565,25 +583,24 @@
  12.801      Uint16 deadband[3];     /**< Size of the dead zone. */
  12.802      Sint16 center[3];       /**< Position of the dead zone. */
  12.803  } SDL_HapticCondition;
  12.804 +
  12.805  /**
  12.806 - * \struct SDL_HapticRamp
  12.807 - *
  12.808 - * \brief A structure containing a template for a Ramp effect.
  12.809 - *
  12.810 - * This struct is exclusively for the SDL_HAPTIC_RAMP effect.
  12.811 - *
  12.812 - * The ramp effect starts at start strength and ends at end strength.
  12.813 + *  \brief A structure containing a template for a Ramp effect.
  12.814 + *  
  12.815 + *  This struct is exclusively for the ::SDL_HAPTIC_RAMP effect.
  12.816 + *  
  12.817 + *  The ramp effect starts at start strength and ends at end strength.
  12.818   *  It augments in linear fashion.  If you use attack and fade with a ramp
  12.819   *  they effects get added to the ramp effect making the effect become
  12.820   *  quadratic instead of linear.
  12.821 - *
  12.822 - * \sa SDL_HAPTIC_RAMP
  12.823 - * \sa SDL_HapticEffect
  12.824 + *  
  12.825 + *  \sa SDL_HAPTIC_RAMP
  12.826 + *  \sa SDL_HapticEffect
  12.827   */
  12.828  typedef struct SDL_HapticRamp
  12.829  {
  12.830      /* Header */
  12.831 -    Uint16 type;            /**< SDL_HAPTIC_RAMP */
  12.832 +    Uint16 type;            /**< ::SDL_HAPTIC_RAMP */
  12.833      SDL_HapticDirection direction;  /**< Direction of the effect. */
  12.834  
  12.835      /* Replay */
  12.836 @@ -604,25 +621,24 @@
  12.837      Uint16 fade_length;     /**< Duration of the fade. */
  12.838      Uint16 fade_level;      /**< Level at the end of the fade. */
  12.839  } SDL_HapticRamp;
  12.840 +
  12.841  /**
  12.842 - * \struct SDL_HapticCustom
  12.843 - *
  12.844 - * \brief A structure containing a template for the SDL_HAPTIC_CUSTOM effect.
  12.845 - *
  12.846 - * A custom force feedback effect is much like a periodic effect, where the
  12.847 + *  \brief A structure containing a template for the ::SDL_HAPTIC_CUSTOM effect.
  12.848 + *  
  12.849 + *  A custom force feedback effect is much like a periodic effect, where the
  12.850   *  application can define it's exact shape.  You will have to allocate the
  12.851   *  data yourself.  Data should consist of channels * samples Uint16 samples.
  12.852 - *
  12.853 - * If channels is one, the effect is rotated using the defined direction.
  12.854 + *  
  12.855 + *  If channels is one, the effect is rotated using the defined direction.
  12.856   *  Otherwise it uses the samples in data for the different axes.
  12.857 - *
  12.858 - * \sa SDL_HAPTIC_CUSTOM
  12.859 - * \sa SDL_HapticEffect
  12.860 + *  
  12.861 + *  \sa SDL_HAPTIC_CUSTOM
  12.862 + *  \sa SDL_HapticEffect
  12.863   */
  12.864  typedef struct SDL_HapticCustom
  12.865  {
  12.866      /* Header */
  12.867 -    Uint16 type;            /**< SDL_HAPTIC_CUSTOM */
  12.868 +    Uint16 type;            /**< ::SDL_HAPTIC_CUSTOM */
  12.869      SDL_HapticDirection direction;  /**< Direction of the effect. */
  12.870  
  12.871      /* Replay */
  12.872 @@ -645,76 +661,74 @@
  12.873      Uint16 fade_length;     /**< Duration of the fade. */
  12.874      Uint16 fade_level;      /**< Level at the end of the fade. */
  12.875  } SDL_HapticCustom;
  12.876 +
  12.877  /**
  12.878 - * \union SDL_HapticEffect
  12.879 - *
  12.880 - * \brief The generic template for any haptic effect.
  12.881 - *
  12.882 - * All values max at 32767 (0x7FFF).  Signed values also can be negative.
  12.883 + *  \brief The generic template for any haptic effect.
  12.884 + *  
  12.885 + *  All values max at 32767 (0x7FFF).  Signed values also can be negative.
  12.886   *  Time values unless specified otherwise are in milliseconds.
  12.887 - *
  12.888 - * You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value.
  12.889 - *  Neither delay, interval, attack_length nor fade_length support 
  12.890 - *  SDL_HAPTIC_INFINITY.  Fade will also not be used since effect never ends.
  12.891 - *
  12.892 - * Additionally, the SDL_HAPTIC_RAMP effect does not support a duration of
  12.893 - *  SDL_HAPTIC_INFINITY.
  12.894 - *
  12.895 - * Button triggers may not be supported on all devices, it is advised to not
  12.896 + *  
  12.897 + *  You can also pass ::SDL_HAPTIC_INFINITY to length instead of a 0-32767 
  12.898 + *  value.  Neither delay, interval, attack_length nor fade_length support 
  12.899 + *  ::SDL_HAPTIC_INFINITY.  Fade will also not be used since effect never ends.
  12.900 + *  
  12.901 + *  Additionally, the ::SDL_HAPTIC_RAMP effect does not support a duration of
  12.902 + *  ::SDL_HAPTIC_INFINITY.
  12.903 + *  
  12.904 + *  Button triggers may not be supported on all devices, it is advised to not
  12.905   *  use them if possible.  Buttons start at index 1 instead of index 0 like
  12.906   *  they joystick.
  12.907 + *  
  12.908 + *  If both attack_length and fade_level are 0, the envelope is not used,
  12.909 + *  otherwise both values are used.
  12.910 + *  
  12.911 + *  Common parts:
  12.912 + *  \code
  12.913 + *  // Replay - All effects have this
  12.914 + *  Uint32 length;        // Duration of effect (ms).
  12.915 + *  Uint16 delay;         // Delay before starting effect.
  12.916 + *  
  12.917 + *  // Trigger - All effects have this
  12.918 + *  Uint16 button;        // Button that triggers effect.
  12.919 + *  Uint16 interval;      // How soon before effect can be triggered again.
  12.920 + *  
  12.921 + *  // Envelope - All effects except condition effects have this
  12.922 + *  Uint16 attack_length; // Duration of the attack (ms).
  12.923 + *  Uint16 attack_level;  // Level at the start of the attack.
  12.924 + *  Uint16 fade_length;   // Duration of the fade out (ms).
  12.925 + *  Uint16 fade_level;    // Level at the end of the fade.
  12.926 + *  \endcode
  12.927   *
  12.928 - * If both attack_length and fade_level are 0, the envelope is not used,
  12.929 - *  otherwise both values are used.
  12.930   *
  12.931 - * Common parts:
  12.932 - * \code
  12.933 - * // Replay - All effects have this
  12.934 - * Uint32 length;        // Duration of effect (ms).
  12.935 - * Uint16 delay;         // Delay before starting effect.
  12.936 - *
  12.937 - * // Trigger - All effects have this
  12.938 - * Uint16 button;        // Button that triggers effect.
  12.939 - * Uint16 interval;      // How soon before effect can be triggered again.
  12.940 - *
  12.941 - * // Envelope - All effects except condition effects have this
  12.942 - * Uint16 attack_length; // Duration of the attack (ms).
  12.943 - * Uint16 attack_level;  // Level at the start of the attack.
  12.944 - * Uint16 fade_length;   // Duration of the fade out (ms).
  12.945 - * Uint16 fade_level;    // Level at the end of the fade.
  12.946 - * \endcode
  12.947 - *
  12.948 - *
  12.949 - * Here we have an example of a constant effect evolution in time:
  12.950 - *
  12.951 - * \code
  12.952 - * Strength
  12.953 - * ^
  12.954 - * |
  12.955 - * |    effect level -->  _________________
  12.956 - * |                     /                 \
  12.957 - * |                    /                   \
  12.958 - * |                   /                     \
  12.959 - * |                  /                       \ 
  12.960 - * | attack_level --> |                        \
  12.961 - * |                  |                        |  <---  fade_level
  12.962 - * |
  12.963 - * +--------------------------------------------------> Time
  12.964 - *                    [--]                 [---]
  12.965 - *                    attack_length        fade_length
  12.966 - * 
  12.967 - * [------------------][-----------------------]
  12.968 - * delay               length
  12.969 - * \endcode
  12.970 - *
  12.971 - * Note either the attack_level or the fade_level may be above the actual
  12.972 + *  Here we have an example of a constant effect evolution in time:
  12.973 + *  \verbatim
  12.974 +    Strength
  12.975 +    ^
  12.976 +    |
  12.977 +    |    effect level -->  _________________
  12.978 +    |                     /                 \
  12.979 +    |                    /                   \
  12.980 +    |                   /                     \
  12.981 +    |                  /                       \ 
  12.982 +    | attack_level --> |                        \
  12.983 +    |                  |                        |  <---  fade_level
  12.984 +    |
  12.985 +    +--------------------------------------------------> Time
  12.986 +                       [--]                 [---]
  12.987 +                       attack_length        fade_length
  12.988 +    
  12.989 +    [------------------][-----------------------]
  12.990 +    delay               length
  12.991 +    \endverbatim
  12.992 + *  
  12.993 + *  Note either the attack_level or the fade_level may be above the actual
  12.994   *  effect level.
  12.995   *
  12.996 - * \sa SDL_HapticConstant
  12.997 - * \sa SDL_HapticPeriodic
  12.998 - * \sa SDL_HapticCondition
  12.999 - * \sa SDL_HapticRamp
 12.1000 - * \sa SDL_HapticCustom
 12.1001 + *  \sa SDL_HapticConstant
 12.1002 + *  \sa SDL_HapticPeriodic
 12.1003 + *  \sa SDL_HapticCondition
 12.1004 + *  \sa SDL_HapticRamp
 12.1005 + *  \sa SDL_HapticCustom
 12.1006   */
 12.1007  typedef union SDL_HapticEffect
 12.1008  {
 12.1009 @@ -730,413 +744,368 @@
 12.1010  
 12.1011  /* Function prototypes */
 12.1012  /**
 12.1013 - * \fn int SDL_NumHaptics(void)
 12.1014 - *
 12.1015 - * \brief Count the number of joysticks attached to the system.
 12.1016 - *
 12.1017 - *    \return Number of haptic devices detected on the system.
 12.1018 + *  \brief Count the number of joysticks attached to the system.
 12.1019 + *  
 12.1020 + *  \return Number of haptic devices detected on the system.
 12.1021   */
 12.1022  extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
 12.1023  
 12.1024  /**
 12.1025 - * \fn const char * SDL_HapticName(int device_index)
 12.1026 + *  \brief Get the implementation dependent name of a Haptic device.
 12.1027 + *  
 12.1028 + *  This can be called before any joysticks are opened.
 12.1029 + *  If no name can be found, this function returns NULL.
 12.1030 + *  
 12.1031 + *  \param device_index Index of the device to get it's name.
 12.1032 + *  \return Name of the device or NULL on error.
 12.1033   *
 12.1034 - * \brief Get the implementation dependent name of a Haptic device.
 12.1035 - * This can be called before any joysticks are opened.
 12.1036 - * If no name can be found, this function returns NULL.
 12.1037 - *
 12.1038 - *    \param device_index Index of the device to get it's name.
 12.1039 - *    \return Name of the device or NULL on error.
 12.1040 - *
 12.1041 - * \sa SDL_NumHaptics
 12.1042 + *  \sa SDL_NumHaptics
 12.1043   */
 12.1044  extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
 12.1045  
 12.1046  /**
 12.1047 - * \fn SDL_Haptic * SDL_HapticOpen(int device_index)
 12.1048 + *  \brief Opens a Haptic device for usage.
 12.1049 + *  
 12.1050 + *  The index passed as an argument refers to the N'th Haptic device on this 
 12.1051 + *  system.
 12.1052   *
 12.1053 - * \brief Opens a Haptic device for usage - the index passed as an
 12.1054 - * argument refers to the N'th Haptic device on this system.
 12.1055 + *  When opening a haptic device, it's gain will be set to maximum and
 12.1056 + *  autocenter will be disabled.  To modify these values use
 12.1057 + *  SDL_HapticSetGain() and SDL_HapticSetAutocenter().
 12.1058   *
 12.1059 - * When opening a haptic device, it's gain will be set to maximum and
 12.1060 - *  autocenter will be disabled.  To modify these values use
 12.1061 - *  SDL_HapticSetGain and SDL_HapticSetAutocenter
 12.1062 + *  \param device_index Index of the device to open.
 12.1063 + *  \return Device identifier or NULL on error.
 12.1064   *
 12.1065 - *    \param device_index Index of the device to open.
 12.1066 - *    \return Device identifier or NULL on error.
 12.1067 - *
 12.1068 - * \sa SDL_HapticIndex
 12.1069 - * \sa SDL_HapticOpenFromMouse
 12.1070 - * \sa SDL_HapticOpenFromJoystick
 12.1071 - * \sa SDL_HapticClose
 12.1072 - * \sa SDL_HapticSetGain
 12.1073 - * \sa SDL_HapticSetAutocenter
 12.1074 - * \sa SDL_HapticPause
 12.1075 - * \sa SDL_HapticStopAll
 12.1076 + *  \sa SDL_HapticIndex
 12.1077 + *  \sa SDL_HapticOpenFromMouse
 12.1078 + *  \sa SDL_HapticOpenFromJoystick
 12.1079 + *  \sa SDL_HapticClose
 12.1080 + *  \sa SDL_HapticSetGain
 12.1081 + *  \sa SDL_HapticSetAutocenter
 12.1082 + *  \sa SDL_HapticPause
 12.1083 + *  \sa SDL_HapticStopAll
 12.1084   */
 12.1085  extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index);
 12.1086  
 12.1087  /**
 12.1088 - * \fn int SDL_HapticOpened(int device_index)
 12.1089 - *
 12.1090 - * \brief Checks if the haptic device at index has been opened.
 12.1091 - *
 12.1092 - *    \param device_index Index to check to see if it has been opened.
 12.1093 - *    \return 1 if it has been opened or 0 if it hasn't.
 12.1094 - * 
 12.1095 - * \sa SDL_HapticOpen
 12.1096 - * \sa SDL_HapticIndex
 12.1097 + *  \brief Checks if the haptic device at index has been opened.
 12.1098 + *  
 12.1099 + *  \param device_index Index to check to see if it has been opened.
 12.1100 + *  \return 1 if it has been opened or 0 if it hasn't.
 12.1101 + *  
 12.1102 + *  \sa SDL_HapticOpen
 12.1103 + *  \sa SDL_HapticIndex
 12.1104   */
 12.1105  extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index);
 12.1106  
 12.1107  /**
 12.1108 - * \fn int SDL_HapticIndex(SDL_Haptic * haptic)
 12.1109 - *
 12.1110 - * \brief Gets the index of a haptic device.
 12.1111 - *
 12.1112 - *    \param haptic Haptic device to get the index of.
 12.1113 - *    \return The index of the haptic device or -1 on error.
 12.1114 - *
 12.1115 - * \sa SDL_HapticOpen
 12.1116 - * \sa SDL_HapticOpened
 12.1117 + *  \brief Gets the index of a haptic device.
 12.1118 + *  
 12.1119 + *  \param haptic Haptic device to get the index of.
 12.1120 + *  \return The index of the haptic device or -1 on error.
 12.1121 + *  
 12.1122 + *  \sa SDL_HapticOpen
 12.1123 + *  \sa SDL_HapticOpened
 12.1124   */
 12.1125  extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic);
 12.1126  
 12.1127  /**
 12.1128 - * \fn int SDL_MouseIsHaptic(void)
 12.1129 - *
 12.1130 - * \brief Gets whether or not the current mouse has haptic capabilities.
 12.1131 - *
 12.1132 - *    \return SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.
 12.1133 - *
 12.1134 - * \sa SDL_HapticOpenFromMouse
 12.1135 + *  \brief Gets whether or not the current mouse has haptic capabilities.
 12.1136 + *  
 12.1137 + *  \return SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.
 12.1138 + *  
 12.1139 + *  \sa SDL_HapticOpenFromMouse
 12.1140   */
 12.1141  extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void);
 12.1142  
 12.1143  /**
 12.1144 - * \fn SDL_Haptic * SDL_HapticOpenFromMouse(void)
 12.1145 - *
 12.1146 - * \brief Tries to open a haptic device from the current mouse.
 12.1147 - *
 12.1148 - *    \return The haptic device identifier or NULL on error.
 12.1149 - *
 12.1150 - * \sa SDL_MouseIsHaptic
 12.1151 - * \sa SDL_HapticOpen
 12.1152 + *  \brief Tries to open a haptic device from the current mouse.
 12.1153 + *  
 12.1154 + *  \return The haptic device identifier or NULL on error.
 12.1155 + *  
 12.1156 + *  \sa SDL_MouseIsHaptic
 12.1157 + *  \sa SDL_HapticOpen
 12.1158   */
 12.1159  extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void);
 12.1160  
 12.1161  /**
 12.1162 - * \fn int SDL_JoystickIsHaptic(SDL_Joystick * joystick)
 12.1163 - *
 12.1164 - * \brief Checks to see if a joystick has haptic features.
 12.1165 - *
 12.1166 - *    \param joystick Joystick to test for haptic capabilities.
 12.1167 - *    \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
 12.1168 - *            or -1 if an error ocurred.
 12.1169 - *
 12.1170 - * \sa SDL_HapticOpenFromJoystick
 12.1171 + *  \brief Checks to see if a joystick has haptic features.
 12.1172 + *  
 12.1173 + *  \param joystick Joystick to test for haptic capabilities.
 12.1174 + *  \return 1 if the joystick is haptic, 0 if it isn't
 12.1175 + *          or -1 if an error ocurred.
 12.1176 + *  
 12.1177 + *  \sa SDL_HapticOpenFromJoystick
 12.1178   */
 12.1179  extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
 12.1180  
 12.1181  /**
 12.1182 - * \fn SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick)
 12.1183 - *
 12.1184 - * \brief Opens a Haptic device for usage from a Joystick device.  Still has
 12.1185 - * to be closed seperately to the joystick.
 12.1186 - *
 12.1187 - * When opening from a joystick you should first close the haptic device before
 12.1188 + *  \brief Opens a Haptic device for usage from a Joystick device.
 12.1189 + *  
 12.1190 + *  You must still close the haptic device seperately.  It will not be closed 
 12.1191 + *  with the joystick.
 12.1192 + *  
 12.1193 + *  When opening from a joystick you should first close the haptic device before
 12.1194   *  closing the joystick device.  If not, on some implementations the haptic
 12.1195   *  device will also get unallocated and you'll be unable to use force feedback
 12.1196   *  on that device.
 12.1197 - *
 12.1198 - *    \param joystick Joystick to create a haptic device from.
 12.1199 - *    \return A valid haptic device identifier on success or NULL on error.
 12.1200 - *
 12.1201 - * \sa SDL_HapticOpen
 12.1202 - * \sa SDL_HapticClose
 12.1203 + *  
 12.1204 + *  \param joystick Joystick to create a haptic device from.
 12.1205 + *  \return A valid haptic device identifier on success or NULL on error.
 12.1206 + *  
 12.1207 + *  \sa SDL_HapticOpen
 12.1208 + *  \sa SDL_HapticClose
 12.1209   */
 12.1210  extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *
 12.1211                                                                 joystick);
 12.1212  
 12.1213  /**
 12.1214 - * \fn void SDL_HapticClose(SDL_Haptic * haptic)
 12.1215 - *
 12.1216 - * \brief Closes a Haptic device previously opened with SDL_HapticOpen.
 12.1217 - *
 12.1218 - *    \param haptic Haptic device to close.
 12.1219 + *  \brief Closes a Haptic device previously opened with SDL_HapticOpen().
 12.1220 + *  
 12.1221 + *  \param haptic Haptic device to close.
 12.1222   */
 12.1223  extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
 12.1224  
 12.1225  /**
 12.1226 - * \fn int SDL_HapticNumEffects(SDL_Haptic * haptic)
 12.1227 - *
 12.1228 - * \brief Returns the number of effects a haptic device can store.
 12.1229 - *
 12.1230 - * On some platforms this isn't fully supported, and therefore is an
 12.1231 + *  \brief Returns the number of effects a haptic device can store.
 12.1232 + *  
 12.1233 + *  On some platforms this isn't fully supported, and therefore is an
 12.1234   *  aproximation.  Always check to see if your created effect was actually
 12.1235 - *  created and do not rely solely on HapticNumEffects.
 12.1236 - *
 12.1237 - *    \param haptic The haptic device to query effect max.
 12.1238 - *    \return The number of effects the haptic device can store or
 12.1239 - *            -1 on error.
 12.1240 - *
 12.1241 - * \sa SDL_HapticNumEffectsPlaying
 12.1242 - * \sa SDL_HapticQuery
 12.1243 + *  created and do not rely solely on SDL_HapticNumEffects().
 12.1244 + *  
 12.1245 + *  \param haptic The haptic device to query effect max.
 12.1246 + *  \return The number of effects the haptic device can store or
 12.1247 + *          -1 on error.
 12.1248 + *  
 12.1249 + *  \sa SDL_HapticNumEffectsPlaying
 12.1250 + *  \sa SDL_HapticQuery
 12.1251   */
 12.1252  extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
 12.1253  
 12.1254  /**
 12.1255 - * \fn int SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic)
 12.1256 + *  \brief Returns the number of effects a haptic device can play at the same 
 12.1257 + *         time.
 12.1258 + *  
 12.1259 + *  This is not supported on all platforms, but will always return a value.  
 12.1260 + *  Added here for the sake of completness.
 12.1261 + *  
 12.1262 + *  \param haptic The haptic device to query maximum playing effects.
 12.1263 + *  \return The number of effects the haptic device can play at the same time
 12.1264 + *          or -1 on error.
 12.1265   *
 12.1266 - * \brief Returns the number of effects a haptic device can play at the same time.
 12.1267 - *
 12.1268 - * This is not supported on all platforms, but will always return a value.  Added
 12.1269 - *  here for the sake of completness.
 12.1270 - *
 12.1271 - *    \param haptic The haptic device to query maximum playing effect.s
 12.1272 - *    \return The number of effects the haptic device can play at the same time
 12.1273 - *            or -1 on error.
 12.1274 - *
 12.1275 - * \sa SDL_HapticNumEffects
 12.1276 - * \sa SDL_HapticQuery
 12.1277 + *  \sa SDL_HapticNumEffects
 12.1278 + *  \sa SDL_HapticQuery
 12.1279   */
 12.1280  extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic);
 12.1281  
 12.1282  /**
 12.1283 - * \fn unsigned int SDL_HapticQuery(SDL_Haptic * haptic)
 12.1284 - *
 12.1285 - * \brief Gets the haptic devices supported features in bitwise matter.
 12.1286 - *
 12.1287 - * Example: 
 12.1288 - * \code
 12.1289 - * if (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT) {
 12.1290 - *    printf("We have constant haptic effect!");
 12.1291 - * }
 12.1292 - * \endcode
 12.1293 - *    
 12.1294 - *
 12.1295 - *    \param haptic The haptic device to query.
 12.1296 - *    \return Haptic features in bitwise manner (OR'd).
 12.1297 - *
 12.1298 - * \sa SDL_HapticNumEffects
 12.1299 - * \sa SDL_HapticEffectSupported
 12.1300 + *  \brief Gets the haptic devices supported features in bitwise matter.
 12.1301 + *  
 12.1302 + *  Example: 
 12.1303 + *  \code
 12.1304 + *  if (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT) {
 12.1305 + *      printf("We have constant haptic effect!");
 12.1306 + *  }
 12.1307 + *  \endcode
 12.1308 + *  
 12.1309 + *  \param haptic The haptic device to query.
 12.1310 + *  \return Haptic features in bitwise manner (OR'd).
 12.1311 + *  
 12.1312 + *  \sa SDL_HapticNumEffects
 12.1313 + *  \sa SDL_HapticEffectSupported
 12.1314   */
 12.1315  extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic);
 12.1316  
 12.1317  
 12.1318  /**
 12.1319 - * \fn int SDL_HapticNumAxes(SDL_Haptic * haptic)
 12.1320 - *
 12.1321 - * \brief Gets the number of haptic axes the device has.
 12.1322 - *
 12.1323 - * \sa SDL_HapticDirection
 12.1324 + *  \brief Gets the number of haptic axes the device has.
 12.1325 + *  
 12.1326 + *  \sa SDL_HapticDirection
 12.1327   */
 12.1328  extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic);
 12.1329  
 12.1330  /**
 12.1331 - * \fn int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect)
 12.1332 - *
 12.1333 - * \brief Checks to see if effect is supported by haptic.
 12.1334 - *
 12.1335 - *    \param haptic Haptic device to check on.
 12.1336 - *    \param effect Effect to check to see if it is supported.
 12.1337 - *    \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or 
 12.1338 - *            -1 on error.
 12.1339 - * 
 12.1340 - * \sa SDL_HapticQuery
 12.1341 - * \sa SDL_HapticNewEffect
 12.1342 + *  \brief Checks to see if effect is supported by haptic.
 12.1343 + *  
 12.1344 + *  \param haptic Haptic device to check on.
 12.1345 + *  \param effect Effect to check to see if it is supported.
 12.1346 + *  \return 1 if effect is supported, 0 if it isn't or -1 on error.
 12.1347 + *  
 12.1348 + *  \sa SDL_HapticQuery
 12.1349 + *  \sa SDL_HapticNewEffect
 12.1350   */
 12.1351  extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic,
 12.1352                                                        SDL_HapticEffect *
 12.1353                                                        effect);
 12.1354  
 12.1355  /**
 12.1356 - * \fn int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect)
 12.1357 - *
 12.1358 - * \brief Creates a new haptic effect on the device.
 12.1359 - *
 12.1360 - *    \param haptic Haptic device to create the effect on.
 12.1361 - *    \param effect Properties of the effect to create.
 12.1362 - *    \return The id of the effect on success or -1 on error.
 12.1363 - *
 12.1364 - * \sa SDL_HapticUpdateEffect
 12.1365 - * \sa SDL_HapticRunEffect
 12.1366 - * \sa SDL_HapticDestroyEffect
 12.1367 + *  \brief Creates a new haptic effect on the device.
 12.1368 + *  
 12.1369 + *  \param haptic Haptic device to create the effect on.
 12.1370 + *  \param effect Properties of the effect to create.
 12.1371 + *  \return The id of the effect on success or -1 on error.
 12.1372 + *  
 12.1373 + *  \sa SDL_HapticUpdateEffect
 12.1374 + *  \sa SDL_HapticRunEffect
 12.1375 + *  \sa SDL_HapticDestroyEffect
 12.1376   */
 12.1377  extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic,
 12.1378                                                  SDL_HapticEffect * effect);
 12.1379  
 12.1380  /**
 12.1381 - * \fn int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data)
 12.1382 - *
 12.1383 - * \brief Updates the properties of an effect.
 12.1384 - *
 12.1385 - * Can be used dynamically, although behaviour when dynamically changing
 12.1386 - * direction may be strange.  Specifically the effect may reupload itself
 12.1387 - * and start playing from the start.  You cannot change the type either when
 12.1388 - * running UpdateEffect.
 12.1389 - *
 12.1390 - *    \param haptic Haptic device that has the effect.
 12.1391 - *    \param effect Effect to update.
 12.1392 - *    \param data New effect properties to use.
 12.1393 - *    \return The id of the effect on success or -1 on error.
 12.1394 - *
 12.1395 - * \sa SDL_HapticNewEffect
 12.1396 - * \sa SDL_HapticRunEffect
 12.1397 - * \sa SDL_HapticDestroyEffect
 12.1398 + *  \brief Updates the properties of an effect.
 12.1399 + *  
 12.1400 + *  Can be used dynamically, although behaviour when dynamically changing
 12.1401 + *  direction may be strange.  Specifically the effect may reupload itself
 12.1402 + *  and start playing from the start.  You cannot change the type either when
 12.1403 + *  running SDL_HapticUpdateEffect().
 12.1404 + *  
 12.1405 + *  \param haptic Haptic device that has the effect.
 12.1406 + *  \param effect Effect to update.
 12.1407 + *  \param data New effect properties to use.
 12.1408 + *  \return The id of the effect on success or -1 on error.
 12.1409 + *  
 12.1410 + *  \sa SDL_HapticNewEffect
 12.1411 + *  \sa SDL_HapticRunEffect
 12.1412 + *  \sa SDL_HapticDestroyEffect
 12.1413   */
 12.1414  extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic,
 12.1415                                                     int effect,
 12.1416                                                     SDL_HapticEffect * data);
 12.1417  
 12.1418  /**
 12.1419 - * \fn int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect, Uint32 iterations)
 12.1420 - *
 12.1421 - * \brief Runs the haptic effect on it's assosciated haptic device.
 12.1422 - *
 12.1423 - * If iterations are SDL_HAPTIC_INFINITY, it'll run the effect over and over
 12.1424 + *  \brief Runs the haptic effect on it's assosciated haptic device.
 12.1425 + *  
 12.1426 + *  If iterations are ::SDL_HAPTIC_INFINITY, it'll run the effect over and over
 12.1427   *  repeating the envelope (attack and fade) every time.  If you only want the
 12.1428 - *  effect to last forever, set SDL_HAPTIC_INFINITY in the effect's length
 12.1429 + *  effect to last forever, set ::SDL_HAPTIC_INFINITY in the effect's length
 12.1430   *  parameter.
 12.1431 - *
 12.1432 - *    \param haptic Haptic device to run the effect on.
 12.1433 - *    \param effect Identifier of the haptic effect to run.
 12.1434 - *    \param iterations Number of iterations to run the effect. Use
 12.1435 - *           SDL_HAPTIC_INFINITY for infinity.
 12.1436 - *    \return 0 on success or -1 on error.
 12.1437 - *
 12.1438 - * \sa SDL_HapticStopEffect
 12.1439 - * \sa SDL_HapticDestroyEffect
 12.1440 - * \sa SDL_HapticGetEffectStatus
 12.1441 + *  
 12.1442 + *  \param haptic Haptic device to run the effect on.
 12.1443 + *  \param effect Identifier of the haptic effect to run.
 12.1444 + *  \param iterations Number of iterations to run the effect. Use
 12.1445 + *         ::SDL_HAPTIC_INFINITY for infinity.
 12.1446 + *  \return 0 on success or -1 on error.
 12.1447 + *  
 12.1448 + *  \sa SDL_HapticStopEffect
 12.1449 + *  \sa SDL_HapticDestroyEffect
 12.1450 + *  \sa SDL_HapticGetEffectStatus
 12.1451   */
 12.1452  extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic,
 12.1453                                                  int effect,
 12.1454                                                  Uint32 iterations);
 12.1455  
 12.1456  /**
 12.1457 - * \fn int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect)
 12.1458 - *
 12.1459 - * \brief Stops the haptic effect on it's assosciated haptic device.
 12.1460 - *
 12.1461 - *    \param haptic Haptic device to stop the effect on.
 12.1462 - *    \param effect Identifier of the effect to stop.
 12.1463 - *    \return 0 on success or -1 on error.
 12.1464 - *
 12.1465 - * \sa SDL_HapticRunEffect
 12.1466 - * \sa SDL_HapticDestroyEffect
 12.1467 + *  \brief Stops the haptic effect on it's assosciated haptic device.
 12.1468 + *  
 12.1469 + *  \param haptic Haptic device to stop the effect on.
 12.1470 + *  \param effect Identifier of the effect to stop.
 12.1471 + *  \return 0 on success or -1 on error.
 12.1472 + *  
 12.1473 + *  \sa SDL_HapticRunEffect
 12.1474 + *  \sa SDL_HapticDestroyEffect
 12.1475   */
 12.1476  extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic,
 12.1477                                                   int effect);
 12.1478  
 12.1479  /**
 12.1480 - * \fn void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect)
 12.1481 - *
 12.1482 - * \brief Destroys a haptic effect on the device.  This will stop the effect
 12.1483 - * if it's running.  Effects are automatically destroyed when the device is
 12.1484 - * closed.
 12.1485 - *
 12.1486 - *    \param haptic Device to destroy the effect on.
 12.1487 - *    \param effect Identifier of the effect to destroy.
 12.1488 - * 
 12.1489 - * \sa SDL_HapticNewEffect
 12.1490 + *  \brief Destroys a haptic effect on the device.
 12.1491 + *  
 12.1492 + *  This will stop the effect if it's running.  Effects are automatically 
 12.1493 + *  destroyed when the device is closed.
 12.1494 + *  
 12.1495 + *  \param haptic Device to destroy the effect on.
 12.1496 + *  \param effect Identifier of the effect to destroy.
 12.1497 + *  
 12.1498 + *  \sa SDL_HapticNewEffect
 12.1499   */
 12.1500  extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic,
 12.1501                                                       int effect);
 12.1502  
 12.1503  /**
 12.1504 - * \fn int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect)
 12.1505 - *
 12.1506 - * \brief Gets the status of the current effect on the haptic device.
 12.1507 - *
 12.1508 - * Device must support the SDL_HAPTIC_STATUS feature.
 12.1509 - *
 12.1510 - *    \param haptic Haptic device to query the effect status on.
 12.1511 - *    \param effect Identifier of the effect to query it's status.
 12.1512 - *    \return 0 if it isn't playing, SDL_HAPTIC_PLAYING if it is playing
 12.1513 - *            or -1 on error.
 12.1514 - *
 12.1515 - * \sa SDL_HapticRunEffect
 12.1516 - * \sa SDL_HapticStopEffect
 12.1517 + *  \brief Gets the status of the current effect on the haptic device.
 12.1518 + *  
 12.1519 + *  Device must support the ::SDL_HAPTIC_STATUS feature.
 12.1520 + *  
 12.1521 + *  \param haptic Haptic device to query the effect status on.
 12.1522 + *  \param effect Identifier of the effect to query it's status.
 12.1523 + *  \return 0 if it isn't playing, ::SDL_HAPTIC_PLAYING if it is playing
 12.1524 + *          or -1 on error.
 12.1525 + *  
 12.1526 + *  \sa SDL_HapticRunEffect
 12.1527 + *  \sa SDL_HapticStopEffect
 12.1528   */
 12.1529  extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic,
 12.1530                                                        int effect);
 12.1531  
 12.1532  /**
 12.1533 - * \fn int SDL_HapticSetGain(SDL_Haptic * haptic, int gain)
 12.1534 - *
 12.1535 - * \brief Sets the global gain of the device.  Gain should be between 0 and 100.
 12.1536 - *
 12.1537 - * Device must support the SDL_HAPTIC_GAIN feature.
 12.1538 - *
 12.1539 - * The user may specify the maxmimum gain by setting the environment variable
 12.1540 - *  SDL_HAPTIC_GAIN_MAX which should be between 0 and 100.  All calls to
 12.1541 - *  SDL_HapticSetGain will scale linearly using SDL_HAPTIC_GAIN_MAX as the
 12.1542 + *  \brief Sets the global gain of the device.
 12.1543 + *  
 12.1544 + *  Device must support the ::SDL_HAPTIC_GAIN feature.
 12.1545 + *  
 12.1546 + *  The user may specify the maxmimum gain by setting the environment variable
 12.1547 + *  ::SDL_HAPTIC_GAIN_MAX which should be between 0 and 100.  All calls to
 12.1548 + *  SDL_HapticSetGain() will scale linearly using ::SDL_HAPTIC_GAIN_MAX as the
 12.1549   *  maximum.
 12.1550 - *
 12.1551 - *    \param haptic Haptic device to set the gain on.
 12.1552 - *    \param gain Value to set the gain to, should be between 0 and 100.
 12.1553 - *    \return 0 on success or -1 on error.
 12.1554 - *
 12.1555 - * \sa SDL_HapticQuery
 12.1556 + *  
 12.1557 + *  \param haptic Haptic device to set the gain on.
 12.1558 + *  \param gain Value to set the gain to, should be between 0 and 100.
 12.1559 + *  \return 0 on success or -1 on error.
 12.1560 + *  
 12.1561 + *  \sa SDL_HapticQuery
 12.1562   */
 12.1563  extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
 12.1564  
 12.1565  /**
 12.1566 - * \fn int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter)
 12.1567 + *  \brief Sets the global autocenter of the device.
 12.1568 + *  
 12.1569 + *  Autocenter should be between 0 and 100.  Setting it to 0 will disable 
 12.1570 + *  autocentering.
 12.1571   *
 12.1572 - * \brief Sets the global autocenter of the device.  Autocenter should be between
 12.1573 - * 0 and 100.  Setting it to 0 will disable autocentering.
 12.1574 + *  Device must support the ::SDL_HAPTIC_AUTOCENTER feature.
 12.1575   *
 12.1576 - * Device must support the SDL_HAPTIC_AUTOCENTER feature.
 12.1577 - *
 12.1578 - *    \param haptic Haptic device to set autocentering on.
 12.1579 - *    \param autocenter Value to set autocenter to, 0 disables autocentering.
 12.1580 - *    \return 0 on success or -1 on error.
 12.1581 - *
 12.1582 - * \sa SDL_HapticQuery
 12.1583 + *  \param haptic Haptic device to set autocentering on.
 12.1584 + *  \param autocenter Value to set autocenter to, 0 disables autocentering.
 12.1585 + *  \return 0 on success or -1 on error.
 12.1586 + *  
 12.1587 + *  \sa SDL_HapticQuery
 12.1588   */
 12.1589  extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic,
 12.1590                                                      int autocenter);
 12.1591  
 12.1592  /**
 12.1593 - * \fn extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic)
 12.1594 - *
 12.1595 - * \brief Pauses a haptic device.
 12.1596 - *
 12.1597 - * Device must support the SDL_HAPTIC_PAUSE feature.  Call SDL_HapticUnpause
 12.1598 - *  to resume playback.
 12.1599 - *
 12.1600 - * Do not modify the effects nor add new ones while the device is paused.
 12.1601 + *  \brief Pauses a haptic device.
 12.1602 + *  
 12.1603 + *  Device must support the ::SDL_HAPTIC_PAUSE feature.  Call 
 12.1604 + *  SDL_HapticUnpause() to resume playback.
 12.1605 + *  
 12.1606 + *  Do not modify the effects nor add new ones while the device is paused.
 12.1607   *  That can cause all sorts of weird errors.
 12.1608 - *
 12.1609 - *    \param haptic Haptic device to pause.
 12.1610 - *    \return 0 on success or -1 on error.
 12.1611 - *
 12.1612 - * \sa SDL_HapticUnpause
 12.1613 + *  
 12.1614 + *  \param haptic Haptic device to pause.
 12.1615 + *  \return 0 on success or -1 on error.
 12.1616 + *  
 12.1617 + *  \sa SDL_HapticUnpause
 12.1618   */
 12.1619  extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic);
 12.1620  
 12.1621  /**
 12.1622 - * \fn extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic)
 12.1623 - *
 12.1624 - * \brief Unpauses a haptic device.
 12.1625 - *
 12.1626 - * Call to unpause after SDL_HapticPause.
 12.1627 - *
 12.1628 - *    \param haptic Haptic device to pause.
 12.1629 - *    \return 0 on success or -1 on error.
 12.1630 - *
 12.1631 - * \sa SDL_HapticPause
 12.1632 + *  \brief Unpauses a haptic device.
 12.1633 + *  
 12.1634 + *  Call to unpause after SDL_HapticPause().
 12.1635 + *  
 12.1636 + *  \param haptic Haptic device to pause.
 12.1637 + *  \return 0 on success or -1 on error.
 12.1638 + *  
 12.1639 + *  \sa SDL_HapticPause
 12.1640   */
 12.1641  extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic);
 12.1642  
 12.1643  /**
 12.1644 - * \fn extern DECSLPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic)
 12.1645 - *
 12.1646 - * \brief Stops all the currently playing effects on a haptic device.
 12.1647 - *
 12.1648 - *    \param haptic Haptic device to stop.
 12.1649 - *    \return 0 on success or -1 on error.
 12.1650 + *  \brief Stops all the currently playing effects on a haptic device.
 12.1651 + *  
 12.1652 + *  \param haptic Haptic device to stop.
 12.1653 + *  \return 0 on success or -1 on error.
 12.1654   */
 12.1655  extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic);
 12.1656  
    13.1 --- a/include/SDL_joystick.h	Sun Oct 18 23:21:15 2009 +0000
    13.2 +++ b/include/SDL_joystick.h	Mon Oct 19 13:31:58 2009 +0000
    13.3 @@ -21,9 +21,9 @@
    13.4  */
    13.5  
    13.6  /**
    13.7 - * \file SDL_joystick.h
    13.8 - *
    13.9 - * Include file for SDL joystick event handling
   13.10 + *  \file SDL_joystick.h
   13.11 + *  
   13.12 + *  Include file for SDL joystick event handling
   13.13   */
   13.14  
   13.15  #ifndef _SDL_joystick_h
   13.16 @@ -40,10 +40,13 @@
   13.17  /* *INDENT-ON* */
   13.18  #endif
   13.19  
   13.20 -/* In order to use these functions, SDL_Init() must have been called
   13.21 -   with the SDL_INIT_JOYSTICK flag.  This causes SDL to scan the system
   13.22 -   for joysticks, and load appropriate drivers.
   13.23 -*/
   13.24 +/**
   13.25 + *  \file SDL_joystick.h
   13.26 + *
   13.27 + *  In order to use these functions, SDL_Init() must have been called
   13.28 + *  with the ::SDL_INIT_JOYSTICK flag.  This causes SDL to scan the system
   13.29 + *  for joysticks, and load appropriate drivers.
   13.30 + */
   13.31  
   13.32  /* The joystick structure used to identify an SDL joystick */
   13.33  struct _SDL_Joystick;
   13.34 @@ -51,87 +54,94 @@
   13.35  
   13.36  
   13.37  /* Function prototypes */
   13.38 -/*
   13.39 - * Count the number of joysticks attached to the system
   13.40 +/**
   13.41 + *  Count the number of joysticks attached to the system
   13.42   */
   13.43  extern DECLSPEC int SDLCALL SDL_NumJoysticks(void);
   13.44  
   13.45 -/*
   13.46 - * Get the implementation dependent name of a joystick.
   13.47 - * This can be called before any joysticks are opened.
   13.48 - * If no name can be found, this function returns NULL.
   13.49 +/**
   13.50 + *  Get the implementation dependent name of a joystick.
   13.51 + *  This can be called before any joysticks are opened.
   13.52 + *  If no name can be found, this function returns NULL.
   13.53   */
   13.54  extern DECLSPEC const char *SDLCALL SDL_JoystickName(int device_index);
   13.55  
   13.56 -/*
   13.57 - * Open a joystick for use - the index passed as an argument refers to
   13.58 - * the N'th joystick on the system.  This index is the value which will
   13.59 - * identify this joystick in future joystick events.
   13.60 - *
   13.61 - * This function returns a joystick identifier, or NULL if an error occurred.
   13.62 +/**
   13.63 + *  Open a joystick for use.  
   13.64 + *  The index passed as an argument refers tothe N'th joystick on the system.  
   13.65 + *  This index is the value which will identify this joystick in future joystick
   13.66 + *  events.
   13.67 + *  
   13.68 + *  \return A joystick identifier, or NULL if an error occurred.
   13.69   */
   13.70  extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickOpen(int device_index);
   13.71  
   13.72 -/*
   13.73 - * Returns 1 if the joystick has been opened, or 0 if it has not.
   13.74 +/**
   13.75 + *  Returns 1 if the joystick has been opened, or 0 if it has not.
   13.76   */
   13.77  extern DECLSPEC int SDLCALL SDL_JoystickOpened(int device_index);
   13.78  
   13.79 -/*
   13.80 - * Get the device index of an opened joystick.
   13.81 +/**
   13.82 + *  Get the device index of an opened joystick.
   13.83   */
   13.84  extern DECLSPEC int SDLCALL SDL_JoystickIndex(SDL_Joystick * joystick);
   13.85  
   13.86 -/*
   13.87 - * Get the number of general axis controls on a joystick
   13.88 +/**
   13.89 + *  Get the number of general axis controls on a joystick.
   13.90   */
   13.91  extern DECLSPEC int SDLCALL SDL_JoystickNumAxes(SDL_Joystick * joystick);
   13.92  
   13.93 -/*
   13.94 - * Get the number of trackballs on a joystick
   13.95 - * Joystick trackballs have only relative motion events associated
   13.96 - * with them and their state cannot be polled.
   13.97 +/**
   13.98 + *  Get the number of trackballs on a joystick.
   13.99 + *  
  13.100 + *  Joystick trackballs have only relative motion events associated
  13.101 + *  with them and their state cannot be polled.
  13.102   */
  13.103  extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(SDL_Joystick * joystick);
  13.104  
  13.105 -/*
  13.106 - * Get the number of POV hats on a joystick
  13.107 +/**
  13.108 + *  Get the number of POV hats on a joystick.
  13.109   */
  13.110  extern DECLSPEC int SDLCALL SDL_JoystickNumHats(SDL_Joystick * joystick);
  13.111  
  13.112 -/*
  13.113 - * Get the number of buttons on a joystick
  13.114 +/**
  13.115 + *  Get the number of buttons on a joystick.
  13.116   */
  13.117  extern DECLSPEC int SDLCALL SDL_JoystickNumButtons(SDL_Joystick * joystick);
  13.118  
  13.119 -/*
  13.120 - * Update the current state of the open joysticks.
  13.121 - * This is called automatically by the event loop if any joystick
  13.122 - * events are enabled.
  13.123 +/**
  13.124 + *  Update the current state of the open joysticks.
  13.125 + *  
  13.126 + *  This is called automatically by the event loop if any joystick
  13.127 + *  events are enabled.
  13.128   */
  13.129  extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void);
  13.130  
  13.131 -/*
  13.132 - * Enable/disable joystick event polling.
  13.133 - * If joystick events are disabled, you must call SDL_JoystickUpdate()
  13.134 - * yourself and check the state of the joystick when you want joystick
  13.135 - * information.
  13.136 - * The state can be one of SDL_QUERY, SDL_ENABLE or SDL_IGNORE.
  13.137 +/**
  13.138 + *  Enable/disable joystick event polling.
  13.139 + *  
  13.140 + *  If joystick events are disabled, you must call SDL_JoystickUpdate()
  13.141 + *  yourself and check the state of the joystick when you want joystick
  13.142 + *  information.
  13.143 + *  
  13.144 + *  The state can be one of ::SDL_QUERY, ::SDL_ENABLE or ::SDL_IGNORE.
  13.145   */
  13.146  extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state);
  13.147  
  13.148 -/*
  13.149 - * Get the current state of an axis control on a joystick
  13.150 - * The state is a value ranging from -32768 to 32767.
  13.151 - * The axis indices start at index 0.
  13.152 +/**
  13.153 + *  Get the current state of an axis control on a joystick.
  13.154 + *  
  13.155 + *  The state is a value ranging from -32768 to 32767.
  13.156 + *  
  13.157 + *  The axis indices start at index 0.
  13.158   */
  13.159  extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick * joystick,
  13.160                                                     int axis);
  13.161  
  13.162 -/*
  13.163 - * Get the current state of a POV hat on a joystick
  13.164 - * The return value is one of the following positions:
  13.165 +/**
  13.166 + *  \name Hat positions
  13.167   */
  13.168 +/*@{*/
  13.169  #define SDL_HAT_CENTERED	0x00
  13.170  #define SDL_HAT_UP		0x01
  13.171  #define SDL_HAT_RIGHT		0x02
  13.172 @@ -141,29 +151,47 @@
  13.173  #define SDL_HAT_RIGHTDOWN	(SDL_HAT_RIGHT|SDL_HAT_DOWN)
  13.174  #define SDL_HAT_LEFTUP		(SDL_HAT_LEFT|SDL_HAT_UP)
  13.175  #define SDL_HAT_LEFTDOWN	(SDL_HAT_LEFT|SDL_HAT_DOWN)
  13.176 -/*
  13.177 - * The hat indices start at index 0.
  13.178 +/*@}*/
  13.179 +
  13.180 +/**
  13.181 + *  Get the current state of a POV hat on a joystick.
  13.182 + *
  13.183 + *  The hat indices start at index 0.
  13.184 + *  
  13.185 + *  \return The return value is one of the following positions:
  13.186 + *           - ::SDL_HAT_CENTERED
  13.187 + *           - ::SDL_HAT_UP
  13.188 + *           - ::SDL_HAT_RIGHT
  13.189 + *           - ::SDL_HAT_DOWN
  13.190 + *           - ::SDL_HAT_LEFT
  13.191 + *           - ::SDL_HAT_RIGHTUP
  13.192 + *           - ::SDL_HAT_RIGHTDOWN
  13.193 + *           - ::SDL_HAT_LEFTUP
  13.194 + *           - ::SDL_HAT_LEFTDOWN
  13.195   */
  13.196  extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick * joystick,
  13.197                                                   int hat);
  13.198  
  13.199 -/*
  13.200 - * Get the ball axis change since the last poll
  13.201 - * This returns 0, or -1 if you passed it invalid parameters.
  13.202 - * The ball indices start at index 0.
  13.203 +/**
  13.204 + *  Get the ball axis change since the last poll.
  13.205 + *  
  13.206 + *  \return 0, or -1 if you passed it invalid parameters.
  13.207 + *  
  13.208 + *  The ball indices start at index 0.
  13.209   */
  13.210  extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick * joystick,
  13.211                                                  int ball, int *dx, int *dy);
  13.212  
  13.213 -/*
  13.214 - * Get the current state of a button on a joystick
  13.215 - * The button indices start at index 0.
  13.216 +/**
  13.217 + *  Get the current state of a button on a joystick.
  13.218 + *  
  13.219 + *  The button indices start at index 0.
  13.220   */
  13.221  extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick * joystick,
  13.222                                                      int button);
  13.223  
  13.224 -/*
  13.225 - * Close a joystick previously opened with SDL_JoystickOpen()
  13.226 +/**
  13.227 + *  Close a joystick previously opened with SDL_JoystickOpen().
  13.228   */
  13.229  extern DECLSPEC void SDLCALL SDL_JoystickClose(SDL_Joystick * joystick);
  13.230  
    14.1 --- a/include/SDL_keyboard.h	Sun Oct 18 23:21:15 2009 +0000
    14.2 +++ b/include/SDL_keyboard.h	Mon Oct 19 13:31:58 2009 +0000
    14.3 @@ -21,9 +21,9 @@
    14.4  */
    14.5  
    14.6  /**
    14.7 - * \file SDL_keyboard.h
    14.8 - *
    14.9 - * Include file for SDL keyboard event handling
   14.10 + *  \file SDL_keyboard.h
   14.11 + *  
   14.12 + *  Include file for SDL keyboard event handling
   14.13   */
   14.14  
   14.15  #ifndef _SDL_keyboard_h
   14.16 @@ -42,143 +42,129 @@
   14.17  #endif
   14.18  
   14.19  /**
   14.20 - * \struct SDL_keysym
   14.21 - *
   14.22 - * \brief The SDL keysym structure, used in key events.
   14.23 + *  \brief The SDL keysym structure, used in key events.
   14.24   */
   14.25  typedef struct SDL_keysym
   14.26  {
   14.27      SDL_scancode scancode;      /**< SDL physical key code - see ::SDL_scancode for details */
   14.28      SDLKey sym;                 /**< SDL virtual key code - see ::SDLKey for details */
   14.29      Uint16 mod;                 /**< current key modifiers */
   14.30 -    Uint32 unicode;             /**< OBSOLETE, use SDL_TextInputEvent instead */
   14.31 +    Uint32 unicode;             /**< \deprecated use SDL_TextInputEvent instead */
   14.32  } SDL_keysym;
   14.33  
   14.34  /* Function prototypes */
   14.35  
   14.36  /**
   14.37 - * \fn int SDL_GetNumKeyboards(void)
   14.38 - *
   14.39 - * \brief Get the number of keyboard input devices available.
   14.40 - *
   14.41 - * \sa SDL_SelectKeyboard()
   14.42 + *  \brief Get the number of keyboard input devices available.
   14.43 + *  
   14.44 + *  \sa SDL_SelectKeyboard()
   14.45   */
   14.46  extern DECLSPEC int SDLCALL SDL_GetNumKeyboards(void);
   14.47  
   14.48  /**
   14.49 - * \fn int SDL_SelectKeyboard(int index)
   14.50 - *
   14.51 - * \brief Set the index of the currently selected keyboard.
   14.52 - *
   14.53 - * \return The index of the previously selected keyboard.
   14.54 - *
   14.55 - * \note You can query the currently selected keyboard by passing an index of -1.
   14.56 - *
   14.57 - * \sa SDL_GetNumKeyboards()
   14.58 + *  \brief Set the index of the currently selected keyboard.
   14.59 + *  
   14.60 + *  \return The index of the previously selected keyboard.
   14.61 + *  
   14.62 + *  \note You can query the currently selected keyboard by passing an index of -1.
   14.63 + *  
   14.64 + *  \sa SDL_GetNumKeyboards()
   14.65   */
   14.66  extern DECLSPEC int SDLCALL SDL_SelectKeyboard(int index);
   14.67  
   14.68  /**
   14.69 - * \fn Uint8 *SDL_GetKeyboardState(int *numkeys)
   14.70 - *
   14.71 - * \brief Get a snapshot of the current state of the selected keyboard.
   14.72 - *
   14.73 - * \param numkeys if non-NULL, receives the length of the returned array.
   14.74 - *
   14.75 - * \return An array of key states. Indexes into this array are obtained by using ::SDL_scancode values.
   14.76 - *
   14.77 - * Example:
   14.78 - * 	Uint8 *state = SDL_GetKeyboardState(NULL);
   14.79 - *	if ( state[SDL_SCANCODE_RETURN)] ) ... <RETURN> is pressed.
   14.80 + *  \brief Get a snapshot of the current state of the selected keyboard.
   14.81 + *  
   14.82 + *  \param numkeys if non-NULL, receives the length of the returned array.
   14.83 + *  
   14.84 + *  \return An array of key states. Indexes into this array are obtained by using ::SDL_scancode values.
   14.85 + *  
   14.86 + *  \b Example:
   14.87 + *  \code
   14.88 + *  Uint8 *state = SDL_GetKeyboardState(NULL);
   14.89 + *  if ( state[SDL_SCANCODE_RETURN] )   {
   14.90 + *      printf("<RETURN> is pressed.\n");
   14.91 + *  }
   14.92 + *  \endcode
   14.93   */
   14.94  extern DECLSPEC Uint8 *SDLCALL SDL_GetKeyboardState(int *numkeys);
   14.95  
   14.96  /**
   14.97 - * \fn SDLMod SDL_GetModState(void)
   14.98 - *
   14.99 - * \brief Get the current key modifier state for the selected keyboard.
  14.100 + *  \brief Get the current key modifier state for the selected keyboard.
  14.101   */
  14.102  extern DECLSPEC SDLMod SDLCALL SDL_GetModState(void);
  14.103  
  14.104  /**
  14.105 - * \fn void SDL_SetModState(SDLMod modstate)
  14.106 - *
  14.107 - * \brief Set the current key modifier state for the selected keyboard.
  14.108 - *
  14.109 - * \note This does not change the keyboard state, only the key modifier flags.
  14.110 + *  \brief Set the current key modifier state for the selected keyboard.
  14.111 + *  
  14.112 + *  \note This does not change the keyboard state, only the key modifier flags.
  14.113   */
  14.114  extern DECLSPEC void SDLCALL SDL_SetModState(SDLMod modstate);
  14.115  
  14.116  /**
  14.117 - * \fn SDLKey SDL_GetKeyFromScancode(SDL_scancode scancode)
  14.118 - * 
  14.119 - * \brief Get the key code corresponding to the given scancode according to the current keyboard layout.
  14.120 - *
  14.121 - * See ::SDLKey for details.
  14.122 - *
  14.123 - * \sa SDL_GetKeyName()
  14.124 + *  \brief Get the key code corresponding to the given scancode according to the
  14.125 + *         current keyboard layout.
  14.126 + *  
  14.127 + *  See ::SDLKey for details.
  14.128 + *  
  14.129 + *  \sa SDL_GetKeyName()
  14.130   */
  14.131  extern DECLSPEC SDLKey SDLCALL SDL_GetKeyFromScancode(SDL_scancode scancode);
  14.132  
  14.133  /**
  14.134 - * \fn SDL_scancode SDL_GetScancodeFromKey(SDLKey key)
  14.135 - * 
  14.136 - * \brief Get the scancode corresponding to the given key code according to the current keyboard layout.
  14.137 - *
  14.138 - * See ::SDL_scancode for details.
  14.139 - *
  14.140 - * \sa SDL_GetScancodeName()
  14.141 + *  \brief Get the scancode corresponding to the given key code according to the
  14.142 + *         current keyboard layout.
  14.143 + *  
  14.144 + *  See ::SDL_scancode for details.
  14.145 + *  
  14.146 + *  \sa SDL_GetScancodeName()
  14.147   */
  14.148  extern DECLSPEC SDL_scancode SDLCALL SDL_GetScancodeFromKey(SDLKey key);
  14.149  
  14.150  /**
  14.151 - * \fn const char *SDL_GetScancodeName(SDL_scancode scancode)
  14.152 - * 
  14.153 - * \brief Get a human-readable name for a scancode.
  14.154 + *  \brief Get a human-readable name for a scancode.
  14.155 + *  
  14.156 + *  \return A pointer to a UTF-8 string that stays valid at least until the next
  14.157 + *          call to this function. If you need it around any longer, you must 
  14.158 + *          copy it.  If the scancode doesn't have a name, this function returns
  14.159 + *          an empty string ("").
  14.160   *
  14.161 - * \return A pointer to a UTF-8 string that stays valid at least until the next call to this function. If you need it around any longer, you must copy it.  If the scancode doesn't have a name, this function returns "".
  14.162 - *
  14.163 - * \sa SDL_scancode
  14.164 + *  \sa SDL_scancode
  14.165   */
  14.166  extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_scancode
  14.167                                                          scancode);
  14.168  
  14.169  /**
  14.170 - * \fn const char *SDL_GetKeyName(SDLKey key)
  14.171 - * 
  14.172 - * \brief Get a human-readable name for a key.
  14.173 - *
  14.174 - * \return A pointer to a UTF-8 string that stays valid at least until the next call to this function. If you need it around any longer, you must copy it.  If the key doesn't have a name, this function returns "".
  14.175 - *
  14.176 - * \sa SDLKey
  14.177 + *  \brief Get a human-readable name for a key.
  14.178 + *  
  14.179 + *  \return A pointer to a UTF-8 string that stays valid at least until the next
  14.180 + *          call to this function. If you need it around any longer, you must 
  14.181 + *          copy it.  If the key doesn't have a name, this function returns an 
  14.182 + *          empty string ("").
  14.183 + *  
  14.184 + *  \sa SDLKey
  14.185   */
  14.186  extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDLKey key);
  14.187  
  14.188  /**
  14.189 - * \fn void SDL_StartTextInput(void)
  14.190 - *
  14.191 - * \brief Start accepting Unicode text input events.
  14.192 - *
  14.193 - * \sa SDL_StopTextInput()
  14.194 - * \sa SDL_SetTextInputRect()
  14.195 + *  \brief Start accepting Unicode text input events.
  14.196 + *  
  14.197 + *  \sa SDL_StopTextInput()
  14.198 + *  \sa SDL_SetTextInputRect()
  14.199   */
  14.200  extern DECLSPEC void SDLCALL SDL_StartTextInput(void);
  14.201  
  14.202  /**
  14.203 - * \fn void SDL_StopTextInput(void)
  14.204 - *
  14.205 - * \brief Stop receiving any text input events.
  14.206 - *
  14.207 - * \sa SDL_StartTextInput()
  14.208 + *  \brief Stop receiving any text input events.
  14.209 + *  
  14.210 + *  \sa SDL_StartTextInput()
  14.211   */
  14.212  extern DECLSPEC void SDLCALL SDL_StopTextInput(void);
  14.213  
  14.214  /**
  14.215 - * \fn void SDL_SetTextInputRect(SDL_Rect *rect)
  14.216 - *
  14.217 - * \brief Set the rectangle used to type Unicode text inputs.
  14.218 - *
  14.219 - * \sa SDL_StartTextInput()
  14.220 + *  \brief Set the rectangle used to type Unicode text inputs.
  14.221 + *  
  14.222 + *  \sa SDL_StartTextInput()
  14.223   */
  14.224  extern DECLSPEC void SDLCALL SDL_SetTextInputRect(SDL_Rect *rect);
  14.225  
    15.1 --- a/include/SDL_keysym.h	Sun Oct 18 23:21:15 2009 +0000
    15.2 +++ b/include/SDL_keysym.h	Mon Oct 19 13:31:58 2009 +0000
    15.3 @@ -21,7 +21,9 @@
    15.4  */
    15.5  
    15.6  /**
    15.7 - * \file SDL_keysym.h
    15.8 + *  \file SDL_keysym.h
    15.9 + *  
   15.10 + *  Defines constants which identify keyboard keys and modifiers.
   15.11   */
   15.12  
   15.13  #ifndef _SDL_keysym_h
   15.14 @@ -31,14 +33,12 @@
   15.15  #include "SDL_scancode.h"
   15.16  
   15.17  /**
   15.18 - * \typedef SDLKey
   15.19 - *
   15.20 - * \brief The SDL virtual key representation.
   15.21 - *
   15.22 - * Values of this type are used to represent keyboard keys using the current
   15.23 - * layout of the keyboard.  These values include Unicode values representing
   15.24 - * the unmodified character that would be generated by pressing the key, or
   15.25 - * an SDLK_* constant for those keys that do not generate characters.
   15.26 + *  \brief The SDL virtual key representation.
   15.27 + *  
   15.28 + *  Values of this type are used to represent keyboard keys using the current
   15.29 + *  layout of the keyboard.  These values include Unicode values representing
   15.30 + *  the unmodified character that would be generated by pressing the key, or
   15.31 + *  an SDLK_* constant for those keys that do not generate characters.
   15.32   */
   15.33  typedef Sint32 SDLKey;
   15.34  
   15.35 @@ -246,9 +246,7 @@
   15.36  };
   15.37  
   15.38  /**
   15.39 - * \enum SDLMod
   15.40 - *
   15.41 - * \brief Enumeration of valid key mods (possibly OR'd together)
   15.42 + * \brief Enumeration of valid key mods (possibly OR'd together).
   15.43   */
   15.44  typedef enum
   15.45  {
    16.1 --- a/include/SDL_loadso.h	Sun Oct 18 23:21:15 2009 +0000
    16.2 +++ b/include/SDL_loadso.h	Mon Oct 19 13:31:58 2009 +0000
    16.3 @@ -21,22 +21,22 @@
    16.4  */
    16.5  
    16.6  /**
    16.7 - * \file SDL_loadso.h
    16.8 + *  \file SDL_loadso.h
    16.9   *
   16.10 - * System dependent library loading routines
   16.11 + *  System dependent library loading routines
   16.12   *
   16.13 - * Some things to keep in mind:                                        
   16.14 - * - These functions only work on C function names.  Other languages may
   16.15 - *   have name mangling and intrinsic language support that varies from
   16.16 - *   compiler to compiler.
   16.17 - * - Make sure you declare your function pointers with the same calling
   16.18 - *   convention as the actual library function.  Your code will crash
   16.19 - *   mysteriously if you do not do this.
   16.20 - * - Avoid namespace collisions.  If you load a symbol from the library,
   16.21 - *   it is not defined whether or not it goes into the global symbol
   16.22 - *   namespace for the application.  If it does and it conflicts with
   16.23 - *   symbols in your code or other shared libraries, you will not get
   16.24 - *   the results you expect. :)
   16.25 + *  Some things to keep in mind:                                        
   16.26 + *  \li These functions only work on C function names.  Other languages may
   16.27 + *      have name mangling and intrinsic language support that varies from
   16.28 + *      compiler to compiler.
   16.29 + *  \li Make sure you declare your function pointers with the same calling
   16.30 + *      convention as the actual library function.  Your code will crash
   16.31 + *      mysteriously if you do not do this.
   16.32 + *  \li Avoid namespace collisions.  If you load a symbol from the library,
   16.33 + *      it is not defined whether or not it goes into the global symbol
   16.34 + *      namespace for the application.  If it does and it conflicts with
   16.35 + *      symbols in your code or other shared libraries, you will not get
   16.36 + *      the results you expect. :)
   16.37   */
   16.38  
   16.39  #ifndef _SDL_loadso_h
   16.40 @@ -53,20 +53,24 @@
   16.41  /* *INDENT-ON* */
   16.42  #endif
   16.43  
   16.44 -/* This function dynamically loads a shared object and returns a pointer
   16.45 - * to the object handle (or NULL if there was an error).
   16.46 - * The 'sofile' parameter is a system dependent name of the object file.
   16.47 +/**
   16.48 + *  This function dynamically loads a shared object and returns a pointer
   16.49 + *  to the object handle (or NULL if there was an error).
   16.50 + *  The 'sofile' parameter is a system dependent name of the object file.
   16.51   */
   16.52  extern DECLSPEC void *SDLCALL SDL_LoadObject(const char *sofile);
   16.53  
   16.54 -/* Given an object handle, this function looks up the address of the
   16.55 - * named function in the shared object and returns it.  This address
   16.56 - * is no longer valid after calling SDL_UnloadObject().
   16.57 +/**
   16.58 + *  Given an object handle, this function looks up the address of the
   16.59 + *  named function in the shared object and returns it.  This address
   16.60 + *  is no longer valid after calling SDL_UnloadObject().
   16.61   */
   16.62  extern DECLSPEC void *SDLCALL SDL_LoadFunction(void *handle,
   16.63                                                 const char *name);
   16.64  
   16.65 -/* Unload a shared object from memory */
   16.66 +/**
   16.67 + *  Unload a shared object from memory.
   16.68 + */
   16.69  extern DECLSPEC void SDLCALL SDL_UnloadObject(void *handle);
   16.70  
   16.71  /* Ends C function definitions when using C++ */
    17.1 --- a/include/SDL_main.h	Sun Oct 18 23:21:15 2009 +0000
    17.2 +++ b/include/SDL_main.h	Mon Oct 19 13:31:58 2009 +0000
    17.3 @@ -25,7 +25,11 @@
    17.4  
    17.5  #include "SDL_stdinc.h"
    17.6  
    17.7 -/* Redefine main() on some platforms so that it is called by SDL */
    17.8 +/**
    17.9 + *  \file SDL_main.h
   17.10 + *  
   17.11 + *  Redefine main() on some platforms so that it is called by SDL.
   17.12 + */
   17.13  
   17.14  #if defined(__WIN32__) || \
   17.15      (defined(__MWERKS__) && !defined(__BEOS__)) || \
   17.16 @@ -37,18 +41,26 @@
   17.17  #define C_LINKAGE
   17.18  #endif /* __cplusplus */
   17.19  
   17.20 -/* The application's main() function must be called with C linkage,
   17.21 -   and should be declared like this:
   17.22 -#ifdef __cplusplus
   17.23 -extern "C"
   17.24 -#endif
   17.25 -	int main(int argc, char *argv[])
   17.26 -	{
   17.27 -	}
   17.28 +/**
   17.29 + *  \file SDL_main.h
   17.30 + *
   17.31 + *  The application's main() function must be called with C linkage,
   17.32 + *  and should be declared like this:
   17.33 + *  \code
   17.34 + *  #ifdef __cplusplus
   17.35 + *  extern "C"
   17.36 + *  #endif
   17.37 + *  int main(int argc, char *argv[])
   17.38 + *  {
   17.39 + *  }
   17.40 + *  \endcode
   17.41   */
   17.42 +
   17.43  #define main	SDL_main
   17.44  
   17.45 -/* The prototype for the application's main() function */
   17.46 +/**
   17.47 + *  The prototype for the application's main() function
   17.48 + */
   17.49  extern C_LINKAGE int SDL_main(int argc, char *argv[]);
   17.50  
   17.51  
   17.52 @@ -62,7 +74,9 @@
   17.53  /* *INDENT-ON* */
   17.54  #endif
   17.55  
   17.56 -/* This can be called to set the application class at startup */
   17.57 +/**
   17.58 + *  This can be called to set the application class at startup
   17.59 + */
   17.60  extern DECLSPEC int SDLCALL SDL_RegisterApp(char *name, Uint32 style,
   17.61                                              void *hInst);
   17.62  extern DECLSPEC void SDLCALL SDL_UnregisterApp(void);
    18.1 --- a/include/SDL_mouse.h	Sun Oct 18 23:21:15 2009 +0000
    18.2 +++ b/include/SDL_mouse.h	Mon Oct 19 13:31:58 2009 +0000
    18.3 @@ -21,9 +21,9 @@
    18.4  */
    18.5  
    18.6  /**
    18.7 - * \file SDL_mouse.h
    18.8 - *
    18.9 - * Include file for SDL mouse event handling
   18.10 + *  \file SDL_mouse.h
   18.11 + *  
   18.12 + *  Include file for SDL mouse event handling.
   18.13   */
   18.14  
   18.15  #ifndef _SDL_mouse_h
   18.16 @@ -46,129 +46,112 @@
   18.17  /* Function prototypes */
   18.18  
   18.19  /**
   18.20 - * \fn int SDL_GetNumMice(void)
   18.21 - *
   18.22 - * \brief Get the number of mouse input devices available.
   18.23 - *
   18.24 - * \sa SDL_SelectMouse()
   18.25 + *  \brief Get the number of mouse input devices available.
   18.26 + *  
   18.27 + *  \sa SDL_SelectMouse()
   18.28   */
   18.29  extern DECLSPEC int SDLCALL SDL_GetNumMice(void);
   18.30  
   18.31  /**
   18.32 - * \fn char* SDL_GetMouseName(int index)
   18.33 - *
   18.34 - * \brief Gets the name of a mouse with the given index.
   18.35 - *
   18.36 - * \param index is the index of the mouse, which name is to be returned.
   18.37 - *
   18.38 - * \return the name of the mouse with the specified index
   18.39 + *  \brief Gets the name of a mouse with the given index.
   18.40 + *  
   18.41 + *  \param index is the index of the mouse, which name is to be returned.
   18.42 + *  
   18.43 + *  \return the name of the mouse with the specified index
   18.44   */
   18.45  extern DECLSPEC char *SDLCALL SDL_GetMouseName(int index);
   18.46  
   18.47  /**
   18.48 - * \fn int SDL_SelectMouse(int index)
   18.49 - *
   18.50 - * \brief Set the index of the currently selected mouse.
   18.51 - *
   18.52 - * \return The index of the previously selected mouse.
   18.53 - *
   18.54 - * \note You can query the currently selected mouse by passing an index of -1.
   18.55 - *
   18.56 - * \sa SDL_GetNumMice()
   18.57 + *  \brief Set the index of the currently selected mouse.
   18.58 + *  
   18.59 + *  \return The index of the previously selected mouse.
   18.60 + *  
   18.61 + *  \note You can query the currently selected mouse by passing an index of -1.
   18.62 + *  
   18.63 + *  \sa SDL_GetNumMice()
   18.64   */
   18.65  extern DECLSPEC int SDLCALL SDL_SelectMouse(int index);
   18.66  
   18.67  /**
   18.68 - * \fn SDL_WindowID SDL_GetMouseFocusWindow(int index)
   18.69 - *
   18.70 - * \brief Get the window which currently has focus for the currently selected mouse.
   18.71 + *  \brief Get the window which currently has focus for the specified mouse.
   18.72   */
   18.73  extern DECLSPEC SDL_WindowID SDLCALL SDL_GetMouseFocusWindow(int index);
   18.74  
   18.75  /**
   18.76 - * \fn int SDL_SetRelativeMouseMode(int index, SDL_bool enabled)
   18.77 - *
   18.78 - * \brief Set relative mouse mode for the currently selected mouse.
   18.79 - *
   18.80 - * \param enabled Whether or not to enable relative mode
   18.81 - *
   18.82 - * \return 0 on success, or -1 if relative mode is not supported.
   18.83 - *
   18.84 - * While the mouse is in relative mode, the cursor is hidden, and the
   18.85 - * driver will try to report continuous motion in the current window.
   18.86 - * Only relative motion events will be delivered, the mouse position
   18.87 - * will not change.
   18.88 - *
   18.89 - * \note This function will flush any pending mouse motion.
   18.90 - *
   18.91 - * \sa SDL_GetRelativeMouseMode()
   18.92 + *  \brief Set relative mouse mode for the specified mouse.
   18.93 + *  
   18.94 + *  \param enabled Whether or not to enable relative mode
   18.95 + *  
   18.96 + *  \return 0 on success, or -1 if relative mode is not supported.
   18.97 + *  
   18.98 + *  While the mouse is in relative mode, the cursor is hidden, and the
   18.99 + *  driver will try to report continuous motion in the current window.
  18.100 + *  Only relative motion events will be delivered, the mouse position
  18.101 + *  will not change.
  18.102 + *  
  18.103 + *  \note This function will flush any pending mouse motion.
  18.104 + *  
  18.105 + *  \sa SDL_GetRelativeMouseMode()
  18.106   */
  18.107  extern DECLSPEC int SDLCALL SDL_SetRelativeMouseMode(int index,
  18.108                                                       SDL_bool enabled);
  18.109  
  18.110  /**
  18.111 - * \fn SDL_bool SDL_GetRelativeMouseMode(int index)
  18.112 - *
  18.113 - * \brief Query whether relative mouse mode is enabled for the currently selected mouse.
  18.114 - *
  18.115 - * \sa SDL_SetRelativeMouseMode()
  18.116 + *  \brief Query whether relative mouse mode is enabled for the specified mouse.
  18.117 + *  
  18.118 + *  \sa SDL_SetRelativeMouseMode()
  18.119   */
  18.120  extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(int index);
  18.121  
  18.122  /**
  18.123 - * \fn Uint8 SDL_GetMouseState(int index, int *x, int *y)
  18.124 - *
  18.125 - * \brief Retrieve the current state of the currently selected mouse.
  18.126 - *
  18.127 - * The current button state is returned as a button bitmask, which can
  18.128 - * be tested using the SDL_BUTTON(X) macros, and x and y are set to the
  18.129 - * mouse cursor position relative to the focus window for the currently
  18.130 - * selected mouse.  You can pass NULL for either x or y.
  18.131 + *  \brief Retrieve the current state of the specified mouse.
  18.132 + *  
  18.133 + *  The current button state is returned as a button bitmask, which can
  18.134 + *  be tested using the SDL_BUTTON(X) macros, and x and y are set to the
  18.135 + *  mouse cursor position relative to the focus window for the currently
  18.136 + *  selected mouse.  You can pass NULL for either x or y.
  18.137   */
  18.138  extern DECLSPEC Uint8 SDLCALL SDL_GetMouseState(int index, int *x, int *y);
  18.139  
  18.140  /**
  18.141 - * \fn Uint8 SDL_GetRelativeMouseState(int index, int *x, int *y)
  18.142 + *  \brief Retrieve the state of the specified mouse.
  18.143   *
  18.144 - * \brief Retrieve the state of the currently selected mouse.
  18.145 - *
  18.146 - * The current button state is returned as a button bitmask, which can
  18.147 - * be tested using the SDL_BUTTON(X) macros, and x and y are set to the
  18.148 - * mouse deltas since the last call to SDL_GetRelativeMouseState().
  18.149 + *  The current button state is returned as a button bitmask, which can
  18.150 + *  be tested using the SDL_BUTTON(X) macros, and x and y are set to the
  18.151 + *  mouse deltas since the last call to SDL_GetRelativeMouseState().
  18.152   */
  18.153  extern DECLSPEC Uint8 SDLCALL SDL_GetRelativeMouseState(int index, int *x,
  18.154                                                          int *y);
  18.155  
  18.156  /**
  18.157 - * \fn void SDL_WarpMouseInWindow(SDL_WindowID windowID, int x, int y)
  18.158 - *
  18.159 - * \brief Moves the currently selected mouse to the given position within the window.
  18.160 - *
  18.161 - * \param windowID The window to move the mouse into, or 0 for the current mouse focus
  18.162 - * \param x The x coordinate within the window
  18.163 - * \param y The y coordinate within the window
  18.164 - *
  18.165 - * \note This function generates a mouse motion event
  18.166 + *  \brief Moves the currently selected mouse to the given position within the window.
  18.167 + *  
  18.168 + *  \param windowID The window to move the mouse into, or 0 for the current mouse focus
  18.169 + *  \param x The x coordinate within the window
  18.170 + *  \param y The y coordinate within the window
  18.171 + *  
  18.172 + *  \note This function generates a mouse motion event
  18.173   */
  18.174  extern DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_WindowID windowID,
  18.175                                                     int x, int y);
  18.176  
  18.177  /**
  18.178 - * \fn SDL_Cursor *SDL_CreateCursor (const Uint8 * data, const Uint8 * mask, int w, int h, int hot_x, int hot_y)
  18.179 - *
  18.180 - * \brief Create a cursor for the currently selected mouse, using the
  18.181 - *        specified bitmap data and mask (in MSB format).
  18.182 - *
  18.183 - * The cursor width must be a multiple of 8 bits.
  18.184 - *
  18.185 - * The cursor is created in black and white according to the following:
  18.186 - * data  mask    resulting pixel on screen
  18.187 - *  0     1       White
  18.188 - *  1     1       Black
  18.189 - *  0     0       Transparent
  18.190 - *  1     0       Inverted color if possible, black if not.
  18.191 - *
  18.192 - * \sa SDL_FreeCursor()
  18.193 + *  \brief Create a cursor for the currently selected mouse, using the
  18.194 + *         specified bitmap data and mask (in MSB format).
  18.195 + *  
  18.196 + *  The cursor width must be a multiple of 8 bits.
  18.197 + *  
  18.198 + *  The cursor is created in black and white according to the following:
  18.199 + *  <table>
  18.200 + *  <tr><td> data </td><td> mask </td><td> resulting pixel on screen </td></tr>
  18.201 + *  <tr><td>  0   </td><td>  1   </td><td> White </td></tr>
  18.202 + *  <tr><td>  1   </td><td>  1   </td><td> Black </td></tr>
  18.203 + *  <tr><td>  0   </td><td>  0   </td><td> Transparent </td></tr>
  18.204 + *  <tr><td>  1   </td><td>  0   </td><td> Inverted color if possible, black 
  18.205 +                                           if not. </td></tr>
  18.206 + *  </table>
  18.207 + *  
  18.208 + *  \sa SDL_FreeCursor()
  18.209   */
  18.210  extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data,
  18.211                                                       const Uint8 * mask,
  18.212 @@ -176,78 +159,73 @@
  18.213                                                       int hot_y);
  18.214  
  18.215  /**
  18.216 - * \fn void SDL_SetCursor(SDL_Cursor * cursor)
  18.217 - *
  18.218 - * \brief Set the active cursor for the currently selected mouse.
  18.219 - *
  18.220 - * \note The cursor must have been created for the selected mouse.
  18.221 + *  \brief Set the active cursor for the currently selected mouse.
  18.222 + *  
  18.223 + *  \note The cursor must have been created for the selected mouse.
  18.224   */
  18.225  extern DECLSPEC void SDLCALL SDL_SetCursor(SDL_Cursor * cursor);
  18.226  
  18.227  /**
  18.228 - * \fn SDL_Cursor *SDL_GetCursor(void)
  18.229 - *
  18.230 - * \brief Return the active cursor for the currently selected mouse.
  18.231 + *  \brief Return the active cursor for the currently selected mouse.
  18.232   */
  18.233  extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetCursor(void);
  18.234  
  18.235  /**
  18.236 - * \fn void SDL_FreeCursor(SDL_Cursor * cursor)
  18.237 - *
  18.238 - * \brief Frees a cursor created with SDL_CreateCursor().
  18.239 - *
  18.240 - * \sa SDL_CreateCursor()
  18.241 + *  \brief Frees a cursor created with SDL_CreateCursor().
  18.242 + *  
  18.243 + *  \sa SDL_CreateCursor()
  18.244   */
  18.245  extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor * cursor);
  18.246  
  18.247  /**
  18.248 - * \fn int SDL_ShowCursor(int toggle)
  18.249 - *
  18.250 - * \brief Toggle whether or not the cursor is shown for the currently selected mouse.
  18.251 - *
  18.252 - * \param toggle 1 to show the cursor, 0 to hide it, -1 to query the current state.
  18.253 - *
  18.254 - * \return 1 if the cursor is shown, or 0 if the cursor is hidden.
  18.255 + *  \brief Toggle whether or not the cursor is shown for the currently selected 
  18.256 + *         mouse.
  18.257 + *  
  18.258 + *  \param toggle 1 to show the cursor, 0 to hide it, -1 to query the current 
  18.259 + *                state.
  18.260 + *  
  18.261 + *  \return 1 if the cursor is shown, or 0 if the cursor is hidden.
  18.262   */
  18.263  extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
  18.264  
  18.265 -/* Used as a mask when testing buttons in buttonstate
  18.266 -   Button 1:	Left mouse button
  18.267 -   Button 2:	Middle mouse button
  18.268 -   Button 3:	Right mouse button
  18.269 - */
  18.270 -
  18.271  /**
  18.272 - * \fn int SDL_GetCursorsNumber(int index)
  18.273 - *
  18.274 - * \brief Gets the number of cursors a pointing device supports.
  18.275 - * Useful for tablet users. Useful only under Windows.
  18.276 - *
  18.277 - * \param index is the index of the pointing device, which number of cursors we
  18.278 - * want to receive.
  18.279 - *
  18.280 - * \return the number of cursors supported by the pointing device. On Windows
  18.281 - * if a device is a tablet it returns a number >=1. Normal mice always return 1.
  18.282 - * On Linux every device reports one cursor.
  18.283 + *  \brief Gets the number of cursors a pointing device supports.
  18.284 + *  
  18.285 + *  Useful for tablet users. Useful only under Windows.
  18.286 + *  
  18.287 + *  \param index is the index of the pointing device, which number of cursors we
  18.288 + *               want to receive.
  18.289 + *  
  18.290 + *  \return the number of cursors supported by the pointing device. On Windows
  18.291 + *          if a device is a tablet it returns a number >=1. Normal mice always 
  18.292 + *          return 1.
  18.293 + *  
  18.294 + *  On Linux every device reports one cursor.
  18.295   */
  18.296  extern DECLSPEC int SDLCALL SDL_GetCursorsNumber(int index);
  18.297  
  18.298  /**
  18.299 - * \fn int SDL_GetCurrentCursor(int index)
  18.300 - *
  18.301 - * \brief Returns the index of the current cursor used by a specific pointing
  18.302 - * device. Useful only under Windows.
  18.303 - *
  18.304 - * \param index is the index of the pointing device, which cursor index we want
  18.305 - * to receive.
  18.306 - *
  18.307 - * \return the index of the cursor currently used by a specific pointing device.
  18.308 - * Always 0 under Linux. On Windows if the device isn't a tablet it returns 0.
  18.309 - * If the device is the tablet it returns the cursor index.
  18.310 - * 0 - stylus, 1 - eraser, 2 - cursor.
  18.311 + *  \brief Returns the index of the current cursor used by a specific pointing
  18.312 + *         device.
  18.313 + *  
  18.314 + *  Useful only under Windows.
  18.315 + *  
  18.316 + *  \param index is the index of the pointing device, which cursor index we want
  18.317 + *               to receive.
  18.318 + *  
  18.319 + *  \return the index of the cursor currently used by a specific pointing 
  18.320 + *          device.  Always 0 under Linux. On Windows if the device isn't a 
  18.321 + *          tablet it returns 0.  If the device is the tablet it returns the 
  18.322 + *          cursor index.  0 - stylus, 1 - eraser, 2 - cursor.
  18.323   */
  18.324  extern DECLSPEC int SDLCALL SDL_GetCurrentCursor(int index);
  18.325  
  18.326 +/**
  18.327 + *  Used as a mask when testing buttons in buttonstate.
  18.328 + *   - Button 1:  Left mouse button
  18.329 + *   - Button 2:  Middle mouse button
  18.330 + *   - Button 3:  Right mouse button
  18.331 + */
  18.332  #define SDL_BUTTON(X)		(1 << ((X)-1))
  18.333  #define SDL_BUTTON_LEFT		1
  18.334  #define SDL_BUTTON_MIDDLE	2
    19.1 --- a/include/SDL_mutex.h	Sun Oct 18 23:21:15 2009 +0000
    19.2 +++ b/include/SDL_mutex.h	Mon Oct 19 13:31:58 2009 +0000
    19.3 @@ -24,9 +24,9 @@
    19.4  #define _SDL_mutex_h
    19.5  
    19.6  /**
    19.7 - * \file SDL_mutex.h
    19.8 - *
    19.9 - * Functions to provide thread synchronization primitives
   19.10 + *  \file SDL_mutex.h
   19.11 + *  
   19.12 + *  Functions to provide thread synchronization primitives.
   19.13   */
   19.14  
   19.15  #include "SDL_stdinc.h"
   19.16 @@ -40,123 +40,176 @@
   19.17  /* *INDENT-ON* */
   19.18  #endif
   19.19  
   19.20 -/* Synchronization functions which can time out return this value
   19.21 -   if they time out.
   19.22 -*/
   19.23 +/**
   19.24 + *  Synchronization functions which can time out return this value
   19.25 + *  if they time out.
   19.26 + */
   19.27  #define SDL_MUTEX_TIMEDOUT	1
   19.28  
   19.29 -/* This is the timeout value which corresponds to never time out */
   19.30 +/**
   19.31 + *  This is the timeout value which corresponds to never time out.
   19.32 + */
   19.33  #define SDL_MUTEX_MAXWAIT	(~(Uint32)0)
   19.34  
   19.35  
   19.36 -/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   19.37 -/* Mutex functions                                               */
   19.38 -/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   19.39 +/**
   19.40 + *  \name Mutex functions
   19.41 + */
   19.42 +/*@{*/
   19.43  
   19.44  /* The SDL mutex structure, defined in SDL_mutex.c */
   19.45  struct SDL_mutex;
   19.46  typedef struct SDL_mutex SDL_mutex;
   19.47  
   19.48 -/* Create a mutex, initialized unlocked */
   19.49 +/**
   19.50 + *  Create a mutex, initialized unlocked.
   19.51 + */
   19.52  extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void);
   19.53  
   19.54 -/* Lock the mutex  (Returns 0, or -1 on error) */
   19.55 +/**
   19.56 + *  Lock the mutex.
   19.57 + *  
   19.58 + *  \return 0, or -1 on error.
   19.59 + */
   19.60  #define SDL_LockMutex(m)	SDL_mutexP(m)
   19.61  extern DECLSPEC int SDLCALL SDL_mutexP(SDL_mutex * mutex);
   19.62  
   19.63 -/* Unlock the mutex  (Returns 0, or -1 on error)
   19.64 -   It is an error to unlock a mutex that has not been locked by
   19.65 -   the current thread, and doing so results in undefined behavior.
   19.66 +/**
   19.67 + *  Unlock the mutex.
   19.68 + *  
   19.69 + *  \return 0, or -1 on error.
   19.70 + *  
   19.71 + *  \warning It is an error to unlock a mutex that has not been locked by
   19.72 + *           the current thread, and doing so results in undefined behavior.
   19.73   */
   19.74  #define SDL_UnlockMutex(m)	SDL_mutexV(m)
   19.75  extern DECLSPEC int SDLCALL SDL_mutexV(SDL_mutex * mutex);
   19.76  
   19.77 -/* Destroy a mutex */
   19.78 +/** 
   19.79 + *  Destroy a mutex.
   19.80 + */
   19.81  extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex * mutex);
   19.82  
   19.83 +/*@}*//*Mutex functions*/
   19.84  
   19.85 -/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   19.86 -/* Semaphore functions                                           */
   19.87 -/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   19.88 +
   19.89 +/**
   19.90 + *  \name Semaphore functions
   19.91 + */
   19.92 +/*@{*/
   19.93  
   19.94  /* The SDL semaphore structure, defined in SDL_sem.c */
   19.95  struct SDL_semaphore;
   19.96  typedef struct SDL_semaphore SDL_sem;
   19.97  
   19.98 -/* Create a semaphore, initialized with value, returns NULL on failure. */
   19.99 +/**
  19.100 + *  Create a semaphore, initialized with value, returns NULL on failure.
  19.101 + */
  19.102  extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
  19.103  
  19.104 -/* Destroy a semaphore */
  19.105 +/**
  19.106 + *  Destroy a semaphore.
  19.107 + */
  19.108  extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem);
  19.109  
  19.110 -/* This function suspends the calling thread until the semaphore pointed 
  19.111 - * to by sem has a positive count. It then atomically decreases the semaphore
  19.112 - * count.
  19.113 +/**
  19.114 + *  This function suspends the calling thread until the semaphore pointed 
  19.115 + *  to by \c sem has a positive count. It then atomically decreases the 
  19.116 + *  semaphore count.
  19.117   */
  19.118  extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem);
  19.119  
  19.120 -/* Non-blocking variant of SDL_SemWait(), returns 0 if the wait succeeds,
  19.121 -   SDL_MUTEX_TIMEDOUT if the wait would block, and -1 on error.
  19.122 -*/
  19.123 +/**
  19.124 + *  Non-blocking variant of SDL_SemWait().
  19.125 + *  
  19.126 + *  \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait would 
  19.127 + *          block, and -1 on error.
  19.128 + */
  19.129  extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem);
  19.130  
  19.131 -/* Variant of SDL_SemWait() with a timeout in milliseconds, returns 0 if
  19.132 -   the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait does not succeed in
  19.133 -   the allotted time, and -1 on error.
  19.134 -   On some platforms this function is implemented by looping with a delay
  19.135 -   of 1 ms, and so should be avoided if possible.
  19.136 -*/
  19.137 +/**
  19.138 + *  Variant of SDL_SemWait() with a timeout in milliseconds.
  19.139 + *  
  19.140 + *  \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait does not 
  19.141 + *          succeed in the allotted time, and -1 on error.
  19.142 + *  
  19.143 + *  \warning On some platforms this function is implemented by looping with a 
  19.144 + *           delay of 1 ms, and so should be avoided if possible.
  19.145 + */
  19.146  extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem * sem, Uint32 ms);
  19.147  
  19.148 -/* Atomically increases the semaphore's count (not blocking), returns 0,
  19.149 -   or -1 on error.
  19.150 +/**
  19.151 + *  Atomically increases the semaphore's count (not blocking).
  19.152 + *  
  19.153 + *  \return 0, or -1 on error.
  19.154   */
  19.155  extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem);
  19.156  
  19.157 -/* Returns the current count of the semaphore */
  19.158 +/**
  19.159 + *  Returns the current count of the semaphore.
  19.160 + */
  19.161  extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem * sem);
  19.162  
  19.163 +/*@}*//*Semaphore functions*/
  19.164  
  19.165 -/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  19.166 -/* Condition variable functions                                  */
  19.167 -/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  19.168 +
  19.169 +/**
  19.170 + *  \name Condition variable functions
  19.171 + */
  19.172 +/*@{*/
  19.173  
  19.174  /* The SDL condition variable structure, defined in SDL_cond.c */
  19.175  struct SDL_cond;
  19.176  typedef struct SDL_cond SDL_cond;
  19.177  
  19.178 -/* Create a condition variable */
  19.179 +/**
  19.180 + *  Create a condition variable.
  19.181 + */
  19.182  extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void);
  19.183  
  19.184 -/* Destroy a condition variable */
  19.185 +/**
  19.186 + *  Destroy a condition variable.
  19.187 + */
  19.188  extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * cond);
  19.189  
  19.190 -/* Restart one of the threads that are waiting on the condition variable,
  19.191 -   returns 0 or -1 on error.
  19.192 +/**
  19.193 + *  Restart one of the threads that are waiting on the condition variable.
  19.194 + *  
  19.195 + *  \return 0 or -1 on error.
  19.196   */
  19.197  extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * cond);
  19.198  
  19.199 -/* Restart all threads that are waiting on the condition variable,
  19.200 -   returns 0 or -1 on error.
  19.201 +/**
  19.202 + *  Restart all threads that are waiting on the condition variable.
  19.203 + *  \return 0 or -1 on error.
  19.204   */
  19.205  extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond);
  19.206  
  19.207 -/* Wait on the condition variable, unlocking the provided mutex.
  19.208 -   The mutex must be locked before entering this function!
  19.209 -   The mutex is re-locked once the condition variable is signaled.
  19.210 -   Returns 0 when it is signaled, or -1 on error.
  19.211 +/**
  19.212 + *  Wait on the condition variable, unlocking the provided mutex.
  19.213 + *  
  19.214 + *  \warning The mutex must be locked before entering this function!
  19.215 + *  
  19.216 + *  The mutex is re-locked once the condition variable is signaled.
  19.217 + *  
  19.218 + *  \return 0 when it is signaled, or -1 on error.
  19.219   */
  19.220  extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mut);
  19.221  
  19.222 -/* Waits for at most 'ms' milliseconds, and returns 0 if the condition
  19.223 -   variable is signaled, SDL_MUTEX_TIMEDOUT if the condition is not
  19.224 -   signaled in the allotted time, and -1 on error.
  19.225 -   On some platforms this function is implemented by looping with a delay
  19.226 -   of 1 ms, and so should be avoided if possible.
  19.227 -*/
  19.228 +/**
  19.229 + *  Waits for at most \c ms milliseconds, and returns 0 if the condition
  19.230 + *  variable is signaled, ::SDL_MUTEX_TIMEDOUT if the condition is not
  19.231 + *  signaled in the allotted time, and -1 on error.
  19.232 + *
  19.233 + *  \warning On some platforms this function is implemented by looping with a 
  19.234 + *           delay of 1 ms, and so should be avoided if possible.
  19.235 + */
  19.236  extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond * cond,
  19.237                                                  SDL_mutex * mutex, Uint32 ms);
  19.238  
  19.239 +/*@}*//*Condition variable functions*/
  19.240 +
  19.241 +
  19.242  /* Ends C function definitions when using C++ */
  19.243  #ifdef __cplusplus
  19.244  /* *INDENT-OFF* */
    20.1 --- a/include/SDL_opengl.h	Sun Oct 18 23:21:15 2009 +0000
    20.2 +++ b/include/SDL_opengl.h	Mon Oct 19 13:31:58 2009 +0000
    20.3 @@ -20,7 +20,11 @@
    20.4      slouken@libsdl.org
    20.5  */
    20.6  
    20.7 -/* This is a simple file to encapsulate the OpenGL API headers */
    20.8 +/**
    20.9 + *  \file SDL_opengl.h
   20.10 + *  
   20.11 + *  This is a simple file to encapsulate the OpenGL API headers.
   20.12 + */
   20.13  
   20.14  #ifndef _SDL_opengl_h
   20.15  #define _SDL_opengl_h
   20.16 @@ -49,11 +53,23 @@
   20.17  #undef __glext_h_
   20.18  #endif
   20.19  
   20.20 -/* This file is included because glext.h is not available on some systems.
   20.21 -   If you don't want this version included, simply define "NO_SDL_GLEXT"
   20.22 -   The latest version is available from:
   20.23 -	http://www.opengl.org/registry/
   20.24 +/**
   20.25 + *  \file SDL_opengl.h
   20.26 + *  
   20.27 + *  This file is included because glext.h is not available on some systems.
   20.28 + *  If you don't want this version included, simply define ::NO_SDL_GLEXT.
   20.29 + *  
   20.30 + *  The latest version is available from:
   20.31 + *  	http://www.opengl.org/registry/
   20.32   */
   20.33 +
   20.34 +/**
   20.35 + *  \def NO_SDL_GLEXT
   20.36 + *  
   20.37 + *  Define this if you have your own version of glext.h and want to disable the 
   20.38 + *  version included in SDL_opengl.h.
   20.39 + */
   20.40 +
   20.41  #if !defined(NO_SDL_GLEXT) && !defined(GL_GLEXT_LEGACY)
   20.42  /* *INDENT-OFF* */
   20.43  #ifndef __glext_h_
    21.1 --- a/include/SDL_opengles.h	Sun Oct 18 23:21:15 2009 +0000
    21.2 +++ b/include/SDL_opengles.h	Mon Oct 19 13:31:58 2009 +0000
    21.3 @@ -20,10 +20,13 @@
    21.4   slouken@libsdl.org
    21.5   */
    21.6  
    21.7 -/*
    21.8 -	This is a simple file to encapsulate the OpenGL ES API headers.
    21.9 -	Headers copied from The Kronos Group website.
   21.10 -	http://www.khronos.org/opengles/
   21.11 +/**
   21.12 + *  \file SDL_opengles.h
   21.13 + *  
   21.14 + *  This is a simple file to encapsulate the OpenGL ES API headers.
   21.15 + *  
   21.16 + *  Headers copied from The Kronos Group website.
   21.17 + *  	http://www.khronos.org/opengles/
   21.18   */
   21.19  
   21.20  #ifndef __gles_h_
    22.1 --- a/include/SDL_pixels.h	Sun Oct 18 23:21:15 2009 +0000
    22.2 +++ b/include/SDL_pixels.h	Mon Oct 19 13:31:58 2009 +0000
    22.3 @@ -21,9 +21,9 @@
    22.4  */
    22.5  
    22.6  /**
    22.7 - * \file SDL_pixels.h
    22.8 - *
    22.9 - * Header for the enumerated pixel format definitions
   22.10 + *  \file SDL_pixels.h
   22.11 + *  
   22.12 + *  Header for the enumerated pixel format definitions.
   22.13   */
   22.14  
   22.15  #ifndef _SDL_pixels_h
   22.16 @@ -37,12 +37,19 @@
   22.17  /* *INDENT-ON* */
   22.18  #endif
   22.19  
   22.20 -/* Transparency definitions: These define alpha as the opacity of a surface */
   22.21 +/**
   22.22 + *  \name Transparency definitions
   22.23 + *  
   22.24 + *  These define alpha as the opacity of a surface.
   22.25 + */
   22.26 +/*@{*/
   22.27  #define SDL_ALPHA_OPAQUE 255
   22.28  #define SDL_ALPHA_TRANSPARENT 0
   22.29 +/*@}*/
   22.30  
   22.31 +/** Pixel type. */
   22.32  enum
   22.33 -{                               /* Pixel type */
   22.34 +{
   22.35      SDL_PIXELTYPE_UNKNOWN,
   22.36      SDL_PIXELTYPE_INDEX1,
   22.37      SDL_PIXELTYPE_INDEX4,
   22.38 @@ -57,14 +64,17 @@
   22.39      SDL_PIXELTYPE_ARRAYF32
   22.40  };
   22.41  
   22.42 +/** Bitmap pixel order, high bit -> low bit. */
   22.43  enum
   22.44 -{                               /* bitmap pixel order, high bit -> low bit */
   22.45 +{
   22.46      SDL_BITMAPORDER_NONE,
   22.47      SDL_BITMAPORDER_4321,
   22.48      SDL_BITMAPORDER_1234
   22.49  };
   22.50 +
   22.51 +/** Packed component order, high bit -> low bit. */
   22.52  enum
   22.53 -{                               /* packed component order, high bit -> low bit */
   22.54 +{
   22.55      SDL_PACKEDORDER_NONE,
   22.56      SDL_PACKEDORDER_XRGB,
   22.57      SDL_PACKEDORDER_RGBX,
   22.58 @@ -75,8 +85,10 @@
   22.59      SDL_PACKEDORDER_ABGR,
   22.60      SDL_PACKEDORDER_BGRA
   22.61  };
   22.62 +
   22.63 +/** Array component order, low byte -> high byte. */
   22.64  enum
   22.65 -{                               /* array component order, low byte -> high byte */
   22.66 +{
   22.67      SDL_ARRAYORDER_NONE,
   22.68      SDL_ARRAYORDER_RGB,
   22.69      SDL_ARRAYORDER_RGBA,
   22.70 @@ -86,8 +98,9 @@
   22.71      SDL_ARRAYORDER_ABGR
   22.72  };
   22.73  
   22.74 +/** Packed component layout. */
   22.75  enum
   22.76 -{                               /* Packed component layout */
   22.77 +{
   22.78      SDL_PACKEDLAYOUT_NONE,
   22.79      SDL_PACKEDLAYOUT_332,
   22.80      SDL_PACKEDLAYOUT_4444,
   22.81 @@ -201,15 +214,15 @@
   22.82          SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB,
   22.83                                 SDL_PACKEDLAYOUT_2101010, 32, 4),
   22.84  
   22.85 -    SDL_PIXELFORMAT_YV12 =      /* Planar mode: Y + V + U  (3 planes) */
   22.86 +    SDL_PIXELFORMAT_YV12 =      /**< Planar mode: Y + V + U  (3 planes) */
   22.87          SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2'),
   22.88 -    SDL_PIXELFORMAT_IYUV =      /* Planar mode: Y + U + V  (3 planes) */
   22.89 +    SDL_PIXELFORMAT_IYUV =      /**< Planar mode: Y + U + V  (3 planes) */
   22.90          SDL_DEFINE_PIXELFOURCC('I', 'Y', 'U', 'V'),
   22.91 -    SDL_PIXELFORMAT_YUY2 =      /* Packed mode: Y0+U0+Y1+V0 (1 plane) */
   22.92 +    SDL_PIXELFORMAT_YUY2 =      /**< Packed mode: Y0+U0+Y1+V0 (1 plane) */
   22.93          SDL_DEFINE_PIXELFOURCC('Y', 'U', 'Y', '2'),
   22.94 -    SDL_PIXELFORMAT_UYVY =      /* Packed mode: U0+Y0+V0+Y1 (1 plane) */
   22.95 +    SDL_PIXELFORMAT_UYVY =      /**< Packed mode: U0+Y0+V0+Y1 (1 plane) */
   22.96          SDL_DEFINE_PIXELFOURCC('U', 'Y', 'V', 'Y'),
   22.97 -    SDL_PIXELFORMAT_YVYU =      /* Packed mode: Y0+V0+Y1+U0 (1 plane) */
   22.98 +    SDL_PIXELFORMAT_YVYU =      /**< Packed mode: Y0+V0+Y1+U0 (1 plane) */
   22.99          SDL_DEFINE_PIXELFOURCC('Y', 'V', 'Y', 'U')
  22.100  };
  22.101  
  22.102 @@ -241,7 +254,9 @@
  22.103      SDL_PaletteWatch *watch;
  22.104  };
  22.105  
  22.106 -/* Everything in the pixel format structure is read-only */
  22.107 +/**
  22.108 + *  \note Everything in the pixel format structure is read-only.
  22.109 + */
  22.110  typedef struct SDL_PixelFormat
  22.111  {
  22.112      SDL_Palette *palette;
  22.113 @@ -262,13 +277,11 @@
  22.114  } SDL_PixelFormat;
  22.115  
  22.116  /**
  22.117 - * \fn SDL_bool SDL_PixelFormatEnumToMasks(Uint32 format, int *bpp, Uint32 * Rmask, Uint32 * Gmask, Uint32 * Bmask, Uint32 * Amask)
  22.118 - *
  22.119 - * \brief Convert one of the enumerated pixel formats to a bpp and RGBA masks.
  22.120 - *
  22.121 - * \return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible.
  22.122 - *
  22.123 - * \sa SDL_MasksToPixelFormatEnum()
  22.124 + *  \brief Convert one of the enumerated pixel formats to a bpp and RGBA masks.
  22.125 + *  
  22.126 + *  \return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible.
  22.127 + *  
  22.128 + *  \sa SDL_MasksToPixelFormatEnum()
  22.129   */
  22.130  extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format,
  22.131                                                              int *bpp,
  22.132 @@ -278,13 +291,12 @@
  22.133                                                              Uint32 * Amask);
  22.134  
  22.135  /**
  22.136 - * \fn Uint32 SDL_MasksToPixelFormatEnum(int bpp, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask)
  22.137 - *
  22.138 - * \brief Convert a bpp and RGBA masks to an enumerated pixel format.
  22.139 - *
  22.140 - * \return The pixel format, or SDL_PixelFormat_Unknown if the conversion wasn't possible.
  22.141 - *
  22.142 - * \sa SDL_PixelFormatEnumToMasks()
  22.143 + *  \brief Convert a bpp and RGBA masks to an enumerated pixel format.
  22.144 + *  
  22.145 + *  \return The pixel format, or ::SDL_PIXELFORMAT_UNKNOWN if the conversion 
  22.146 + *          wasn't possible.
  22.147 + *  
  22.148 + *  \sa SDL_PixelFormatEnumToMasks()
  22.149   */
  22.150  extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
  22.151                                                            Uint32 Rmask,
  22.152 @@ -293,107 +305,87 @@
  22.153                                                            Uint32 Amask);
  22.154  
  22.155  /**
  22.156 - * \fn SDL_Palette *SDL_AllocPalette(int ncolors)
  22.157 - *
  22.158 - * \brief Create a palette structure with the specified number of color entries.
  22.159 - *
  22.160 - * \return A new palette, or NULL if there wasn't enough memory
  22.161 - *
  22.162 - * \note The palette entries are initialized to white.
  22.163 - *
  22.164 - * \sa SDL_FreePalette()
  22.165 + *  \brief Create a palette structure with the specified number of color 
  22.166 + *         entries.
  22.167 + *  
  22.168 + *  \return A new palette, or NULL if there wasn't enough memory.
  22.169 + *  
  22.170 + *  \note The palette entries are initialized to white.
  22.171 + *  
  22.172 + *  \sa SDL_FreePalette()
  22.173   */
  22.174  extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors);
  22.175  
  22.176  /**
  22.177 - * \fn int SDL_AddPaletteWatch(SDL_Palette *palette, SDL_PaletteChangedFunc callback, void *userdata)
  22.178 - *
  22.179 - * \brief Add a callback function which is called when the palette changes.
  22.180 - *
  22.181 - * \sa SDL_DelPaletteWatch()
  22.182 + *  \brief Add a callback function which is called when the palette changes.
  22.183 + *  
  22.184 + *  \sa SDL_DelPaletteWatch()
  22.185   */
  22.186  extern DECLSPEC int SDLCALL SDL_AddPaletteWatch(SDL_Palette * palette,
  22.187                                                  SDL_PaletteChangedFunc
  22.188                                                  callback, void *userdata);
  22.189  
  22.190  /**
  22.191 - * \fn void SDL_DelPaletteWatch(SDL_Palette *palette, SDL_PaletteChangedFunc callback, void *userdata)
  22.192 - *
  22.193 - * \brief Remove a callback function previously added with SDL_AddPaletteWatch()
  22.194 - *
  22.195 - * \sa SDL_AddPaletteWatch()
  22.196 + *  \brief Remove a callback function previously added with 
  22.197 + *         SDL_AddPaletteWatch().
  22.198 + *  
  22.199 + *  \sa SDL_AddPaletteWatch()
  22.200   */
  22.201  extern DECLSPEC void SDLCALL SDL_DelPaletteWatch(SDL_Palette * palette,
  22.202                                                   SDL_PaletteChangedFunc
  22.203                                                   callback, void *userdata);
  22.204  
  22.205  /**
  22.206 - * \fn int SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Colors *colors, int firstcolor, int numcolors)
  22.207 - *
  22.208 - * \brief Set a range of colors in a palette.
  22.209 - *
  22.210 - * \param palette The palette to modify
  22.211 - * \param colors An array of colors to copy into the palette
  22.212 - * \param firstcolor The index of the first palette entry to modify
  22.213 - * \param ncolors The number of entries to modify
  22.214 - *
  22.215 - * \return 0 on success, or -1 if not all of the colors could be set
  22.216 + *  \brief Set a range of colors in a palette.
  22.217 + *  
  22.218 + *  \param palette    The palette to modify.
  22.219 + *  \param colors     An array of colors to copy into the palette.
  22.220 + *  \param firstcolor The index of the first palette entry to modify.
  22.221 + *  \param ncolors    The number of entries to modify.
  22.222 + *  
  22.223 + *  \return 0 on success, or -1 if not all of the colors could be set.
  22.224   */
  22.225  extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette,
  22.226                                                   const SDL_Color * colors,
  22.227                                                   int firstcolor, int ncolors);
  22.228  
  22.229  /**
  22.230 - * \fn void SDL_FreePalette(SDL_Palette *palette)
  22.231 - *
  22.232 - * \brief Free a palette created with SDL_AllocPalette()
  22.233 - *
  22.234 - * \sa SDL_AllocPalette()
  22.235 + *  \brief Free a palette created with SDL_AllocPalette().
  22.236 + *  
  22.237 + *  \sa SDL_AllocPalette()
  22.238   */
  22.239  extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette);
  22.240  
  22.241  /**
  22.242 - * \fn Uint32 SDL_MapRGB(const SDL_PixelFormat *format,
  22.243 - *                       Uint8 r, Uint8 g, Uint8 b)
  22.244 - *
  22.245 - * \brief Maps an RGB triple to an opaque pixel value for a given pixel format
  22.246 - *
  22.247 - * \sa SDL_MapRGBA
  22.248 + *  \brief Maps an RGB triple to an opaque pixel value for a given pixel format.
  22.249 + *  
  22.250 + *  \sa SDL_MapRGBA
  22.251   */
  22.252  extern DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format,
  22.253                                            Uint8 r, Uint8 g, Uint8 b);
  22.254  
  22.255  /**
  22.256 - * \fn Uint32 SDL_MapRGBA(const SDL_PixelFormat *fmt,
  22.257 - *                        Uint8 r, Uint8 g, Uint8 b, Uint8 a)
  22.258 - *
  22.259 - * \brief Maps an RGBA quadruple to a pixel value for a given pixel format
  22.260 - *
  22.261 - * \sa SDL_MapRGB
  22.262 + *  \brief Maps an RGBA quadruple to a pixel value for a given pixel format.
  22.263 + *  
  22.264 + *  \sa SDL_MapRGB
  22.265   */
  22.266  extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format,
  22.267                                             Uint8 r, Uint8 g, Uint8 b,
  22.268                                             Uint8 a);
  22.269  
  22.270  /**
  22.271 - * \fn void SDL_GetRGB(Uint32 pixel, const SDL_PixelFormat * format,
  22.272 - *                     Uint8 * r, Uint8 * g, Uint8 * b)
  22.273 - *
  22.274 - * \brief Maps a pixel value into the RGB components for a given pixel format
  22.275 - *
  22.276 - * \sa SDL_GetRGBA
  22.277 + *  \brief Maps a pixel value into the RGB components for a given pixel format.
  22.278 + *  
  22.279 + *  \sa SDL_GetRGBA
  22.280   */
  22.281  extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
  22.282                                          const SDL_PixelFormat * format,
  22.283                                          Uint8 * r, Uint8 * g, Uint8 * b);
  22.284  
  22.285  /**
  22.286 - * \fn void SDL_GetRGBA(Uint32 pixel, const SDL_PixelFormat * format,
  22.287 - *                      Uint8 * r, Uint8 * g, Uint8 * b, Uint8 * a)
  22.288 - *
  22.289 - * \brief Maps a pixel value into the RGBA components for a given pixel format
  22.290 - *
  22.291 - * \sa SDL_GetRGB
  22.292 + *  \brief Maps a pixel value into the RGBA components for a given pixel format.
  22.293 + *  
  22.294 + *  \sa SDL_GetRGB
  22.295   */
  22.296  extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
  22.297                                           const SDL_PixelFormat * format,
    23.1 --- a/include/SDL_platform.h	Sun Oct 18 23:21:15 2009 +0000
    23.2 +++ b/include/SDL_platform.h	Mon Oct 19 13:31:58 2009 +0000
    23.3 @@ -20,7 +20,11 @@
    23.4      slouken@libsdl.org
    23.5  */
    23.6  
    23.7 -/* Try to get a standard set of platform defines */
    23.8 +/**
    23.9 + *  \file SDL_platform.h
   23.10 + *  
   23.11 + *  Try to get a standard set of platform defines.
   23.12 + */
   23.13  
   23.14  #ifndef _SDL_platform_h
   23.15  #define _SDL_platform_h
   23.16 @@ -133,8 +137,7 @@
   23.17  #endif
   23.18  
   23.19  /**
   23.20 - * \fn const char *SDL_GetPlatform(void)
   23.21 - * \brief Gets the name of the platform.
   23.22 + *  \brief Gets the name of the platform.
   23.23   */
   23.24  extern DECLSPEC const char * SDLCALL SDL_GetPlatform (void);
   23.25  
    24.1 --- a/include/SDL_power.h	Sun Oct 18 23:21:15 2009 +0000
    24.2 +++ b/include/SDL_power.h	Mon Oct 19 13:31:58 2009 +0000
    24.3 @@ -24,9 +24,9 @@
    24.4  #define _SDL_power_h
    24.5  
    24.6  /**
    24.7 - * \file SDL_power.h
    24.8 - *
    24.9 - * Header for the SDL power management routines
   24.10 + *  \file SDL_power.h
   24.11 + *  
   24.12 + *  Header for the SDL power management routines.
   24.13   */
   24.14  
   24.15  #include "SDL_stdinc.h"
   24.16 @@ -40,9 +40,7 @@
   24.17  #endif
   24.18  
   24.19  /**
   24.20 - * \enum SDL_PowerState
   24.21 - *
   24.22 - * \brief The basic state for the system's power supply.
   24.23 + *  \brief The basic state for the system's power supply.
   24.24   */
   24.25  typedef enum
   24.26  {
   24.27 @@ -55,19 +53,17 @@
   24.28  
   24.29  
   24.30  /**
   24.31 - * \fn int SDL_GetPowerInfo(void)
   24.32 - *
   24.33 - * \brief Get the current power supply details.
   24.34 - *
   24.35 - * \param secs Seconds of battery life left. You can pass a NULL here if
   24.36 - *                you don't care. Will return -1 if we can't determine a
   24.37 - *                value, or we're not running on a battery.
   24.38 - *
   24.39 - * \param pct Percentage of battery life left, between 0 and 100. You can
   24.40 - *                pass a NULL here if you don't care. Will return -1 if we
   24.41 - *                can't determine a value, or we're not running on a battery.
   24.42 - *
   24.43 - * \return The state of the battery (if any).
   24.44 + *  \brief Get the current power supply details.
   24.45 + *  
   24.46 + *  \param secs Seconds of battery life left. You can pass a NULL here if
   24.47 + *              you don't care. Will return -1 if we can't determine a
   24.48 + *              value, or we're not running on a battery.
   24.49 + *  
   24.50 + *  \param pct Percentage of battery life left, between 0 and 100. You can
   24.51 + *             pass a NULL here if you don't care. Will return -1 if we
   24.52 + *             can't determine a value, or we're not running on a battery.
   24.53 + *  
   24.54 + *  \return The state of the battery (if any).
   24.55   */
   24.56  extern DECLSPEC SDL_PowerState SDLCALL SDL_GetPowerInfo(int *secs, int *pct);
   24.57  
    25.1 --- a/include/SDL_quit.h	Sun Oct 18 23:21:15 2009 +0000
    25.2 +++ b/include/SDL_quit.h	Mon Oct 19 13:31:58 2009 +0000
    25.3 @@ -21,9 +21,9 @@
    25.4  */
    25.5  
    25.6  /**
    25.7 - * \file SDL_quit.h
    25.8 - *
    25.9 - * Include file for SDL quit event handling
   25.10 + *  \file SDL_quit.h
   25.11 + *  
   25.12 + *  Include file for SDL quit event handling.
   25.13   */
   25.14  
   25.15  #ifndef _SDL_quit_h
   25.16 @@ -32,22 +32,27 @@
   25.17  #include "SDL_stdinc.h"
   25.18  #include "SDL_error.h"
   25.19  
   25.20 -/* 
   25.21 -  An SDL_QUITEVENT is generated when the user tries to close the application
   25.22 -  window.  If it is ignored or filtered out, the window will remain open.
   25.23 -  If it is not ignored or filtered, it is queued normally and the window
   25.24 -  is allowed to close.  When the window is closed, screen updates will 
   25.25 -  complete, but have no effect.
   25.26 -
   25.27 -  SDL_Init() installs signal handlers for SIGINT (keyboard interrupt)
   25.28 -  and SIGTERM (system termination request), if handlers do not already
   25.29 -  exist, that generate SDL_QUITEVENT events as well.  There is no way
   25.30 -  to determine the cause of an SDL_QUITEVENT, but setting a signal
   25.31 -  handler in your application will override the default generation of
   25.32 -  quit events for that signal.
   25.33 -*/
   25.34 +/**
   25.35 + *  \file SDL_quit.h
   25.36 + *  
   25.37 + *  An ::SDL_QUIT event is generated when the user tries to close the application
   25.38 + *  window.  If it is ignored or filtered out, the window will remain open.
   25.39 + *  If it is not ignored or filtered, it is queued normally and the window
   25.40 + *  is allowed to close.  When the window is closed, screen updates will 
   25.41 + *  complete, but have no effect.
   25.42 + *
   25.43 + *  SDL_Init() installs signal handlers for SIGINT (keyboard interrupt)
   25.44 + *  and SIGTERM (system termination request), if handlers do not already
   25.45 + *  exist, that generate ::SDL_QUIT events as well.  There is no way
   25.46 + *  to determine the cause of an ::SDL_QUIT event, but setting a signal
   25.47 + *  handler in your application will override the default generation of
   25.48 + *  quit events for that signal.
   25.49 + *  
   25.50 + *  \sa SDL_Quit()
   25.51 + */
   25.52  
   25.53  /* There are no functions directly affecting the quit event */
   25.54 +
   25.55  #define SDL_QuitRequested() \
   25.56          (SDL_PumpEvents(), SDL_PeepEvents(NULL,0,SDL_PEEKEVENT,SDL_QUITMASK))
   25.57  
    26.1 --- a/include/SDL_rect.h	Sun Oct 18 23:21:15 2009 +0000
    26.2 +++ b/include/SDL_rect.h	Mon Oct 19 13:31:58 2009 +0000
    26.3 @@ -21,9 +21,9 @@
    26.4  */
    26.5  
    26.6  /**
    26.7 - * \file SDL_rect.h
    26.8 - *
    26.9 - * Header file for SDL_rect definition and management functions
   26.10 + *  \file SDL_rect.h
   26.11 + *  
   26.12 + *  Header file for SDL_rect definition and management functions.
   26.13   */
   26.14  
   26.15  #ifndef _SDL_rect_h
   26.16 @@ -43,15 +43,13 @@
   26.17  #endif
   26.18  
   26.19  /**
   26.20 - * \struct SDL_Rect
   26.21 - *
   26.22 - * \brief A rectangle, with the origin at the upper left.
   26.23 - *
   26.24 - * \sa SDL_RectEmpty
   26.25 - * \sa SDL_RectEquals
   26.26 - * \sa SDL_HasIntersection
   26.27 - * \sa SDL_IntersectRect
   26.28 - * \sa SDL_UnionRect
   26.29 + *  \brief A rectangle, with the origin at the upper left.
   26.30 + *  
   26.31 + *  \sa SDL_RectEmpty
   26.32 + *  \sa SDL_RectEquals
   26.33 + *  \sa SDL_HasIntersection
   26.34 + *  \sa SDL_IntersectRect
   26.35 + *  \sa SDL_UnionRect
   26.36   */
   26.37  typedef struct SDL_Rect
   26.38  {
   26.39 @@ -60,56 +58,44 @@
   26.40  } SDL_Rect;
   26.41  
   26.42  /**
   26.43 - * \def SDL_RectEmpty()
   26.44 - *
   26.45 - * \brief Returns true if the rectangle has no area.
   26.46 + *  \brief Returns true if the rectangle has no area.
   26.47   */
   26.48  #define SDL_RectEmpty(X)    (((X)->w <= 0) || ((X)->h <= 0))
   26.49  
   26.50  /**
   26.51 - * \def SDL_RectEquals()
   26.52 - *
   26.53 - * \brief Returns true if the two rectangles are equal.
   26.54 + *  \brief Returns true if the two rectangles are equal.
   26.55   */
   26.56  #define SDL_RectEquals(A, B)   (((A)->x == (B)->x) && ((A)->y == (B)->y) && \
   26.57                                  ((A)->w == (B)->w) && ((A)->h == (B)->h))
   26.58  
   26.59  /**
   26.60 - * \fn SDL_bool SDL_HasIntersection(const SDL_Rect * A, const SDL_Rect * B);
   26.61 - *
   26.62 - * \brief Determine whether two rectangles intersect.
   26.63 - *
   26.64 - * \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
   26.65 + *  \brief Determine whether two rectangles intersect.
   26.66 + *  
   26.67 + *  \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
   26.68   */
   26.69  extern DECLSPEC SDL_bool SDLCALL SDL_HasIntersection(const SDL_Rect * A,
   26.70                                                       const SDL_Rect * B);
   26.71  
   26.72  /**
   26.73 - * \fn SDL_bool SDL_IntersectRect(const SDL_Rect * A, const SDL_Rect * B, SDL_Rect * result)
   26.74 - *
   26.75 - * \brief Calculate the intersection of two rectangles.
   26.76 - *
   26.77 - * \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
   26.78 + *  \brief Calculate the intersection of two rectangles.
   26.79 + *  
   26.80 + *  \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
   26.81   */
   26.82  extern DECLSPEC SDL_bool SDLCALL SDL_IntersectRect(const SDL_Rect * A,
   26.83                                                     const SDL_Rect * B,
   26.84                                                     SDL_Rect * result);
   26.85  
   26.86  /**
   26.87 - * \fn void SDL_UnionRect(const SDL_Rect * A, const SDL_Rect * B, SDL_Rect * result)
   26.88 - *
   26.89 - * \brief Calculate the union of two rectangles
   26.90 + *  \brief Calculate the union of two rectangles.
   26.91   */
   26.92  extern DECLSPEC void SDLCALL SDL_UnionRect(const SDL_Rect * A,
   26.93                                             const SDL_Rect * B,
   26.94                                             SDL_Rect * result);
   26.95  
   26.96  /**
   26.97 - * \fn SDL_bool SDL_IntersectRectAndLine(const SDL_Rect *rect, int *X1, int *Y1, int *X2, int *Y2)
   26.98 - *
   26.99 - * \brief Calculate the intersection of a rectangle and line segment.
  26.100 - *
  26.101 - * \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
  26.102 + *  \brief Calculate the intersection of a rectangle and line segment.
  26.103 + *  
  26.104 + *  \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
  26.105   */
  26.106  extern DECLSPEC SDL_bool SDLCALL SDL_IntersectRectAndLine(const SDL_Rect *
  26.107                                                            rect, int *X1,
    27.1 --- a/include/SDL_rwops.h	Sun Oct 18 23:21:15 2009 +0000
    27.2 +++ b/include/SDL_rwops.h	Mon Oct 19 13:31:58 2009 +0000
    27.3 @@ -21,10 +21,10 @@
    27.4  */
    27.5  
    27.6  /**
    27.7 - * \file SDL_rwops.h
    27.8 - *
    27.9 - * This file provides a general interface for SDL to read and write
   27.10 - * data sources.  It can easily be extended to files, memory, etc.
   27.11 + *  \file SDL_rwops.h
   27.12 + *  
   27.13 + *  This file provides a general interface for SDL to read and write
   27.14 + *  data sources.  It can easily be extended to files, memory, etc.
   27.15   */
   27.16  
   27.17  #ifndef _SDL_rwops_h
   27.18 @@ -41,33 +41,42 @@
   27.19  /* *INDENT-ON* */
   27.20  #endif
   27.21  
   27.22 -/* This is the read/write operation structure -- very basic */
   27.23 -
   27.24 +/**
   27.25 + * This is the read/write operation structure -- very basic.
   27.26 + */
   27.27  typedef struct SDL_RWops
   27.28  {
   27.29 -    /* Seek to 'offset' relative to whence, one of stdio's whence values:
   27.30 -       RW_SEEK_SET, RW_SEEK_CUR, RW_SEEK_END
   27.31 -       Returns the final offset in the data source.
   27.32 +    /**
   27.33 +     *  Seek to \c offset relative to \c whence, one of stdio's whence values:
   27.34 +     *  RW_SEEK_SET, RW_SEEK_CUR, RW_SEEK_END
   27.35 +     *  
   27.36 +     *  \return the final offset in the data source.
   27.37       */
   27.38      long (SDLCALL * seek) (struct SDL_RWops * context, long offset,
   27.39                             int whence);
   27.40  
   27.41 -    /* Read up to 'num' objects each of size 'objsize' from the data
   27.42 -       source to the area pointed at by 'ptr'.
   27.43 -       Returns the number of objects read, or 0 at error or end of file.
   27.44 +    /**
   27.45 +     *  Read up to \c num objects each of size \c objsize from the data
   27.46 +     *  source to the area pointed at by \c ptr.
   27.47 +     *  
   27.48 +     *  \return the number of objects read, or 0 at error or end of file.
   27.49       */
   27.50 -      size_t(SDLCALL * read) (struct SDL_RWops * context, void *ptr,
   27.51 -                              size_t size, size_t maxnum);
   27.52 +    size_t(SDLCALL * read) (struct SDL_RWops * context, void *ptr,
   27.53 +                            size_t size, size_t maxnum);
   27.54  
   27.55 -    /* Write exactly 'num' objects each of size 'objsize' from the area
   27.56 -       pointed at by 'ptr' to data source.
   27.57 -       Returns the number of objects written, or 0 at error or end of file.
   27.58 +    /**
   27.59 +     *  Write exactly \c num objects each of size \c objsize from the area
   27.60 +     *  pointed at by \c ptr to data source.
   27.61 +     *  
   27.62 +     *  \return the number of objects written, or 0 at error or end of file.
   27.63       */
   27.64 -      size_t(SDLCALL * write) (struct SDL_RWops * context, const void *ptr,
   27.65 -                               size_t size, size_t num);
   27.66 +    size_t(SDLCALL * write) (struct SDL_RWops * context, const void *ptr,
   27.67 +                             size_t size, size_t num);
   27.68  
   27.69 -    /* Close and free an allocated SDL_RWops structure.
   27.70 -       Returns 0 if successful or -1 on write error when flushing data.
   27.71 +    /**
   27.72 +     *  Close and free an allocated SDL_RWops structure.
   27.73 +     *  
   27.74 +     *  \return 0 if successful or -1 on write error when flushing data.
   27.75       */
   27.76      int (SDLCALL * close) (struct SDL_RWops * context);
   27.77  
   27.78 @@ -109,7 +118,12 @@
   27.79  } SDL_RWops;
   27.80  
   27.81  
   27.82 -/* Functions to create SDL_RWops structures from various data sources */
   27.83 +/**
   27.84 + *  \name RWFrom functions
   27.85 + *  
   27.86 + *  Functions to create SDL_RWops structures from various data sources.
   27.87 + */
   27.88 +/*@{*/
   27.89  
   27.90  extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFile(const char *file,
   27.91                                                    const char *mode);
   27.92 @@ -123,36 +137,57 @@
   27.93  extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromConstMem(const void *mem,
   27.94                                                        int size);
   27.95  
   27.96 +/*@}*//*RWFrom functions*/
   27.97 +
   27.98 +
   27.99  extern DECLSPEC SDL_RWops *SDLCALL SDL_AllocRW(void);
  27.100  extern DECLSPEC void SDLCALL SDL_FreeRW(SDL_RWops * area);
  27.101  
  27.102 -#define RW_SEEK_SET	0       /* Seek from the beginning of data */
  27.103 -#define RW_SEEK_CUR	1       /* Seek relative to current read point */
  27.104 -#define RW_SEEK_END	2       /* Seek relative to the end of data */
  27.105 +#define RW_SEEK_SET	0       /**< Seek from the beginning of data */
  27.106 +#define RW_SEEK_CUR	1       /**< Seek relative to current read point */
  27.107 +#define RW_SEEK_END	2       /**< Seek relative to the end of data */
  27.108  
  27.109 -/* Macros to easily read and write from an SDL_RWops structure */
  27.110 +/**
  27.111 + *  \name Read/write macros
  27.112 + *  
  27.113 + *  Macros to easily read and write from an SDL_RWops structure.
  27.114 + */
  27.115 +/*@{*/
  27.116  #define SDL_RWseek(ctx, offset, whence)	(ctx)->seek(ctx, offset, whence)
  27.117  #define SDL_RWtell(ctx)			(ctx)->seek(ctx, 0, RW_SEEK_CUR)
  27.118  #define SDL_RWread(ctx, ptr, size, n)	(ctx)->read(ctx, ptr, size, n)
  27.119  #define SDL_RWwrite(ctx, ptr, size, n)	(ctx)->write(ctx, ptr, size, n)
  27.120  #define SDL_RWclose(ctx)		(ctx)->close(ctx)
  27.121 +/*@}*//*Read/write macros*/
  27.122  
  27.123  
  27.124 -/* Read an item of the specified endianness and return in native format */
  27.125 +/** 
  27.126 + *  \name Read endian functions
  27.127 + *  
  27.128 + *  Read an item of the specified endianness and return in native format.
  27.129 + */
  27.130 +/*@{*/
  27.131  extern DECLSPEC Uint16 SDLCALL SDL_ReadLE16(SDL_RWops * src);
  27.132  extern DECLSPEC Uint16 SDLCALL SDL_ReadBE16(SDL_RWops * src);
  27.133  extern DECLSPEC Uint32 SDLCALL SDL_ReadLE32(SDL_RWops * src);
  27.134  extern DECLSPEC Uint32 SDLCALL SDL_ReadBE32(SDL_RWops * src);
  27.135  extern DECLSPEC Uint64 SDLCALL SDL_ReadLE64(SDL_RWops * src);
  27.136  extern DECLSPEC Uint64 SDLCALL SDL_ReadBE64(SDL_RWops * src);
  27.137 +/*@}*//*Read endian functions*/
  27.138  
  27.139 -/* Write an item of native format to the specified endianness */
  27.140 +/** 
  27.141 + *  \name Write endian functions
  27.142 + *  
  27.143 + *  Write an item of native format to the specified endianness.
  27.144 + */
  27.145 +/*@{*/
  27.146  extern DECLSPEC size_t SDLCALL SDL_WriteLE16(SDL_RWops * dst, Uint16 value);
  27.147  extern DECLSPEC size_t SDLCALL SDL_WriteBE16(SDL_RWops * dst, Uint16 value);
  27.148  extern DECLSPEC size_t SDLCALL SDL_WriteLE32(SDL_RWops * dst, Uint32 value);
  27.149  extern DECLSPEC size_t SDLCALL SDL_WriteBE32(SDL_RWops * dst, Uint32 value);
  27.150  extern DECLSPEC size_t SDLCALL SDL_WriteLE64(SDL_RWops * dst, Uint64 value);
  27.151  extern DECLSPEC size_t SDLCALL SDL_WriteBE64(SDL_RWops * dst, Uint64 value);
  27.152 +/*@}*//*Write endian functions*/
  27.153  
  27.154  
  27.155  /* Ends C function definitions when using C++ */
    28.1 --- a/include/SDL_scancode.h	Sun Oct 18 23:21:15 2009 +0000
    28.2 +++ b/include/SDL_scancode.h	Mon Oct 19 13:31:58 2009 +0000
    28.3 @@ -21,7 +21,9 @@
    28.4  */
    28.5  
    28.6  /**
    28.7 - * \file SDL_scancode.h
    28.8 + *  \file SDL_scancode.h
    28.9 + *  
   28.10 + *  Defines keyboard scancodes.
   28.11   */
   28.12  
   28.13  #ifndef _SDL_scancode_h
   28.14 @@ -30,22 +32,25 @@
   28.15  #include "SDL_stdinc.h"
   28.16  
   28.17  /**
   28.18 - * \enum SDL_scancode
   28.19 - *
   28.20 - * \brief The SDL keyboard scancode representation.
   28.21 - *
   28.22 - * Values of this type are used to represent keyboard keys, among other places
   28.23 - * in the \link SDL_keysym::scancode key.keysym.scancode \endlink field of the
   28.24 - * SDL_Event structure.
   28.25 - *
   28.26 - * The values in this enumeration are based on the USB usage page standard:
   28.27 - * http://www.usb.org/developers/devclass_docs/Hut1_12.pdf
   28.28 + *  \brief The SDL keyboard scancode representation.
   28.29 + *  
   28.30 + *  Values of this type are used to represent keyboard keys, among other places
   28.31 + *  in the \link SDL_keysym::scancode key.keysym.scancode \endlink field of the
   28.32 + *  SDL_Event structure.
   28.33 + *  
   28.34 + *  The values in this enumeration are based on the USB usage page standard:
   28.35 + *  http://www.usb.org/developers/devclass_docs/Hut1_12.pdf
   28.36   */
   28.37  typedef enum
   28.38  {
   28.39      SDL_SCANCODE_UNKNOWN = 0,
   28.40  
   28.41 -    /* These values are from usage page 0x07 (USB keyboard page) */
   28.42 +    /** 
   28.43 +     *  \name Usage page 0x07
   28.44 +     *  
   28.45 +     *  These values are from usage page 0x07 (USB keyboard page).
   28.46 +     */
   28.47 +    /*@{*/
   28.48  
   28.49      SDL_SCANCODE_A = 4,
   28.50      SDL_SCANCODE_B = 5,
   28.51 @@ -95,11 +100,51 @@
   28.52      SDL_SCANCODE_EQUALS = 46,
   28.53      SDL_SCANCODE_LEFTBRACKET = 47,
   28.54      SDL_SCANCODE_RIGHTBRACKET = 48,
   28.55 -    SDL_SCANCODE_BACKSLASH = 49, /**< Located at the lower left of the return key on ISO keyboards and at the right end of the QWERTY row on ANSI keyboards. Produces REVERSE SOLIDUS (backslash) and VERTICAL LINE in a US layout, REVERSE SOLIDUS and VERTICAL LINE in a UK Mac layout, NUMBER SIGN and TILDE in a UK Windows layout, DOLLAR SIGN and POUND SIGN in a Swiss German layout, NUMBER SIGN and APOSTROPHE in a German layout, GRAVE ACCENT and POUND SIGN in a French Mac layout, and ASTERISK and MICRO SIGN in a French Windows layout. */
   28.56 -    SDL_SCANCODE_NONUSHASH = 50, /**< ISO USB keyboards actually use this code instead of 49 for the same key, but all OSes I've seen treat the two codes identically. So, as an implementor, unless your keyboard generates both of those codes and your OS treats them differently, you should generate SDL_SCANCODE_BACKSLASH instead of this code. As a user, you should not rely on this code because SDL will never generate it with most (all?) keyboards. */
   28.57 +    SDL_SCANCODE_BACKSLASH = 49, /**< Located at the lower left of the return 
   28.58 +                                  *   key on ISO keyboards and at the right end 
   28.59 +                                  *   of the QWERTY row on ANSI keyboards. 
   28.60 +                                  *   Produces REVERSE SOLIDUS (backslash) and 
   28.61 +                                  *   VERTICAL LINE in a US layout, REVERSE 
   28.62 +                                  *   SOLIDUS and VERTICAL LINE in a UK Mac 
   28.63 +                                  *   layout, NUMBER SIGN and TILDE in a UK 
   28.64 +                                  *   Windows layout, DOLLAR SIGN and POUND SIGN
   28.65 +                                  *   in a Swiss German layout, NUMBER SIGN and 
   28.66 +                                  *   APOSTROPHE in a German layout, GRAVE 
   28.67 +                                  *   ACCENT and POUND SIGN in a French Mac 
   28.68 +                                  *   layout, and ASTERISK and MICRO SIGN in a 
   28.69 +                                  *   French Windows layout.
   28.70 +                                  */
   28.71 +    SDL_SCANCODE_NONUSHASH = 50, /**< ISO USB keyboards actually use this code 
   28.72 +                                  *   instead of 49 for the same key, but all 
   28.73 +                                  *   OSes I've seen treat the two codes 
   28.74 +                                  *   identically. So, as an implementor, unless
   28.75 +                                  *   your keyboard generates both of those 
   28.76 +                                  *   codes and your OS treats them differently,
   28.77 +                                  *   you should generate SDL_SCANCODE_BACKSLASH
   28.78 +                                  *   instead of this code. As a user, you 
   28.79 +                                  *   should not rely on this code because SDL 
   28.80 +                                  *   will never generate it with most (all?) 
   28.81 +                                  *   keyboards. 
   28.82 +                                  */
   28.83      SDL_SCANCODE_SEMICOLON = 51,
   28.84      SDL_SCANCODE_APOSTROPHE = 52,
   28.85 -    SDL_SCANCODE_GRAVE = 53, /**< Located in the top left corner (on both ANSI and ISO keyboards). Produces GRAVE ACCENT and TILDE in a US Windows layout and in US and UK Mac layouts on ANSI keyboards, GRAVE ACCENT and NOT SIGN in a UK Windows layout, SECTION SIGN and PLUS-MINUS SIGN in US and UK Mac layouts on ISO keyboards, SECTION SIGN and DEGREE SIGN in a Swiss German layout (Mac: only on ISO keyboards), CIRCUMFLEX ACCENT and DEGREE SIGN in a German layout (Mac: only on ISO keyboards), SUPERSCRIPT TWO and TILDE in a French Windows layout, COMMERCIAL AT and NUMBER SIGN in a French Mac layout on ISO keyboards, and LESS-THAN SIGN and GREATER-THAN SIGN in a Swiss German, German, or French Mac layout on ANSI keyboards. */
   28.86 +    SDL_SCANCODE_GRAVE = 53, /**< Located in the top left corner (on both ANSI 
   28.87 +                              *   and ISO keyboards). Produces GRAVE ACCENT and 
   28.88 +                              *   TILDE in a US Windows layout and in US and UK 
   28.89 +                              *   Mac layouts on ANSI keyboards, GRAVE ACCENT 
   28.90 +                              *   and NOT SIGN in a UK Windows layout, SECTION 
   28.91 +                              *   SIGN and PLUS-MINUS SIGN in US and UK Mac 
   28.92 +                              *   layouts on ISO keyboards, SECTION SIGN and 
   28.93 +                              *   DEGREE SIGN in a Swiss German layout (Mac: 
   28.94 +                              *   only on ISO keyboards), CIRCUMFLEX ACCENT and 
   28.95 +                              *   DEGREE SIGN in a German layout (Mac: only on 
   28.96 +                              *   ISO keyboards), SUPERSCRIPT TWO and TILDE in a
   28.97 +                              *   French Windows layout, COMMERCIAL AT and 
   28.98 +                              *   NUMBER SIGN in a French Mac layout on ISO 
   28.99 +                              *   keyboards, and LESS-THAN SIGN and GREATER-THAN
  28.100 +                              *   SIGN in a Swiss German, German, or French Mac 
  28.101 +                              *   layout on ANSI keyboards.
  28.102 +                              */
  28.103      SDL_SCANCODE_COMMA = 54,
  28.104      SDL_SCANCODE_PERIOD = 55,
  28.105      SDL_SCANCODE_SLASH = 56,
  28.106 @@ -122,7 +167,8 @@
  28.107      SDL_SCANCODE_PRINTSCREEN = 70,
  28.108      SDL_SCANCODE_SCROLLLOCK = 71,
  28.109      SDL_SCANCODE_PAUSE = 72,
  28.110 -    SDL_SCANCODE_INSERT = 73, /**< insert on PC, help on some Mac keyboards (but does send code 73, not 117) */
  28.111 +    SDL_SCANCODE_INSERT = 73, /**< insert on PC, help on some Mac keyboards (but
  28.112 +                                   does send code 73, not 117) */
  28.113      SDL_SCANCODE_HOME = 74,
  28.114      SDL_SCANCODE_PAGEUP = 75,
  28.115      SDL_SCANCODE_DELETE = 76,
  28.116 @@ -133,7 +179,8 @@
  28.117      SDL_SCANCODE_DOWN = 81,
  28.118      SDL_SCANCODE_UP = 82,
  28.119  
  28.120 -    SDL_SCANCODE_NUMLOCKCLEAR = 83, /**< num lock on PC, clear on Mac keyboards */
  28.121 +    SDL_SCANCODE_NUMLOCKCLEAR = 83, /**< num lock on PC, clear on Mac keyboards 
  28.122 +                                     */
  28.123      SDL_SCANCODE_KP_DIVIDE = 84,
  28.124      SDL_SCANCODE_KP_MULTIPLY = 85,
  28.125      SDL_SCANCODE_KP_MINUS = 86,
  28.126 @@ -151,9 +198,20 @@
  28.127      SDL_SCANCODE_KP_0 = 98,
  28.128      SDL_SCANCODE_KP_PERIOD = 99,
  28.129  
  28.130 -    SDL_SCANCODE_NONUSBACKSLASH = 100, /**< This is the additional key that ISO keyboards have over ANSI ones, located between left shift and Y. Produces GRAVE ACCENT and TILDE in a US or UK Mac layout, REVERSE SOLIDUS (backslash) and VERTICAL LINE in a US or UK Windows layout, and LESS-THAN SIGN and GREATER-THAN SIGN in a Swiss German, German, or French layout. */
  28.131 +    SDL_SCANCODE_NONUSBACKSLASH = 100, /**< This is the additional key that ISO 
  28.132 +                                        *   keyboards have over ANSI ones, 
  28.133 +                                        *   located between left shift and Y. 
  28.134 +                                        *   Produces GRAVE ACCENT and TILDE in a
  28.135 +                                        *   US or UK Mac layout, REVERSE SOLIDUS
  28.136 +                                        *   (backslash) and VERTICAL LINE in a 
  28.137 +                                        *   US or UK Windows layout, and 
  28.138 +                                        *   LESS-THAN SIGN and GREATER-THAN SIGN
  28.139 +                                        *   in a Swiss German, German, or French
  28.140 +                                        *   layout. */
  28.141      SDL_SCANCODE_APPLICATION = 101, /**< windows contextual menu, compose */
  28.142 -    SDL_SCANCODE_POWER = 102, /**< The USB document says this is a status flag, not a physical key - but some Mac keyboards do have a power key. */
  28.143 +    SDL_SCANCODE_POWER = 102, /**< The USB document says this is a status flag, 
  28.144 +                               *   not a physical key - but some Mac keyboards 
  28.145 +                               *   do have a power key. */
  28.146      SDL_SCANCODE_KP_EQUALS = 103,
  28.147      SDL_SCANCODE_F13 = 104,
  28.148      SDL_SCANCODE_F14 = 105,
  28.149 @@ -172,7 +230,7 @@
  28.150      SDL_SCANCODE_MENU = 118,
  28.151      SDL_SCANCODE_SELECT = 119,
  28.152      SDL_SCANCODE_STOP = 120,
  28.153 -    SDL_SCANCODE_AGAIN = 121,   /*!< redo */
  28.154 +    SDL_SCANCODE_AGAIN = 121,   /**< redo */
  28.155      SDL_SCANCODE_UNDO = 122,
  28.156      SDL_SCANCODE_CUT = 123,
  28.157      SDL_SCANCODE_COPY = 124,
  28.158 @@ -188,7 +246,8 @@
  28.159      SDL_SCANCODE_KP_COMMA = 133,
  28.160      SDL_SCANCODE_KP_EQUALSAS400 = 134,
  28.161  
  28.162 -    SDL_SCANCODE_INTERNATIONAL1 = 135, /**< used on Asian keyboards, see footnotes in USB doc */
  28.163 +    SDL_SCANCODE_INTERNATIONAL1 = 135, /**< used on Asian keyboards, see 
  28.164 +                                            footnotes in USB doc */
  28.165      SDL_SCANCODE_INTERNATIONAL2 = 136,
  28.166      SDL_SCANCODE_INTERNATIONAL3 = 137, /**< Yen */
  28.167      SDL_SCANCODE_INTERNATIONAL4 = 138,
  28.168 @@ -276,9 +335,19 @@
  28.169      SDL_SCANCODE_RALT = 230, /**< alt gr, option */
  28.170      SDL_SCANCODE_RGUI = 231, /**< windows, command (apple), meta */
  28.171  
  28.172 -    SDL_SCANCODE_MODE = 257,    /* I'm not sure if this is really not covered by any of the above, but since there's a special KMOD_MODE for it I'm adding it here */
  28.173 +    SDL_SCANCODE_MODE = 257,    /**< I'm not sure if this is really not covered 
  28.174 +                                 *   by any of the above, but since there's a 
  28.175 +                                 *   special KMOD_MODE for it I'm adding it here
  28.176 +                                 */
  28.177 +    
  28.178 +    /*@}*//*Usage page 0x07*/
  28.179  
  28.180 -    /* These values are mapped from usage page 0x0C (USB consumer page) */
  28.181 +    /**
  28.182 +     *  \name Usage page 0x0C
  28.183 +     *  
  28.184 +     *  These values are mapped from usage page 0x0C (USB consumer page).
  28.185 +     */
  28.186 +    /*@{*/
  28.187  
  28.188      SDL_SCANCODE_AUDIONEXT = 258,
  28.189      SDL_SCANCODE_AUDIOPREV = 259,
  28.190 @@ -297,21 +366,32 @@
  28.191      SDL_SCANCODE_AC_STOP = 272,
  28.192      SDL_SCANCODE_AC_REFRESH = 273,
  28.193      SDL_SCANCODE_AC_BOOKMARKS = 274,
  28.194 +    
  28.195 +    /*@}*//*Usage page 0x0C*/
  28.196  
  28.197 -    /* These are values that Christian Walther added (for mac keyboard?) */
  28.198 +    /**
  28.199 +     *  \name Walther keys
  28.200 +     *  
  28.201 +     *  These are values that Christian Walther added (for mac keyboard?).
  28.202 +     */
  28.203 +    /*@{*/
  28.204  
  28.205      SDL_SCANCODE_BRIGHTNESSDOWN = 275,
  28.206      SDL_SCANCODE_BRIGHTNESSUP = 276,
  28.207 -    SDL_SCANCODE_DISPLAYSWITCH = 277, /**< display mirroring/dual display switch, video mode switch */
  28.208 +    SDL_SCANCODE_DISPLAYSWITCH = 277, /**< display mirroring/dual display 
  28.209 +                                           switch, video mode switch */
  28.210      SDL_SCANCODE_KBDILLUMTOGGLE = 278,
  28.211      SDL_SCANCODE_KBDILLUMDOWN = 279,
  28.212      SDL_SCANCODE_KBDILLUMUP = 280,
  28.213      SDL_SCANCODE_EJECT = 281,
  28.214      SDL_SCANCODE_SLEEP = 282,
  28.215 +    
  28.216 +    /*@}*//*Walther keys*/
  28.217  
  28.218 -    /* Add any other keys here */
  28.219 +    /* Add any other keys here. */
  28.220  
  28.221 -    SDL_NUM_SCANCODES = 512 /**< (not a key, just marks the number of scancodes for array bounds) */
  28.222 +    SDL_NUM_SCANCODES = 512 /**< not a key, just marks the number of scancodes 
  28.223 +                                 for array bounds */
  28.224  } SDL_scancode;
  28.225  
  28.226  #endif /* _SDL_scancode_h */
    29.1 --- a/include/SDL_stdinc.h	Sun Oct 18 23:21:15 2009 +0000
    29.2 +++ b/include/SDL_stdinc.h	Mon Oct 19 13:31:58 2009 +0000
    29.3 @@ -21,9 +21,9 @@
    29.4  */
    29.5  
    29.6  /**
    29.7 - * \file SDL_stdinc.h
    29.8 - *
    29.9 - * This is a general header that includes C language support
   29.10 + *  \file SDL_stdinc.h
   29.11 + *  
   29.12 + *  This is a general header that includes C language support.
   29.13   */
   29.14  
   29.15  #ifndef _SDL_stdinc_h
   29.16 @@ -79,12 +79,19 @@
   29.17  # include <iconv.h>
   29.18  #endif
   29.19  
   29.20 -/* The number of elements in an array */
   29.21 +/**
   29.22 + *  The number of elements in an array.
   29.23 + */
   29.24  #define SDL_arraysize(array)	(sizeof(array)/sizeof(array[0]))
   29.25  #define SDL_TABLESIZE(table)	SDL_arraysize(table)
   29.26  
   29.27 -/* Use proper C++ casts when compiled as C++ to be compatible with the option
   29.28 - -Wold-style-cast of GCC (and -Werror=old-style-cast in GCC 4.2 and above. */
   29.29 +/**
   29.30 + *  \name Cast operators
   29.31 + *  
   29.32 + *  Use proper C++ casts when compiled as C++ to be compatible with the option
   29.33 + *  -Wold-style-cast of GCC (and -Werror=old-style-cast in GCC 4.2 and above).
   29.34 + */
   29.35 +/*@{*/
   29.36  #ifdef __cplusplus
   29.37  #define SDL_reinterpret_cast(type, expression) reinterpret_cast<type>(expression)
   29.38  #define SDL_static_cast(type, expression) static_cast<type>(expression)
   29.39 @@ -92,8 +99,13 @@
   29.40  #define SDL_reinterpret_cast(type, expression) ((type)(expression))
   29.41  #define SDL_static_cast(type, expression) ((type)(expression))
   29.42  #endif
   29.43 +/*@}*//*Cast operators*/
   29.44  
   29.45 -/* Basic data types */
   29.46 +/**
   29.47 + *  \name Basic data types
   29.48 + */
   29.49 +/*@{*/
   29.50 +
   29.51  typedef enum
   29.52  {
   29.53      SDL_FALSE = 0,
   29.54 @@ -101,45 +113,37 @@
   29.55  } SDL_bool;
   29.56  
   29.57  /**
   29.58 - * \typedef Sint8
   29.59   * \brief A signed 8-bit integer type.
   29.60   */
   29.61  typedef int8_t Sint8;
   29.62  /**
   29.63 - * \typedef Uint8
   29.64   * \brief An unsigned 8-bit integer type.
   29.65   */
   29.66  typedef uint8_t Uint8;
   29.67  /**
   29.68 - * \typedef Sint16
   29.69   * \brief A signed 16-bit integer type.
   29.70   */
   29.71  typedef int16_t Sint16;
   29.72  /**
   29.73 - * \typedef Uint16
   29.74   * \brief An unsigned 16-bit integer type.
   29.75   */
   29.76  typedef uint16_t Uint16;
   29.77  /**
   29.78 - * \typedef Sint32
   29.79   * \brief A signed 32-bit integer type.
   29.80   */
   29.81  typedef int32_t Sint32;
   29.82  /**
   29.83 - * \typedef Uint32
   29.84   * \brief An unsigned 32-bit integer type.
   29.85   */
   29.86  typedef uint32_t Uint32;
   29.87  
   29.88  #ifdef SDL_HAS_64BIT_TYPE
   29.89  /**
   29.90 - * \typedef Sint64
   29.91   * \brief A signed 64-bit integer type.
   29.92   * \warning On platforms without any sort of 64-bit datatype, this is equivalent to Sint32!
   29.93   */
   29.94  typedef int64_t Sint64;
   29.95  /**
   29.96 - * \typedef Uint64
   29.97   * \brief An unsigned 64-bit integer type.
   29.98   * \warning On platforms without any sort of 64-bit datatype, this is equivalent to Uint32!
   29.99   */
  29.100 @@ -150,9 +154,12 @@
  29.101  typedef Uint32 Uint64;
  29.102  #endif
  29.103  
  29.104 -/* Make sure the types really have the right sizes */
  29.105 +/*@}*//*Basic data types*/
  29.106 +
  29.107 +
  29.108  #define SDL_COMPILE_TIME_ASSERT(name, x)               \
  29.109         typedef int SDL_dummy_ ## name[(x) * 2 - 1]
  29.110 +/** \cond */
  29.111  #ifndef DOXYGEN_SHOULD_IGNORE_THIS
  29.112  SDL_COMPILE_TIME_ASSERT(uint8, sizeof(Uint8) == 1);
  29.113  SDL_COMPILE_TIME_ASSERT(sint8, sizeof(Sint8) == 1);
  29.114 @@ -167,6 +174,7 @@
  29.115  SDL_COMPILE_TIME_ASSERT(sint64, sizeof(Sint64) == 8);
  29.116  #endif
  29.117  #endif /* DOXYGEN_SHOULD_IGNORE_THIS */
  29.118 +/** \endcond */
  29.119  
  29.120  /* Check to make sure enums are the size of ints, for structure packing.
  29.121     For both Watcom C/C++ and Borland C/C++ the compiler option that makes
  29.122 @@ -178,6 +186,7 @@
  29.123  #pragma enumsalwaysint on
  29.124  #endif
  29.125  
  29.126 +/** \cond */
  29.127  #ifndef DOXYGEN_SHOULD_IGNORE_THIS
  29.128  #ifndef __NINTENDODS__          /* TODO: include/SDL_stdinc.h:174: error: size of array 'SDL_dummy_enum' is negative */
  29.129  typedef enum
  29.130 @@ -188,6 +197,7 @@
  29.131  SDL_COMPILE_TIME_ASSERT(enum, sizeof(SDL_DUMMY_ENUM) == sizeof(int));
  29.132  #endif
  29.133  #endif /* DOXYGEN_SHOULD_IGNORE_THIS */
  29.134 +/** \endcond */
  29.135  
  29.136  #include "begin_code.h"
  29.137  /* Set up for C function definitions, even when using C++ */
  29.138 @@ -748,9 +758,10 @@
  29.139  extern DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf,
  29.140                                           size_t * inbytesleft, char **outbuf,
  29.141                                           size_t * outbytesleft);
  29.142 -/* This function converts a string between encodings in one pass, returning a
  29.143 -   string that must be freed with SDL_free() or NULL on error.
  29.144 -*/
  29.145 +/**
  29.146 + *  This function converts a string between encodings in one pass, returning a
  29.147 + *  string that must be freed with SDL_free() or NULL on error.
  29.148 + */
  29.149  extern DECLSPEC char *SDLCALL SDL_iconv_string(const char *tocode,
  29.150                                                 const char *fromcode,
  29.151                                                 const char *inbuf,
    30.1 --- a/include/SDL_surface.h	Sun Oct 18 23:21:15 2009 +0000
    30.2 +++ b/include/SDL_surface.h	Mon Oct 19 13:31:58 2009 +0000
    30.3 @@ -21,9 +21,9 @@
    30.4  */
    30.5  
    30.6  /**
    30.7 - * \file SDL_surface.h
    30.8 - *
    30.9 - * Header file for SDL_surface definition and management functions
   30.10 + *  \file SDL_surface.h
   30.11 + *  
   30.12 + *  Header file for ::SDL_surface definition and management functions.
   30.13   */
   30.14  
   30.15  #ifndef _SDL_surface_h
   30.16 @@ -42,21 +42,28 @@
   30.17  /* *INDENT-ON* */
   30.18  #endif
   30.19  
   30.20 -/** These are the currently supported flags for the SDL_surface
   30.21 - *  \internal Used internally (read-only) 
   30.22 +/**
   30.23 + *  \name Surface flags
   30.24 + *  
   30.25 + *  These are the currently supported flags for the ::SDL_surface.
   30.26 + *  
   30.27 + *  \internal
   30.28 + *  Used internally (read-only).
   30.29   */
   30.30  /*@{*/
   30.31  #define SDL_PREALLOC        0x00000001  /**< Surface uses preallocated memory */
   30.32  #define SDL_RLEACCEL        0x00000002  /**< Surface is RLE encoded */
   30.33 -/*@}*/
   30.34 +/*@}*//*Surface flags*/
   30.35  
   30.36 -/** Evaluates to true if the surface needs to be locked before access */
   30.37 +/**
   30.38 + *  Evaluates to true if the surface needs to be locked before access.
   30.39 + */
   30.40  #define SDL_MUSTLOCK(S)	(((S)->flags & SDL_RLEACCEL) != 0)
   30.41  
   30.42  /**
   30.43 - * \brief A collection of pixels used in software blitting
   30.44 + * \brief A collection of pixels used in software blitting.
   30.45   *
   30.46 - * \note  This structure should be treated as read-only, except for 'pixels',
   30.47 + * \note  This structure should be treated as read-only, except for \c pixels,
   30.48   *        which, if not NULL, contains the raw pixel data for the surface.
   30.49   */
   30.50  typedef struct SDL_Surface
   30.51 @@ -67,40 +74,42 @@
   30.52      int pitch;                  /**< Read-only */
   30.53      void *pixels;               /**< Read-write */
   30.54  
   30.55 -    /* Application data associated with the surfade */
   30.56 +    /** Application data associated with the surfade */
   30.57      void *userdata;             /**< Read-write */
   30.58  
   30.59 -    /* information needed for surfaces requiring locks */
   30.60 +    /** information needed for surfaces requiring locks */
   30.61      int locked;                 /**< Read-only */
   30.62      void *lock_data;            /**< Read-only */
   30.63  
   30.64 -    /* clipping information */
   30.65 +    /** clipping information */
   30.66      SDL_Rect clip_rect;         /**< Read-only */
   30.67  
   30.68 -    /* info for fast blit mapping to other surfaces */
   30.69 +    /** info for fast blit mapping to other surfaces */
   30.70      struct SDL_BlitMap *map;    /**< Private */
   30.71  
   30.72 -    /* format version, bumped at every change to invalidate blit maps */
   30.73 +    /** format version, bumped at every change to invalidate blit maps */
   30.74      unsigned int format_version;        /**< Private */
   30.75  
   30.76 -    /* Reference count -- used when freeing surface */
   30.77 +    /** Reference count -- used when freeing surface */
   30.78      int refcount;               /**< Read-mostly */
   30.79  } SDL_Surface;
   30.80  
   30.81  /**
   30.82 - * \brief The type of function used for surface blitting functions
   30.83 + * \brief The type of function used for surface blitting functions.
   30.84   */
   30.85  typedef int (*SDL_blit) (struct SDL_Surface * src, SDL_Rect * srcrect,
   30.86                           struct SDL_Surface * dst, SDL_Rect * dstrect);
   30.87  
   30.88  /**
   30.89 - * Allocate and free an RGB surface (must be called after SDL_SetVideoMode)
   30.90 - * If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
   30.91 - * If the depth is greater than 8 bits, the pixel format is set using the
   30.92 - * flags '[RGB]mask'.
   30.93 - * If the function runs out of memory, it will return NULL.
   30.94 - *
   30.95 - * \param flags The 'flags' are obsolete and should be set to 0.
   30.96 + *  Allocate and free an RGB surface (must be called after SDL_SetVideoMode).
   30.97 + *  
   30.98 + *  If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
   30.99 + *  If the depth is greater than 8 bits, the pixel format is set using the
  30.100 + *  flags '[RGB]mask'.
  30.101 + *  
  30.102 + *  If the function runs out of memory, it will return NULL.
  30.103 + *  
  30.104 + *  \param flags The \c flags are obsolete and should be set to 0.
  30.105   */
  30.106  extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface
  30.107      (Uint32 flags, int width, int height, int depth,
  30.108 @@ -117,387 +126,426 @@
  30.109  extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface);
  30.110  
  30.111  /**
  30.112 - * \brief Set the palette used by a surface.
  30.113 - *
  30.114 - * \return 0, or -1 if the surface format doesn't use a palette.
  30.115 - *
  30.116 - * \note A single palette can be shared with many surfaces.
  30.117 + *  \brief Set the palette used by a surface.
  30.118 + *  
  30.119 + *  \return 0, or -1 if the surface format doesn't use a palette.
  30.120 + *  
  30.121 + *  \note A single palette can be shared with many surfaces.
  30.122   */
  30.123  extern DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface * surface,
  30.124                                                    SDL_Palette * palette);
  30.125  
  30.126  /**
  30.127 - * \brief Sets up a surface for directly accessing the pixels.
  30.128 - *
  30.129 - * Between calls to SDL_LockSurface()/SDL_UnlockSurface(), you can write
  30.130 - * to and read from 'surface->pixels', using the pixel format stored in 
  30.131 - * 'surface->format'.  Once you are done accessing the surface, you should 
  30.132 - * use SDL_UnlockSurface() to release it.
  30.133 - *
  30.134 - * Not all surfaces require locking.  If SDL_MUSTLOCK(surface) evaluates
  30.135 - * to 0, then you can read and write to the surface at any time, and the
  30.136 - * pixel format of the surface will not change.
  30.137 - * 
  30.138 - * No operating system or library calls should be made between lock/unlock
  30.139 - * pairs, as critical system locks may be held during this time.
  30.140 - *
  30.141 - * SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked.
  30.142 - * 
  30.143 - * \sa SDL_UnlockSurface()
  30.144 + *  \brief Sets up a surface for directly accessing the pixels.
  30.145 + *  
  30.146 + *  Between calls to SDL_LockSurface() / SDL_UnlockSurface(), you can write
  30.147 + *  to and read from \c surface->pixels, using the pixel format stored in 
  30.148 + *  \c surface->format.  Once you are done accessing the surface, you should 
  30.149 + *  use SDL_UnlockSurface() to release it.
  30.150 + *  
  30.151 + *  Not all surfaces require locking.  If SDL_MUSTLOCK(surface) evaluates
  30.152 + *  to 0, then you can read and write to the surface at any time, and the
  30.153 + *  pixel format of the surface will not change.
  30.154 + *  
  30.155 + *  No operating system or library calls should be made between lock/unlock
  30.156 + *  pairs, as critical system locks may be held during this time.
  30.157 + *  
  30.158 + *  SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked.
  30.159 + *  
  30.160 + *  \sa SDL_UnlockSurface()
  30.161   */
  30.162  extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface);
  30.163  /** \sa SDL_LockSurface() */
  30.164  extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface);
  30.165  
  30.166  /**
  30.167 - * Load a surface from a seekable SDL data source (memory or file.)
  30.168 - * If 'freesrc' is non-zero, the source will be closed after being read.
  30.169 - * Returns the new surface, or NULL if there was an error.
  30.170 - * The new surface should be freed with SDL_FreeSurface().
  30.171 + *  Load a surface from a seekable SDL data source (memory or file).
  30.172 + *  
  30.173 + *  If \c freesrc is non-zero, the source will be closed after being read.
  30.174 + *  
  30.175 + *  The new surface should be freed with SDL_FreeSurface().
  30.176 + *  
  30.177 + *  \return the new surface, or NULL if there was an error.
  30.178   */
  30.179  extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src,
  30.180                                                      int freesrc);
  30.181  
  30.182 -/** Convenience macro -- load a surface from a file */
  30.183 +/**
  30.184 + *  Load a surface from a file.
  30.185 + *  
  30.186 + *  Convenience macro.
  30.187 + */
  30.188  #define SDL_LoadBMP(file)	SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
  30.189  
  30.190  /**
  30.191 - * Save a surface to a seekable SDL data source (memory or file.)
  30.192 - * If 'freedst' is non-zero, the source will be closed after being written.
  30.193 - * Returns 0 if successful or -1 if there was an error.
  30.194 + *  Save a surface to a seekable SDL data source (memory or file).
  30.195 + *  
  30.196 + *  If \c freedst is non-zero, the source will be closed after being written.
  30.197 + *  
  30.198 + *  \return 0 if successful or -1 if there was an error.
  30.199   */
  30.200  extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
  30.201      (SDL_Surface * surface, SDL_RWops * dst, int freedst);
  30.202  
  30.203 -/** Convenience macro -- save a surface to a file */
  30.204 +/** 
  30.205 + *  Save a surface to a file.
  30.206 + *  
  30.207 + *  Convenience macro.
  30.208 + */
  30.209  #define SDL_SaveBMP(surface, file) \
  30.210  		SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
  30.211  
  30.212  /**
  30.213 - * \brief Sets the RLE acceleration hint for a surface.
  30.214 - *
  30.215 - * \return 0 on success, or -1 if the surface is not valid
  30.216 - *
  30.217 - * \note If RLE is enabled, colorkey and alpha blending blits are much faster,
  30.218 - *       but the surface must be locked before directly accessing the pixels.
  30.219 + *  \brief Sets the RLE acceleration hint for a surface.
  30.220 + *  
  30.221 + *  \return 0 on success, or -1 if the surface is not valid
  30.222 + *  
  30.223 + *  \note If RLE is enabled, colorkey and alpha blending blits are much faster,
  30.224 + *        but the surface must be locked before directly accessing the pixels.
  30.225   */
  30.226  extern DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface * surface,
  30.227                                                int flag);
  30.228  
  30.229  /**
  30.230 - * \brief Sets the color key (transparent pixel) in a blittable surface.
  30.231 - *
  30.232 - * \param surface The surface to update
  30.233 - * \param flag Non-zero to enable colorkey and 0 to disable colorkey 
  30.234 - * \param key The transparent pixel in the native surface format
  30.235 - *
  30.236 - * \return 0 on success, or -1 if the surface is not valid
  30.237 + *  \brief Sets the color key (transparent pixel) in a blittable surface.
  30.238 + *  
  30.239 + *  \param surface The surface to update
  30.240 + *  \param flag Non-zero to enable colorkey and 0 to disable colorkey 
  30.241 + *  \param key The transparent pixel in the native surface format
  30.242 + *  
  30.243 + *  \return 0 on success, or -1 if the surface is not valid
  30.244   */
  30.245  extern DECLSPEC int SDLCALL SDL_SetColorKey(SDL_Surface * surface,
  30.246                                              Uint32 flag, Uint32 key);
  30.247  
  30.248  /**
  30.249 - * \brief Sets the color key (transparent pixel) in a blittable surface.
  30.250 - *
  30.251 - * \param surface The surface to update
  30.252 - * \param key A pointer filled in with the transparent pixel in the native surface format
  30.253 - *
  30.254 - * \return 0 on success, or -1 if the surface is not valid or colorkey is not enabled.
  30.255 + *  \brief Sets the color key (transparent pixel) in a blittable surface.
  30.256 + *  
  30.257 + *  \param surface The surface to update
  30.258 + *  \param key A pointer filled in with the transparent pixel in the native 
  30.259 + *             surface format
  30.260 + *  
  30.261 + *  \return 0 on success, or -1 if the surface is not valid or colorkey is not 
  30.262 + *          enabled.
  30.263   */
  30.264  extern DECLSPEC int SDLCALL SDL_GetColorKey(SDL_Surface * surface,
  30.265                                              Uint32 * key);
  30.266  
  30.267  /**
  30.268 - * \brief Set an additional color value used in blit operations
  30.269 - *
  30.270 - * \param surface The surface to update
  30.271 - * \param r The red source color value multiplied into blit operations
  30.272 - * \param g The green source color value multiplied into blit operations
  30.273 - * \param b The blue source color value multiplied into blit operations
  30.274 - *
  30.275 - * \return 0 on success, or -1 if the surface is not valid
  30.276 - *
  30.277 - * \sa SDL_GetSurfaceColorMod()
  30.278 + *  \brief Set an additional color value used in blit operations.
  30.279 + *  
  30.280 + *  \param surface The surface to update.
  30.281 + *  \param r The red source color value multiplied into blit operations.
  30.282 + *  \param g The green source color value multiplied into blit operations.
  30.283 + *  \param b The blue source color value multiplied into blit operations.
  30.284 + *  
  30.285 + *  \return 0 on success, or -1 if the surface is not valid.
  30.286 + *  
  30.287 + *  \sa SDL_GetSurfaceColorMod()
  30.288   */
  30.289  extern DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface * surface,
  30.290                                                     Uint8 r, Uint8 g, Uint8 b);
  30.291  
  30.292  
  30.293  /**
  30.294 - * \brief Get the additional color value used in blit operations
  30.295 - *
  30.296 - * \param surface The surface to query
  30.297 - * \param r A pointer filled in with the source red color value
  30.298 - * \param g A pointer filled in with the source green color value
  30.299 - * \param b A pointer filled in with the source blue color value
  30.300 - *
  30.301 - * \return 0 on success, or -1 if the surface is not valid
  30.302 - *
  30.303 - * \sa SDL_SetSurfaceColorMod()
  30.304 + *  \brief Get the additional color value used in blit operations.
  30.305 + *  
  30.306 + *  \param surface The surface to query.
  30.307 + *  \param r A pointer filled in with the source red color value.
  30.308 + *  \param g A pointer filled in with the source green color value.
  30.309 + *  \param b A pointer filled in with the source blue color value.
  30.310 + *  
  30.311 + *  \return 0 on success, or -1 if the surface is not valid.
  30.312 + *  
  30.313 + *  \sa SDL_SetSurfaceColorMod()
  30.314   */
  30.315  extern DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface * surface,
  30.316                                                     Uint8 * r, Uint8 * g,
  30.317                                                     Uint8 * b);
  30.318  
  30.319  /**
  30.320 - * \brief Set an additional alpha value used in blit operations
  30.321 - *
  30.322 - * \param surface The surface to update
  30.323 - * \param alpha The source alpha value multiplied into blit operations.
  30.324 - *
  30.325 - * \return 0 on success, or -1 if the surface is not valid
  30.326 - *
  30.327 - * \sa SDL_GetSurfaceAlphaMod()
  30.328 + *  \brief Set an additional alpha value used in blit operations.
  30.329 + *  
  30.330 + *  \param surface The surface to update.
  30.331 + *  \param alpha The source alpha value multiplied into blit operations.
  30.332 + *  
  30.333 + *  \return 0 on success, or -1 if the surface is not valid.
  30.334 + *  
  30.335 + *  \sa SDL_GetSurfaceAlphaMod()
  30.336   */
  30.337  extern DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface * surface,
  30.338                                                     Uint8 alpha);
  30.339  
  30.340  /**
  30.341 - * \brief Get the additional alpha value used in blit operations
  30.342 - *
  30.343 - * \param surface The surface to query
  30.344 - * \param alpha A pointer filled in with the source alpha value
  30.345 - *
  30.346 - * \return 0 on success, or -1 if the surface is not valid
  30.347 - *
  30.348 - * \sa SDL_SetSurfaceAlphaMod()
  30.349 + *  \brief Get the additional alpha value used in blit operations.
  30.350 + *  
  30.351 + *  \param surface The surface to query.
  30.352 + *  \param alpha A pointer filled in with the source alpha value.
  30.353 + *  
  30.354 + *  \return 0 on success, or -1 if the surface is not valid.
  30.355 + *  
  30.356 + *  \sa SDL_SetSurfaceAlphaMod()
  30.357   */
  30.358  extern DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface * surface,
  30.359                                                     Uint8 * alpha);
  30.360  
  30.361  /**
  30.362 - * \brief Set the blend mode used for blit operations
  30.363 - *
  30.364 - * \param surface The surface to update
  30.365 - * \param blendMode SDL_TextureBlendMode to use for blit blending
  30.366 - *
  30.367 - * \return 0 on success, or -1 if the parameters are not valid
  30.368 - *
  30.369 - * \sa SDL_GetSurfaceBlendMode()
  30.370 + *  \brief Set the blend mode used for blit operations.
  30.371 + *  
  30.372 + *  \param surface The surface to update.
  30.373 + *  \param blendMode ::SDL_BlendMode to use for blit blending.
  30.374 + *  
  30.375 + *  \return 0 on success, or -1 if the parameters are not valid.
  30.376 + *  
  30.377 + *  \sa SDL_GetSurfaceBlendMode()
  30.378   */
  30.379  extern DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface * surface,
  30.380                                                      int blendMode);
  30.381  
  30.382  /**
  30.383 - * \brief Get the blend mode used for blit operations
  30.384 - *
  30.385 - * \param surface The surface to query
  30.386 - * \param blendMode A pointer filled in with the current blend mode
  30.387 - *
  30.388 - * \return 0 on success, or -1 if the surface is not valid
  30.389 - *
  30.390 - * \sa SDL_SetSurfaceBlendMode()
  30.391 + *  \brief Get the blend mode used for blit operations.
  30.392 + *  
  30.393 + *  \param surface   The surface to query.
  30.394 + *  \param blendMode A pointer filled in with the current blend mode.
  30.395 + *  
  30.396 + *  \return 0 on success, or -1 if the surface is not valid.
  30.397 + *  
  30.398 + *  \sa SDL_SetSurfaceBlendMode()
  30.399   */
  30.400  extern DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface * surface,
  30.401                                                      int *blendMode);
  30.402  
  30.403  /**
  30.404 - * \brief Set the scale mode used for blit operations
  30.405 - *
  30.406 - * \param surface The surface to update
  30.407 - * \param scaleMode SDL_TextureScaleMode to use for blit scaling
  30.408 - *
  30.409 - * \return 0 on success, or -1 if the surface is not valid or the scale mode is not supported
  30.410 - *
  30.411 - * \note If the scale mode is not supported, the closest supported mode is chosen.  Currently only SDL_TEXTURESCALEMODE_FAST is supported on surfaces.
  30.412 - *
  30.413 - * \sa SDL_GetSurfaceScaleMode()
  30.414 + *  \brief Set the scale mode used for blit operations.
  30.415 + *  
  30.416 + *  \param surface   The surface to update.
  30.417 + *  \param scaleMode ::SDL_TextureScaleMode to use for blit scaling.
  30.418 + *  
  30.419 + *  \return 0 on success, or -1 if the surface is not valid or the scale mode is
  30.420 + *          not supported.
  30.421 + *  
  30.422 + *  \note If the scale mode is not supported, the closest supported mode is 
  30.423 + *        chosen.  Currently only ::SDL_TEXTURESCALEMODE_FAST is supported on 
  30.424 + *        surfaces.
  30.425 + *  
  30.426 + *  \sa SDL_GetSurfaceScaleMode()
  30.427   */
  30.428  extern DECLSPEC int SDLCALL SDL_SetSurfaceScaleMode(SDL_Surface * surface,
  30.429                                                      int scaleMode);
  30.430  
  30.431  /**
  30.432 - * \brief Get the scale mode used for blit operations
  30.433 - *
  30.434 - * \param surface The surface to query
  30.435 - * \param scaleMode A pointer filled in with the current scale mode
  30.436 - *
  30.437 - * \return 0 on success, or -1 if the surface is not valid
  30.438 - *
  30.439 - * \sa SDL_SetSurfaceScaleMode()
  30.440 + *  \brief Get the scale mode used for blit operations.
  30.441 + *  
  30.442 + *  \param surface   The surface to query.
  30.443 + *  \param scaleMode A pointer filled in with the current scale mode.
  30.444 + *  
  30.445 + *  \return 0 on success, or -1 if the surface is not valid.
  30.446 + *  
  30.447 + *  \sa SDL_SetSurfaceScaleMode()
  30.448   */
  30.449  extern DECLSPEC int SDLCALL SDL_GetSurfaceScaleMode(SDL_Surface * surface,
  30.450                                                      int *scaleMode);
  30.451  
  30.452  /**
  30.453 - * Sets the clipping rectangle for the destination surface in a blit.
  30.454 - *
  30.455 - * If the clip rectangle is NULL, clipping will be disabled.
  30.456 - * If the clip rectangle doesn't intersect the surface, the function will
  30.457 - * return SDL_FALSE and blits will be completely clipped.  Otherwise the
  30.458 - * function returns SDL_TRUE and blits to the surface will be clipped to
  30.459 - * the intersection of the surface area and the clipping rectangle.
  30.460 - *
  30.461 - * Note that blits are automatically clipped to the edges of the source
  30.462 - * and destination surfaces.
  30.463 + *  Sets the clipping rectangle for the destination surface in a blit.
  30.464 + *  
  30.465 + *  If the clip rectangle is NULL, clipping will be disabled.
  30.466 + *  
  30.467 + *  If the clip rectangle doesn't intersect the surface, the function will
  30.468 + *  return SDL_FALSE and blits will be completely clipped.  Otherwise the
  30.469 + *  function returns SDL_TRUE and blits to the surface will be clipped to
  30.470 + *  the intersection of the surface area and the clipping rectangle.
  30.471 + *  
  30.472 + *  Note that blits are automatically clipped to the edges of the source
  30.473 + *  and destination surfaces.
  30.474   */
  30.475  extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface,
  30.476                                                   const SDL_Rect * rect);
  30.477  
  30.478  /**
  30.479 - * Gets the clipping rectangle for the destination surface in a blit.
  30.480 - * 'rect' must be a pointer to a valid rectangle which will be filled
  30.481 - * with the correct values.
  30.482 + *  Gets the clipping rectangle for the destination surface in a blit.
  30.483 + *  
  30.484 + *  \c rect must be a pointer to a valid rectangle which will be filled
  30.485 + *  with the correct values.
  30.486   */
  30.487  extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface * surface,
  30.488                                               SDL_Rect * rect);
  30.489  
  30.490  /**
  30.491 - * Creates a new surface of the specified format, and then copies and maps 
  30.492 - * the given surface to it so the blit of the converted surface will be as 
  30.493 - * fast as possible.  If this function fails, it returns NULL.
  30.494 - *
  30.495 - * The 'flags' parameter is passed to SDL_CreateRGBSurface() and has those 
  30.496 - * semantics.  You can also pass SDL_RLEACCEL in the flags parameter and
  30.497 - * SDL will try to RLE accelerate colorkey and alpha blits in the resulting
  30.498 - * surface.
  30.499 - *
  30.500 - * This function is used internally by SDL_DisplayFormat().
  30.501 + *  Creates a new surface of the specified format, and then copies and maps 
  30.502 + *  the given surface to it so the blit of the converted surface will be as 
  30.503 + *  fast as possible.  If this function fails, it returns NULL.
  30.504 + *  
  30.505 + *  The \c flags parameter is passed to SDL_CreateRGBSurface() and has those 
  30.506 + *  semantics.  You can also pass ::SDL_RLEACCEL in the flags parameter and
  30.507 + *  SDL will try to RLE accelerate colorkey and alpha blits in the resulting
  30.508 + *  surface.
  30.509 + *  
  30.510 + *  This function is used internally by SDL_DisplayFormat().
  30.511   */
  30.512  extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface
  30.513      (SDL_Surface * src, SDL_PixelFormat * fmt, Uint32 flags);
  30.514  
  30.515  /**
  30.516 - * This function draws a point with 'color'
  30.517 - * The color should be a pixel of the format used by the surface, and 
  30.518 - * can be generated by the SDL_MapRGB() function.
  30.519 - * \return This function returns 0 on success, or -1 on error.
  30.520 + *  Draws a point with \c color.
  30.521 + *
  30.522 + *  The color should be a pixel of the format used by the surface, and 
  30.523 + *  can be generated by the SDL_MapRGB() function.
  30.524 + *  
  30.525 + *  \return 0 on success, or -1 on error.
  30.526   */
  30.527  extern DECLSPEC int SDLCALL SDL_DrawPoint
  30.528      (SDL_Surface * dst, int x, int y, Uint32 color);
  30.529  
  30.530  /**
  30.531 - * This function blends a point with an RGBA value
  30.532 - * The color should be a pixel of the format used by the surface, and 
  30.533 - * can be generated by the SDL_MapRGB() function.
  30.534 - * \return This function returns 0 on success, or -1 on error.
  30.535 + *  Blends a point with an RGBA value.
  30.536 + *  
  30.537 + *  The color should be a pixel of the format used by the surface, and 
  30.538 + *  can be generated by the SDL_MapRGB() function.
  30.539 + *  
  30.540 + *  \return 0 on success, or -1 on error.
  30.541   */
  30.542  extern DECLSPEC int SDLCALL SDL_BlendPoint
  30.543      (SDL_Surface * dst, int x, int y, int blendMode,
  30.544       Uint8 r, Uint8 g, Uint8 b, Uint8 a);
  30.545  
  30.546  /**
  30.547 - * This function draws a line with 'color'
  30.548 - * The color should be a pixel of the format used by the surface, and 
  30.549 - * can be generated by the SDL_MapRGB() function.
  30.550 - * \return This function returns 0 on success, or -1 on error.
  30.551 + *  Draws a line with \c color.
  30.552 + *  
  30.553 + *  The color should be a pixel of the format used by the surface, and 
  30.554 + *  can be generated by the SDL_MapRGB() function.
  30.555 + *  
  30.556 + *  \return 0 on success, or -1 on error.
  30.557   */
  30.558  extern DECLSPEC int SDLCALL SDL_DrawLine
  30.559      (SDL_Surface * dst, int x1, int y1, int x2, int y2, Uint32 color);
  30.560  
  30.561  /**
  30.562 - * This function blends an RGBA value along a line
  30.563 - * \return This function returns 0 on success, or -1 on error.
  30.564 + *  Blends an RGBA value along a line.
  30.565 + *  
  30.566 + *  \return 0 on success, or -1 on error.
  30.567   */
  30.568  extern DECLSPEC int SDLCALL SDL_BlendLine
  30.569      (SDL_Surface * dst, int x1, int y1, int x2, int y2, int blendMode,
  30.570       Uint8 r, Uint8 g, Uint8 b, Uint8 a);
  30.571  
  30.572  /**
  30.573 - * This function performs a fast fill of the given rectangle with 'color'
  30.574 - * The given rectangle is clipped to the destination surface clip area
  30.575 - * and the final fill rectangle is saved in the passed in pointer.
  30.576 - * If 'dstrect' is NULL, the whole surface will be filled with 'color'
  30.577 - * The color should be a pixel of the format used by the surface, and 
  30.578 - * can be generated by the SDL_MapRGB() function.
  30.579 - * \return This function returns 0 on success, or -1 on error.
  30.580 + *  Performs a fast fill of the given rectangle with \c color.
  30.581 + *  
  30.582 + *  The given rectangle is clipped to the destination surface clip area
  30.583 + *  and the final fill rectangle is saved in the passed in pointer.
  30.584 + *  
  30.585 + *  If \c dstrect is NULL, the whole surface will be filled with \c color.
  30.586 + *  
  30.587 + *  The color should be a pixel of the format used by the surface, and 
  30.588 + *  can be generated by the SDL_MapRGB() function.
  30.589 + *  
  30.590 + *  \return 0 on success, or -1 on error.
  30.591   */
  30.592  extern DECLSPEC int SDLCALL SDL_FillRect
  30.593      (SDL_Surface * dst, SDL_Rect * dstrect, Uint32 color);
  30.594  
  30.595  /**
  30.596 - * This function blends an RGBA value into the given rectangle.
  30.597 - * The given rectangle is clipped to the destination surface clip area
  30.598 - * and the final fill rectangle is saved in the passed in pointer.
  30.599 - * If 'dstrect' is NULL, the whole surface will be filled with 'color'
  30.600 - * \return This function returns 0 on success, or -1 on error.
  30.601 + *  Blends an RGBA value into the given rectangle.
  30.602 + *  
  30.603 + *  The given rectangle is clipped to the destination surface clip area
  30.604 + *  and the final fill rectangle is saved in the passed in pointer.
  30.605 + *  
  30.606 + *  If \c dstrect is NULL, the whole surface will be filled with \c color.
  30.607 + *  
  30.608 + *  \return This function returns 0 on success, or -1 on error.
  30.609   */
  30.610  extern DECLSPEC int SDLCALL SDL_BlendRect
  30.611      (SDL_Surface * dst, SDL_Rect * dstrect, int blendMode, Uint8 r, Uint8 g,
  30.612       Uint8 b, Uint8 a);
  30.613  
  30.614  /**
  30.615 - * This performs a fast blit from the source surface to the destination
  30.616 - * surface.  It assumes that the source and destination rectangles are
  30.617 - * the same size.  If either 'srcrect' or 'dstrect' are NULL, the entire
  30.618 - * surface (src or dst) is copied.  The final blit rectangles are saved
  30.619 - * in 'srcrect' and 'dstrect' after all clipping is performed.
  30.620 - * If the blit is successful, it returns 0, otherwise it returns -1.
  30.621 + *  Performs a fast blit from the source surface to the destination surface.
  30.622 + *  
  30.623 + *  This assumes that the source and destination rectangles are
  30.624 + *  the same size.  If either \c srcrect or \c dstrect are NULL, the entire
  30.625 + *  surface (\c src or \c dst) is copied.  The final blit rectangles are saved
  30.626 + *  in \c srcrect and \c dstrect after all clipping is performed.
  30.627 + *  
  30.628 + *  \return If the blit is successful, it returns 0, otherwise it returns -1.
  30.629   *
  30.630 - * The blit function should not be called on a locked surface.
  30.631 + *  The blit function should not be called on a locked surface.
  30.632   *
  30.633 - * The blit semantics for surfaces with and without alpha and colorkey
  30.634 - * are defined as follows:
  30.635 - *
  30.636 - * RGBA->RGB:
  30.637 - *     SDL_SRCALPHA set:
  30.638 - * 	alpha-blend (using alpha-channel).
  30.639 - * 	SDL_SRCCOLORKEY ignored.
  30.640 - *     SDL_SRCALPHA not set:
  30.641 - * 	copy RGB.
  30.642 - * 	if SDL_SRCCOLORKEY set, only copy the pixels matching the
  30.643 - * 	RGB values of the source colour key, ignoring alpha in the
  30.644 - * 	comparison.
  30.645 - * 
  30.646 - * RGB->RGBA:
  30.647 - *     SDL_SRCALPHA set:
  30.648 - * 	alpha-blend (using the source per-surface alpha value);
  30.649 - * 	set destination alpha to opaque.
  30.650 - *     SDL_SRCALPHA not set:
  30.651 - * 	copy RGB, set destination alpha to source per-surface alpha value.
  30.652 - *     both:
  30.653 - * 	if SDL_SRCCOLORKEY set, only copy the pixels matching the
  30.654 - * 	source colour key.
  30.655 - * 
  30.656 - * RGBA->RGBA:
  30.657 - *     SDL_SRCALPHA set:
  30.658 - * 	alpha-blend (using the source alpha channel) the RGB values;
  30.659 - * 	leave destination alpha untouched. [Note: is this correct?]
  30.660 - * 	SDL_SRCCOLORKEY ignored.
  30.661 - *     SDL_SRCALPHA not set:
  30.662 - * 	copy all of RGBA to the destination.
  30.663 - * 	if SDL_SRCCOLORKEY set, only copy the pixels matching the
  30.664 - * 	RGB values of the source colour key, ignoring alpha in the
  30.665 - * 	comparison.
  30.666 - * 
  30.667 - * RGB->RGB: 
  30.668 - *     SDL_SRCALPHA set:
  30.669 - * 	alpha-blend (using the source per-surface alpha value).
  30.670 - *     SDL_SRCALPHA not set:
  30.671 - * 	copy RGB.
  30.672 - *     both:
  30.673 - * 	if SDL_SRCCOLORKEY set, only copy the pixels matching the
  30.674 - * 	source colour key.
  30.675 - *
  30.676 - * If either of the surfaces were in video memory, and the blit returns -2,
  30.677 - * the video memory was lost, so it should be reloaded with artwork and 
  30.678 - * re-blitted:
  30.679 - * @code
  30.680 - *	while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
  30.681 - *		while ( SDL_LockSurface(image) < 0 )
  30.682 - *			Sleep(10);
  30.683 - *		-- Write image pixels to image->pixels --
  30.684 - *		SDL_UnlockSurface(image);
  30.685 - *	}
  30.686 - * @endcode
  30.687 - *
  30.688 - * This happens under DirectX 5.0 when the system switches away from your
  30.689 - * fullscreen application.  The lock will also fail until you have access
  30.690 - * to the video memory again.
  30.691 - *
  30.692 - * You should call SDL_BlitSurface() unless you know exactly how SDL
  30.693 - * blitting works internally and how to use the other blit functions.
  30.694 + *  The blit semantics for surfaces with and without alpha and colorkey
  30.695 + *  are defined as follows:
  30.696 + *  \verbatim
  30.697 +    RGBA->RGB:
  30.698 +      SDL_SRCALPHA set:
  30.699 +        alpha-blend (using alpha-channel).
  30.700 +        SDL_SRCCOLORKEY ignored.
  30.701 +      SDL_SRCALPHA not set:
  30.702 +        copy RGB.
  30.703 +        if SDL_SRCCOLORKEY set, only copy the pixels matching the
  30.704 +        RGB values of the source colour key, ignoring alpha in the
  30.705 +        comparison.
  30.706 +   
  30.707 +    RGB->RGBA:
  30.708 +      SDL_SRCALPHA set:
  30.709 +        alpha-blend (using the source per-surface alpha value);
  30.710 +        set destination alpha to opaque.
  30.711 +      SDL_SRCALPHA not set:
  30.712 +        copy RGB, set destination alpha to source per-surface alpha value.
  30.713 +      both:
  30.714 +        if SDL_SRCCOLORKEY set, only copy the pixels matching the
  30.715 +        source colour key.
  30.716 +   
  30.717 +    RGBA->RGBA:
  30.718 +      SDL_SRCALPHA set:
  30.719 +        alpha-blend (using the source alpha channel) the RGB values;
  30.720 +        leave destination alpha untouched. [Note: is this correct?]
  30.721 +        SDL_SRCCOLORKEY ignored.
  30.722 +      SDL_SRCALPHA not set:
  30.723 +        copy all of RGBA to the destination.
  30.724 +        if SDL_SRCCOLORKEY set, only copy the pixels matching the
  30.725 +        RGB values of the source colour key, ignoring alpha in the
  30.726 +       comparison.
  30.727 +   
  30.728 +    RGB->RGB: 
  30.729 +      SDL_SRCALPHA set:
  30.730 +        alpha-blend (using the source per-surface alpha value).
  30.731 +      SDL_SRCALPHA not set:
  30.732 +        copy RGB.
  30.733 +      both:
  30.734 +        if SDL_SRCCOLORKEY set, only copy the pixels matching the
  30.735 +        source colour key.
  30.736 +    \endverbatim
  30.737 + *  
  30.738 + *  If either of the surfaces were in video memory, and the blit returns -2,
  30.739 + *  the video memory was lost, so it should be reloaded with artwork and 
  30.740 + *  re-blitted:
  30.741 + *  @code
  30.742 + *  while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
  30.743 + *      while ( SDL_LockSurface(image) < 0 )
  30.744 + *          Sleep(10);
  30.745 + *      -- Write image pixels to image->pixels --
  30.746 + *      SDL_UnlockSurface(image);
  30.747 + *  }
  30.748 + *  @endcode
  30.749 + *  
  30.750 + *  This happens under DirectX 5.0 when the system switches away from your
  30.751 + *  fullscreen application.  The lock will also fail until you have access
  30.752 + *  to the video memory again.
  30.753 + *  
  30.754 + *  You should call SDL_BlitSurface() unless you know exactly how SDL
  30.755 + *  blitting works internally and how to use the other blit functions.
  30.756   */
  30.757  #define SDL_BlitSurface SDL_UpperBlit
  30.758  
  30.759 -/** This is the public blit function, SDL_BlitSurface(), and it performs
  30.760 +/**
  30.761 + *  This is the public blit function, SDL_BlitSurface(), and it performs
  30.762   *  rectangle validation and clipping before passing it to SDL_LowerBlit()
  30.763   */
  30.764  extern DECLSPEC int SDLCALL SDL_UpperBlit
  30.765      (SDL_Surface * src, SDL_Rect * srcrect,
  30.766       SDL_Surface * dst, SDL_Rect * dstrect);
  30.767  
  30.768 -/** This is a semi-private blit function and it performs low-level surface
  30.769 +/**
  30.770 + *  This is a semi-private blit function and it performs low-level surface
  30.771   *  blitting only.
  30.772   */
  30.773  extern DECLSPEC int SDLCALL SDL_LowerBlit
  30.774 @@ -505,9 +553,10 @@
  30.775       SDL_Surface * dst, SDL_Rect * dstrect);
  30.776  
  30.777  /**
  30.778 - * \brief Perform a fast, low quality, stretch blit between two surfaces of the same pixel format.
  30.779 - *
  30.780 - * \note This function uses a static buffer, and is not thread-safe.
  30.781 + *  \brief Perform a fast, low quality, stretch blit between two surfaces of the
  30.782 + *         same pixel format.
  30.783 + *  
  30.784 + *  \note This function uses a static buffer, and is not thread-safe.
  30.785   */
  30.786  extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src,
  30.787                                              const SDL_Rect * srcrect,
    31.1 --- a/include/SDL_syswm.h	Sun Oct 18 23:21:15 2009 +0000
    31.2 +++ b/include/SDL_syswm.h	Mon Oct 19 13:31:58 2009 +0000
    31.3 @@ -21,9 +21,9 @@
    31.4  */
    31.5  
    31.6  /**
    31.7 - * \file SDL_syswm.h
    31.8 - *
    31.9 - * Include file for SDL custom system window manager hooks
   31.10 + *  \file SDL_syswm.h
   31.11 + *  
   31.12 + *  Include file for SDL custom system window manager hooks.
   31.13   */
   31.14  
   31.15  #ifndef _SDL_syswm_h
   31.16 @@ -42,11 +42,14 @@
   31.17  /* *INDENT-ON* */
   31.18  #endif
   31.19  
   31.20 -/* Your application has access to a special type of event 'SDL_SYSWMEVENT',
   31.21 -   which contains window-manager specific information and arrives whenever
   31.22 -   an unhandled window event occurs.  This event is ignored by default, but
   31.23 -   you can enable it with SDL_EventState()
   31.24 -*/
   31.25 +/**
   31.26 + *  \file SDL_syswm.h
   31.27 + *  
   31.28 + *  Your application has access to a special type of event ::SDL_SYSWMEVENT,
   31.29 + *  which contains window-manager specific information and arrives whenever
   31.30 + *  an unhandled window event occurs.  This event is ignored by default, but
   31.31 + *  you can enable it with SDL_EventState().
   31.32 + */
   31.33  #ifdef SDL_PROTOTYPES_ONLY
   31.34  struct SDL_SysWMinfo;
   31.35  #else
   31.36 @@ -66,13 +69,17 @@
   31.37  #undef Cursor
   31.38  #endif
   31.39  
   31.40 -/* These are the various supported subsystems under UNIX */
   31.41 +/** 
   31.42 + *  These are the various supported subsystems under UNIX.
   31.43 + */
   31.44  typedef enum
   31.45  {
   31.46      SDL_SYSWM_X11
   31.47  } SDL_SYSWM_TYPE;
   31.48  
   31.49 -/* The UNIX custom event structure */
   31.50 +/**
   31.51 + *  The UNIX custom event structure.
   31.52 + */
   31.53  struct SDL_SysWMmsg
   31.54  {
   31.55      SDL_version version;
   31.56 @@ -83,9 +90,11 @@
   31.57      } event;
   31.58  };
   31.59  
   31.60 -/* The UNIX custom window manager information structure.
   31.61 -   When this structure is returned, it holds information about which
   31.62 -   low level system it is using, and will be one of SDL_SYSWM_TYPE.
   31.63 +/**
   31.64 + *  The UNIX custom window manager information structure.
   31.65 + *
   31.66 + *  When this structure is returned, it holds information about which
   31.67 + *  low level system it is using, and will be one of SDL_SYSWM_TYPE.
   31.68   */
   31.69  struct SDL_SysWMinfo
   31.70  {
   31.71 @@ -95,19 +104,26 @@
   31.72      {
   31.73          struct
   31.74          {
   31.75 -            Display *display;   /* The X11 display */
   31.76 -            Window window;      /* The X11 display window */
   31.77 -            /* These locking functions should be called around
   31.78 -               any X11 functions using the display variable.
   31.79 -               They lock the event thread, so should not be
   31.80 -               called around event functions or from event filters.
   31.81 +            Display *display;   /**< The X11 display */
   31.82 +            Window window;      /**< The X11 display window */
   31.83 +            /**
   31.84 +             *  These locking functions should be called around
   31.85 +             *  any X11 functions using the display variable.
   31.86 +             *  They lock the event thread, so should not be
   31.87 +             *  called around event functions or from event filters.
   31.88               */
   31.89 +            /*@{*/
   31.90              void (*lock_func) (void);
   31.91              void (*unlock_func) (void);
   31.92 +            /*@}*/
   31.93  
   31.94 -            /* Introduced in SDL 1.0.2 */
   31.95 -            Window fswindow;    /* The X11 fullscreen window */
   31.96 -            Window wmwindow;    /* The X11 managed input window */
   31.97 +            /**
   31.98 +             *  Introduced in SDL 1.0.2.
   31.99 +             */
  31.100 +            /*@{*/
  31.101 +            Window fswindow;    /**< The X11 fullscreen window */
  31.102 +            Window wmwindow;    /**< The X11 managed input window */
  31.103 +            /*@}*/
  31.104          } x11;
  31.105      } info;
  31.106  };
  31.107 @@ -116,40 +132,48 @@
  31.108  #define WIN32_LEAN_AND_MEAN
  31.109  #include <windows.h>
  31.110  
  31.111 -/* The windows custom event structure */
  31.112 +/**
  31.113 + *  The windows custom event structure.
  31.114 + */
  31.115  struct SDL_SysWMmsg
  31.116  {
  31.117      SDL_version version;
  31.118 -    HWND hwnd;                  /* The window for the message */
  31.119 -    UINT msg;                   /* The type of message */
  31.120 -    WPARAM wParam;              /* WORD message parameter */
  31.121 -    LPARAM lParam;              /* LONG message parameter */
  31.122 +    HWND hwnd;                  /**< The window for the message */
  31.123 +    UINT msg;                   /**< The type of message */
  31.124 +    WPARAM wParam;              /**< WORD message parameter */
  31.125 +    LPARAM lParam;              /**< LONG message parameter */
  31.126  };
  31.127  
  31.128 -/* The windows custom window manager information structure */
  31.129 +/**
  31.130 + *  The windows custom window manager information structure.
  31.131 + */
  31.132  struct SDL_SysWMinfo
  31.133  {
  31.134      SDL_version version;
  31.135 -    HWND window;                /* The Win32 display window */
  31.136 +    HWND window;                /**< The Win32 display window */
  31.137  };
  31.138  
  31.139  #elif defined(SDL_VIDEO_DRIVER_RISCOS)
  31.140  
  31.141 -/* RISC OS custom event structure */
  31.142 +/**
  31.143 + *  RISC OS custom event structure.
  31.144 + */
  31.145  struct SDL_SysWMmsg
  31.146  {
  31.147      SDL_version version;
  31.148 -    int eventCode;              /* The window for the message */
  31.149 +    int eventCode;              /**< The window for the message */
  31.150      int pollBlock[64];
  31.151  };
  31.152  
  31.153 -/* The RISC OS custom window manager information structure */
  31.154 +/**
  31.155 + *  The RISC OS custom window manager information structure.
  31.156 + */
  31.157  struct SDL_SysWMinfo
  31.158  {
  31.159      SDL_version version;
  31.160 -    int wimpVersion;            /* Wimp version running under */
  31.161 -    int taskHandle;             /* The RISC OS task handle */
  31.162 -    int window;                 /* The RISC OS display window */
  31.163 +    int wimpVersion;            /**< Wimp version running under */
  31.164 +    int taskHandle;             /**< The RISC OS task handle */
  31.165 +    int window;                 /**< The RISC OS display window */
  31.166  };
  31.167  
  31.168  #elif defined(SDL_VIDEO_DRIVER_PHOTON) || defined(SDL_VIDEO_DRIVER_QNXGF)
  31.169 @@ -159,14 +183,18 @@
  31.170  #endif /* SDL_VIDEO_OPENGL_ES */
  31.171  #include <Ph.h>
  31.172  
  31.173 -/* The QNX custom event structure */
  31.174 +/**
  31.175 + * The QNX custom event structure.
  31.176 + */
  31.177  struct SDL_SysWMmsg
  31.178  {
  31.179      SDL_version version;
  31.180      int data;
  31.181  };
  31.182  
  31.183 -/* The QNX Photon custom window manager information structure */
  31.184 +/**
  31.185 + *  The QNX Photon custom window manager information structure.
  31.186 + */
  31.187  struct SDL_SysWMinfo
  31.188  {
  31.189      SDL_version version;
  31.190 @@ -175,14 +203,18 @@
  31.191  
  31.192  #else
  31.193  
  31.194 -/* The generic custom event structure */
  31.195 +/**
  31.196 + *  The generic custom event structure.
  31.197 + */
  31.198  struct SDL_SysWMmsg
  31.199  {
  31.200      SDL_version version;
  31.201      int data;
  31.202  };
  31.203  
  31.204 -/* The generic custom window manager information structure */
  31.205 +/**
  31.206 + *  The generic custom window manager information structure.
  31.207 + */
  31.208  struct SDL_SysWMinfo
  31.209  {
  31.210      SDL_version version;
  31.211 @@ -197,21 +229,21 @@
  31.212  
  31.213  /* Function prototypes */
  31.214  /**
  31.215 - * \fn SDL_bool SDL_GetWindowWMInfo (SDL_WindowID windowID, SDL_SysWMinfo * info)
  31.216 - *
  31.217 - * \brief This function allows access to driver-dependent window information.
  31.218 - *
  31.219 - * \param windowID The window about which information is being requested
  31.220 - * \param info This structure must be initialized with the SDL version, and is then filled in with information about the given window.
  31.221 - *
  31.222 - * \return SDL_TRUE if the function is implemented and the version member of the 'info' struct is valid, SDL_FALSE otherwise.
  31.223 - *
  31.224 - * You typically use this function like this:
  31.225 - * \code
  31.226 - * SDL_SysWMInfo info;
  31.227 - * SDL_VERSION(&info.version);
  31.228 - * if ( SDL_GetWindowWMInfo(&info) ) { ... }
  31.229 - * \endcode
  31.230 + *  \brief This function allows access to driver-dependent window information.
  31.231 + *  
  31.232 + *  \param windowID The window about which information is being requested
  31.233 + *  \param info This structure must be initialized with the SDL version, and is 
  31.234 + *              then filled in with information about the given window.
  31.235 + *  
  31.236 + *  \return SDL_TRUE if the function is implemented and the version member of 
  31.237 + *          the \c info struct is valid, SDL_FALSE otherwise.
  31.238 + *  
  31.239 + *  You typically use this function like this:
  31.240 + *  \code
  31.241 + *  SDL_SysWMInfo info;
  31.242 + *  SDL_VERSION(&info.version);
  31.243 + *  if ( SDL_GetWindowWMInfo(&info) ) { ... }
  31.244 + *  \endcode
  31.245   */
  31.246  extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowWMInfo(SDL_WindowID windowID,
  31.247                                                       SDL_SysWMinfo * info);
    32.1 --- a/include/SDL_thread.h	Sun Oct 18 23:21:15 2009 +0000
    32.2 +++ b/include/SDL_thread.h	Mon Oct 19 13:31:58 2009 +0000
    32.3 @@ -24,9 +24,9 @@
    32.4  #define _SDL_thread_h
    32.5  
    32.6  /**
    32.7 - * \file SDL_thread.h
    32.8 - *
    32.9 - * Header for the SDL thread management routines 
   32.10 + *  \file SDL_thread.h
   32.11 + *  
   32.12 + *  Header for the SDL thread management routines.
   32.13   */
   32.14  
   32.15  #include "SDL_stdinc.h"
   32.16 @@ -47,21 +47,27 @@
   32.17  struct SDL_Thread;
   32.18  typedef struct SDL_Thread SDL_Thread;
   32.19  
   32.20 -/* Create a thread */
   32.21  #if defined(__WIN32__) && !defined(HAVE_LIBC)
   32.22 -/*
   32.23 -   We compile SDL into a DLL. This means, that it's the DLL which
   32.24 -   creates a new thread for the calling process with the SDL_CreateThread()
   32.25 -   API. There is a problem with this, that only the RTL of the SDL.DLL will
   32.26 -   be initialized for those threads, and not the RTL of the calling application!
   32.27 -   To solve this, we make a little hack here.
   32.28 -   We'll always use the caller's _beginthread() and _endthread() APIs to
   32.29 -   start a new thread. This way, if it's the SDL.DLL which uses this API,
   32.30 -   then the RTL of SDL.DLL will be used to create the new thread, and if it's
   32.31 -   the application, then the RTL of the application will be used.
   32.32 -   So, in short:
   32.33 -   Always use the _beginthread() and _endthread() of the calling runtime library!
   32.34 -*/
   32.35 +/**
   32.36 + *  \file SDL_thread.h
   32.37 + *  
   32.38 + *  We compile SDL into a DLL. This means, that it's the DLL which
   32.39 + *  creates a new thread for the calling process with the SDL_CreateThread()
   32.40 + *  API. There is a problem with this, that only the RTL of the SDL.DLL will
   32.41 + *  be initialized for those threads, and not the RTL of the calling 
   32.42 + *  application!
   32.43 + *  
   32.44 + *  To solve this, we make a little hack here.
   32.45 + *  
   32.46 + *  We'll always use the caller's _beginthread() and _endthread() APIs to
   32.47 + *  start a new thread. This way, if it's the SDL.DLL which uses this API,
   32.48 + *  then the RTL of SDL.DLL will be used to create the new thread, and if it's
   32.49 + *  the application, then the RTL of the application will be used.
   32.50 + *  
   32.51 + *  So, in short:
   32.52 + *  Always use the _beginthread() and _endthread() of the calling runtime 
   32.53 + *  library!
   32.54 + */
   32.55  #define SDL_PASSED_BEGINTHREAD_ENDTHREAD
   32.56  #ifndef _WIN32_WCE
   32.57  #include <process.h>            /* This has _beginthread() and _endthread() defined! */
   32.58 @@ -87,40 +93,66 @@
   32.59  typedef void (__cdecl * pfnSDL_CurrentEndThread) (unsigned code);
   32.60  #endif
   32.61  
   32.62 +/**
   32.63 + *  Create a thread.
   32.64 + */
   32.65  extern DECLSPEC SDL_Thread *SDLCALL
   32.66  SDL_CreateThread(int (SDLCALL * f) (void *), void *data,
   32.67                   pfnSDL_CurrentBeginThread pfnBeginThread,
   32.68                   pfnSDL_CurrentEndThread pfnEndThread);
   32.69  
   32.70  #if defined(_WIN32_WCE)
   32.71 +
   32.72 +/**
   32.73 + *  Create a thread.
   32.74 + */
   32.75  #define SDL_CreateThread(fn, data) SDL_CreateThread(fn, data, NULL, NULL)
   32.76 +
   32.77  #else
   32.78 +
   32.79 +/**
   32.80 + *  Create a thread.
   32.81 + */
   32.82  #define SDL_CreateThread(fn, data) SDL_CreateThread(fn, data, _beginthreadex, _endthreadex)
   32.83 +
   32.84  #endif
   32.85  #else
   32.86 +
   32.87 +/**
   32.88 + *  Create a thread.
   32.89 + */
   32.90  extern DECLSPEC SDL_Thread *SDLCALL
   32.91  SDL_CreateThread(int (SDLCALL * fn) (void *), void *data);
   32.92 +
   32.93  #endif
   32.94  
   32.95 -/* Get the 32-bit thread identifier for the current thread */
   32.96 +/**
   32.97 + *  Get the 32-bit thread identifier for the current thread.
   32.98 + */
   32.99  extern DECLSPEC Uint32 SDLCALL SDL_ThreadID(void);
  32.100  
  32.101 -/* Get the 32-bit thread identifier for the specified thread,
  32.102 -   equivalent to SDL_ThreadID() if the specified thread is NULL.
  32.103 +/**
  32.104 + *  Get the 32-bit thread identifier for the specified thread.
  32.105 + *  
  32.106 + *  Equivalent to SDL_ThreadID() if the specified thread is NULL.
  32.107   */
  32.108  extern DECLSPEC Uint32 SDLCALL SDL_GetThreadID(SDL_Thread * thread);
  32.109  
  32.110 -/* Wait for a thread to finish.
  32.111 -   The return code for the thread function is placed in the area
  32.112 -   pointed to by 'status', if 'status' is not NULL.
  32.113 +/**
  32.114 + *  Wait for a thread to finish.
  32.115 + *  
  32.116 + *  The return code for the thread function is placed in the area
  32.117 + *  pointed to by \c status, if \c status is not NULL.
  32.118   */
  32.119  extern DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread * thread, int *status);
  32.120  
  32.121 -/* This function is here for binary compatibility with legacy apps, but
  32.122 -   in SDL 1.3 and later, it's a no-op. You cannot forcibly kill a thread
  32.123 -   in a safe manner on many platforms. You should instead find a way to
  32.124 -   alert your thread that it is time to terminate, and then have it gracefully
  32.125 -   exit on its own. Do not ever call this function!
  32.126 +/**
  32.127 + *  \deprecated This function is here for binary compatibility with legacy apps,
  32.128 + *              but in SDL 1.3 and later, it's a no-op.
  32.129 + *  
  32.130 + *  You cannot forcibly kill a thread in a safe manner on many platforms. You 
  32.131 + *  should instead find a way to alert your thread that it is time to terminate,
  32.132 + *  and then have it gracefully exit on its own. Do not ever call this function!
  32.133   */
  32.134  extern DECLSPEC void SDLCALL SDL_KillThread(SDL_Thread * thread);
  32.135  
    33.1 --- a/include/SDL_timer.h	Sun Oct 18 23:21:15 2009 +0000
    33.2 +++ b/include/SDL_timer.h	Mon Oct 19 13:31:58 2009 +0000
    33.3 @@ -24,9 +24,9 @@
    33.4  #define _SDL_timer_h
    33.5  
    33.6  /**
    33.7 - * \file SDL_timer.h
    33.8 - *
    33.9 - * Header for the SDL time management routines
   33.10 + *  \file SDL_timer.h
   33.11 + *  
   33.12 + *  Header for the SDL time management routines.
   33.13   */
   33.14  
   33.15  #include "SDL_stdinc.h"
   33.16 @@ -40,81 +40,106 @@
   33.17  /* *INDENT-ON* */
   33.18  #endif
   33.19  
   33.20 -/* This is the OS scheduler timeslice, in milliseconds */
   33.21 +/**
   33.22 + *  This is the OS scheduler timeslice, in milliseconds.
   33.23 + */
   33.24  #define SDL_TIMESLICE		10
   33.25  
   33.26 -/* This is the maximum resolution of the SDL timer on all platforms */
   33.27 -#define TIMER_RESOLUTION	10      /* Experimentally determined */
   33.28 +/**
   33.29 + *  This is the maximum resolution of the SDL timer on all platforms.
   33.30 + */
   33.31 +#define TIMER_RESOLUTION	10      /**< Experimentally determined */
   33.32  
   33.33 -/* Get the number of milliseconds since the SDL library initialization.
   33.34 - * Note that this value wraps if the program runs for more than ~49 days.
   33.35 +/**
   33.36 + *  Get the number of milliseconds since the SDL library initialization.
   33.37 + *  
   33.38 + *  Note that this value wraps if the program runs for more than ~49 days.
   33.39   */
   33.40  extern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void);
   33.41  
   33.42 -/* Wait a specified number of milliseconds before returning */
   33.43 +/**
   33.44 + *  Wait a specified number of milliseconds before returning.
   33.45 + */
   33.46  extern DECLSPEC void SDLCALL SDL_Delay(Uint32 ms);
   33.47  
   33.48 -/* Function prototype for the timer callback function */
   33.49 +/**
   33.50 + *  Function prototype for the timer callback function.
   33.51 + */
   33.52  typedef Uint32(SDLCALL * SDL_TimerCallback) (Uint32 interval);
   33.53  
   33.54 -/* Set a callback to run after the specified number of milliseconds has
   33.55 - * elapsed. The callback function is passed the current timer interval
   33.56 - * and returns the next timer interval.  If the returned value is the 
   33.57 - * same as the one passed in, the periodic alarm continues, otherwise a
   33.58 - * new alarm is scheduled.  If the callback returns 0, the periodic alarm
   33.59 - * is cancelled.
   33.60 - *
   33.61 - * To cancel a currently running timer, call SDL_SetTimer(0, NULL);
   33.62 - *
   33.63 - * The timer callback function may run in a different thread than your
   33.64 - * main code, and so shouldn't call any functions from within itself.
   33.65 - *
   33.66 - * The maximum resolution of this timer is 10 ms, which means that if
   33.67 - * you request a 16 ms timer, your callback will run approximately 20 ms
   33.68 - * later on an unloaded system.  If you wanted to set a flag signaling
   33.69 - * a frame update at 30 frames per second (every 33 ms), you might set a 
   33.70 - * timer for 30 ms:
   33.71 - *   SDL_SetTimer((33/10)*10, flag_update);
   33.72 - *
   33.73 - * If you use this function, you need to pass SDL_INIT_TIMER to SDL_Init().
   33.74 - *
   33.75 - * Under UNIX, you should not use raise or use SIGALRM and this function
   33.76 - * in the same program, as it is implemented using setitimer().  You also
   33.77 - * should not use this function in multi-threaded applications as signals
   33.78 - * to multi-threaded apps have undefined behavior in some implementations.
   33.79 - *
   33.80 - * This function returns 0 if successful, or -1 if there was an error.
   33.81 +/**
   33.82 + *  Set a callback to run after the specified number of milliseconds has
   33.83 + *  elapsed. The callback function is passed the current timer interval
   33.84 + *  and returns the next timer interval.  If the returned value is the 
   33.85 + *  same as the one passed in, the periodic alarm continues, otherwise a
   33.86 + *  new alarm is scheduled.  If the callback returns 0, the periodic alarm
   33.87 + *  is cancelled.
   33.88 + *  
   33.89 + *  To cancel a currently running timer, call 
   33.90 + *  \code SDL_SetTimer(0, NULL); \endcode
   33.91 + *  
   33.92 + *  The timer callback function may run in a different thread than your
   33.93 + *  main code, and so shouldn't call any functions from within itself.
   33.94 + *  
   33.95 + *  The maximum resolution of this timer is 10 ms, which means that if
   33.96 + *  you request a 16 ms timer, your callback will run approximately 20 ms
   33.97 + *  later on an unloaded system.  If you wanted to set a flag signaling
   33.98 + *  a frame update at 30 frames per second (every 33 ms), you might set a 
   33.99 + *  timer for 30 ms:
  33.100 + *  \code
  33.101 + *    SDL_SetTimer((33/10)*10, flag_update);
  33.102 + *  \endcode
  33.103 + *  
  33.104 + *  If you use this function, you need to pass ::SDL_INIT_TIMER to SDL_Init().
  33.105 + *  
  33.106 + *  Under UNIX, you should not use raise or use SIGALRM and this function
  33.107 + *  in the same program, as it is implemented using setitimer().  You also
  33.108 + *  should not use this function in multi-threaded applications as signals
  33.109 + *  to multi-threaded apps have undefined behavior in some implementations.
  33.110 + *  
  33.111 + *  \return 0 if successful, or -1 if there was an error.
  33.112   */
  33.113  extern DECLSPEC int SDLCALL SDL_SetTimer(Uint32 interval,
  33.114                                           SDL_TimerCallback callback);
  33.115  
  33.116 -/* New timer API, supports multiple timers
  33.117 - * Written by Stephane Peter <megastep@lokigames.com>
  33.118 +/**
  33.119 + *  \name Peter timers
  33.120 + *  New timer API, supports multiple timers
  33.121 + *  Written by Stephane Peter <megastep@lokigames.com>
  33.122   */
  33.123 +/*@{*/
  33.124  
  33.125 -/* Function prototype for the new timer callback function.
  33.126 - * The callback function is passed the current timer interval and returns
  33.127 - * the next timer interval.  If the returned value is the same as the one
  33.128 - * passed in, the periodic alarm continues, otherwise a new alarm is
  33.129 - * scheduled.  If the callback returns 0, the periodic alarm is cancelled.
  33.130 +/**
  33.131 + *  Function prototype for the new timer callback function.
  33.132 + *  
  33.133 + *  The callback function is passed the current timer interval and returns
  33.134 + *  the next timer interval.  If the returned value is the same as the one
  33.135 + *  passed in, the periodic alarm continues, otherwise a new alarm is
  33.136 + *  scheduled.  If the callback returns 0, the periodic alarm is cancelled.
  33.137   */
  33.138  typedef Uint32(SDLCALL * SDL_NewTimerCallback) (Uint32 interval, void *param);
  33.139  
  33.140 -/* Definition of the timer ID type */
  33.141 +/**
  33.142 + *  Definition of the timer ID type.
  33.143 + */
  33.144  typedef struct _SDL_TimerID *SDL_TimerID;
  33.145  
  33.146 -/* Add a new timer to the pool of timers already running.
  33.147 -   Returns a timer ID, or NULL when an error occurs.
  33.148 +/**
  33.149 + *  Add a new timer to the pool of timers already running.
  33.150 + *  \return A timer ID, or NULL when an error occurs.
  33.151   */
  33.152  extern DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval,
  33.153                                                   SDL_NewTimerCallback
  33.154                                                   callback, void *param);
  33.155  
  33.156 -/* Remove one of the multiple timers knowing its ID.
  33.157 - * Returns a boolean value indicating success.
  33.158 +/**
  33.159 + *  Remove one of the multiple timers knowing its ID.
  33.160 + *  \return A boolean value indicating success or failure.
  33.161   */
  33.162  extern DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID t);
  33.163  
  33.164 +/*@}*//*Peter timers*/
  33.165 +
  33.166  /* Ends C function definitions when using C++ */
  33.167  #ifdef __cplusplus
  33.168  /* *INDENT-OFF* */
    34.1 --- a/include/SDL_types.h	Sun Oct 18 23:21:15 2009 +0000
    34.2 +++ b/include/SDL_types.h	Mon Oct 19 13:31:58 2009 +0000
    34.3 @@ -20,5 +20,11 @@
    34.4      slouken@libsdl.org
    34.5  */
    34.6  
    34.7 +/**
    34.8 + *  \file SDL_types.h
    34.9 + *  
   34.10 + *  \deprecated
   34.11 + */
   34.12 +
   34.13  /* DEPRECATED */
   34.14  #include "SDL_stdinc.h"
    35.1 --- a/include/SDL_version.h	Sun Oct 18 23:21:15 2009 +0000
    35.2 +++ b/include/SDL_version.h	Mon Oct 19 13:31:58 2009 +0000
    35.3 @@ -21,9 +21,9 @@
    35.4  */
    35.5  
    35.6  /**
    35.7 - * \file SDL_version.h
    35.8 - *
    35.9 - * This header defines the current SDL version
   35.10 + *  \file SDL_version.h
   35.11 + *  
   35.12 + *  This header defines the current SDL version.
   35.13   */
   35.14  
   35.15  #ifndef _SDL_version_h
   35.16 @@ -41,17 +41,16 @@
   35.17  #endif
   35.18  
   35.19  /**
   35.20 - * \struct SDL_version
   35.21 - * \brief Information the version of SDL in use.
   35.22 - *
   35.23 - * Represents the library's version as three levels: major revision
   35.24 + *  \brief Information the version of SDL in use.
   35.25 + *  
   35.26 + *  Represents the library's version as three levels: major revision
   35.27   *  (increments with massive changes, additions, and enhancements),
   35.28   *  minor revision (increments with backwards-compatible changes to the
   35.29   *  major revision), and patchlevel (increments with fixes to the minor
   35.30   *  revision).
   35.31 - *
   35.32 - * \sa SDL_VERSION
   35.33 - * \sa SDL_GetVersion
   35.34 + *  
   35.35 + *  \sa SDL_VERSION
   35.36 + *  \sa SDL_GetVersion
   35.37   */
   35.38  typedef struct SDL_version
   35.39  {
   35.40 @@ -67,20 +66,19 @@
   35.41  #define SDL_PATCHLEVEL		0
   35.42  
   35.43  /**
   35.44 - * \def SDL_VERSION(x)
   35.45 - * \brief Macro to determine SDL version program was compiled against.
   35.46 - *
   35.47 - * This macro fills in a SDL_version structure with the version of the
   35.48 + *  \brief Macro to determine SDL version program was compiled against.
   35.49 + *  
   35.50 + *  This macro fills in a SDL_version structure with the version of the
   35.51   *  library you compiled against. This is determined by what header the
   35.52   *  compiler uses. Note that if you dynamically linked the library, you might
   35.53   *  have a slightly newer or older version at runtime. That version can be
   35.54 - *  determined with SDL_GetVersion(), which, unlike SDL_VERSION,
   35.55 + *  determined with SDL_GetVersion(), which, unlike SDL_VERSION(),
   35.56   *  is not a macro.
   35.57 - *
   35.58 - * \param x A pointer to a SDL_version struct to initialize.
   35.59 - *
   35.60 - * \sa SDL_version
   35.61 - * \sa SDL_GetVersion
   35.62 + *  
   35.63 + *  \param x A pointer to a SDL_version struct to initialize.
   35.64 + *  
   35.65 + *  \sa SDL_version
   35.66 + *  \sa SDL_GetVersion
   35.67   */
   35.68  #define SDL_VERSION(x)							\
   35.69  {									\
   35.70 @@ -89,52 +87,58 @@
   35.71  	(x)->patch = SDL_PATCHLEVEL;					\
   35.72  }
   35.73  
   35.74 -/* This macro turns the version numbers into a numeric value:
   35.75 -   (1,2,3) -> (1203)
   35.76 -   This assumes that there will never be more than 100 patchlevels
   35.77 -*/
   35.78 +/**
   35.79 + *  This macro turns the version numbers into a numeric value:
   35.80 + *  \verbatim
   35.81 +    (1,2,3) -> (1203)
   35.82 +    \endverbatim
   35.83 + *  
   35.84 + *  This assumes that there will never be more than 100 patchlevels.
   35.85 + */
   35.86  #define SDL_VERSIONNUM(X, Y, Z)						\
   35.87  	((X)*1000 + (Y)*100 + (Z))
   35.88  
   35.89 -/* This is the version number macro for the current SDL version */
   35.90 +/**
   35.91 + *  This is the version number macro for the current SDL version.
   35.92 + */
   35.93  #define SDL_COMPILEDVERSION \
   35.94  	SDL_VERSIONNUM(SDL_MAJOR_VERSION, SDL_MINOR_VERSION, SDL_PATCHLEVEL)
   35.95  
   35.96 -/* This macro will evaluate to true if compiled with SDL at least X.Y.Z */
   35.97 +/**
   35.98 + *  This macro will evaluate to true if compiled with SDL at least X.Y.Z.
   35.99 + */
  35.100  #define SDL_VERSION_ATLEAST(X, Y, Z) \
  35.101  	(SDL_COMPILEDVERSION >= SDL_VERSIONNUM(X, Y, Z))
  35.102  
  35.103  /**
  35.104 - * \fn void SDL_GetVersion(SDL_version *ver)
  35.105 - * \brief Get the version of SDL that is linked against your program.
  35.106 - *
  35.107 - * If you are using a shared library (DLL) version of SDL, then it is
  35.108 + *  \brief Get the version of SDL that is linked against your program.
  35.109 + *  
  35.110 + *  If you are using a shared library (DLL) version of SDL, then it is
  35.111   *  possible that it will be different than the version you compiled against.
  35.112   *
  35.113 - * This is a real function; the macro SDL_VERSION tells you what version
  35.114 + *  This is a real function; the macro SDL_VERSION() tells you what version
  35.115   *  of SDL you compiled against:
  35.116 - *
  35.117 - * \code
  35.118 - * SDL_version compiled;
  35.119 - * SDL_version linked;
  35.120 - *
  35.121 - * SDL_VERSION(&compiled);
  35.122 - * SDL_GetVersion(&linked);
  35.123 - * printf("We compiled against SDL version %d.%d.%d ...\n",
  35.124 - *           compiled.major, compiled.minor, compiled.patch);
  35.125 - * printf("But we linked against SDL version %d.%d.%d.\n",
  35.126 - *           linked.major, linked.minor, linked.patch);
  35.127 - * \endcode
  35.128 - *
  35.129 - * This function may be called safely at any time, even before SDL_Init().
  35.130 - *
  35.131 - * \sa SDL_VERSION
  35.132 + *  
  35.133 + *  \code
  35.134 + *  SDL_version compiled;
  35.135 + *  SDL_version linked;
  35.136 + *  
  35.137 + *  SDL_VERSION(&compiled);
  35.138 + *  SDL_GetVersion(&linked);
  35.139 + *  printf("We compiled against SDL version %d.%d.%d ...\n",
  35.140 + *         compiled.major, compiled.minor, compiled.patch);
  35.141 + *  printf("But we linked against SDL version %d.%d.%d.\n",
  35.142 + *         linked.major, linked.minor, linked.patch);
  35.143 + *  \endcode
  35.144 + *  
  35.145 + *  This function may be called safely at any time, even before SDL_Init().
  35.146 + *  
  35.147 + *  \sa SDL_VERSION
  35.148   */
  35.149  extern DECLSPEC void SDLCALL SDL_GetVersion(SDL_version * ver);
  35.150  
  35.151  /**
  35.152 - * \fn int SDL_GetRevision(void)
  35.153 - * \brief Get the code revision of SDL that is linked against your program.
  35.154 + *  \brief Get the code revision of SDL that is linked against your program.
  35.155   */
  35.156  extern DECLSPEC int SDLCALL SDL_GetRevision(void);
  35.157  
    36.1 --- a/include/SDL_video.h	Sun Oct 18 23:21:15 2009 +0000
    36.2 +++ b/include/SDL_video.h	Mon Oct 19 13:31:58 2009 +0000
    36.3 @@ -21,9 +21,9 @@
    36.4  */
    36.5  
    36.6  /**
    36.7 - * \file SDL_video.h
    36.8 - *
    36.9 - * Header file for SDL video functions.
   36.10 + *  \file SDL_video.h
   36.11 + *  
   36.12 + *  Header file for SDL video functions.
   36.13   */
   36.14  
   36.15  #ifndef _SDL_video_h
   36.16 @@ -43,16 +43,14 @@
   36.17  #endif
   36.18  
   36.19  /**
   36.20 - * \struct SDL_DisplayMode
   36.21 - *
   36.22 - * \brief  The structure that defines a display mode
   36.23 - *
   36.24 - * \sa SDL_GetNumDisplayModes()
   36.25 - * \sa SDL_GetDisplayMode()
   36.26 - * \sa SDL_GetDesktopDisplayMode()
   36.27 - * \sa SDL_GetCurrentDisplayMode()
   36.28 - * \sa SDL_GetClosestDisplayMode()
   36.29 - * \sa SDL_SetDisplayMode()
   36.30 + *  \brief  The structure that defines a display mode
   36.31 + *  
   36.32 + *  \sa SDL_GetNumDisplayModes()
   36.33 + *  \sa SDL_GetDisplayMode()
   36.34 + *  \sa SDL_GetDesktopDisplayMode()
   36.35 + *  \sa SDL_GetCurrentDisplayMode()
   36.36 + *  \sa SDL_GetClosestDisplayMode()
   36.37 + *  \sa SDL_SetDisplayMode()
   36.38   */
   36.39  typedef struct
   36.40  {
   36.41 @@ -64,41 +62,37 @@
   36.42  } SDL_DisplayMode;
   36.43  
   36.44  /**
   36.45 - * \typedef SDL_WindowID
   36.46 - *
   36.47 - * \brief The type used to identify a window
   36.48 - *
   36.49 - * \sa SDL_CreateWindow()
   36.50 - * \sa SDL_CreateWindowFrom()
   36.51 - * \sa SDL_DestroyWindow()
   36.52 - * \sa SDL_GetWindowData()
   36.53 - * \sa SDL_GetWindowFlags()
   36.54 - * \sa SDL_GetWindowGrab()
   36.55 - * \sa SDL_GetWindowPosition()
   36.56 - * \sa SDL_GetWindowSize()
   36.57 - * \sa SDL_GetWindowTitle()
   36.58 - * \sa SDL_HideWindow()
   36.59 - * \sa SDL_MaximizeWindow()
   36.60 - * \sa SDL_MinimizeWindow()
   36.61 - * \sa SDL_RaiseWindow()
   36.62 - * \sa SDL_RestoreWindow()
   36.63 - * \sa SDL_SetWindowData()
   36.64 - * \sa SDL_SetWindowFullscreen()
   36.65 - * \sa SDL_SetWindowGrab()
   36.66 - * \sa SDL_SetWindowIcon()
   36.67 - * \sa SDL_SetWindowPosition()
   36.68 - * \sa SDL_SetWindowSize()
   36.69 - * \sa SDL_SetWindowTitle()
   36.70 - * \sa SDL_ShowWindow()
   36.71 + *  \brief The type used to identify a window
   36.72 + *  
   36.73 + *  \sa SDL_CreateWindow()
   36.74 + *  \sa SDL_CreateWindowFrom()
   36.75 + *  \sa SDL_DestroyWindow()
   36.76 + *  \sa SDL_GetWindowData()
   36.77 + *  \sa SDL_GetWindowFlags()
   36.78 + *  \sa SDL_GetWindowGrab()
   36.79 + *  \sa SDL_GetWindowPosition()
   36.80 + *  \sa SDL_GetWindowSize()
   36.81 + *  \sa SDL_GetWindowTitle()
   36.82 + *  \sa SDL_HideWindow()
   36.83 + *  \sa SDL_MaximizeWindow()
   36.84 + *  \sa SDL_MinimizeWindow()
   36.85 + *  \sa SDL_RaiseWindow()
   36.86 + *  \sa SDL_RestoreWindow()
   36.87 + *  \sa SDL_SetWindowData()
   36.88 + *  \sa SDL_SetWindowFullscreen()
   36.89 + *  \sa SDL_SetWindowGrab()
   36.90 + *  \sa SDL_SetWindowIcon()
   36.91 + *  \sa SDL_SetWindowPosition()
   36.92 + *  \sa SDL_SetWindowSize()
   36.93 + *  \sa SDL_SetWindowTitle()
   36.94 + *  \sa SDL_ShowWindow()
   36.95   */
   36.96  typedef Uint32 SDL_WindowID;
   36.97  
   36.98  /**
   36.99 - * \enum SDL_WindowFlags
  36.100 - *
  36.101 - * \brief The flags on a window
  36.102 - *
  36.103 - * \sa SDL_GetWindowFlags()
  36.104 + *  \brief The flags on a window
  36.105 + *  
  36.106 + *  \sa SDL_GetWindowFlags()
  36.107   */
  36.108  typedef enum
  36.109  {
  36.110 @@ -116,64 +110,80 @@
  36.111  } SDL_WindowFlags;
  36.112  
  36.113  /**
  36.114 - * \def SDL_WINDOWPOS_UNDEFINED
  36.115 - * \brief Used to indicate that you don't care what the window position is.
  36.116 + *  \brief Used to indicate that you don't care what the window position is.
  36.117   */
  36.118  #define SDL_WINDOWPOS_UNDEFINED 0x7FFFFFF
  36.119 +
  36.120  /**
  36.121 - * \def SDL_WINDOWPOS_CENTERED
  36.122 - * \brief Used to indicate that the window position should be centered.
  36.123 + *  \brief Used to indicate that the window position should be centered.
  36.124   */
  36.125  #define SDL_WINDOWPOS_CENTERED  0x7FFFFFE
  36.126  
  36.127  /**
  36.128 - * \enum SDL_WindowEventID
  36.129 - *
  36.130 - * \brief Event subtype for window events
  36.131 + *  \brief Event subtype for window events
  36.132   */
  36.133  typedef enum
  36.134  {
  36.135 -    SDL_WINDOWEVENT_NONE,               /**< Never used */
  36.136 -    SDL_WINDOWEVENT_SHOWN,              /**< Window has been shown */
  36.137 -    SDL_WINDOWEVENT_HIDDEN,             /**< Window has been hidden */
  36.138 -    SDL_WINDOWEVENT_EXPOSED,            /**< Window has been exposed and should be redrawn */
  36.139 -    SDL_WINDOWEVENT_MOVED,              /**< Window has been moved to data1,data2 */
  36.140 -    SDL_WINDOWEVENT_RESIZED,            /**< Window size changed to data1xdata2 */
  36.141 -    SDL_WINDOWEVENT_MINIMIZED,          /**< Window has been minimized */
  36.142 -    SDL_WINDOWEVENT_MAXIMIZED,          /**< Window has been maximized */
  36.143 -    SDL_WINDOWEVENT_RESTORED,           /**< Window has been restored to normal size and position */
  36.144 -    SDL_WINDOWEVENT_ENTER,              /**< The window has gained mouse focus */
  36.145 -    SDL_WINDOWEVENT_LEAVE,              /**< The window has lost mouse focus */
  36.146 -    SDL_WINDOWEVENT_FOCUS_GAINED,       /**< The window has gained keyboard focus */
  36.147 -    SDL_WINDOWEVENT_FOCUS_LOST,         /**< The window has lost keyboard focus */
  36.148 -    SDL_WINDOWEVENT_CLOSE               /**< The window manager requests that the window be closed */
  36.149 +    SDL_WINDOWEVENT_NONE,           /**< Never used */
  36.150 +    SDL_WINDOWEVENT_SHOWN,          /**< Window has been shown */
  36.151 +    SDL_WINDOWEVENT_HIDDEN,         /**< Window has been hidden */
  36.152 +    SDL_WINDOWEVENT_EXPOSED,        /**< Window has been exposed and should be 
  36.153 +                                         redrawn */
  36.154 +    SDL_WINDOWEVENT_MOVED,          /**< Window has been moved to data1, data2 
  36.155 +                                     */
  36.156 +    SDL_WINDOWEVENT_RESIZED,        /**< Window size changed to data1xdata2 */
  36.157 +    SDL_WINDOWEVENT_MINIMIZED,      /**< Window has been minimized */
  36.158 +    SDL_WINDOWEVENT_MAXIMIZED,      /**< Window has been maximized */
  36.159 +    SDL_WINDOWEVENT_RESTORED,       /**< Window has been restored to normal size
  36.160 +                                         and position */
  36.161 +    SDL_WINDOWEVENT_ENTER,          /**< The window has gained mouse focus */
  36.162 +    SDL_WINDOWEVENT_LEAVE,          /**< The window has lost mouse focus */
  36.163 +    SDL_WINDOWEVENT_FOCUS_GAINED,   /**< The window has gained keyboard focus */
  36.164 +    SDL_WINDOWEVENT_FOCUS_LOST,     /**< The window has lost keyboard focus */
  36.165 +    SDL_WINDOWEVENT_CLOSE           /**< The window manager requests that the 
  36.166 +                                         window be closed */
  36.167  } SDL_WindowEventID;
  36.168  
  36.169  /**
  36.170 - * \enum SDL_RendererFlags
  36.171 - *
  36.172 - * \brief Flags used when creating a rendering context
  36.173 + *  \brief Flags used when creating a rendering context
  36.174   */
  36.175  typedef enum
  36.176  {
  36.177 -    SDL_RENDERER_SINGLEBUFFER = 0x00000001,     /**< Render directly to the window, if possible */
  36.178 -    SDL_RENDERER_PRESENTCOPY = 0x00000002,      /**< Present uses a copy from back buffer to the front buffer */
  36.179 -    SDL_RENDERER_PRESENTFLIP2 = 0x00000004,     /**< Present uses a flip, swapping back buffer and front buffer */
  36.180 -    SDL_RENDERER_PRESENTFLIP3 = 0x00000008,     /**< Present uses a flip, rotating between two back buffers and a front buffer */
  36.181 -    SDL_RENDERER_PRESENTDISCARD = 0x00000010,   /**< Present leaves the contents of the backbuffer undefined */
  36.182 -    SDL_RENDERER_PRESENTVSYNC = 0x00000020,     /**< Present is synchronized with the refresh rate */
  36.183 -    SDL_RENDERER_ACCELERATED = 0x00000040       /**< The renderer uses hardware acceleration */
  36.184 -} SDL_RendererFlags;
  36.185 +    SDL_RENDERER_SINGLEBUFFER = 0x00000001,     /**< Render directly to the 
  36.186 +                                                     window, if possible */
  36.187 +    
  36.188 +    SDL_RENDERER_PRESENTCOPY = 0x00000002,      /**< Present uses a copy from 
  36.189 +                                                     back buffer to the front 
  36.190 +                                                     buffer */
  36.191 +    
  36.192 +    SDL_RENDERER_PRESENTFLIP2 = 0x00000004,     /**< Present uses a flip, 
  36.193 +                                                     swapping back buffer and 
  36.194 +                                                     front buffer */
  36.195 +    
  36.196 +    SDL_RENDERER_PRESENTFLIP3 = 0x00000008,     /**< Present uses a flip, 
  36.197 +                                                     rotating between two back 
  36.198 +                                                     buffers and a front buffer
  36.199 +                                                 */
  36.200 +    
  36.201 +    SDL_RENDERER_PRESENTDISCARD = 0x00000010,   /**< Present leaves the contents
  36.202 +                                                     of the backbuffer undefined
  36.203 +                                                 */
  36.204 +    
  36.205 +    SDL_RENDERER_PRESENTVSYNC = 0x00000020,     /**< Present is synchronized 
  36.206 +                                                     with the refresh rate */
  36.207 +    
  36.208 +    SDL_RENDERER_ACCELERATED = 0x00000040       /**< The renderer uses hardware 
  36.209 +                                                     acceleration */
  36.210 +    
  36.211 +    } SDL_RendererFlags;
  36.212  
  36.213  /**
  36.214 - * \struct SDL_RendererInfo
  36.215 - *
  36.216 - * \brief Information on the capabilities of a render driver or context
  36.217 + *  \brief Information on the capabilities of a render driver or context.
  36.218   */
  36.219  typedef struct SDL_RendererInfo
  36.220  {
  36.221      const char *name;           /**< The name of the renderer */
  36.222 -    Uint32 flags;               /**< Supported SDL_RendererFlags */
  36.223 +    Uint32 flags;               /**< Supported ::SDL_RendererFlags */
  36.224      Uint32 mod_modes;           /**< A mask of supported channel modulation */
  36.225      Uint32 blend_modes;         /**< A mask of supported blend modes */
  36.226      Uint32 scale_modes;         /**< A mask of supported scale modes */
  36.227 @@ -184,9 +194,7 @@
  36.228  } SDL_RendererInfo;
  36.229  
  36.230  /**
  36.231 - * \enum SDL_TextureAccess
  36.232 - *
  36.233 - * \brief The access pattern allowed for a texture
  36.234 + *  \brief The access pattern allowed for a texture.
  36.235   */
  36.236  typedef enum
  36.237  {
  36.238 @@ -195,9 +203,7 @@
  36.239  } SDL_TextureAccess;
  36.240  
  36.241  /**
  36.242 - * \enum SDL_TextureModulate
  36.243 - *
  36.244 - * \brief The texture channel modulation used in SDL_RenderCopy()
  36.245 + *  \brief The texture channel modulation used in SDL_RenderCopy().
  36.246   */
  36.247  typedef enum
  36.248  {
  36.249 @@ -207,50 +213,49 @@
  36.250  } SDL_TextureModulate;
  36.251  
  36.252  /**
  36.253 - * \enum SDL_BlendMode
  36.254 - *
  36.255 - * \brief The blend mode used in SDL_RenderCopy() and drawing operations
  36.256 + *  \brief The blend mode used in SDL_RenderCopy() and drawing operations.
  36.257   */
  36.258  typedef enum
  36.259  {
  36.260      SDL_BLENDMODE_NONE = 0x00000000,     /**< No blending */
  36.261 -    SDL_BLENDMODE_MASK = 0x00000001,     /**< dst = A ? src : dst (alpha is mask) */
  36.262 +    SDL_BLENDMODE_MASK = 0x00000001,     /**< dst = A ? src : dst 
  36.263 +                                              (alpha is mask) */
  36.264 +    
  36.265      SDL_BLENDMODE_BLEND = 0x00000002,    /**< dst = (src * A) + (dst * (1-A)) */
  36.266      SDL_BLENDMODE_ADD = 0x00000004,      /**< dst = (src * A) + dst */
  36.267      SDL_BLENDMODE_MOD = 0x00000008       /**< dst = src * dst */
  36.268  } SDL_BlendMode;
  36.269  
  36.270  /**
  36.271 - * \enum SDL_TextureScaleMode
  36.272 - *
  36.273 - * \brief The texture scale mode used in SDL_RenderCopy()
  36.274 + *  \brief The texture scale mode used in SDL_RenderCopy().
  36.275   */
  36.276  typedef enum
  36.277  {
  36.278 -    SDL_TEXTURESCALEMODE_NONE = 0x00000000,     /**< No scaling, rectangles must match dimensions */
  36.279 -    SDL_TEXTURESCALEMODE_FAST = 0x00000001,     /**< Point sampling or equivalent algorithm */
  36.280 -    SDL_TEXTURESCALEMODE_SLOW = 0x00000002,     /**< Linear filtering or equivalent algorithm */
  36.281 -    SDL_TEXTURESCALEMODE_BEST = 0x00000004      /**< Bicubic filtering or equivalent algorithm */
  36.282 +    SDL_TEXTURESCALEMODE_NONE = 0x00000000,     /**< No scaling, rectangles must
  36.283 +                                                     match dimensions */
  36.284 +    
  36.285 +    SDL_TEXTURESCALEMODE_FAST = 0x00000001,     /**< Point sampling or 
  36.286 +                                                     equivalent algorithm */
  36.287 +    
  36.288 +    SDL_TEXTURESCALEMODE_SLOW = 0x00000002,     /**< Linear filtering or 
  36.289 +                                                     equivalent algorithm */
  36.290 +    
  36.291 +    SDL_TEXTURESCALEMODE_BEST = 0x00000004      /**< Bicubic filtering or 
  36.292 +                                                     equivalent algorithm */
  36.293  } SDL_TextureScaleMode;
  36.294  
  36.295  /**
  36.296 - * \typedef SDL_TextureID
  36.297 - *
  36.298 - * \brief An efficient driver-specific representation of pixel data
  36.299 + *  \brief An efficient driver-specific representation of pixel data
  36.300   */
  36.301  typedef Uint32 SDL_TextureID;
  36.302  
  36.303  /**
  36.304 - * \typedef SDL_GLContext
  36.305 - *
  36.306 - * \brief An opaque handle to an OpenGL context.
  36.307 + *  \brief An opaque handle to an OpenGL context.
  36.308   */
  36.309  typedef void *SDL_GLContext;
  36.310  
  36.311  /**
  36.312 - * \enum SDL_GLattr
  36.313 - *
  36.314 - * \brief OpenGL configuration attributes
  36.315 + *  \brief OpenGL configuration attributes
  36.316   */
  36.317  typedef enum
  36.318  {
  36.319 @@ -279,156 +284,140 @@
  36.320  /* Function prototypes */
  36.321  
  36.322  /**
  36.323 - * \fn int SDL_GetNumVideoDrivers(void)
  36.324 - *
  36.325 - * \brief Get the number of video drivers compiled into SDL
  36.326 - *
  36.327 - * \sa SDL_GetVideoDriver()
  36.328 + *  \brief Get the number of video drivers compiled into SDL
  36.329 + *  
  36.330 + *  \sa SDL_GetVideoDriver()
  36.331   */
  36.332  extern DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void);
  36.333  
  36.334  /**
  36.335 - * \fn const char *SDL_GetVideoDriver(int index)
  36.336 - *
  36.337 - * \brief Get the name of a built in video driver.
  36.338 - *
  36.339 - * \note The video drivers are presented in the order in which they are
  36.340 - * normally checked during initialization.
  36.341 - *
  36.342 - * \sa SDL_GetNumVideoDrivers()
  36.343 + *  \brief Get the name of a built in video driver.
  36.344 + *  
  36.345 + *  \note The video drivers are presented in the order in which they are
  36.346 + *        normally checked during initialization.
  36.347 + *  
  36.348 + *  \sa SDL_GetNumVideoDrivers()
  36.349   */
  36.350  extern DECLSPEC const char *SDLCALL SDL_GetVideoDriver(int index);
  36.351  
  36.352  /**
  36.353 - * \fn int SDL_VideoInit(const char *driver_name, Uint32 flags)
  36.354 - *
  36.355 - * \brief Initialize the video subsystem, optionally specifying a video driver.
  36.356 - *
  36.357 - * \param driver_name Initialize a specific driver by name, or NULL for the default video driver.
  36.358 - * \param flags FIXME: Still needed?
  36.359 - *
  36.360 - * \return 0 on success, -1 on error
  36.361 - *
  36.362 - * This function initializes the video subsystem; setting up a connection
  36.363 - * to the window manager, etc, and determines the available display modes
  36.364 - * and pixel formats, but does not initialize a window or graphics mode.
  36.365 - *
  36.366 - * \sa SDL_VideoQuit()
  36.367 + *  \brief Initialize the video subsystem, optionally specifying a video driver.
  36.368 + *  
  36.369 + *  \param driver_name Initialize a specific driver by name, or NULL for the 
  36.370 + *                     default video driver.
  36.371 + *  
  36.372 + *  \param flags FIXME: Still needed?
  36.373 + *  
  36.374 + *  \return 0 on success, -1 on error
  36.375 + *  
  36.376 + *  This function initializes the video subsystem; setting up a connection
  36.377 + *  to the window manager, etc, and determines the available display modes
  36.378 + *  and pixel formats, but does not initialize a window or graphics mode.
  36.379 + *  
  36.380 + *  \sa SDL_VideoQuit()
  36.381   */
  36.382  extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name,
  36.383                                            Uint32 flags);
  36.384  
  36.385  /**
  36.386 - * \fn void SDL_VideoQuit(void)
  36.387 - *
  36.388 - * \brief Shuts down the video subsystem.
  36.389 - *
  36.390 - * This function closes all windows, and restores the original video mode.
  36.391 - *
  36.392 - * \sa SDL_VideoInit()
  36.393 + *  \brief Shuts down the video subsystem.
  36.394 + *  
  36.395 + *  This function closes all windows, and restores the original video mode.
  36.396 + *  
  36.397 + *  \sa SDL_VideoInit()
  36.398   */
  36.399  extern DECLSPEC void SDLCALL SDL_VideoQuit(void);
  36.400  
  36.401  /**
  36.402 - * \fn const char *SDL_GetCurrentVideoDriver(void)
  36.403 - *
  36.404 - * \brief Returns the name of the currently initialized video driver.
  36.405 - *
  36.406 - * \return The name of the current video driver or NULL if no driver
  36.407 - *         has been initialized
  36.408 - *
  36.409 - * \sa SDL_GetNumVideoDrivers()
  36.410 - * \sa SDL_GetVideoDriver()
  36.411 + *  \brief Returns the name of the currently initialized video driver.
  36.412 + *  
  36.413 + *  \return The name of the current video driver or NULL if no driver
  36.414 + *          has been initialized
  36.415 + *  
  36.416 + *  \sa SDL_GetNumVideoDrivers()
  36.417 + *  \sa SDL_GetVideoDriver()
  36.418   */
  36.419  extern DECLSPEC const char *SDLCALL SDL_GetCurrentVideoDriver(void);
  36.420  
  36.421  /**
  36.422 - * \fn int SDL_GetNumVideoDisplays(void)
  36.423 - *
  36.424 - * \brief Returns the number of available video displays.
  36.425 - *
  36.426 - * \sa SDL_SelectVideoDisplay()
  36.427 + *  \brief Returns the number of available video displays.
  36.428 + *  
  36.429 + *  \sa SDL_SelectVideoDisplay()
  36.430   */
  36.431  extern DECLSPEC int SDLCALL SDL_GetNumVideoDisplays(void);
  36.432  
  36.433  /**
  36.434 - * \fn int SDL_SelectVideoDisplay(int index)
  36.435 - *
  36.436 - * \brief Set the index of the currently selected display.
  36.437 - *
  36.438 - * \return 0 on success, or -1 if the index is out of range.
  36.439 - *
  36.440 - * \sa SDL_GetNumVideoDisplays()
  36.441 - * \sa SDL_GetCurrentVideoDisplay()
  36.442 + *  \brief Set the index of the currently selected display.
  36.443 + *  
  36.444 + *  \return 0 on success, or -1 if the index is out of range.
  36.445 + *  
  36.446 + *  \sa SDL_GetNumVideoDisplays()
  36.447 + *  \sa SDL_GetCurrentVideoDisplay()
  36.448   */
  36.449  extern DECLSPEC int SDLCALL SDL_SelectVideoDisplay(int index);
  36.450  
  36.451  /**
  36.452 - * \fn int SDL_GetCurrentVideoDisplay(void)
  36.453 - *
  36.454 - * \brief Get the index of the currently selected display.
  36.455 - *
  36.456 - * \return The index of the currently selected display.
  36.457 - *
  36.458 - * \sa SDL_GetNumVideoDisplays()
  36.459 - * \sa SDL_SelectVideoDisplay()
  36.460 + *  \brief Get the index of the currently selected display.
  36.461 + *  
  36.462 + *  \return The index of the currently selected display.
  36.463 + *  
  36.464 + *  \sa SDL_GetNumVideoDisplays()
  36.465 + *  \sa SDL_SelectVideoDisplay()
  36.466   */
  36.467  extern DECLSPEC int SDLCALL SDL_GetCurrentVideoDisplay(void);
  36.468  
  36.469  /**
  36.470 - * \fn int SDL_GetNumDisplayModes(void)
  36.471 - *
  36.472 - * \brief Returns the number of available display modes for the current display.
  36.473 - *
  36.474 - * \sa SDL_GetDisplayMode()
  36.475 + *  \brief Returns the number of available display modes for the current display.
  36.476 + *  
  36.477 + *  \sa SDL_GetDisplayMode()
  36.478   */
  36.479  extern DECLSPEC int SDLCALL SDL_GetNumDisplayModes(void);
  36.480  
  36.481  /**
  36.482 - * \fn int SDL_GetDisplayMode(int index, SDL_DisplayMode *mode)
  36.483 - *
  36.484 - * \brief Fill in information about a specific display mode.
  36.485 - *
  36.486 - * \note The display modes are sorted in this priority:
  36.487 - *       \li bits per pixel -> more colors to fewer colors
  36.488 - *       \li width -> largest to smallest
  36.489 - *       \li height -> largest to smallest
  36.490 - *       \li refresh rate -> highest to lowest
  36.491 - *
  36.492 - * \sa SDL_GetNumDisplayModes()
  36.493 + *  \brief Fill in information about a specific display mode.
  36.494 + *  
  36.495 + *  \note The display modes are sorted in this priority:
  36.496 + *        \li bits per pixel -> more colors to fewer colors
  36.497 + *        \li width -> largest to smallest
  36.498 + *        \li height -> largest to smallest
  36.499 + *        \li refresh rate -> highest to lowest
  36.500 + *  
  36.501 + *  \sa SDL_GetNumDisplayModes()
  36.502   */
  36.503  extern DECLSPEC int SDLCALL SDL_GetDisplayMode(int index,
  36.504                                                 SDL_DisplayMode * mode);
  36.505  
  36.506  /**
  36.507 - * \fn int SDL_GetDesktopDisplayMode(SDL_DisplayMode *mode)
  36.508 - *
  36.509 - * \brief Fill in information about the desktop display mode for the current display.
  36.510 + *  \brief Fill in information about the desktop display mode for the current 
  36.511 + *         display.
  36.512   */
  36.513  extern DECLSPEC int SDLCALL SDL_GetDesktopDisplayMode(SDL_DisplayMode * mode);
  36.514  
  36.515  /**
  36.516 - * \fn int SDL_GetCurrentDisplayMode(SDL_DisplayMode *mode)
  36.517 - *
  36.518 - * \brief Fill in information about the current display mode.
  36.519 + *  \brief Fill in information about the current display mode.
  36.520   */
  36.521  extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(SDL_DisplayMode * mode);
  36.522  
  36.523  
  36.524  /**
  36.525 - * \fn SDL_DisplayMode SDL_GetClosestDisplayMode(const SDL_DisplayMode mode, SDL_DisplayMode closest)
  36.526 - *
  36.527 - * \brief Get the closest match to the requested display mode.
  36.528 - *
  36.529 - * \param mode The desired display mode
  36.530 - * \param closest A pointer to a display mode to be filled in with the closest match of the available display modes.
  36.531 - *
  36.532 - * \return The passed in value 'closest', or NULL if no matching video mode was available.
  36.533 - *
  36.534 - * The available display modes are scanned, and 'closest' is filled in with the closest mode matching the requested mode and returned.  The mode format and refresh_rate default to the desktop mode if they are 0.  The modes are scanned with size being first priority, format being second priority, and finally checking the refresh_rate.  If all the available modes are too small, then NULL is returned.
  36.535 - *
  36.536 - * \sa SDL_GetNumDisplayModes()
  36.537 - * \sa SDL_GetDisplayMode()
  36.538 + *  \brief Get the closest match to the requested display mode.
  36.539 + *  
  36.540 + *  \param mode The desired display mode
  36.541 + *  \param closest A pointer to a display mode to be filled in with the closest 
  36.542 + *                 match of the available display modes.
  36.543 + *  
  36.544 + *  \return The passed in value \c closest, or NULL if no matching video mode 
  36.545 + *          was available.
  36.546 + *  
  36.547 + *  The available display modes are scanned, and \c closest is filled in with the
  36.548 + *  closest mode matching the requested mode and returned.  The mode format and 
  36.549 + *  refresh_rate default to the desktop mode if they are 0.  The modes are 
  36.550 + *  scanned with size being first priority, format being second priority, and 
  36.551 + *  finally checking the refresh_rate.  If all the available modes are too 
  36.552 + *  small, then NULL is returned.
  36.553 + *  
  36.554 + *  \sa SDL_GetNumDisplayModes()
  36.555 + *  \sa SDL_GetDisplayMode()
  36.556   */
  36.557  extern DECLSPEC SDL_DisplayMode *SDLCALL SDL_GetClosestDisplayMode(const
  36.558                                                                     SDL_DisplayMode
  36.559 @@ -437,335 +426,290 @@
  36.560                                                                     * closest);
  36.561  
  36.562  /**
  36.563 - * \fn int SDL_SetFullscreenDisplayMode(const SDL_DisplayMode *mode)
  36.564 - *
  36.565 - * \brief Set the display mode used when a fullscreen window is visible
  36.566 - *        on the currently selected display.
  36.567 - *
  36.568 - * \param mode The mode to use, or NULL for the desktop mode.
  36.569 - *
  36.570 - * \return 0 on success, or -1 if setting the display mode failed.
  36.571 - *
  36.572 - * \sa SDL_SetWindowFullscreen()
  36.573 + *  \brief Set the display mode used when a fullscreen window is visible
  36.574 + *         on the currently selected display.
  36.575 + *  
  36.576 + *  \param mode The mode to use, or NULL for the desktop mode.
  36.577 + *  
  36.578 + *  \return 0 on success, or -1 if setting the display mode failed.
  36.579 + *  
  36.580 + *  \sa SDL_SetWindowFullscreen()
  36.581   */
  36.582  extern DECLSPEC int SDLCALL SDL_SetFullscreenDisplayMode(const SDL_DisplayMode
  36.583                                                           * mode);
  36.584  
  36.585  /**
  36.586 - * \fn int SDL_GetFullscreenDisplayMode(SDL_DisplayMode *mode)
  36.587 - *
  36.588 - * \brief Fill in information about the display mode used when a fullscreen
  36.589 - *        window is visible on the currently selected display.
  36.590 + *  \brief Fill in information about the display mode used when a fullscreen
  36.591 + *         window is visible on the currently selected display.
  36.592   */
  36.593  extern DECLSPEC int SDLCALL SDL_GetFullscreenDisplayMode(SDL_DisplayMode *
  36.594                                                           mode);
  36.595  
  36.596  /**
  36.597 - * \fn int SDL_SetDisplayPalette(const SDL_Color *colors, int firstcolor, int ncolors)
  36.598 - *
  36.599 - * \brief Set the palette entries for indexed display modes.
  36.600 - *
  36.601 - * \return 0 on success, or -1 if the display mode isn't palettized or the colors couldn't be set.
  36.602 + *  \brief Set the palette entries for indexed display modes.
  36.603 + *  
  36.604 + *  \return 0 on success, or -1 if the display mode isn't palettized or the 
  36.605 + *          colors couldn't be set.
  36.606   */
  36.607  extern DECLSPEC int SDLCALL SDL_SetDisplayPalette(const SDL_Color * colors,
  36.608                                                    int firstcolor,
  36.609                                                    int ncolors);
  36.610  
  36.611  /**
  36.612 - * \fn int SDL_GetDisplayPalette(SDL_Color *colors, int firstcolor, int ncolors)
  36.613 - *
  36.614 - * \brief Gets the palette entries for indexed display modes.
  36.615 - *
  36.616 - * \return 0 on success, or -1 if the display mode isn't palettized
  36.617 + *  \brief Gets the palette entries for indexed display modes.
  36.618 + *  
  36.619 + *  \return 0 on success, or -1 if the display mode isn't palettized
  36.620   */
  36.621  extern DECLSPEC int SDLCALL SDL_GetDisplayPalette(SDL_Color * colors,
  36.622                                                    int firstcolor,
  36.623                                                    int ncolors);
  36.624  
  36.625  /**
  36.626 - * \fn int SDL_SetGamma(float red, float green, float blue)
  36.627 - *
  36.628 - * \brief Set the gamma correction for each of the color channels on the currently selected display.
  36.629 - *
  36.630 - * \return 0 on success, or -1 if setting the gamma isn't supported.
  36.631 - *
  36.632 - * \sa SDL_SetGammaRamp()
  36.633 + *  \brief Set the gamma correction for each of the color channels on the 
  36.634 + *         currently selected display.
  36.635 + *