* Update SDL headers and win32 libs to 1.2.14

code/SDL12/include/SDL.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -20,7 +20,9 @@
     slouken@libsdl.org
 */
 
-/* Main include header for the SDL library */
+/** @file SDL.h
+ *  Main include header for the SDL library
+ */
 
 #ifndef _SDL_H
 #define _SDL_H
@@ -47,40 +49,45 @@
 extern "C" {
 #endif
 
-/* As of version 0.5, SDL is loaded dynamically into the application */
+/** @file SDL.h
-
+ *  @note As of version 0.5, SDL is loaded dynamically into the application
-/* These are the flags which may be passed to SDL_Init() -- you should
-   specify the subsystems which you will be using in your application.
  */
+
+/** @name SDL_INIT Flags
+ *  These are the flags which may be passed to SDL_Init() -- you should
+ *  specify the subsystems which you will be using in your application.
+ */
+/*@{*/
 #define	SDL_INIT_TIMER		0x00000001
 #define SDL_INIT_AUDIO		0x00000010
 #define SDL_INIT_VIDEO		0x00000020
 #define SDL_INIT_CDROM		0x00000100
 #define SDL_INIT_JOYSTICK	0x00000200
-#define SDL_INIT_NOPARACHUTE	0x00100000	/* Don't catch fatal signals */
+#define SDL_INIT_NOPARACHUTE	0x00100000	/**< Don't catch fatal signals */
-#define SDL_INIT_EVENTTHREAD	0x01000000	/* Not supported on all OS's */
+#define SDL_INIT_EVENTTHREAD	0x01000000	/**< Not supported on all OS's */
 #define SDL_INIT_EVERYTHING	0x0000FFFF
+/*@}*/
 
-/* This function loads the SDL dynamically linked library and initializes 
+/** This function loads the SDL dynamically linked library and initializes 
  *  the subsystems specified by 'flags' (and those satisfying dependencies)
  *  Unless the SDL_INIT_NOPARACHUTE flag is set, it will install cleanup
  *  signal handlers for some commonly ignored fatal signals (like SIGSEGV)
  */
 extern DECLSPEC int SDLCALL SDL_Init(Uint32 flags);
 
-/* This function initializes specific SDL subsystems */
+/** This function initializes specific SDL subsystems */
 extern DECLSPEC int SDLCALL SDL_InitSubSystem(Uint32 flags);
 
-/* This function cleans up specific SDL subsystems */
+/** This function cleans up specific SDL subsystems */
 extern DECLSPEC void SDLCALL SDL_QuitSubSystem(Uint32 flags);
 
-/* This function returns mask of the specified subsystems which have
+/** This function returns mask of the specified subsystems which have
-   been initialized.
+ *  been initialized.
-   If 'flags' is 0, it returns a mask of all initialized subsystems.
+ *  If 'flags' is 0, it returns a mask of all initialized subsystems.
  */
 extern DECLSPEC Uint32 SDLCALL SDL_WasInit(Uint32 flags);
 
-/* This function cleans up all initialized subsystems and unloads the
+/** This function cleans up all initialized subsystems and unloads the
  *  dynamically linked library.  You should call it upon all exit conditions.
  */
 extern DECLSPEC void SDLCALL SDL_Quit(void);

code/SDL12/include/SDL_active.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -20,7 +20,10 @@
     slouken@libsdl.org
 */
 
-/* Include file for SDL application focus event handling */
+/**
+ *  @file SDL_active.h
+ *  Include file for SDL application focus event handling 
+ */
 
 #ifndef _SDL_active_h
 #define _SDL_active_h
@@ -34,13 +37,15 @@
 extern "C" {
 #endif
 
-/* The available application states */
+/** @name The available application states */
-#define SDL_APPMOUSEFOCUS	0x01		/* The app has mouse coverage */
+/*@{*/
-#define SDL_APPINPUTFOCUS	0x02		/* The app has input focus */
+#define SDL_APPMOUSEFOCUS	0x01		/**< The app has mouse coverage */
-#define SDL_APPACTIVE		0x04		/* The application is active */
+#define SDL_APPINPUTFOCUS	0x02		/**< The app has input focus */
+#define SDL_APPACTIVE		0x04		/**< The application is active */
+/*@}*/
 
 /* Function prototypes */
-/* 
+/** 
  * This function returns the current state of the application, which is a
  * bitwise combination of SDL_APPMOUSEFOCUS, SDL_APPINPUTFOCUS, and
  * SDL_APPACTIVE.  If SDL_APPACTIVE is set, then the user is able to

code/SDL12/include/SDL_audio.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -20,7 +20,10 @@
     slouken@libsdl.org
 */
 
-/* Access to the raw audio mixing buffer for the SDL library */
+/**
+ *  @file SDL_audio.h
+ *  Access to the raw audio mixing buffer for the SDL library
+ */
 
 #ifndef _SDL_audio_h
 #define _SDL_audio_h
@@ -38,89 +41,11 @@
 extern "C" {
 #endif
 
-/* The calculated values in this structure are calculated by SDL_OpenAudio() */
+/**
-typedef struct SDL_AudioSpec {
-	int freq;		/* DSP frequency -- samples per second */
-	Uint16 format;		/* Audio data format */
-	Uint8  channels;	/* Number of channels: 1 mono, 2 stereo */
-	Uint8  silence;		/* Audio buffer silence value (calculated) */
-	Uint16 samples;		/* Audio buffer size in samples (power of 2) */
-	Uint16 padding;		/* Necessary for some compile environments */
-	Uint32 size;		/* Audio buffer size in bytes (calculated) */
-	/* This function is called when the audio device needs more data.
-	   'stream' is a pointer to the audio data buffer
-	   'len' is the length of that buffer in bytes.
-	   Once the callback returns, the buffer will no longer be valid.
-	   Stereo samples are stored in a LRLRLR ordering.
-	*/
-	void (SDLCALL *callback)(void *userdata, Uint8 *stream, int len);
-	void  *userdata;
-} SDL_AudioSpec;
-
-/* Audio format flags (defaults to LSB byte order) */
-#define AUDIO_U8	0x0008	/* Unsigned 8-bit samples */
-#define AUDIO_S8	0x8008	/* Signed 8-bit samples */
-#define AUDIO_U16LSB	0x0010	/* Unsigned 16-bit samples */
-#define AUDIO_S16LSB	0x8010	/* Signed 16-bit samples */
-#define AUDIO_U16MSB	0x1010	/* As above, but big-endian byte order */
-#define AUDIO_S16MSB	0x9010	/* As above, but big-endian byte order */
-#define AUDIO_U16	AUDIO_U16LSB
-#define AUDIO_S16	AUDIO_S16LSB
-
-/* Native audio byte ordering */
-#if SDL_BYTEORDER == SDL_LIL_ENDIAN
-#define AUDIO_U16SYS	AUDIO_U16LSB
-#define AUDIO_S16SYS	AUDIO_S16LSB
-#else
-#define AUDIO_U16SYS	AUDIO_U16MSB
-#define AUDIO_S16SYS	AUDIO_S16MSB
-#endif
-
-
-/* A structure to hold a set of audio conversion filters and buffers */
-typedef struct SDL_AudioCVT {
-	int needed;			/* Set to 1 if conversion possible */
-	Uint16 src_format;		/* Source audio format */
-	Uint16 dst_format;		/* Target audio format */
-	double rate_incr;		/* Rate conversion increment */
-	Uint8 *buf;			/* Buffer to hold entire audio data */
-	int    len;			/* Length of original audio buffer */
-	int    len_cvt;			/* Length of converted audio buffer */
-	int    len_mult;		/* buffer must be len*len_mult big */
-	double len_ratio; 	/* Given len, final size is len*len_ratio */
-	void (SDLCALL *filters[10])(struct SDL_AudioCVT *cvt, Uint16 format);
-	int filter_index;		/* Current audio conversion function */
-} SDL_AudioCVT;
-
-
-/* Function prototypes */
-
-/* These functions are used internally, and should not be used unless you
- * have a specific need to specify the audio driver you want to use.
- * You should normally use SDL_Init() or SDL_InitSubSystem().
- */
-extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name);
-extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
-
-/* This function fills the given character buffer with the name of the
- * current audio driver, and returns a pointer to it if the audio driver has
- * been initialized.  It returns NULL if no driver has been initialized.
- */
-extern DECLSPEC char * SDLCALL SDL_AudioDriverName(char *namebuf, int maxlen);
-
-/*
- * This function opens the audio device with the desired parameters, and
- * returns 0 if successful, placing the actual hardware parameters in the
- * structure pointed to by 'obtained'.  If 'obtained' is NULL, the audio
- * data passed to the callback function will be guaranteed to be in the
- * requested format, and will be automatically converted to the hardware
- * audio format if necessary.  This function returns -1 if it failed 
- * to open the audio device, or couldn't set up the audio thread.
- *
  * When filling in the desired audio spec structure,
- *  'desired->freq' should be the desired audio frequency in samples-per-second.
+ * - 'desired->freq' should be the desired audio frequency in samples-per-second.
- *  'desired->format' should be the desired audio format.
+ * - 'desired->format' should be the desired audio format.
- *  'desired->samples' is the desired size of the audio buffer, in samples.
+ * - 'desired->samples' is the desired size of the audio buffer, in samples.
  *     This number should be a power of two, and may be adjusted by the audio
  *     driver to a value more suitable for the hardware.  Good values seem to
  *     range between 512 and 8096 inclusive, depending on the application and
@@ -130,38 +55,138 @@ extern DECLSPEC char * SDLCALL SDL_AudioDriverName(char *namebuf, int maxlen);
  *     and left channels in LR ordering.
  *     Note that the number of samples is directly related to time by the
  *     following formula:  ms = (samples*1000)/freq
- *  'desired->size' is the size in bytes of the audio buffer, and is
+ * - 'desired->size' is the size in bytes of the audio buffer, and is
  *     calculated by SDL_OpenAudio().
- *  'desired->silence' is the value used to set the buffer to silence,
+ * - 'desired->silence' is the value used to set the buffer to silence,
  *     and is calculated by SDL_OpenAudio().
- *  'desired->callback' should be set to a function that will be called
+ * - 'desired->callback' should be set to a function that will be called
  *     when the audio device is ready for more data.  It is passed a pointer
  *     to the audio buffer, and the length in bytes of the audio buffer.
  *     This function usually runs in a separate thread, and so you should
  *     protect data structures that it accesses by calling SDL_LockAudio()
  *     and SDL_UnlockAudio() in your code.
- *  'desired->userdata' is passed as the first parameter to your callback
+ * - 'desired->userdata' is passed as the first parameter to your callback
  *     function.
  *
+ * @note The calculated values in this structure are calculated by SDL_OpenAudio()
+ *
+ */
+typedef struct SDL_AudioSpec {
+	int freq;		/**< DSP frequency -- samples per second */
+	Uint16 format;		/**< Audio data format */
+	Uint8  channels;	/**< Number of channels: 1 mono, 2 stereo */
+	Uint8  silence;		/**< Audio buffer silence value (calculated) */
+	Uint16 samples;		/**< Audio buffer size in samples (power of 2) */
+	Uint16 padding;		/**< Necessary for some compile environments */
+	Uint32 size;		/**< Audio buffer size in bytes (calculated) */
+	/**
+	 *  This function is called when the audio device needs more data.
+	 *
+	 *  @param[out] stream	A pointer to the audio data buffer
+	 *  @param[in]  len	The length of the audio buffer in bytes.
+	 *
+	 *  Once the callback returns, the buffer will no longer be valid.
+	 *  Stereo samples are stored in a LRLRLR ordering.
+	 */
+	void (SDLCALL *callback)(void *userdata, Uint8 *stream, int len);
+	void  *userdata;
+} SDL_AudioSpec;
+
+/**
+ *  @name Audio format flags
+ *  defaults to LSB byte order
+ */
+/*@{*/
+#define AUDIO_U8	0x0008	/**< Unsigned 8-bit samples */
+#define AUDIO_S8	0x8008	/**< Signed 8-bit samples */
+#define AUDIO_U16LSB	0x0010	/**< Unsigned 16-bit samples */
+#define AUDIO_S16LSB	0x8010	/**< Signed 16-bit samples */
+#define AUDIO_U16MSB	0x1010	/**< As above, but big-endian byte order */
+#define AUDIO_S16MSB	0x9010	/**< As above, but big-endian byte order */
+#define AUDIO_U16	AUDIO_U16LSB
+#define AUDIO_S16	AUDIO_S16LSB
+
+/**
+ *  @name Native audio byte ordering
+ */
+/*@{*/
+#if SDL_BYTEORDER == SDL_LIL_ENDIAN
+#define AUDIO_U16SYS	AUDIO_U16LSB
+#define AUDIO_S16SYS	AUDIO_S16LSB
+#else
+#define AUDIO_U16SYS	AUDIO_U16MSB
+#define AUDIO_S16SYS	AUDIO_S16MSB
+#endif
+/*@}*/
+
+/*@}*/
+
+
+/** A structure to hold a set of audio conversion filters and buffers */
+typedef struct SDL_AudioCVT {
+	int needed;			/**< Set to 1 if conversion possible */
+	Uint16 src_format;		/**< Source audio format */
+	Uint16 dst_format;		/**< Target audio format */
+	double rate_incr;		/**< Rate conversion increment */
+	Uint8 *buf;			/**< Buffer to hold entire audio data */
+	int    len;			/**< Length of original audio buffer */
+	int    len_cvt;			/**< Length of converted audio buffer */
+	int    len_mult;		/**< buffer must be len*len_mult big */
+	double len_ratio; 	/**< Given len, final size is len*len_ratio */
+	void (SDLCALL *filters[10])(struct SDL_AudioCVT *cvt, Uint16 format);
+	int filter_index;		/**< Current audio conversion function */
+} SDL_AudioCVT;
+
+
+/* Function prototypes */
+
+/**
+ * @name Audio Init and Quit
+ * These functions are used internally, and should not be used unless you
+ * have a specific need to specify the audio driver you want to use.
+ * You should normally use SDL_Init() or SDL_InitSubSystem().
+ */
+/*@{*/
+extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name);
+extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
+/*@}*/
+
+/**
+ * This function fills the given character buffer with the name of the
+ * current audio driver, and returns a pointer to it if the audio driver has
+ * been initialized.  It returns NULL if no driver has been initialized.
+ */
+extern DECLSPEC char * SDLCALL SDL_AudioDriverName(char *namebuf, int maxlen);
+
+/**
+ * This function opens the audio device with the desired parameters, and
+ * returns 0 if successful, placing the actual hardware parameters in the
+ * structure pointed to by 'obtained'.  If 'obtained' is NULL, the audio
+ * data passed to the callback function will be guaranteed to be in the
+ * requested format, and will be automatically converted to the hardware
+ * audio format if necessary.  This function returns -1 if it failed 
+ * to open the audio device, or couldn't set up the audio thread.
+ *
  * The audio device starts out playing silence when it's opened, and should
  * be enabled for playing by calling SDL_PauseAudio(0) when you are ready
  * for your audio callback function to be called.  Since the audio driver
  * may modify the requested size of the audio buffer, you should allocate
  * any local mixing buffers after you open the audio device.
+ *
+ * @sa SDL_AudioSpec
  */
 extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec *desired, SDL_AudioSpec *obtained);
 
-/*
- * Get the current audio state:
- */
 typedef enum {
 	SDL_AUDIO_STOPPED = 0,
 	SDL_AUDIO_PLAYING,
 	SDL_AUDIO_PAUSED
 } SDL_audiostatus;
+
+/** Get the current audio state */
 extern DECLSPEC SDL_audiostatus SDLCALL SDL_GetAudioStatus(void);
 
-/*
+/**
  * This function pauses and unpauses the audio callback processing.
  * It should be called with a parameter of 0 after opening the audio
  * device to start playing sound.  This is so you can safely initialize
@@ -170,11 +195,11 @@ extern DECLSPEC SDL_audiostatus SDLCALL SDL_GetAudioStatus(void);
  */
 extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
 
-/*
+/**
  * This function loads a WAVE from the data source, automatically freeing
  * that source if 'freesrc' is non-zero.  For example, to load a WAVE file,
  * you could do:
- *	SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...);
+ *	@code SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...); @endcode
  *
  * If this function succeeds, it returns the given SDL_AudioSpec,
  * filled with the audio data format of the wave data, and sets
@@ -189,27 +214,29 @@ extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
  */
 extern DECLSPEC SDL_AudioSpec * SDLCALL SDL_LoadWAV_RW(SDL_RWops *src, int freesrc, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len);
 
-/* Compatibility convenience function -- loads a WAV from a file */
+/** Compatibility convenience function -- loads a WAV from a file */
 #define SDL_LoadWAV(file, spec, audio_buf, audio_len) \
 	SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
 
-/*
+/**
  * This function frees data previously allocated with SDL_LoadWAV_RW()
  */
 extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 *audio_buf);
 
-/*
+/**
  * This function takes a source format and rate and a destination format
  * and rate, and initializes the 'cvt' structure with information needed
  * by SDL_ConvertAudio() to convert a buffer of audio data from one format
  * to the other.
- * This function returns 0, or -1 if there was an error.
+ *
+ * @return This function returns 0, or -1 if there was an error.
  */
 extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT *cvt,
 		Uint16 src_format, Uint8 src_channels, int src_rate,
 		Uint16 dst_format, Uint8 dst_channels, int dst_rate);
 
-/* Once you have initialized the 'cvt' structure using SDL_BuildAudioCVT(),
+/**
+ * Once you have initialized the 'cvt' structure using SDL_BuildAudioCVT(),
  * created an audio buffer cvt->buf, and filled it with cvt->len bytes of
  * audio data in the source format, this function will convert it in-place
  * to the desired format.
@@ -219,26 +246,30 @@ extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT *cvt,
  */
 extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT *cvt);
 
-/*
+
+#define SDL_MIX_MAXVOLUME 128
+/**
  * This takes two audio buffers of the playing audio format and mixes
  * them, performing addition, volume adjustment, and overflow clipping.
  * The volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
  * for full audio volume.  Note this does not change hardware volume.
  * This is provided for convenience -- you can mix your own audio data.
  */
-#define SDL_MIX_MAXVOLUME 128
 extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, Uint32 len, int volume);
 
-/*
+/**
+ * @name Audio Locks
  * The lock manipulated by these functions protects the callback function.
  * During a LockAudio/UnlockAudio pair, you can be guaranteed that the
  * callback function is not running.  Do not call these from the callback
  * function or you will cause deadlock.
  */
+/*@{*/
 extern DECLSPEC void SDLCALL SDL_LockAudio(void);
 extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
+/*@}*/
 
-/*
+/**
  * This function shuts down audio processing and closes the audio device.
  */
 extern DECLSPEC void SDLCALL SDL_CloseAudio(void);

code/SDL12/include/SDL_byteorder.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -20,5 +20,10 @@
     slouken@libsdl.org
 */
 
+/**
+ *  @file SDL_byteorder.h
+ *  @deprecated Use SDL_endian.h instead
+ */
+
 /* DEPRECATED */
 #include "SDL_endian.h"

code/SDL12/include/SDL_cdrom.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -20,7 +20,10 @@
     slouken@libsdl.org
 */
 
-/* This is the CD-audio control API for Simple DirectMedia Layer */
+/**
+ *  @file SDL_cdrom.h
+ *  This is the CD-audio control API for Simple DirectMedia Layer
+ */
 
 #ifndef _SDL_cdrom_h
 #define _SDL_cdrom_h
@@ -34,19 +37,25 @@
 extern "C" {
 #endif
 
-/* In order to use these functions, SDL_Init() must have been called
+/**
-   with the SDL_INIT_CDROM flag.  This causes SDL to scan the system
+ *  @file SDL_cdrom.h
-   for CD-ROM drives, and load appropriate drivers.
+ *  In order to use these functions, SDL_Init() must have been called
+ *  with the SDL_INIT_CDROM flag.  This causes SDL to scan the system
+ *  for CD-ROM drives, and load appropriate drivers.
  */
 
-/* The maximum number of CD-ROM tracks on a disk */
+/** The maximum number of CD-ROM tracks on a disk */
 #define SDL_MAX_TRACKS	99
 
-/* The types of CD-ROM track possible */
+/** @name Track Types
+ *  The types of CD-ROM track possible
+ */
+/*@{*/
 #define SDL_AUDIO_TRACK	0x00
 #define SDL_DATA_TRACK	0x04
+/*@}*/
 
-/* The possible states which a CD-ROM drive can be in. */
+/** The possible states which a CD-ROM drive can be in. */
 typedef enum {
 	CD_TRAYEMPTY,
 	CD_STOPPED,
@@ -55,30 +64,35 @@ typedef enum {
 	CD_ERROR = -1
 } CDstatus;
 
-/* Given a status, returns true if there's a disk in the drive */
+/** Given a status, returns true if there's a disk in the drive */
 #define CD_INDRIVE(status)	((int)(status) > 0)
 
 typedef struct SDL_CDtrack {
-	Uint8 id;		/* Track number */
+	Uint8 id;		/**< Track number */
-	Uint8 type;		/* Data or audio track */
+	Uint8 type;		/**< Data or audio track */
 	Uint16 unused;
-	Uint32 length;		/* Length, in frames, of this track */
+	Uint32 length;		/**< Length, in frames, of this track */
-	Uint32 offset;		/* Offset, in frames, from start of disk */
+	Uint32 offset;		/**< Offset, in frames, from start of disk */
 } SDL_CDtrack;
 
-/* This structure is only current as of the last call to SDL_CDStatus() */
+/** This structure is only current as of the last call to SDL_CDStatus() */
 typedef struct SDL_CD {
-	int id;			/* Private drive identifier */
+	int id;			/**< Private drive identifier */
-	CDstatus status;	/* Current drive status */
+	CDstatus status;	/**< Current drive status */
 
-	/* The rest of this structure is only valid if there's a CD in drive */
+	/** The rest of this structure is only valid if there's a CD in drive */
-	int numtracks;		/* Number of tracks on disk */
+        /*@{*/
-	int cur_track;		/* Current track position */
+	int numtracks;		/**< Number of tracks on disk */
-	int cur_frame;		/* Current frame offset within current track */
+	int cur_track;		/**< Current track position */
+	int cur_frame;		/**< Current frame offset within current track */
 	SDL_CDtrack track[SDL_MAX_TRACKS+1];
+        /*@}*/
 } SDL_CD;
 
-/* Conversion functions from frames to Minute/Second/Frames and vice versa */
+/** @name Frames / MSF Conversion Functions
+ *  Conversion functions from frames to Minute/Second/Frames and vice versa
+ */
+/*@{*/
 #define CD_FPS	75
 #define FRAMES_TO_MSF(f, M,S,F)	{					\
 	int value = f;							\
@@ -89,76 +103,93 @@ typedef struct SDL_CD {
 	*(M) = value;							\
 }
 #define MSF_TO_FRAMES(M, S, F)	((M)*60*CD_FPS+(S)*CD_FPS+(F))
+/*@}*/
 
 /* CD-audio API functions: */
 
-/* Returns the number of CD-ROM drives on the system, or -1 if
+/**
-   SDL_Init() has not been called with the SDL_INIT_CDROM flag.
+ *  Returns the number of CD-ROM drives on the system, or -1 if
+ *  SDL_Init() has not been called with the SDL_INIT_CDROM flag.
  */
 extern DECLSPEC int SDLCALL SDL_CDNumDrives(void);
 
-/* Returns a human-readable, system-dependent identifier for the CD-ROM.
+/**
-   Example:
+ *  Returns a human-readable, system-dependent identifier for the CD-ROM.
-	"/dev/cdrom"
+ *  Example:
-	"E:"
+ *   - "/dev/cdrom"
-	"/dev/disk/ide/1/master"
+ *   - "E:"
+ *   - "/dev/disk/ide/1/master"
  */
 extern DECLSPEC const char * SDLCALL SDL_CDName(int drive);
 
-/* Opens a CD-ROM drive for access.  It returns a drive handle on success,
+/**
-   or NULL if the drive was invalid or busy.  This newly opened CD-ROM
+ *  Opens a CD-ROM drive for access.  It returns a drive handle on success,
-   becomes the default CD used when other CD functions are passed a NULL
+ *  or NULL if the drive was invalid or busy.  This newly opened CD-ROM
-   CD-ROM handle.
+ *  becomes the default CD used when other CD functions are passed a NULL
-   Drives are numbered starting with 0.  Drive 0 is the system default CD-ROM.
+ *  CD-ROM handle.
+ *  Drives are numbered starting with 0.  Drive 0 is the system default CD-ROM.
  */
 extern DECLSPEC SDL_CD * SDLCALL SDL_CDOpen(int drive);
 
-/* This function returns the current status of the given drive.
+/**
-   If the drive has a CD in it, the table of contents of the CD and current
+ *  This function returns the current status of the given drive.
-   play position of the CD will be stored in the SDL_CD structure.
+ *  If the drive has a CD in it, the table of contents of the CD and current
+ *  play position of the CD will be stored in the SDL_CD structure.
  */
 extern DECLSPEC CDstatus SDLCALL SDL_CDStatus(SDL_CD *cdrom);
 
-/* Play the given CD starting at 'start_track' and 'start_frame' for 'ntracks'
+/**
-   tracks and 'nframes' frames.  If both 'ntrack' and 'nframe' are 0, play 
+ *  Play the given CD starting at 'start_track' and 'start_frame' for 'ntracks'
-   until the end of the CD.  This function will skip data tracks.
+ *  tracks and 'nframes' frames.  If both 'ntrack' and 'nframe' are 0, play 
-   This function should only be called after calling SDL_CDStatus() to 
+ *  until the end of the CD.  This function will skip data tracks.
-   get track information about the CD.
+ *  This function should only be called after calling SDL_CDStatus() to 
-   For example:
+ *  get track information about the CD.
-	// Play entire CD:
+ *  For example:
-	if ( CD_INDRIVE(SDL_CDStatus(cdrom)) )
+ *      @code
-		SDL_CDPlayTracks(cdrom, 0, 0, 0, 0);
+ *	// Play entire CD:
-	// Play last track:
+ *	if ( CD_INDRIVE(SDL_CDStatus(cdrom)) )
-	if ( CD_INDRIVE(SDL_CDStatus(cdrom)) ) {
+ *		SDL_CDPlayTracks(cdrom, 0, 0, 0, 0);
-		SDL_CDPlayTracks(cdrom, cdrom->numtracks-1, 0, 0, 0);
+ *	// Play last track:
-	}
+ *	if ( CD_INDRIVE(SDL_CDStatus(cdrom)) ) {
-	// Play first and second track and 10 seconds of third track:
+ *		SDL_CDPlayTracks(cdrom, cdrom->numtracks-1, 0, 0, 0);
-	if ( CD_INDRIVE(SDL_CDStatus(cdrom)) )
+ *	}
-		SDL_CDPlayTracks(cdrom, 0, 0, 2, 10);
+ *	// Play first and second track and 10 seconds of third track:
-
+ *	if ( CD_INDRIVE(SDL_CDStatus(cdrom)) )
-   This function returns 0, or -1 if there was an error.
+ *		SDL_CDPlayTracks(cdrom, 0, 0, 2, 10);
+ *      @endcode
+ *
+ *  @return This function returns 0, or -1 if there was an error.
  */
 extern DECLSPEC int SDLCALL SDL_CDPlayTracks(SDL_CD *cdrom,
 		int start_track, int start_frame, int ntracks, int nframes);
 
-/* Play the given CD starting at 'start' frame for 'length' frames.
+/**
-   It returns 0, or -1 if there was an error.
+ *  Play the given CD starting at 'start' frame for 'length' frames.
+ *  @return It returns 0, or -1 if there was an error.
  */
 extern DECLSPEC int SDLCALL SDL_CDPlay(SDL_CD *cdrom, int start, int length);
 
-/* Pause play -- returns 0, or -1 on error */
+/** Pause play
+ *  @return returns 0, or -1 on error
+ */
 extern DECLSPEC int SDLCALL SDL_CDPause(SDL_CD *cdrom);
 
-/* Resume play -- returns 0, or -1 on error */
+/** Resume play
+ *  @return returns 0, or -1 on error
+ */
 extern DECLSPEC int SDLCALL SDL_CDResume(SDL_CD *cdrom);
 
-/* Stop play -- returns 0, or -1 on error */
+/** Stop play
+ *  @return returns 0, or -1 on error
+ */
 extern DECLSPEC int SDLCALL SDL_CDStop(SDL_CD *cdrom);
 
-/* Eject CD-ROM -- returns 0, or -1 on error */
+/** Eject CD-ROM
+ *  @return returns 0, or -1 on error
+ */
 extern DECLSPEC int SDLCALL SDL_CDEject(SDL_CD *cdrom);
 
-/* Closes the handle for the CD-ROM drive */
+/** Closes the handle for the CD-ROM drive */
 extern DECLSPEC void SDLCALL SDL_CDClose(SDL_CD *cdrom);
 
 

code/SDL12/include/SDL_config.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -26,14 +26,14 @@
 #include "SDL_platform.h"
 
 /* Add any platform that doesn't build using the configure system */
-#if defined(__AMIGA__)
+#if defined(__DREAMCAST__)
-#include "SDL_config_amiga.h"
-#elif defined(__DREAMCAST__)
 #include "SDL_config_dreamcast.h"
 #elif defined(__MACOS__)
 #include "SDL_config_macos.h"
 #elif defined(__MACOSX__)
 #include "SDL_config_macosx.h"
+#elif defined(__SYMBIAN32__)
+#include "SDL_config_symbian.h"  /* must be before win32! */
 #elif defined(__WIN32__)
 #include "SDL_config_win32.h"
 #elif defined(__OS2__)

code/SDL12/include/SDL_config_dreamcast.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public

code/SDL12/include/SDL_config_macos.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public

code/SDL12/include/SDL_config_macosx.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -25,6 +25,9 @@
 
 #include "SDL_platform.h"
 
+/* This gets us MAC_OS_X_VERSION_MIN_REQUIRED... */
+#include <AvailabilityMacros.h>
+
 /* This is a set of defines to configure the SDL features */
 
 #define SDL_HAS_64BIT_TYPE	1
@@ -87,7 +90,6 @@
 
 /* Enable various audio drivers */
 #define SDL_AUDIO_DRIVER_COREAUDIO	1
-#define SDL_AUDIO_DRIVER_SNDMGR	1
 #define SDL_AUDIO_DRIVER_DISK	1
 #define SDL_AUDIO_DRIVER_DUMMY	1
 
@@ -114,14 +116,30 @@
 
 /* Enable various video drivers */
 #define SDL_VIDEO_DRIVER_DUMMY	1
-#if TARGET_API_MAC_CARBON
+#if ((defined TARGET_API_MAC_CARBON) && (TARGET_API_MAC_CARBON))
 #define SDL_VIDEO_DRIVER_TOOLBOX	1
 #else
 #define SDL_VIDEO_DRIVER_QUARTZ	1
 #endif
+#define SDL_VIDEO_DRIVER_DGA 1
+#define SDL_VIDEO_DRIVER_X11 1
+#define SDL_VIDEO_DRIVER_X11_DGAMOUSE 1
+#define SDL_VIDEO_DRIVER_X11_DYNAMIC "/usr/X11R6/lib/libX11.6.dylib"
+#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XEXT "/usr/X11R6/lib/libXext.6.dylib"
+#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XRANDR "/usr/X11R6/lib/libXrandr.2.dylib"
+#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XRENDER "/usr/X11R6/lib/libXrender.1.dylib"
+#define SDL_VIDEO_DRIVER_X11_VIDMODE 1
+#define SDL_VIDEO_DRIVER_X11_XINERAMA 1
+#define SDL_VIDEO_DRIVER_X11_XME 1
+#define SDL_VIDEO_DRIVER_X11_XRANDR 1
+#define SDL_VIDEO_DRIVER_X11_XV 1
 
 /* Enable OpenGL support */
 #define SDL_VIDEO_OPENGL	1
+#define SDL_VIDEO_OPENGL_GLX 1
+
+/* Disable screensaver */
+#define SDL_VIDEO_DISABLE_SCREENSAVER	1
 
 /* Enable assembly routines */
 #define SDL_ASSEMBLY_ROUTINES	1

code/SDL12/include/SDL_config_minimal.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public

code/SDL12/include/SDL_config_nds.h

@@ -0,0 +1,115 @@
+/*
+    SDL - Simple DirectMedia Layer
+    Copyright (C) 1997-2009 Sam Lantinga
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation; either
+    version 2.1 of the License, or (at your option) any later version.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+
+    Sam Lantinga
+    slouken@libsdl.org
+*/
+
+#ifndef _SDL_config_nds_h
+#define _SDL_config_nds_h
+
+#include "SDL_platform.h"
+
+/* This is a set of defines to configure the SDL features */
+
+/* General platform specific identifiers */
+#include "SDL_platform.h"
+
+/* C datatypes */
+#define SDL_HAS_64BIT_TYPE 1
+
+/* Endianness */
+#define SDL_BYTEORDER 1234
+
+/* Useful headers */
+#define HAVE_ALLOCA_H 1
+#define HAVE_SYS_TYPES_H 1
+#define HAVE_STDIO_H 1
+#define STDC_HEADERS 1
+#define HAVE_STDLIB_H 1
+#define HAVE_STDARG_H 1
+#define HAVE_MALLOC_H 1
+#define HAVE_STRING_H 1
+#define HAVE_INTTYPES_H 1
+#define HAVE_STDINT_H 1
+#define HAVE_CTYPE_H 1
+#define HAVE_MATH_H 1
+#define HAVE_ICONV_H 1
+#define HAVE_SIGNAL_H 1
+
+/* C library functions */
+#define HAVE_MALLOC 1
+#define HAVE_CALLOC 1
+#define HAVE_REALLOC 1
+#define HAVE_FREE 1
+#define HAVE_ALLOCA 1
+#define HAVE_GETENV 1
+#define HAVE_PUTENV 1
+#define HAVE_UNSETENV 1
+#define HAVE_QSORT 1
+#define HAVE_ABS 1
+#define HAVE_BCOPY 1
+#define HAVE_MEMSET 1
+#define HAVE_MEMCPY 1
+#define HAVE_MEMMOVE 1
+#define HAVE_STRLEN 1
+#define HAVE_STRLCPY 1
+#define HAVE_STRLCAT 1
+#define HAVE_STRDUP 1
+#define HAVE_STRCHR 1
+#define HAVE_STRRCHR 1
+#define HAVE_STRSTR 1
+#define HAVE_STRTOL 1
+#define HAVE_STRTOUL 1
+#define HAVE_STRTOLL 1
+#define HAVE_STRTOULL 1
+#define HAVE_ATOI 1
+#define HAVE_ATOF 1
+#define HAVE_STRCMP 1
+#define HAVE_STRNCMP 1
+#define HAVE_STRCASECMP 1
+#define HAVE_STRNCASECMP 1
+#define HAVE_SSCANF 1
+#define HAVE_SNPRINTF 1
+#define HAVE_VSNPRINTF 1
+#define HAVE_SETJMP 1
+
+/* Enable various audio drivers */
+#define SDL_AUDIO_DRIVER_NDS	1
+#define SDL_AUDIO_DRIVER_DUMMY	1
+
+/* Enable the stub cdrom driver (src/cdrom/dummy/\*.c) */
+#define SDL_CDROM_DISABLED	1
+
+/* Enable various input drivers */
+#define SDL_JOYSTICK_NDS	1
+
+/* Enable the stub shared object loader (src/loadso/dummy/\*.c) */
+#define SDL_LOADSO_DISABLED	1
+
+/* Enable the stub thread support (src/thread/generic/\*.c) */
+#define SDL_THREADS_DISABLED	1
+
+/* Enable various timer systems */
+#define SDL_TIMER_NDS	1
+
+/* Enable various video drivers */
+#define SDL_VIDEO_DRIVER_NDS	1
+#define SDL_VIDEO_DRIVER_DUMMY	1
+
+#endif /* _SDL_config_nds_h */

code/SDL12/include/SDL_config_os2.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public

code/SDL12/include/SDL_config_symbian.h

@@ -0,0 +1,146 @@
+/*
+    SDL - Simple DirectMedia Layer
+    Copyright (C) 1997-2009 Sam Lantinga
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation; either
+    version 2.1 of the License, or (at your option) any later version.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+
+    Sam Lantinga
+    slouken@libsdl.org
+*/
+
+/*
+
+Symbian version Markus Mertama
+
+*/
+
+
+#ifndef _SDL_CONFIG_SYMBIAN_H
+#define _SDL_CONFIG_SYMBIAN_H
+
+#include "SDL_platform.h"
+
+/* This is the minimal configuration that can be used to build SDL */
+
+
+#include <stdarg.h>
+#include <stddef.h>
+
+
+#ifdef __GCCE__
+#define SYMBIAN32_GCCE
+#endif
+
+#ifndef _SIZE_T_DEFINED
+typedef unsigned int size_t;
+#endif
+
+#ifndef _INTPTR_T_DECLARED
+typedef unsigned int uintptr_t;
+#endif 
+
+#ifndef _INT8_T_DECLARED
+typedef signed char int8_t;
+#endif 
+
+#ifndef _UINT8_T_DECLARED
+typedef unsigned char uint8_t;
+#endif
+
+#ifndef _INT16_T_DECLARED
+typedef signed short int16_t;
+#endif
+
+#ifndef _UINT16_T_DECLARED
+typedef unsigned short uint16_t;
+#endif
+
+#ifndef _INT32_T_DECLARED
+typedef signed int int32_t;
+#endif
+
+#ifndef _UINT32_T_DECLARED
+typedef unsigned int uint32_t;
+#endif
+
+#ifndef _INT64_T_DECLARED
+typedef signed long long int64_t;
+#endif
+
+#ifndef _UINT64_T_DECLARED
+typedef unsigned long long uint64_t;
+#endif
+
+#define SDL_AUDIO_DRIVER_EPOCAUDIO	1
+
+
+/* Enable the stub cdrom driver (src/cdrom/dummy/\*.c) */
+#define SDL_CDROM_DISABLED	1
+
+/* Enable the stub joystick driver (src/joystick/dummy/\*.c) */
+#define SDL_JOYSTICK_DISABLED	1
+
+/* Enable the stub shared object loader (src/loadso/dummy/\*.c) */
+#define SDL_LOADSO_DISABLED	1
+
+#define SDL_THREAD_SYMBIAN 1
+
+#define SDL_VIDEO_DRIVER_EPOC    1
+
+#define SDL_VIDEO_OPENGL 0
+
+#define SDL_HAS_64BIT_TYPE	1
+
+#define HAVE_LIBC	1
+#define HAVE_STDIO_H 1
+#define STDC_HEADERS 1
+#define HAVE_STRING_H 1
+#define HAVE_CTYPE_H 1
+#define HAVE_MATH_H 1
+
+#define HAVE_MALLOC 1
+#define HAVE_CALLOC 1
+#define HAVE_REALLOC 1
+#define HAVE_FREE 1
+/*#define HAVE_ALLOCA 1*/
+#define HAVE_QSORT 1
+#define HAVE_ABS 1
+#define HAVE_MEMSET 1
+#define HAVE_MEMCPY 1
+#define HAVE_MEMMOVE 1
+#define HAVE_MEMCMP 1
+#define HAVE_STRLEN 1
+#define HAVE__STRUPR 1
+#define HAVE_STRCHR 1
+#define HAVE_STRRCHR 1
+#define HAVE_STRSTR 1
+#define HAVE_ITOA 1
+#define HAVE_STRTOL 1
+#define HAVE_STRTOUL 1
+#define HAVE_STRTOLL 1
+#define HAVE_STRTOD 1
+#define HAVE_ATOI 1
+#define HAVE_ATOF 1
+#define HAVE_STRCMP 1
+#define HAVE_STRNCMP 1
+/*#define HAVE__STRICMP 1*/
+#define HAVE__STRNICMP 1
+#define HAVE_SSCANF 1
+#define HAVE_STDARG_H	1
+#define HAVE_STDDEF_H	1
+
+
+
+#endif /* _SDL_CONFIG_SYMBIAN_H */

code/SDL12/include/SDL_config_win32.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -27,7 +27,7 @@
 
 /* This is a set of defines to configure the SDL features */
 
-#ifdef __GNUC__
+#if defined(__GNUC__) || defined(__DMC__)
 #define HAVE_STDINT_H	1
 #elif defined(_MSC_VER)
 typedef signed __int8		int8_t;
@@ -46,6 +46,13 @@ typedef unsigned int   uintptr_t;
 #endif
 #define _UINTPTR_T_DEFINED
 #endif
+/* Older Visual C++ headers don't have the Win64-compatible typedefs... */
+#if ((_MSC_VER <= 1200) && (!defined(DWORD_PTR)))
+#define DWORD_PTR DWORD
+#endif
+#if ((_MSC_VER <= 1200) && (!defined(LONG_PTR)))
+#define LONG_PTR LONG
+#endif
 #else	/* !__GNUC__ && !_MSC_VER */
 typedef signed char int8_t;
 typedef unsigned char uint8_t;
@@ -165,6 +172,9 @@ typedef unsigned int uintptr_t;
 #define SDL_VIDEO_OPENGL_WGL	1
 #endif
 
+/* Disable screensaver */
+#define SDL_VIDEO_DISABLE_SCREENSAVER	1
+
 /* Enable assembly routines (Win64 doesn't have inline asm) */
 #ifndef _WIN64
 #define SDL_ASSEMBLY_ROUTINES	1

code/SDL12/include/SDL_copying.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public

code/SDL12/include/SDL_cpuinfo.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -20,8 +20,10 @@
     slouken@libsdl.org
 */
 
-/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+/**
-/* CPU feature detection for SDL                                       */
+ *  @file SDL_cpuinfo.h
+ *  CPU feature detection for SDL
+ */
 
 #ifndef _SDL_cpuinfo_h
 #define _SDL_cpuinfo_h
@@ -34,36 +36,28 @@
 extern "C" {
 #endif
 
-/* This function returns true if the CPU has the RDTSC instruction
+/** This function returns true if the CPU has the RDTSC instruction */
- */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasRDTSC(void);
 
-/* This function returns true if the CPU has MMX features
+/** This function returns true if the CPU has MMX features */
- */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasMMX(void);
 
-/* This function returns true if the CPU has MMX Ext. features
+/** This function returns true if the CPU has MMX Ext. features */
- */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasMMXExt(void);
 
-/* This function returns true if the CPU has 3DNow features
+/** This function returns true if the CPU has 3DNow features */
- */
 extern DECLSPEC SDL_bool SDLCALL SDL_Has3DNow(void);
 
-/* This function returns true if the CPU has 3DNow! Ext. features
+/** This function returns true if the CPU has 3DNow! Ext. features */
- */
 extern DECLSPEC SDL_bool SDLCALL SDL_Has3DNowExt(void);
 
-/* This function returns true if the CPU has SSE features
+/** This function returns true if the CPU has SSE features */
- */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE(void);
 
-/* This function returns true if the CPU has SSE2 features
+/** This function returns true if the CPU has SSE2 features */
- */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE2(void);
 
-/* This function returns true if the CPU has AltiVec features
+/** This function returns true if the CPU has AltiVec features */
- */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasAltiVec(void);
 
 /* Ends C function definitions when using C++ */

code/SDL12/include/SDL_endian.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -20,16 +20,23 @@
     slouken@libsdl.org
 */
 
-/* Functions for reading and writing endian-specific values */
+/**
+ *  @file SDL_endian.h
+ *  Functions for reading and writing endian-specific values
+ */
 
 #ifndef _SDL_endian_h
 #define _SDL_endian_h
 
 #include "SDL_stdinc.h"
 
-/* The two types of endianness */
+/** @name SDL_ENDIANs
+ *  The two types of endianness 
+ */
+/*@{*/
 #define SDL_LIL_ENDIAN	1234
 #define SDL_BIG_ENDIAN	4321
+/*@}*/
 
 #ifndef SDL_BYTEORDER	/* Not defined in SDL_config.h? */
 #if defined(__hppa__) || \
@@ -50,13 +57,16 @@
 extern "C" {
 #endif
 
-/* Use inline functions for compilers that support them, and static
+/**
-   functions for those that do not.  Because these functions become
+ *  @name SDL_Swap Functions
-   static for compilers that do not support inline functions, this
+ *  Use inline functions for compilers that support them, and static
-   header should only be included in files that actually use them.
+ *  functions for those that do not.  Because these functions become
+ *  static for compilers that do not support inline functions, this
+ *  header should only be included in files that actually use them.
  */
+/*@{*/
 #if defined(__GNUC__) && defined(__i386__) && \
-   !(__GNUC__ == 2 && __GNUC_MINOR__ == 95 /* broken gcc version */)
+   !(__GNUC__ == 2 && __GNUC_MINOR__ <= 95 /* broken gcc version */)
 static __inline__ Uint16 SDL_Swap16(Uint16 x)
 {
 	__asm__("xchgb %b0,%h0" : "=q" (x) :  "0" (x));
@@ -88,7 +98,8 @@ static __inline__ Uint16 SDL_Swap16(Uint16 x) {
 }
 #endif
 
-#if defined(__GNUC__) && defined(__i386__)
+#if defined(__GNUC__) && defined(__i386__) && \
+   !(__GNUC__ == 2 && __GNUC_MINOR__ <= 95 /* broken gcc version */)
 static __inline__ Uint32 SDL_Swap32(Uint32 x)
 {
 	__asm__("bswap %0" : "=r" (x) : "0" (x));
@@ -123,7 +134,8 @@ static __inline__ Uint32 SDL_Swap32(Uint32 x) {
 #endif
 
 #ifdef SDL_HAS_64BIT_TYPE
-#if defined(__GNUC__) && defined(__i386__)
+#if defined(__GNUC__) && defined(__i386__) && \
+   !(__GNUC__ == 2 && __GNUC_MINOR__ <= 95 /* broken gcc version */)
 static __inline__ Uint64 SDL_Swap64(Uint64 x)
 {
 	union { 
@@ -148,9 +160,9 @@ static __inline__ Uint64 SDL_Swap64(Uint64 x)
 	Uint32 hi, lo;
 
 	/* Separate into high and low 32-bit values and swap them */
-	lo = (Uint32)(x&0xFFFFFFFF);
+	lo = SDL_static_cast(Uint32, x & 0xFFFFFFFF);
 	x >>= 32;
-	hi = (Uint32)(x&0xFFFFFFFF);
+	hi = SDL_static_cast(Uint32, x & 0xFFFFFFFF);
 	x = SDL_Swap32(lo);
 	x <<= 32;
 	x |= SDL_Swap32(hi);
@@ -159,14 +171,18 @@ static __inline__ Uint64 SDL_Swap64(Uint64 x)
 #endif
 #else
 /* This is mainly to keep compilers from complaining in SDL code.
-   If there is no real 64-bit datatype, then compilers will complain about
+ * If there is no real 64-bit datatype, then compilers will complain about
-   the fake 64-bit datatype that SDL provides when it compiles user code.
+ * the fake 64-bit datatype that SDL provides when it compiles user code.
  */
 #define SDL_Swap64(X)	(X)
 #endif /* SDL_HAS_64BIT_TYPE */
+/*@}*/
 
-
+/**
-/* Byteswap item from the specified endianness to the native endianness */
+ *  @name SDL_SwapLE and SDL_SwapBE Functions
+ *  Byteswap item from the specified endianness to the native endianness
+ */
+/*@{*/
 #if SDL_BYTEORDER == SDL_LIL_ENDIAN
 #define SDL_SwapLE16(X)	(X)
 #define SDL_SwapLE32(X)	(X)
@@ -182,6 +198,7 @@ static __inline__ Uint64 SDL_Swap64(Uint64 x)
 #define SDL_SwapBE32(X)	(X)
 #define SDL_SwapBE64(X)	(X)
 #endif
+/*@}*/
 
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus

code/SDL12/include/SDL_error.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -20,7 +20,10 @@
     slouken@libsdl.org
 */
 
-/* Simple error message routines for SDL */
+/**
+ *  @file SDL_error.h
+ *  Simple error message routines for SDL
+ */
 
 #ifndef _SDL_error_h
 #define _SDL_error_h
@@ -33,12 +36,20 @@
 extern "C" {
 #endif
 
-/* Public functions */
+/** 
+ *  @name Public functions
+ */
+/*@{*/
 extern DECLSPEC void SDLCALL SDL_SetError(const char *fmt, ...);
 extern DECLSPEC char * SDLCALL SDL_GetError(void);
 extern DECLSPEC void SDLCALL SDL_ClearError(void);
+/*@}*/
 
-/* Private error message function - used internally */
+/**
+ *  @name Private functions
+ *  @internal Private error message function - used internally
+ */
+/*@{*/
 #define SDL_OutOfMemory()	SDL_Error(SDL_ENOMEM)
 #define SDL_Unsupported()	SDL_Error(SDL_UNSUPPORTED)
 typedef enum {
@@ -50,7 +61,7 @@ typedef enum {
 	SDL_LASTERROR
 } SDL_errorcode;
 extern DECLSPEC void SDLCALL SDL_Error(SDL_errorcode code);
-
+/*@}*/
 
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus

code/SDL12/include/SDL_events.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -20,7 +20,10 @@
     slouken@libsdl.org
 */
 
-/* Include file for SDL event handling */
+/**
+ *  @file SDL_events.h
+ *  Include file for SDL event handling
+ */
 
 #ifndef _SDL_events_h
 #define _SDL_events_h
@@ -39,45 +42,48 @@
 extern "C" {
 #endif
 
-/* General keyboard/mouse state definitions */
+/** @name General keyboard/mouse state definitions */
+/*@{*/
 #define SDL_RELEASED	0
 #define SDL_PRESSED	1
+/*@}*/
 
-/* Event enumerations */
+/** Event enumerations */
 typedef enum {
-       SDL_NOEVENT = 0,			/* Unused (do not remove) */
+       SDL_NOEVENT = 0,			/**< Unused (do not remove) */
-       SDL_ACTIVEEVENT,			/* Application loses/gains visibility */
+       SDL_ACTIVEEVENT,			/**< Application loses/gains visibility */
-       SDL_KEYDOWN,			/* Keys pressed */
+       SDL_KEYDOWN,			/**< Keys pressed */
-       SDL_KEYUP,			/* Keys released */
+       SDL_KEYUP,			/**< Keys released */
-       SDL_MOUSEMOTION,			/* Mouse moved */
+       SDL_MOUSEMOTION,			/**< Mouse moved */
-       SDL_MOUSEBUTTONDOWN,		/* Mouse button pressed */
+       SDL_MOUSEBUTTONDOWN,		/**< Mouse button pressed */
-       SDL_MOUSEBUTTONUP,		/* Mouse button released */
+       SDL_MOUSEBUTTONUP,		/**< Mouse button released */
-       SDL_JOYAXISMOTION,		/* Joystick axis motion */
+       SDL_JOYAXISMOTION,		/**< Joystick axis motion */
-       SDL_JOYBALLMOTION,		/* Joystick trackball motion */
+       SDL_JOYBALLMOTION,		/**< Joystick trackball motion */
-       SDL_JOYHATMOTION,		/* Joystick hat position change */
+       SDL_JOYHATMOTION,		/**< Joystick hat position change */
-       SDL_JOYBUTTONDOWN,		/* Joystick button pressed */
+       SDL_JOYBUTTONDOWN,		/**< Joystick button pressed */
-       SDL_JOYBUTTONUP,			/* Joystick button released */
+       SDL_JOYBUTTONUP,			/**< Joystick button released */
-       SDL_QUIT,			/* User-requested quit */
+       SDL_QUIT,			/**< User-requested quit */
-       SDL_SYSWMEVENT,			/* System specific event */
+       SDL_SYSWMEVENT,			/**< System specific event */
-       SDL_EVENT_RESERVEDA,		/* Reserved for future use.. */
+       SDL_EVENT_RESERVEDA,		/**< Reserved for future use.. */
-       SDL_EVENT_RESERVEDB,		/* Reserved for future use.. */
+       SDL_EVENT_RESERVEDB,		/**< Reserved for future use.. */
-       SDL_VIDEORESIZE,			/* User resized video mode */
+       SDL_VIDEORESIZE,			/**< User resized video mode */
-       SDL_VIDEOEXPOSE,			/* Screen needs to be redrawn */
+       SDL_VIDEOEXPOSE,			/**< Screen needs to be redrawn */
-       SDL_EVENT_RESERVED2,		/* Reserved for future use.. */
+       SDL_EVENT_RESERVED2,		/**< Reserved for future use.. */
-       SDL_EVENT_RESERVED3,		/* Reserved for future use.. */
+       SDL_EVENT_RESERVED3,		/**< Reserved for future use.. */
-       SDL_EVENT_RESERVED4,		/* Reserved for future use.. */
+       SDL_EVENT_RESERVED4,		/**< Reserved for future use.. */
-       SDL_EVENT_RESERVED5,		/* Reserved for future use.. */
+       SDL_EVENT_RESERVED5,		/**< Reserved for future use.. */
-       SDL_EVENT_RESERVED6,		/* Reserved for future use.. */
+       SDL_EVENT_RESERVED6,		/**< Reserved for future use.. */
-       SDL_EVENT_RESERVED7,		/* Reserved for future use.. */
+       SDL_EVENT_RESERVED7,		/**< Reserved for future use.. */
-       /* Events SDL_USEREVENT through SDL_MAXEVENTS-1 are for your use */
+       /** Events SDL_USEREVENT through SDL_MAXEVENTS-1 are for your use */
        SDL_USEREVENT = 24,
-       /* This last event is only for bounding internal arrays
+       /** This last event is only for bounding internal arrays
-	  It is the number of bits in the event mask datatype -- Uint32
+	*  It is the number of bits in the event mask datatype -- Uint32
         */
        SDL_NUMEVENTS = 32
 } SDL_EventType;
 
-/* Predefined event masks */
+/** @name Predefined event masks */
+/*@{*/
 #define SDL_EVENTMASK(X)	(1<<(X))
 typedef enum {
 	SDL_ACTIVEEVENTMASK	= SDL_EVENTMASK(SDL_ACTIVEEVENT),
@@ -107,108 +113,109 @@ typedef enum {
 	SDL_SYSWMEVENTMASK	= SDL_EVENTMASK(SDL_SYSWMEVENT)
 } SDL_EventMask ;
 #define SDL_ALLEVENTS		0xFFFFFFFF
+/*@}*/
 
-/* Application visibility event structure */
+/** Application visibility event structure */
 typedef struct SDL_ActiveEvent {
-	Uint8 type;	/* SDL_ACTIVEEVENT */
+	Uint8 type;	/**< SDL_ACTIVEEVENT */
-	Uint8 gain;	/* Whether given states were gained or lost (1/0) */
+	Uint8 gain;	/**< Whether given states were gained or lost (1/0) */
-	Uint8 state;	/* A mask of the focus states */
+	Uint8 state;	/**< A mask of the focus states */
 } SDL_ActiveEvent;
 
-/* Keyboard event structure */
+/** Keyboard event structure */
 typedef struct SDL_KeyboardEvent {
-	Uint8 type;	/* SDL_KEYDOWN or SDL_KEYUP */
+	Uint8 type;	/**< SDL_KEYDOWN or SDL_KEYUP */
-	Uint8 which;	/* The keyboard device index */
+	Uint8 which;	/**< The keyboard device index */
-	Uint8 state;	/* SDL_PRESSED or SDL_RELEASED */
+	Uint8 state;	/**< SDL_PRESSED or SDL_RELEASED */
 	SDL_keysym keysym;
 } SDL_KeyboardEvent;
 
-/* Mouse motion event structure */
+/** Mouse motion event structure */
 typedef struct SDL_MouseMotionEvent {
-	Uint8 type;	/* SDL_MOUSEMOTION */
+	Uint8 type;	/**< SDL_MOUSEMOTION */
-	Uint8 which;	/* The mouse device index */
+	Uint8 which;	/**< The mouse device index */
-	Uint8 state;	/* The current button state */
+	Uint8 state;	/**< The current button state */
-	Uint16 x, y;	/* The X/Y coordinates of the mouse */
+	Uint16 x, y;	/**< The X/Y coordinates of the mouse */
-	Sint16 xrel;	/* The relative motion in the X direction */
+	Sint16 xrel;	/**< The relative motion in the X direction */
-	Sint16 yrel;	/* The relative motion in the Y direction */
+	Sint16 yrel;	/**< The relative motion in the Y direction */
 } SDL_MouseMotionEvent;
 
-/* Mouse button event structure */
+/** Mouse button event structure */
 typedef struct SDL_MouseButtonEvent {
-	Uint8 type;	/* SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */
+	Uint8 type;	/**< SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */
-	Uint8 which;	/* The mouse device index */
+	Uint8 which;	/**< The mouse device index */
-	Uint8 button;	/* The mouse button index */
+	Uint8 button;	/**< The mouse button index */
-	Uint8 state;	/* SDL_PRESSED or SDL_RELEASED */
+	Uint8 state;	/**< SDL_PRESSED or SDL_RELEASED */
-	Uint16 x, y;	/* The X/Y coordinates of the mouse at press time */
+	Uint16 x, y;	/**< The X/Y coordinates of the mouse at press time */
 } SDL_MouseButtonEvent;
 
-/* Joystick axis motion event structure */
+/** Joystick axis motion event structure */
 typedef struct SDL_JoyAxisEvent {
-	Uint8 type;	/* SDL_JOYAXISMOTION */
+	Uint8 type;	/**< SDL_JOYAXISMOTION */
-	Uint8 which;	/* The joystick device index */
+	Uint8 which;	/**< The joystick device index */
-	Uint8 axis;	/* The joystick axis index */
+	Uint8 axis;	/**< The joystick axis index */
-	Sint16 value;	/* The axis value (range: -32768 to 32767) */
+	Sint16 value;	/**< The axis value (range: -32768 to 32767) */
 } SDL_JoyAxisEvent;
 
-/* Joystick trackball motion event structure */
+/** Joystick trackball motion event structure */
 typedef struct SDL_JoyBallEvent {
-	Uint8 type;	/* SDL_JOYBALLMOTION */
+	Uint8 type;	/**< SDL_JOYBALLMOTION */
-	Uint8 which;	/* The joystick device index */
+	Uint8 which;	/**< The joystick device index */
-	Uint8 ball;	/* The joystick trackball index */
+	Uint8 ball;	/**< The joystick trackball index */
-	Sint16 xrel;	/* The relative motion in the X direction */
+	Sint16 xrel;	/**< The relative motion in the X direction */
-	Sint16 yrel;	/* The relative motion in the Y direction */
+	Sint16 yrel;	/**< The relative motion in the Y direction */
 } SDL_JoyBallEvent;
 
-/* Joystick hat position change event structure */
+/** Joystick hat position change event structure */
 typedef struct SDL_JoyHatEvent {
-	Uint8 type;	/* SDL_JOYHATMOTION */
+	Uint8 type;	/**< SDL_JOYHATMOTION */
-	Uint8 which;	/* The joystick device index */
+	Uint8 which;	/**< The joystick device index */
-	Uint8 hat;	/* The joystick hat index */
+	Uint8 hat;	/**< The joystick hat index */
-	Uint8 value;	/* The hat position value:
+	Uint8 value;	/**< The hat position value:
-			    SDL_HAT_LEFTUP   SDL_HAT_UP       SDL_HAT_RIGHTUP
+			 *   SDL_HAT_LEFTUP   SDL_HAT_UP       SDL_HAT_RIGHTUP
-			    SDL_HAT_LEFT     SDL_HAT_CENTERED SDL_HAT_RIGHT
+			 *   SDL_HAT_LEFT     SDL_HAT_CENTERED SDL_HAT_RIGHT
-			    SDL_HAT_LEFTDOWN SDL_HAT_DOWN     SDL_HAT_RIGHTDOWN
+			 *   SDL_HAT_LEFTDOWN SDL_HAT_DOWN     SDL_HAT_RIGHTDOWN
-			   Note that zero means the POV is centered.
+			 *  Note that zero means the POV is centered.
 			 */
 } SDL_JoyHatEvent;
 
-/* Joystick button event structure */
+/** Joystick button event structure */
 typedef struct SDL_JoyButtonEvent {
-	Uint8 type;	/* SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP */
+	Uint8 type;	/**< SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP */
-	Uint8 which;	/* The joystick device index */
+	Uint8 which;	/**< The joystick device index */
-	Uint8 button;	/* The joystick button index */
+	Uint8 button;	/**< The joystick button index */
-	Uint8 state;	/* SDL_PRESSED or SDL_RELEASED */
+	Uint8 state;	/**< SDL_PRESSED or SDL_RELEASED */
 } SDL_JoyButtonEvent;
 
-/* The "window resized" event
+/** The "window resized" event
-   When you get this event, you are responsible for setting a new video
+ *  When you get this event, you are responsible for setting a new video
-   mode with the new width and height.
+ *  mode with the new width and height.
  */
 typedef struct SDL_ResizeEvent {
-	Uint8 type;	/* SDL_VIDEORESIZE */
+	Uint8 type;	/**< SDL_VIDEORESIZE */
-	int w;		/* New width */
+	int w;		/**< New width */
-	int h;		/* New height */
+	int h;		/**< New height */
 } SDL_ResizeEvent;
 
-/* The "screen redraw" event */
+/** The "screen redraw" event */
 typedef struct SDL_ExposeEvent {
-	Uint8 type;	/* SDL_VIDEOEXPOSE */
+	Uint8 type;	/**< SDL_VIDEOEXPOSE */
 } SDL_ExposeEvent;
 
-/* The "quit requested" event */
+/** The "quit requested" event */
 typedef struct SDL_QuitEvent {
-	Uint8 type;	/* SDL_QUIT */
+	Uint8 type;	/**< SDL_QUIT */
 } SDL_QuitEvent;
 
-/* A user-defined event type */
+/** A user-defined event type */
 typedef struct SDL_UserEvent {
-	Uint8 type;	/* SDL_USEREVENT through SDL_NUMEVENTS-1 */
+	Uint8 type;	/**< SDL_USEREVENT through SDL_NUMEVENTS-1 */
-	int code;	/* User defined event code */
+	int code;	/**< User defined event code */
-	void *data1;	/* User defined data pointer */
+	void *data1;	/**< User defined data pointer */
-	void *data2;	/* User defined data pointer */
+	void *data2;	/**< User defined data pointer */
 } SDL_UserEvent;
 
-/* If you want to use this event, you should include SDL_syswm.h */
+/** If you want to use this event, you should include SDL_syswm.h */
 struct SDL_SysWMmsg;
 typedef struct SDL_SysWMmsg SDL_SysWMmsg;
 typedef struct SDL_SysWMEvent {
@@ -216,7 +223,7 @@ typedef struct SDL_SysWMEvent {
 	SDL_SysWMmsg *msg;
 } SDL_SysWMEvent;
 
-/* General event structure */
+/** General event structure */
 typedef union SDL_Event {
 	Uint8 type;
 	SDL_ActiveEvent active;
@@ -237,96 +244,108 @@ typedef union SDL_Event {
 
 /* Function prototypes */
 
-/* Pumps the event loop, gathering events from the input devices.
+/** Pumps the event loop, gathering events from the input devices.
-   This function updates the event queue and internal input device state.
+ *  This function updates the event queue and internal input device state.
-   This should only be run in the thread that sets the video mode.
+ *  This should only be run in the thread that sets the video mode.
  */
 extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
 
-/* Checks the event queue for messages and optionally returns them.
-   If 'action' is SDL_ADDEVENT, up to 'numevents' events will be added to
-   the back of the event queue.
-   If 'action' is SDL_PEEKEVENT, up to 'numevents' events at the front
-   of the event queue, matching 'mask', will be returned and will not
-   be removed from the queue.
-   If 'action' is SDL_GETEVENT, up to 'numevents' events at the front 
-   of the event queue, matching 'mask', will be returned and will be
-   removed from the queue.
-   This function returns the number of events actually stored, or -1
-   if there was an error.  This function is thread-safe.
-*/
 typedef enum {
 	SDL_ADDEVENT,
 	SDL_PEEKEVENT,
 	SDL_GETEVENT
 } SDL_eventaction;
-/* */
+
+/**
+ *  Checks the event queue for messages and optionally returns them.
+ *
+ *  If 'action' is SDL_ADDEVENT, up to 'numevents' events will be added to
+ *  the back of the event queue.
+ *  If 'action' is SDL_PEEKEVENT, up to 'numevents' events at the front
+ *  of the event queue, matching 'mask', will be returned and will not
+ *  be removed from the queue.
+ *  If 'action' is SDL_GETEVENT, up to 'numevents' events at the front 
+ *  of the event queue, matching 'mask', will be returned and will be
+ *  removed from the queue.
+ *
+ *  @return
+ *  This function returns the number of events actually stored, or -1
+ *  if there was an error.
+ *
+ *  This function is thread-safe.
+ */
 extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event *events, int numevents,
 				SDL_eventaction action, Uint32 mask);
 
-/* Polls for currently pending events, and returns 1 if there are any pending
+/** Polls for currently pending events, and returns 1 if there are any pending
-   events, or 0 if there are none available.  If 'event' is not NULL, the next
+ *  events, or 0 if there are none available.  If 'event' is not NULL, the next
-   event is removed from the queue and stored in that area.
+ *  event is removed from the queue and stored in that area.
  */
 extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event *event);
 
-/* Waits indefinitely for the next available event, returning 1, or 0 if there
+/** Waits indefinitely for the next available event, returning 1, or 0 if there
-   was an error while waiting for events.  If 'event' is not NULL, the next
+ *  was an error while waiting for events.  If 'event' is not NULL, the next
-   event is removed from the queue and stored in that area.
+ *  event is removed from the queue and stored in that area.
  */
 extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event *event);
 
-/* Add an event to the event queue.
+/** Add an event to the event queue.
-   This function returns 0 on success, or -1 if the event queue was full
+ *  This function returns 0 on success, or -1 if the event queue was full
-   or there was some other error.
+ *  or there was some other error.
  */
 extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event *event);
 
-/*
+/** @name Event Filtering */
-  This function sets up a filter to process all events before they
+/*@{*/
-  change internal state and are posted to the internal event queue.
-
-  The filter is protypted as:
-*/
 typedef int (SDLCALL *SDL_EventFilter)(const SDL_Event *event);
-/*
+/**
-  If the filter returns 1, then the event will be added to the internal queue.
+ *  This function sets up a filter to process all events before they
-  If it returns 0, then the event will be dropped from the queue, but the 
+ *  change internal state and are posted to the internal event queue.
-  internal state will still be updated.  This allows selective filtering of
+ *
-  dynamically arriving events.
+ *  The filter is protypted as:
-
+ *      @code typedef int (SDLCALL *SDL_EventFilter)(const SDL_Event *event); @endcode
-  WARNING:  Be very careful of what you do in the event filter function, as 
+ *
-            it may run in a different thread!
+ * If the filter returns 1, then the event will be added to the internal queue.
-
+ * If it returns 0, then the event will be dropped from the queue, but the 
-  There is one caveat when dealing with the SDL_QUITEVENT event type.  The
+ * internal state will still be updated.  This allows selective filtering of
-  event filter is only called when the window manager desires to close the
+ * dynamically arriving events.
-  application window.  If the event filter returns 1, then the window will
+ *
-  be closed, otherwise the window will remain open if possible.
+ * @warning  Be very careful of what you do in the event filter function, as 
-  If the quit event is generated by an interrupt signal, it will bypass the
+ *           it may run in a different thread!
-  internal queue and be delivered to the application at the next event poll.
+ *
+ * There is one caveat when dealing with the SDL_QUITEVENT event type.  The
+ * event filter is only called when the window manager desires to close the
+ * application window.  If the event filter returns 1, then the window will
+ * be closed, otherwise the window will remain open if possible.
+ * If the quit event is generated by an interrupt signal, it will bypass the
+ * internal queue and be delivered to the application at the next event poll.
  */
 extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter);
 
-/*
+/**
-  Return the current event filter - can be used to "chain" filters.
+ *  Return the current event filter - can be used to "chain" filters.
-  If there is no event filter set, this function returns NULL.
+ *  If there is no event filter set, this function returns NULL.
  */
 extern DECLSPEC SDL_EventFilter SDLCALL SDL_GetEventFilter(void);
+/*@}*/
 
-/*
+/** @name Event State */
-  This function allows you to set the state of processing certain events.
+/*@{*/
-  If 'state' is set to SDL_IGNORE, that event will be automatically dropped
-  from the event queue and will not event be filtered.
-  If 'state' is set to SDL_ENABLE, that event will be processed normally.
-  If 'state' is set to SDL_QUERY, SDL_EventState() will return the 
-  current processing state of the specified event.
-*/
 #define SDL_QUERY	-1
 #define SDL_IGNORE	 0
 #define SDL_DISABLE	 0
 #define SDL_ENABLE	 1
-extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint8 type, int state);
+/*@}*/
 
+/**
+* This function allows you to set the state of processing certain events.
+* If 'state' is set to SDL_IGNORE, that event will be automatically dropped
+* from the event queue and will not event be filtered.
+* If 'state' is set to SDL_ENABLE, that event will be processed normally.
+* If 'state' is set to SDL_QUERY, SDL_EventState() will return the 
+* current processing state of the specified event.
+*/
+extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint8 type, int state);
 
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus

code/SDL12/include/SDL_getenv.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -20,5 +20,9 @@
     slouken@libsdl.org
 */
 
+/** @file SDL_getenv.h
+ *  @deprecated Use SDL_stdinc.h instead
+ */
+
 /* DEPRECATED */
 #include "SDL_stdinc.h"

code/SDL12/include/SDL_joystick.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -20,7 +20,9 @@
     slouken@libsdl.org
 */
 
-/* Include file for SDL joystick event handling */
+/** @file SDL_joystick.h
+ *  Include file for SDL joystick event handling
+ */
 
 #ifndef _SDL_joystick_h
 #define _SDL_joystick_h
@@ -34,97 +36,108 @@
 extern "C" {
 #endif
 
-/* In order to use these functions, SDL_Init() must have been called
+/** @file SDL_joystick.h
-   with the SDL_INIT_JOYSTICK flag.  This causes SDL to scan the system
+ *  @note In order to use these functions, SDL_Init() must have been called
-   for joysticks, and load appropriate drivers.
+ *        with the SDL_INIT_JOYSTICK flag.  This causes SDL to scan the system
+ *        for joysticks, and load appropriate drivers.
  */
 
-/* The joystick structure used to identify an SDL joystick */
+/** The joystick structure used to identify an SDL joystick */
 struct _SDL_Joystick;
 typedef struct _SDL_Joystick SDL_Joystick;
 
-
 /* Function prototypes */
-/*
+/**
  * Count the number of joysticks attached to the system
  */
 extern DECLSPEC int SDLCALL SDL_NumJoysticks(void);
 
-/*
+/**
  * Get the implementation dependent name of a joystick.
+ *
  * This can be called before any joysticks are opened.
  * If no name can be found, this function returns NULL.
  */
 extern DECLSPEC const char * SDLCALL SDL_JoystickName(int device_index);
 
-/*
+/**
- * Open a joystick for use - the index passed as an argument refers to
+ * Open a joystick for use.
+ *
+ * @param[in] device_index
+ * The index passed as an argument refers to
  * the N'th joystick on the system.  This index is the value which will
  * identify this joystick in future joystick events.
  *
- * This function returns a joystick identifier, or NULL if an error occurred.
+ * @return This function returns a joystick identifier, or NULL if an error occurred.
  */
 extern DECLSPEC SDL_Joystick * SDLCALL SDL_JoystickOpen(int device_index);
 
-/*
+/**
  * Returns 1 if the joystick has been opened, or 0 if it has not.
  */
 extern DECLSPEC int SDLCALL SDL_JoystickOpened(int device_index);
 
-/*
+/**
  * Get the device index of an opened joystick.
  */
 extern DECLSPEC int SDLCALL SDL_JoystickIndex(SDL_Joystick *joystick);
 
-/*
+/**
  * Get the number of general axis controls on a joystick
  */
 extern DECLSPEC int SDLCALL SDL_JoystickNumAxes(SDL_Joystick *joystick);
 
-/*
+/**
  * Get the number of trackballs on a joystick
+ *
  * Joystick trackballs have only relative motion events associated
  * with them and their state cannot be polled.
  */
 extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(SDL_Joystick *joystick);
 
-/*
+/**
  * Get the number of POV hats on a joystick
  */
 extern DECLSPEC int SDLCALL SDL_JoystickNumHats(SDL_Joystick *joystick);
 
-/*
+/**
  * Get the number of buttons on a joystick
  */
 extern DECLSPEC int SDLCALL SDL_JoystickNumButtons(SDL_Joystick *joystick);
 
-/*
+/**
  * Update the current state of the open joysticks.
+ *
  * This is called automatically by the event loop if any joystick
  * events are enabled.
  */
 extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void);
 
-/*
+/**
  * Enable/disable joystick event polling.
+ *
  * If joystick events are disabled, you must call SDL_JoystickUpdate()
  * yourself and check the state of the joystick when you want joystick
  * information.
- * The state can be one of SDL_QUERY, SDL_ENABLE or SDL_IGNORE.
+ *
+ * @param[in] state The state can be one of SDL_QUERY, SDL_ENABLE or SDL_IGNORE.
  */
 extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state);
 
-/*
+/**
  * Get the current state of an axis control on a joystick
- * The state is a value ranging from -32768 to 32767.
+ *
- * The axis indices start at index 0.
+ * @param[in] axis The axis indices start at index 0.
+ *
+ * @return The state is a value ranging from -32768 to 32767.
  */
 extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick *joystick, int axis);
 
-/*
+/**
- * Get the current state of a POV hat on a joystick
+ *  @name Hat Positions
- * The return value is one of the following positions:
+ *  The return value of SDL_JoystickGetHat() is one of the following positions:
  */
+/*@{*/
 #define SDL_HAT_CENTERED	0x00
 #define SDL_HAT_UP		0x01
 #define SDL_HAT_RIGHT		0x02
@@ -134,25 +147,32 @@ extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick *joystick, int a
 #define SDL_HAT_RIGHTDOWN	(SDL_HAT_RIGHT|SDL_HAT_DOWN)
 #define SDL_HAT_LEFTUP		(SDL_HAT_LEFT|SDL_HAT_UP)
 #define SDL_HAT_LEFTDOWN	(SDL_HAT_LEFT|SDL_HAT_DOWN)
-/*
+/*@}*/
- * The hat indices start at index 0.
+
+/** 
+ *  Get the current state of a POV hat on a joystick
+ *
+ *  @param[in] hat The hat indices start at index 0.
  */
 extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick *joystick, int hat);
 
-/*
+/**
  * Get the ball axis change since the last poll
- * This returns 0, or -1 if you passed it invalid parameters.
+ *
- * The ball indices start at index 0.
+ * @param[in] ball The ball indices start at index 0.
+ *
+ * @return This returns 0, or -1 if you passed it invalid parameters.
  */
 extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick *joystick, int ball, int *dx, int *dy);
 
-/*
+/**
  * Get the current state of a button on a joystick
- * The button indices start at index 0.
+ *
+ * @param[in] button The button indices start at index 0.
  */
 extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick *joystick, int button);
 
-/*
+/**
  * Close a joystick previously opened with SDL_JoystickOpen()
  */
 extern DECLSPEC void SDLCALL SDL_JoystickClose(SDL_Joystick *joystick);

code/SDL12/include/SDL_keyboard.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -20,7 +20,9 @@
     slouken@libsdl.org
 */
 
-/* Include file for SDL keyboard event handling */
+/** @file SDL_keyboard.h
+ *  Include file for SDL keyboard event handling
+ */
 
 #ifndef _SDL_keyboard_h
 #define _SDL_keyboard_h
@@ -35,78 +37,90 @@
 extern "C" {
 #endif
 
-/* Keysym structure
+/** Keysym structure
-   - The scancode is hardware dependent, and should not be used by general
+ *
-     applications.  If no hardware scancode is available, it will be 0.
+ *  - The scancode is hardware dependent, and should not be used by general
-
+ *    applications.  If no hardware scancode is available, it will be 0.
-   - The 'unicode' translated character is only available when character
+ *
-     translation is enabled by the SDL_EnableUNICODE() API.  If non-zero,
+ *  - The 'unicode' translated character is only available when character
-     this is a UNICODE character corresponding to the keypress.  If the
+ *    translation is enabled by the SDL_EnableUNICODE() API.  If non-zero,
-     high 9 bits of the character are 0, then this maps to the equivalent
+ *    this is a UNICODE character corresponding to the keypress.  If the
-     ASCII character:
+ *    high 9 bits of the character are 0, then this maps to the equivalent
-	char ch;
+ *    ASCII character:
-	if ( (keysym.unicode & 0xFF80) == 0 ) {
+ *      @code
-		ch = keysym.unicode & 0x7F;
+ *	char ch;
-	} else {
+ *	if ( (keysym.unicode & 0xFF80) == 0 ) {
-		An international character..
+ *		ch = keysym.unicode & 0x7F;
-	}
+ *	} else {
+ *		An international character..
+ *	}
+ *      @endcode
  */
 typedef struct SDL_keysym {
-	Uint8 scancode;			/* hardware specific scancode */
+	Uint8 scancode;			/**< hardware specific scancode */
-	SDLKey sym;			/* SDL virtual keysym */
+	SDLKey sym;			/**< SDL virtual keysym */
-	SDLMod mod;			/* current key modifiers */
+	SDLMod mod;			/**< current key modifiers */
-	Uint16 unicode;			/* translated character */
+	Uint16 unicode;			/**< translated character */
 } SDL_keysym;
 
-/* This is the mask which refers to all hotkey bindings */
+/** This is the mask which refers to all hotkey bindings */
 #define SDL_ALL_HOTKEYS		0xFFFFFFFF
 
 /* Function prototypes */
-/*
+/**
  * Enable/Disable UNICODE translation of keyboard input.
+ *
  * This translation has some overhead, so translation defaults off.
+ *
+ * @param[in] enable
  * If 'enable' is 1, translation is enabled.
  * If 'enable' is 0, translation is disabled.
  * If 'enable' is -1, the translation state is not changed.
- * It returns the previous state of keyboard translation.
+ *
+ * @return It returns the previous state of keyboard translation.
  */
 extern DECLSPEC int SDLCALL SDL_EnableUNICODE(int enable);
 
-/*
- * Enable/Disable keyboard repeat.  Keyboard repeat defaults to off.
- * 'delay' is the initial delay in ms between the time when a key is
- * pressed, and keyboard repeat begins.
- * 'interval' is the time in ms between keyboard repeat events.
- */
 #define SDL_DEFAULT_REPEAT_DELAY	500
 #define SDL_DEFAULT_REPEAT_INTERVAL	30
-/*
+/**
+ * Enable/Disable keyboard repeat.  Keyboard repeat defaults to off.
+ *
+ *  @param[in] delay
+ *  'delay' is the initial delay in ms between the time when a key is
+ *  pressed, and keyboard repeat begins.
+ *
+ *  @param[in] interval
+ *  'interval' is the time in ms between keyboard repeat events.
+ *
  *  If 'delay' is set to 0, keyboard repeat is disabled.
  */
 extern DECLSPEC int SDLCALL SDL_EnableKeyRepeat(int delay, int interval);
 extern DECLSPEC void SDLCALL SDL_GetKeyRepeat(int *delay, int *interval);
 
-/*
+/**
  * Get a snapshot of the current state of the keyboard.
  * Returns an array of keystates, indexed by the SDLK_* syms.
- * Used:
+ * Usage:
+ *	@code
  * 	Uint8 *keystate = SDL_GetKeyState(NULL);
- *	if ( keystate[SDLK_RETURN] ) ... <RETURN> is pressed.
+ *	if ( keystate[SDLK_RETURN] ) //... \<RETURN> is pressed.
+ *	@endcode
  */
 extern DECLSPEC Uint8 * SDLCALL SDL_GetKeyState(int *numkeys);
 
-/*
+/**
  * Get the current key modifier state
  */
 extern DECLSPEC SDLMod SDLCALL SDL_GetModState(void);
 
-/*
+/**
- * Set the current key modifier state
+ * Set the current key modifier state.
  * This does not change the keyboard state, only the key modifier flags.
  */
 extern DECLSPEC void SDLCALL SDL_SetModState(SDLMod modstate);
 
-/*
+/**
  * Get the name of an SDL virtual keysym
  */
 extern DECLSPEC char * SDLCALL SDL_GetKeyName(SDLKey key);

code/SDL12/include/SDL_keysym.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -23,14 +23,16 @@
 #ifndef _SDL_keysym_h
 #define _SDL_keysym_h
 
-/* What we really want is a mapping of every raw key on the keyboard.
+/** What we really want is a mapping of every raw key on the keyboard.
-   To support international keyboards, we use the range 0xA1 - 0xFF
+ *  To support international keyboards, we use the range 0xA1 - 0xFF
-   as international virtual keycodes.  We'll follow in the footsteps of X11...
+ *  as international virtual keycodes.  We'll follow in the footsteps of X11...
-   The names of the keys
+ *  @brief The names of the keys
  */
- 
 typedef enum {
-	/* The keyboard syms have been cleverly chosen to map to ASCII */
+        /** @name ASCII mapped keysyms
+         *  The keyboard syms have been cleverly chosen to map to ASCII
+         */
+        /*@{*/
 	SDLK_UNKNOWN		= 0,
 	SDLK_FIRST		= 0,
 	SDLK_BACKSPACE		= 8,
@@ -108,8 +110,10 @@ typedef enum {
 	SDLK_z			= 122,
 	SDLK_DELETE		= 127,
 	/* End of ASCII mapped keysyms */
+        /*@}*/
 
-	/* International keyboard syms */
+	/** @name International keyboard syms */
+        /*@{*/
 	SDLK_WORLD_0		= 160,		/* 0xA0 */
 	SDLK_WORLD_1		= 161,
 	SDLK_WORLD_2		= 162,
@@ -206,8 +210,10 @@ typedef enum {
 	SDLK_WORLD_93		= 253,
 	SDLK_WORLD_94		= 254,
 	SDLK_WORLD_95		= 255,		/* 0xFF */
+        /*@}*/
 
-	/* Numeric keypad */
+	/** @name Numeric keypad */
+        /*@{*/
 	SDLK_KP0		= 256,
 	SDLK_KP1		= 257,
 	SDLK_KP2		= 258,
@@ -225,8 +231,10 @@ typedef enum {
 	SDLK_KP_PLUS		= 270,
 	SDLK_KP_ENTER		= 271,
 	SDLK_KP_EQUALS		= 272,
+        /*@}*/
 
-	/* Arrows + Home/End pad */
+	/** @name Arrows + Home/End pad */
+        /*@{*/
 	SDLK_UP			= 273,
 	SDLK_DOWN		= 274,
 	SDLK_RIGHT		= 275,
@@ -236,8 +244,10 @@ typedef enum {
 	SDLK_END		= 279,
 	SDLK_PAGEUP		= 280,
 	SDLK_PAGEDOWN		= 281,
+        /*@}*/
 
-	/* Function keys */
+	/** @name Function keys */
+        /*@{*/
 	SDLK_F1			= 282,
 	SDLK_F2			= 283,
 	SDLK_F3			= 284,
@@ -253,8 +263,10 @@ typedef enum {
 	SDLK_F13		= 294,
 	SDLK_F14		= 295,
 	SDLK_F15		= 296,
+        /*@}*/
 
-	/* Key state modifier keys */
+	/** @name Key state modifier keys */
+        /*@{*/
 	SDLK_NUMLOCK		= 300,
 	SDLK_CAPSLOCK		= 301,
 	SDLK_SCROLLOCK		= 302,
@@ -266,27 +278,30 @@ typedef enum {
 	SDLK_LALT		= 308,
 	SDLK_RMETA		= 309,
 	SDLK_LMETA		= 310,
-	SDLK_LSUPER		= 311,		/* Left "Windows" key */
+	SDLK_LSUPER		= 311,		/**< Left "Windows" key */
-	SDLK_RSUPER		= 312,		/* Right "Windows" key */
+	SDLK_RSUPER		= 312,		/**< Right "Windows" key */
-	SDLK_MODE		= 313,		/* "Alt Gr" key */
+	SDLK_MODE		= 313,		/**< "Alt Gr" key */
-	SDLK_COMPOSE		= 314,		/* Multi-key compose key */
+	SDLK_COMPOSE		= 314,		/**< Multi-key compose key */
+        /*@}*/
 
-	/* Miscellaneous function keys */
+	/** @name Miscellaneous function keys */
+        /*@{*/
 	SDLK_HELP		= 315,
 	SDLK_PRINT		= 316,
 	SDLK_SYSREQ		= 317,
 	SDLK_BREAK		= 318,
 	SDLK_MENU		= 319,
-	SDLK_POWER		= 320,		/* Power Macintosh power key */
+	SDLK_POWER		= 320,		/**< Power Macintosh power key */
-	SDLK_EURO		= 321,		/* Some european keyboards */
+	SDLK_EURO		= 321,		/**< Some european keyboards */
-	SDLK_UNDO		= 322,		/* Atari keyboard has Undo */
+	SDLK_UNDO		= 322,		/**< Atari keyboard has Undo */
+        /*@}*/
 
 	/* Add any other keys here */
 
 	SDLK_LAST
 } SDLKey;
 
-/* Enumeration of valid key mods (possibly OR'd together) */
+/** Enumeration of valid key mods (possibly OR'd together) */
 typedef enum {
 	KMOD_NONE  = 0x0000,
 	KMOD_LSHIFT= 0x0001,

code/SDL12/include/SDL_loadso.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -20,21 +20,23 @@
     slouken@libsdl.org
 */
 
-/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+/** @file SDL_loadso.h
-/* System dependent library loading routines                           */
+ *  System dependent library loading routines
+ */
 
-/* Some things to keep in mind:                                        
+/** @file SDL_loadso.h
-   - These functions only work on C function names.  Other languages may
+ *  Some things to keep in mind:                                        
-     have name mangling and intrinsic language support that varies from
+ *  - These functions only work on C function names.  Other languages may
-     compiler to compiler.
+ *    have name mangling and intrinsic language support that varies from
-   - Make sure you declare your function pointers with the same calling
+ *    compiler to compiler.
-     convention as the actual library function.  Your code will crash
+ *  - Make sure you declare your function pointers with the same calling
-     mysteriously if you do not do this.
+ *    convention as the actual library function.  Your code will crash
-   - Avoid namespace collisions.  If you load a symbol from the library,
+ *    mysteriously if you do not do this.
-     it is not defined whether or not it goes into the global symbol
+ *  - Avoid namespace collisions.  If you load a symbol from the library,
-     namespace for the application.  If it does and it conflicts with
+ *    it is not defined whether or not it goes into the global symbol
-     symbols in your code or other shared libraries, you will not get
+ *    namespace for the application.  If it does and it conflicts with
-     the results you expect. :)
+ *    symbols in your code or other shared libraries, you will not get
+ *    the results you expect. :)
  */
 
 
@@ -50,19 +52,21 @@
 extern "C" {
 #endif
 
-/* This function dynamically loads a shared object and returns a pointer
+/**
+ * This function dynamically loads a shared object and returns a pointer
  * to the object handle (or NULL if there was an error).
  * The 'sofile' parameter is a system dependent name of the object file.
  */
 extern DECLSPEC void * SDLCALL SDL_LoadObject(const char *sofile);
 
-/* Given an object handle, this function looks up the address of the
+/**
+ * Given an object handle, this function looks up the address of the
  * named function in the shared object and returns it.  This address
  * is no longer valid after calling SDL_UnloadObject().
  */
 extern DECLSPEC void * SDLCALL SDL_LoadFunction(void *handle, const char *name);
 
-/* Unload a shared object from memory */
+/** Unload a shared object from memory */
 extern DECLSPEC void SDLCALL SDL_UnloadObject(void *handle);
 
 /* Ends C function definitions when using C++ */

code/SDL12/include/SDL_main.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -25,7 +25,9 @@
 
 #include "SDL_stdinc.h"
 
-/* Redefine main() on Win32 and MacOS so that it is called by winmain.c */
+/** @file SDL_main.h
+ *  Redefine main() on Win32 and MacOS so that it is called by winmain.c
+ */
 
 #if defined(__WIN32__) || \
     (defined(__MWERKS__) && !defined(__BEOS__)) || \
@@ -38,22 +40,25 @@
 #define C_LINKAGE
 #endif /* __cplusplus */
 
-/* The application's main() function must be called with C linkage,
+/** The application's main() function must be called with C linkage,
-   and should be declared like this:
+ *  and should be declared like this:
-#ifdef __cplusplus
+ *      @code
-extern "C"
+ *      #ifdef __cplusplus
-#endif
+ *      extern "C"
-	int main(int argc, char *argv[])
+ *      #endif
-	{
+ *	int main(int argc, char *argv[])
-	}
+ *	{
+ *	}
+ *      @endcode
  */
 #define main	SDL_main
 
-/* The prototype for the application's main() function */
+/** The prototype for the application's main() function */
 extern C_LINKAGE int SDL_main(int argc, char *argv[]);
 
 
-/* From the SDL library code -- needed for registering the app on Win32 */
+/** @name From the SDL library code -- needed for registering the app on Win32 */
+/*@{*/
 #ifdef __WIN32__
 
 #include "begin_code.h"
@@ -61,19 +66,21 @@ extern C_LINKAGE int SDL_main(int argc, char *argv[]);
 extern "C" {
 #endif
 
-/* This should be called from your WinMain() function, if any */
+/** This should be called from your WinMain() function, if any */
 extern DECLSPEC void SDLCALL SDL_SetModuleHandle(void *hInst);
-/* This can also be called, but is no longer necessary */
+/** This can also be called, but is no longer necessary */
 extern DECLSPEC int SDLCALL SDL_RegisterApp(char *name, Uint32 style, void *hInst);
-/* This can also be called, but is no longer necessary (SDL_Quit calls it) */
+/** This can also be called, but is no longer necessary (SDL_Quit calls it) */
 extern DECLSPEC void SDLCALL SDL_UnregisterApp(void);
 #ifdef __cplusplus
 }
 #endif
 #include "close_code.h"
 #endif
+/*@}*/
 
-/* From the SDL library code -- needed for registering QuickDraw on MacOS */
+/** @name From the SDL library code -- needed for registering QuickDraw on MacOS */
+/*@{*/
 #if defined(__MACOS__)
 
 #include "begin_code.h"
@@ -81,10 +88,10 @@ extern DECLSPEC void SDLCALL SDL_UnregisterApp(void);
 extern "C" {
 #endif
 
-/* Forward declaration so we don't need to include QuickDraw.h */
+/** Forward declaration so we don't need to include QuickDraw.h */
 struct QDGlobals;
 
-/* This should be called from your main() function, if any */
+/** This should be called from your main() function, if any */
 extern DECLSPEC void SDLCALL SDL_InitQuickDraw(struct QDGlobals *the_qd);
 
 #ifdef __cplusplus
@@ -92,6 +99,7 @@ extern DECLSPEC void SDLCALL SDL_InitQuickDraw(struct QDGlobals *the_qd);
 #endif
 #include "close_code.h"
 #endif
+/*@}*/
 
 #endif /* Need to redefine main()? */
 

code/SDL12/include/SDL_mouse.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -20,7 +20,9 @@
     slouken@libsdl.org
 */
 
-/* Include file for SDL mouse event handling */
+/** @file SDL_mouse.h
+ *  Include file for SDL mouse event handling
+ */
 
 #ifndef _SDL_mouse_h
 #define _SDL_mouse_h
@@ -35,18 +37,18 @@
 extern "C" {
 #endif
 
-typedef struct WMcursor WMcursor;	/* Implementation dependent */
+typedef struct WMcursor WMcursor;	/**< Implementation dependent */
 typedef struct SDL_Cursor {
-	SDL_Rect area;			/* The area of the mouse cursor */
+	SDL_Rect area;			/**< The area of the mouse cursor */
-	Sint16 hot_x, hot_y;		/* The "tip" of the cursor */
+	Sint16 hot_x, hot_y;		/**< The "tip" of the cursor */
-	Uint8 *data;			/* B/W cursor data */
+	Uint8 *data;			/**< B/W cursor data */
-	Uint8 *mask;			/* B/W cursor mask */
+	Uint8 *mask;			/**< B/W cursor mask */
-	Uint8 *save[2];			/* Place to save cursor area */
+	Uint8 *save[2];			/**< Place to save cursor area */
-	WMcursor *wm_cursor;		/* Window-manager cursor */
+	WMcursor *wm_cursor;		/**< Window-manager cursor */
 } SDL_Cursor;
 
 /* Function prototypes */
-/*
+/**
  * Retrieve the current state of the mouse.
  * The current button state is returned as a button bitmask, which can
  * be tested using the SDL_BUTTON(X) macros, and x and y are set to the
@@ -54,7 +56,7 @@ typedef struct SDL_Cursor {
  */
 extern DECLSPEC Uint8 SDLCALL SDL_GetMouseState(int *x, int *y);
 
-/*
+/**
  * Retrieve the current state of the mouse.
  * The current button state is returned as a button bitmask, which can
  * be tested using the SDL_BUTTON(X) macros, and x and y are set to the
@@ -62,12 +64,12 @@ extern DECLSPEC Uint8 SDLCALL SDL_GetMouseState(int *x, int *y);
  */
 extern DECLSPEC Uint8 SDLCALL SDL_GetRelativeMouseState(int *x, int *y);
 
-/*
+/**
  * Set the position of the mouse cursor (generates a mouse motion event)
  */
 extern DECLSPEC void SDLCALL SDL_WarpMouse(Uint16 x, Uint16 y);
 
-/*
+/**
  * Create a cursor using the specified data and mask (in MSB format).
  * The cursor width must be a multiple of 8 bits.
  *
@@ -83,24 +85,24 @@ extern DECLSPEC void SDLCALL SDL_WarpMouse(Uint16 x, Uint16 y);
 extern DECLSPEC SDL_Cursor * SDLCALL SDL_CreateCursor
 		(Uint8 *data, Uint8 *mask, int w, int h, int hot_x, int hot_y);
 
-/*
+/**
  * Set the currently active cursor to the specified one.
  * If the cursor is currently visible, the change will be immediately 
  * represented on the display.
  */
 extern DECLSPEC void SDLCALL SDL_SetCursor(SDL_Cursor *cursor);
 
-/*
+/**
  * Returns the currently active cursor.
  */
 extern DECLSPEC SDL_Cursor * SDLCALL SDL_GetCursor(void);
 
-/*
+/**
  * Deallocates a cursor created with SDL_CreateCursor().
  */
 extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor *cursor);
 
-/*
+/**
  * Toggle whether or not the cursor is shown on the screen.
  * The cursor start off displayed, but can be turned off.
  * SDL_ShowCursor() returns 1 if the cursor was being displayed
@@ -109,12 +111,13 @@ extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor *cursor);
  */
 extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
 
-/* Used as a mask when testing buttons in buttonstate
+/*@{*/
-   Button 1:	Left mouse button
+/** Used as a mask when testing buttons in buttonstate
-   Button 2:	Middle mouse button
+ *  Button 1:	Left mouse button
-   Button 3:	Right mouse button
+ *  Button 2:	Middle mouse button
-   Button 4:	Mouse wheel up	 (may also be a real button)
+ *  Button 3:	Right mouse button
-   Button 5:	Mouse wheel down (may also be a real button)
+ *  Button 4:	Mouse wheel up	 (may also be a real button)
+ *  Button 5:	Mouse wheel down (may also be a real button)
  */
 #define SDL_BUTTON(X)		(1 << ((X)-1))
 #define SDL_BUTTON_LEFT		1
@@ -122,10 +125,14 @@ extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
 #define SDL_BUTTON_RIGHT	3
 #define SDL_BUTTON_WHEELUP	4
 #define SDL_BUTTON_WHEELDOWN	5
+#define SDL_BUTTON_X1		6
+#define SDL_BUTTON_X2		7
 #define SDL_BUTTON_LMASK	SDL_BUTTON(SDL_BUTTON_LEFT)
 #define SDL_BUTTON_MMASK	SDL_BUTTON(SDL_BUTTON_MIDDLE)
 #define SDL_BUTTON_RMASK	SDL_BUTTON(SDL_BUTTON_RIGHT)
-
+#define SDL_BUTTON_X1MASK	SDL_BUTTON(SDL_BUTTON_X1)
+#define SDL_BUTTON_X2MASK	SDL_BUTTON(SDL_BUTTON_X2)
+/*@}*/
 
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus

code/SDL12/include/SDL_mutex.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -23,9 +23,10 @@
 #ifndef _SDL_mutex_h
 #define _SDL_mutex_h
 
-/* Functions to provide thread synchronization primitives
+/** @file SDL_mutex.h
-
+ *  Functions to provide thread synchronization primitives
-	These are independent of the other SDL routines.
+ *
+ *  @note These are independent of the other SDL routines.
  */
 
 #include "SDL_stdinc.h"
@@ -37,122 +38,135 @@
 extern "C" {
 #endif
 
-/* Synchronization functions which can time out return this value
+/** Synchronization functions which can time out return this value
-   if they time out.
+ *  if they time out.
  */
 #define SDL_MUTEX_TIMEDOUT	1
 
-/* This is the timeout value which corresponds to never time out */
+/** This is the timeout value which corresponds to never time out */
 #define SDL_MUTEX_MAXWAIT	(~(Uint32)0)
 
 
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-/* Mutex functions                                               */
+/** @name Mutex functions                                        */ /*@{*/
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
-/* The SDL mutex structure, defined in SDL_mutex.c */
+/** The SDL mutex structure, defined in SDL_mutex.c */
 struct SDL_mutex;
 typedef struct SDL_mutex SDL_mutex;
 
-/* Create a mutex, initialized unlocked */
+/** Create a mutex, initialized unlocked */
 extern DECLSPEC SDL_mutex * SDLCALL SDL_CreateMutex(void);
 
-/* Lock the mutex  (Returns 0, or -1 on error) */
 #define SDL_LockMutex(m)	SDL_mutexP(m)
+/** Lock the mutex
+ *  @return 0, or -1 on error
+ */
 extern DECLSPEC int SDLCALL SDL_mutexP(SDL_mutex *mutex);
 
-/* Unlock the mutex  (Returns 0, or -1 on error)
-   It is an error to unlock a mutex that has not been locked by
-   the current thread, and doing so results in undefined behavior.
- */
 #define SDL_UnlockMutex(m)	SDL_mutexV(m)
+/** Unlock the mutex
+ *  @return 0, or -1 on error
+ *
+ *  It is an error to unlock a mutex that has not been locked by
+ *  the current thread, and doing so results in undefined behavior.
+ */
 extern DECLSPEC int SDLCALL SDL_mutexV(SDL_mutex *mutex);
 
-/* Destroy a mutex */
+/** Destroy a mutex */
 extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex *mutex);
 
+/*@}*/
 
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-/* Semaphore functions                                           */
+/** @name Semaphore functions                                    */ /*@{*/
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
-/* The SDL semaphore structure, defined in SDL_sem.c */
+/** The SDL semaphore structure, defined in SDL_sem.c */
 struct SDL_semaphore;
 typedef struct SDL_semaphore SDL_sem;
 
-/* Create a semaphore, initialized with value, returns NULL on failure. */
+/** Create a semaphore, initialized with value, returns NULL on failure. */
 extern DECLSPEC SDL_sem * SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
 
-/* Destroy a semaphore */
+/** Destroy a semaphore */
 extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem *sem);
 
-/* This function suspends the calling thread until the semaphore pointed 
+/**
+ * This function suspends the calling thread until the semaphore pointed 
  * to by sem has a positive count. It then atomically decreases the semaphore
  * count.
  */
 extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem *sem);
 
-/* Non-blocking variant of SDL_SemWait(), returns 0 if the wait succeeds,
+/** Non-blocking variant of SDL_SemWait().
-   SDL_MUTEX_TIMEDOUT if the wait would block, and -1 on error.
+ *  @return 0 if the wait succeeds,
+ *  SDL_MUTEX_TIMEDOUT if the wait would block, and -1 on error.
  */
 extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem *sem);
 
-/* Variant of SDL_SemWait() with a timeout in milliseconds, returns 0 if
+/** Variant of SDL_SemWait() with a timeout in milliseconds, returns 0 if
-   the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait does not succeed in
+ *  the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait does not succeed in
-   the allotted time, and -1 on error.
+ *  the allotted time, and -1 on error.
-   On some platforms this function is implemented by looping with a delay
+ *
-   of 1 ms, and so should be avoided if possible.
+ *  On some platforms this function is implemented by looping with a delay
+ *  of 1 ms, and so should be avoided if possible.
  */
 extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem *sem, Uint32 ms);
 
-/* Atomically increases the semaphore's count (not blocking), returns 0,
+/** Atomically increases the semaphore's count (not blocking).
-   or -1 on error.
+ *  @return 0, or -1 on error.
  */
 extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem *sem);
 
-/* Returns the current count of the semaphore */
+/** Returns the current count of the semaphore */
 extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem *sem);
 
+/*@}*/
 
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-/* Condition variable functions                                  */
+/** @name Condition_variable_functions                           */ /*@{*/
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
-/* The SDL condition variable structure, defined in SDL_cond.c */
+/*@{*/
+/** The SDL condition variable structure, defined in SDL_cond.c */
 struct SDL_cond;
 typedef struct SDL_cond SDL_cond;
+/*@}*/
 
-/* Create a condition variable */
+/** Create a condition variable */
 extern DECLSPEC SDL_cond * SDLCALL SDL_CreateCond(void);
 
-/* Destroy a condition variable */
+/** Destroy a condition variable */
 extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond *cond);
 
-/* Restart one of the threads that are waiting on the condition variable,
+/** Restart one of the threads that are waiting on the condition variable,
-   returns 0 or -1 on error.
+ *  @return 0 or -1 on error.
  */
 extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond *cond);
 
-/* Restart all threads that are waiting on the condition variable,
+/** Restart all threads that are waiting on the condition variable,
-   returns 0 or -1 on error.
+ *  @return 0 or -1 on error.
  */
 extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond *cond);
 
-/* Wait on the condition variable, unlocking the provided mutex.
+/** Wait on the condition variable, unlocking the provided mutex.
-   The mutex must be locked before entering this function!
+ *  The mutex must be locked before entering this function!
-   The mutex is re-locked once the condition variable is signaled.
+ *  The mutex is re-locked once the condition variable is signaled.
-   Returns 0 when it is signaled, or -1 on error.
+ *  @return 0 when it is signaled, or -1 on error.
  */
 extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond *cond, SDL_mutex *mut);
 
-/* Waits for at most 'ms' milliseconds, and returns 0 if the condition
+/** Waits for at most 'ms' milliseconds, and returns 0 if the condition
-   variable is signaled, SDL_MUTEX_TIMEDOUT if the condition is not
+ *  variable is signaled, SDL_MUTEX_TIMEDOUT if the condition is not
-   signaled in the allotted time, and -1 on error.
+ *  signaled in the allotted time, and -1 on error.
-   On some platforms this function is implemented by looping with a delay
+ *  On some platforms this function is implemented by looping with a delay
-   of 1 ms, and so should be avoided if possible.
+ *  of 1 ms, and so should be avoided if possible.
  */
 extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond *cond, SDL_mutex *mutex, Uint32 ms);
 
+/*@}*/
+
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
 }
@@ -160,3 +174,4 @@ extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond *cond, SDL_mutex *mutex
 #include "close_code.h"
 
 #endif /* _SDL_mutex_h */
+

code/SDL12/include/SDL_opengl.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -20,7 +20,9 @@
     slouken@libsdl.org
 */
 
-/* This is a simple file to encapsulate the OpenGL API headers */
+/** @file SDL_opengl.h
+ *  This is a simple file to encapsulate the OpenGL API headers
+ */
 
 #include "SDL_config.h"
 
@@ -48,10 +50,12 @@
 #undef __glext_h_
 #endif
 
-/* This file taken from "GLext.h" from the Jeff Molofee OpenGL tutorials.
+/** @name GLext.h
-   It is included here because glext.h is not available on some systems.
+ *  This file taken from "GLext.h" from the Jeff Molofee OpenGL tutorials.
-   If you don't want this version included, simply define "NO_SDL_GLEXT"
+ *  It is included here because glext.h is not available on some systems.
+ *  If you don't want this version included, simply define "NO_SDL_GLEXT"
  */
+/*@{*/
 #ifndef NO_SDL_GLEXT
 #if !defined(__glext_h_) && !defined(GL_GLEXT_LEGACY)
 #define __glext_h_
@@ -6549,3 +6553,4 @@ typedef void (APIENTRYP PFNGLSTRINGMARKERGREMEDYPROC) (GLsizei len, const GLvoid
 
 #endif
 #endif /* NO_SDL_GLEXT */
+/*@}*/

code/SDL12/include/SDL_platform.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -20,7 +20,9 @@
     slouken@libsdl.org
 */
 
-/* Try to get a standard set of platform defines */
+/** @file SDL_platform.h
+ *  Try to get a standard set of platform defines
+ */
 
 #ifndef _SDL_platform_h
 #define _SDL_platform_h
@@ -29,14 +31,14 @@
 #undef __AIX__
 #define __AIX__		1
 #endif
-#if defined(AMIGA) || defined(__AMIGA) || defined(__amigados__)
-#undef __AMIGA__
-#define __AMIGA__	1
-#endif
 #if defined(__BEOS__)
 #undef __BEOS__
 #define __BEOS__	1
 #endif
+#if defined(__HAIKU__)
+#undef __HAIKU__
+#define __HAIKU__ 1
+#endif
 #if defined(bsdi) || defined(__bsdi) || defined(__bsdi__)
 #undef __BSDI__
 #define __BSDI__	1
@@ -45,10 +47,14 @@
 #undef __DREAMCAST__
 #define __DREAMCAST__	1
 #endif
-#if defined(__FreeBSD__) || defined(__DragonFly__)
+#if defined(__FreeBSD__) || defined(__FreeBSD_kernel__) || defined(__DragonFly__)
 #undef __FREEBSD__
 #define __FREEBSD__	1
 #endif
+#if defined(__HAIKU__)
+#undef __HAIKU__
+#define __HAIKU__	1
+#endif
 #if defined(hpux) || defined(__hpux) || defined(__hpux__)
 #undef __HPUX__
 #define __HPUX__	1

code/SDL12/include/SDL_quit.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -20,7 +20,9 @@
     slouken@libsdl.org
 */
 
-/* Include file for SDL quit event handling */
+/** @file SDL_quit.h
+ *  Include file for SDL quit event handling
+ */
 
 #ifndef _SDL_quit_h
 #define _SDL_quit_h
@@ -28,22 +30,25 @@
 #include "SDL_stdinc.h"
 #include "SDL_error.h"
 
-/* 
+/** @file SDL_quit.h
-  An SDL_QUITEVENT is generated when the user tries to close the application
+ *  An SDL_QUITEVENT is generated when the user tries to close the application
-  window.  If it is ignored or filtered out, the window will remain open.
+ *  window.  If it is ignored or filtered out, the window will remain open.
-  If it is not ignored or filtered, it is queued normally and the window
+ *  If it is not ignored or filtered, it is queued normally and the window
-  is allowed to close.  When the window is closed, screen updates will 
+ *  is allowed to close.  When the window is closed, screen updates will 
-  complete, but have no effect.
+ *  complete, but have no effect.
-
+ *
-  SDL_Init() installs signal handlers for SIGINT (keyboard interrupt)
+ *  SDL_Init() installs signal handlers for SIGINT (keyboard interrupt)
-  and SIGTERM (system termination request), if handlers do not already
+ *  and SIGTERM (system termination request), if handlers do not already
-  exist, that generate SDL_QUITEVENT events as well.  There is no way
+ *  exist, that generate SDL_QUITEVENT events as well.  There is no way
-  to determine the cause of an SDL_QUITEVENT, but setting a signal
+ *  to determine the cause of an SDL_QUITEVENT, but setting a signal
-  handler in your application will override the default generation of
+ *  handler in your application will override the default generation of
-  quit events for that signal.
+ *  quit events for that signal.
+ */
+
+/** @file SDL_quit.h
+ *  There are no functions directly affecting the quit event 
  */
 
-/* There are no functions directly affecting the quit event */
 #define SDL_QuitRequested() \
         (SDL_PumpEvents(), SDL_PeepEvents(NULL,0,SDL_PEEKEVENT,SDL_QUITMASK))
 

code/SDL12/include/SDL_rwops.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -20,8 +20,9 @@
     slouken@libsdl.org
 */
 
-/* This file provides a general interface for SDL to read and write
+/** @file SDL_rwops.h
-   data sources.  It can easily be extended to files, memory, etc.
+ *  This file provides a general interface for SDL to read and write
+ *  data sources.  It can easily be extended to files, memory, etc.
  */
 
 #ifndef _SDL_rwops_h
@@ -36,36 +37,41 @@
 extern "C" {
 #endif
 
-/* This is the read/write operation structure -- very basic */
+/** This is the read/write operation structure -- very basic */
 
 typedef struct SDL_RWops {
-	/* Seek to 'offset' relative to whence, one of stdio's whence values:
+	/** Seek to 'offset' relative to whence, one of stdio's whence values:
-		SEEK_SET, SEEK_CUR, SEEK_END
+	 *	SEEK_SET, SEEK_CUR, SEEK_END
-	   Returns the final offset in the data source.
+	 *  Returns the final offset in the data source.
 	 */
 	int (SDLCALL *seek)(struct SDL_RWops *context, int offset, int whence);
 
-	/* Read up to 'num' objects each of size 'objsize' from the data
+	/** Read up to 'maxnum' objects each of size 'size' from the data
-	   source to the area pointed at by 'ptr'.
+	 *  source to the area pointed at by 'ptr'.
-	   Returns the number of objects read, or -1 if the read failed.
+	 *  Returns the number of objects read, or -1 if the read failed.
 	 */
 	int (SDLCALL *read)(struct SDL_RWops *context, void *ptr, int size, int maxnum);
 
-	/* Write exactly 'num' objects each of size 'objsize' from the area
+	/** Write exactly 'num' objects each of size 'objsize' from the area
-	   pointed at by 'ptr' to data source.
+	 *  pointed at by 'ptr' to data source.
-	   Returns 'num', or -1 if the write failed.
+	 *  Returns 'num', or -1 if the write failed.
 	 */
 	int (SDLCALL *write)(struct SDL_RWops *context, const void *ptr, int size, int num);
 
-	/* Close and free an allocated SDL_FSops structure */
+	/** Close and free an allocated SDL_FSops structure */
 	int (SDLCALL *close)(struct SDL_RWops *context);
 
 	Uint32 type;
 	union {
-#ifdef __WIN32__
+#if defined(__WIN32__) && !defined(__SYMBIAN32__)
 	    struct {
 		int   append;
 		void *h;
+		struct {
+		    void *data;
+		    int size;
+		    int left;
+		} buffer;
 	    } win32io;
 #endif
 #ifdef HAVE_STDIO_H 
@@ -87,7 +93,8 @@ typedef struct SDL_RWops {
 } SDL_RWops;
 
 
-/* Functions to create SDL_RWops structures from various data sources */
+/** @name Functions to create SDL_RWops structures from various data sources */
+/*@{*/
 
 extern DECLSPEC SDL_RWops * SDLCALL SDL_RWFromFile(const char *file, const char *mode);
 
@@ -101,34 +108,43 @@ extern DECLSPEC SDL_RWops * SDLCALL SDL_RWFromConstMem(const void *mem, int size
 extern DECLSPEC SDL_RWops * SDLCALL SDL_AllocRW(void);
 extern DECLSPEC void SDLCALL SDL_FreeRW(SDL_RWops *area);
 
-#define RW_SEEK_SET	0	/* Seek from the beginning of data */
+/*@}*/
-#define RW_SEEK_CUR	1	/* Seek relative to current read point */
-#define RW_SEEK_END	2	/* Seek relative to the end of data */
 
-/* Macros to easily read and write from an SDL_RWops structure */
+/** @name Seek Reference Points */
+/*@{*/
+#define RW_SEEK_SET	0	/**< Seek from the beginning of data */
+#define RW_SEEK_CUR	1	/**< Seek relative to current read point */
+#define RW_SEEK_END	2	/**< Seek relative to the end of data */
+/*@}*/
+
+/** @name Macros to easily read and write from an SDL_RWops structure */
+/*@{*/
 #define SDL_RWseek(ctx, offset, whence)	(ctx)->seek(ctx, offset, whence)
 #define SDL_RWtell(ctx)			(ctx)->seek(ctx, 0, RW_SEEK_CUR)
 #define SDL_RWread(ctx, ptr, size, n)	(ctx)->read(ctx, ptr, size, n)
 #define SDL_RWwrite(ctx, ptr, size, n)	(ctx)->write(ctx, ptr, size, n)
 #define SDL_RWclose(ctx)		(ctx)->close(ctx)
+/*@}*/
 
-
+/** @name Read an item of the specified endianness and return in native format */
-/* Read an item of the specified endianness and return in native format */
+/*@{*/
 extern DECLSPEC Uint16 SDLCALL SDL_ReadLE16(SDL_RWops *src);
 extern DECLSPEC Uint16 SDLCALL SDL_ReadBE16(SDL_RWops *src);
 extern DECLSPEC Uint32 SDLCALL SDL_ReadLE32(SDL_RWops *src);
 extern DECLSPEC Uint32 SDLCALL SDL_ReadBE32(SDL_RWops *src);
 extern DECLSPEC Uint64 SDLCALL SDL_ReadLE64(SDL_RWops *src);
 extern DECLSPEC Uint64 SDLCALL SDL_ReadBE64(SDL_RWops *src);
+/*@}*/
 
-/* Write an item of native format to the specified endianness */
+/** @name Write an item of native format to the specified endianness */
+/*@{*/
 extern DECLSPEC int SDLCALL SDL_WriteLE16(SDL_RWops *dst, Uint16 value);
 extern DECLSPEC int SDLCALL SDL_WriteBE16(SDL_RWops *dst, Uint16 value);
 extern DECLSPEC int SDLCALL SDL_WriteLE32(SDL_RWops *dst, Uint32 value);
 extern DECLSPEC int SDLCALL SDL_WriteBE32(SDL_RWops *dst, Uint32 value);
 extern DECLSPEC int SDLCALL SDL_WriteLE64(SDL_RWops *dst, Uint64 value);
 extern DECLSPEC int SDLCALL SDL_WriteBE64(SDL_RWops *dst, Uint64 value);
-
+/*@}*/
 
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus

code/SDL12/include/SDL_stdinc.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -20,7 +20,9 @@
     slouken@libsdl.org
 */
 
-/* This is a general header that includes C language support */
+/** @file SDL_stdinc.h
+ *  This is a general header that includes C language support
+ */
 
 #ifndef _SDL_stdinc_h
 #define _SDL_stdinc_h
@@ -68,16 +70,27 @@
 #ifdef HAVE_CTYPE_H
 # include <ctype.h>
 #endif
-#ifdef HAVE_ICONV_H
+#if defined(HAVE_ICONV) && defined(HAVE_ICONV_H)
 # include <iconv.h>
 #endif
 
-/* The number of elements in an array */
+/** The number of elements in an array */
 #define SDL_arraysize(array)	(sizeof(array)/sizeof(array[0]))
 #define SDL_TABLESIZE(table)	SDL_arraysize(table)
 
-/* Basic data types */
+/* Use proper C++ casts when compiled as C++ to be compatible with the option
-typedef enum SDL_bool {
+ -Wold-style-cast of GCC (and -Werror=old-style-cast in GCC 4.2 and above. */
+#ifdef __cplusplus
+#define SDL_reinterpret_cast(type, expression) reinterpret_cast<type>(expression)
+#define SDL_static_cast(type, expression) static_cast<type>(expression)
+#else
+#define SDL_reinterpret_cast(type, expression) ((type)(expression))
+#define SDL_static_cast(type, expression) ((type)(expression))
+#endif
+
+/** @name Basic data types */
+/*@{*/
+typedef enum {
 	SDL_FALSE = 0,
 	SDL_TRUE  = 1
 } SDL_bool;
@@ -91,7 +104,9 @@ typedef uint32_t	Uint32;
 
 #ifdef SDL_HAS_64BIT_TYPE
 typedef int64_t		Sint64;
+#ifndef SYMBIAN32_GCCE
 typedef uint64_t	Uint64;
+#endif
 #else
 /* This is really just a hack to prevent the compiler from complaining */
 typedef struct {
@@ -100,7 +115,10 @@ typedef struct {
 } Uint64, Sint64;
 #endif
 
-/* Make sure the types really have the right sizes */
+/*@}*/
+
+/** @name Make sure the types really have the right sizes */
+/*@{*/
 #define SDL_COMPILE_TIME_ASSERT(name, x)               \
        typedef int SDL_dummy_ ## name[(x) * 2 - 1]
 
@@ -112,11 +130,13 @@ SDL_COMPILE_TIME_ASSERT(uint32, sizeof(Uint32) == 4);
 SDL_COMPILE_TIME_ASSERT(sint32, sizeof(Sint32) == 4);
 SDL_COMPILE_TIME_ASSERT(uint64, sizeof(Uint64) == 8);
 SDL_COMPILE_TIME_ASSERT(sint64, sizeof(Sint64) == 8);
+/*@}*/
 
-/* Check to make sure enums are the size of ints, for structure packing.
+/** @name Enum Size Check
-   For both Watcom C/C++ and Borland C/C++ the compiler option that makes
+ *  Check to make sure enums are the size of ints, for structure packing.
-   enums having the size of an int must be enabled.
+ *  For both Watcom C/C++ and Borland C/C++ the compiler option that makes
-   This is "-b" for Borland C/C++ and "-ei" for Watcom C/C++ (v11).
+ *  enums having the size of an int must be enabled.
+ *  This is "-b" for Borland C/C++ and "-ei" for Watcom C/C++ (v11).
  */
 /* Enable enums always int in CodeWarrior (for MPW use "-enum int") */
 #ifdef __MWERKS__
@@ -127,8 +147,10 @@ typedef enum {
 	DUMMY_ENUM_VALUE
 } SDL_DUMMY_ENUM;
 
+#ifndef __NDS__
 SDL_COMPILE_TIME_ASSERT(enum, sizeof(SDL_DUMMY_ENUM) == sizeof(int));
-
+#endif
+/*@}*/
 
 #include "begin_code.h"
 /* Set up for C function definitions, even when using C++ */
@@ -170,6 +192,8 @@ extern DECLSPEC void SDLCALL SDL_free(void *mem);
 #  define alloca _alloca
 # elif defined(__WATCOMC__)
 #  include <malloc.h>
+# elif defined(__BORLANDC__)
+#  include <malloc.h>
 # elif defined(__DMC__)
 #  include <stdlib.h>
 # elif defined(__AIX__)
@@ -181,10 +205,10 @@ extern DECLSPEC void SDLCALL SDL_free(void *mem);
 # endif
 #endif
 #ifdef HAVE_ALLOCA
-#define SDL_stack_alloc(type, count)    (type*)alloca(sizeof(type)*count)
+#define SDL_stack_alloc(type, count)    (type*)alloca(sizeof(type)*(count))
 #define SDL_stack_free(data)
 #else
-#define SDL_stack_alloc(type, count)    (type*)SDL_malloc(sizeof(type)*count)
+#define SDL_stack_alloc(type, count)    (type*)SDL_malloc(sizeof(type)*(count))
 #define SDL_stack_free(data)            SDL_free(data)
 #endif
 
@@ -242,7 +266,7 @@ do {								\
 		"cld\n\t"					\
 		"rep ; stosl\n\t"				\
 		: "=&D" (u0), "=&a" (u1), "=&c" (u2)		\
-		: "0" (dst), "1" (val), "2" ((Uint32)(len))	\
+		: "0" (dst), "1" (val), "2" (SDL_static_cast(Uint32, len))	\
 		: "memory" );					\
 } while(0)
 #endif
@@ -251,8 +275,9 @@ do {								\
 do {						\
 	unsigned _count = (len);		\
 	unsigned _n = (_count + 3) / 4;		\
-	Uint32 *_p = (Uint32 *)(dst);		\
+	Uint32 *_p = SDL_static_cast(Uint32 *, dst);	\
 	Uint32 _val = (val);			\
+	if (len == 0) break;			\
         switch (_count % 4) {			\
         case 0: do {    *_p++ = _val;		\
         case 3:         *_p++ = _val;		\
@@ -263,7 +288,10 @@ do {						\
 } while(0)
 #endif
 
-#if defined(__GNUC__) && defined(i386)
+/* We can count on memcpy existing on Mac OS X and being well-tuned. */
+#if defined(__MACH__) && defined(__APPLE__)
+#define SDL_memcpy(dst, src, len) memcpy(dst, src, len)
+#elif defined(__GNUC__) && defined(i386)
 #define SDL_memcpy(dst, src, len)					  \
 do {									  \
 	int u0, u1, u2;						  	  \
@@ -278,7 +306,7 @@ do {									  \
 		"movsb\n"						  \
 		"2:"							  \
 		: "=&c" (u0), "=&D" (u1), "=&S" (u2)			  \
-		: "0" ((unsigned)(len)/4), "q" (len), "1" (dst),"2" (src) \
+		: "0" (SDL_static_cast(unsigned, len)/4), "q" (len), "1" (dst),"2" (src) \
 		: "memory" );						  \
 } while(0)
 #endif
@@ -292,7 +320,10 @@ extern DECLSPEC void * SDLCALL SDL_memcpy(void *dst, const void *src, size_t len
 #endif
 #endif
 
-#if defined(__GNUC__) && defined(i386)
+/* We can count on memcpy existing on Mac OS X and being well-tuned. */
+#if defined(__MACH__) && defined(__APPLE__)
+#define SDL_memcpy4(dst, src, len) memcpy(dst, src, (len)*4)
+#elif defined(__GNUC__) && defined(i386)
 #define SDL_memcpy4(dst, src, len)				\
 do {								\
 	int ecx, edi, esi;					\
@@ -300,7 +331,7 @@ do {								\
 		"cld\n\t"					\
 		"rep ; movsl"					\
 		: "=&c" (ecx), "=&D" (edi), "=&S" (esi)		\
-		: "0" ((unsigned)(len)), "1" (dst), "2" (src)	\
+		: "0" (SDL_static_cast(unsigned, len)), "1" (dst), "2" (src)	\
 		: "memory" );					\
 } while(0)
 #endif
@@ -312,13 +343,14 @@ do {								\
 #define SDL_revcpy(dst, src, len)			\
 do {							\
 	int u0, u1, u2;					\
-	char *dstp = (char *)(dst);			\
+	char *dstp = SDL_static_cast(char *, dst);	\
-	char *srcp = (char *)(src);			\
+	char *srcp = SDL_static_cast(char *, src);	\
 	int n = (len);					\
 	if ( n >= 4 ) {					\
 	__asm__ __volatile__ (				\
 		"std\n\t"				\
 		"rep ; movsl\n\t"			\
+		"cld\n\t"				\
 		: "=&c" (u0), "=&D" (u1), "=&S" (u2)	\
 		: "0" (n >> 2),				\
 		  "1" (dstp+(n-4)), "2" (srcp+(n-4))	\
@@ -551,29 +583,31 @@ extern DECLSPEC int SDLCALL SDL_snprintf(char *text, size_t maxlen, const char *
 extern DECLSPEC int SDLCALL SDL_vsnprintf(char *text, size_t maxlen, const char *fmt, va_list ap);
 #endif
 
-/* The SDL implementation of iconv() returns these error codes */
+/** @name SDL_ICONV Error Codes
+ *  The SDL implementation of iconv() returns these error codes 
+ */
+/*@{*/
 #define SDL_ICONV_ERROR		(size_t)-1
 #define SDL_ICONV_E2BIG		(size_t)-2
 #define SDL_ICONV_EILSEQ	(size_t)-3
 #define SDL_ICONV_EINVAL	(size_t)-4
+/*@}*/
 
-#ifdef HAVE_ICONV
+#if defined(HAVE_ICONV) && defined(HAVE_ICONV_H)
 #define SDL_iconv_t     iconv_t
 #define SDL_iconv_open  iconv_open
 #define SDL_iconv_close iconv_close
-extern DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft);
 #else
 typedef struct _SDL_iconv_t *SDL_iconv_t;
 extern DECLSPEC SDL_iconv_t SDLCALL SDL_iconv_open(const char *tocode, const char *fromcode);
 extern DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd);
-extern DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft);
 #endif
-/* This function converts a string between encodings in one pass, returning a
+extern DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft);
-   string that must be freed with SDL_free() or NULL on error.
+/** This function converts a string between encodings in one pass, returning a
+ *  string that must be freed with SDL_free() or NULL on error.
  */
-extern DECLSPEC char * SDLCALL SDL_iconv_string(const char *tocode, const char *fromcode, char *inbuf, size_t inbytesleft);
+extern DECLSPEC char * SDLCALL SDL_iconv_string(const char *tocode, const char *fromcode, const char *inbuf, size_t inbytesleft);
-#define SDL_iconv_utf8_ascii(S)		SDL_iconv_string("ASCII", "UTF-8", S, SDL_strlen(S)+1)
+#define SDL_iconv_utf8_locale(S)	SDL_iconv_string("", "UTF-8", S, SDL_strlen(S)+1)
-#define SDL_iconv_utf8_latin1(S)	SDL_iconv_string("LATIN1", "UTF-8", S, SDL_strlen(S)+1)
 #define SDL_iconv_utf8_ucs2(S)		(Uint16 *)SDL_iconv_string("UCS-2", "UTF-8", S, SDL_strlen(S)+1)
 #define SDL_iconv_utf8_ucs4(S)		(Uint32 *)SDL_iconv_string("UCS-4", "UTF-8", S, SDL_strlen(S)+1)
 

code/SDL12/include/SDL_syswm.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -20,7 +20,9 @@
     slouken@libsdl.org
 */
 
-/* Include file for SDL custom system window manager hooks */
+/** @file SDL_syswm.h
+ *  Include file for SDL custom system window manager hooks
+ */
 
 #ifndef _SDL_syswm_h
 #define _SDL_syswm_h
@@ -35,10 +37,11 @@
 extern "C" {
 #endif
 
-/* Your application has access to a special type of event 'SDL_SYSWMEVENT',
+/** @file SDL_syswm.h
-   which contains window-manager specific information and arrives whenever
+ *  Your application has access to a special type of event 'SDL_SYSWMEVENT',
-   an unhandled window event occurs.  This event is ignored by default, but
+ *  which contains window-manager specific information and arrives whenever
-   you can enable it with SDL_EventState()
+ *  an unhandled window event occurs.  This event is ignored by default, but
+ *  you can enable it with SDL_EventState()
  */
 #ifdef SDL_PROTOTYPES_ONLY
 struct SDL_SysWMinfo;
@@ -60,12 +63,12 @@ typedef struct SDL_SysWMinfo SDL_SysWMinfo;
 #undef Cursor
 #endif
 
-/* These are the various supported subsystems under UNIX */
+/** These are the various supported subsystems under UNIX */
 typedef enum {
 	SDL_SYSWM_X11
 } SDL_SYSWM_TYPE;
 
-/* The UNIX custom event structure */
+/** The UNIX custom event structure */
 struct SDL_SysWMmsg {
 	SDL_version version;
 	SDL_SYSWM_TYPE subsystem;
@@ -74,28 +77,38 @@ struct SDL_SysWMmsg {
 	} event;
 };
 
-/* The UNIX custom window manager information structure.
+/** The UNIX custom window manager information structure.
-   When this structure is returned, it holds information about which
+ *  When this structure is returned, it holds information about which
-   low level system it is using, and will be one of SDL_SYSWM_TYPE.
+ *  low level system it is using, and will be one of SDL_SYSWM_TYPE.
  */
 typedef struct SDL_SysWMinfo {
 	SDL_version version;
 	SDL_SYSWM_TYPE subsystem;
 	union {
 	    struct {
-	    	Display *display;	/* The X11 display */
+	    	Display *display;	/**< The X11 display */
-	    	Window window;		/* The X11 display window */
+	    	Window window;		/**< The X11 display window */
-		/* These locking functions should be called around
+		/** These locking functions should be called around
-                   any X11 functions using the display variable.
+                 *  any X11 functions using the display variable, 
-                   They lock the event thread, so should not be
+                 *  but not the gfxdisplay variable.
-		   called around event functions or from event filters.
+                 *  They lock the event thread, so should not be
+		 *  called around event functions or from event filters.
 		 */
+                /*@{*/
 		void (*lock_func)(void);
 		void (*unlock_func)(void);
+                /*@}*/
 
-		/* Introduced in SDL 1.0.2 */
+		/** @name Introduced in SDL 1.0.2 */
-	    	Window fswindow;	/* The X11 fullscreen window */
+                /*@{*/
-	    	Window wmwindow;	/* The X11 managed input window */
+	    	Window fswindow;	/**< The X11 fullscreen window */
+	    	Window wmwindow;	/**< The X11 managed input window */
+                /*@}*/
+
+		/** @name Introduced in SDL 1.2.12 */
+                /*@{*/
+		Display *gfxdisplay;	/**< The X11 display to which rendering is done */
+                /*@}*/
 	    } x11;
 	} info;
 } SDL_SysWMinfo;
@@ -103,13 +116,13 @@ typedef struct SDL_SysWMinfo {
 #elif defined(SDL_VIDEO_DRIVER_NANOX)
 #include <microwin/nano-X.h>
 
-/* The generic custom event structure */
+/** The generic custom event structure */
 struct SDL_SysWMmsg {
 	SDL_version version;
 	int data;
 };
 
-/* The windows custom window manager information structure */
+/** The windows custom window manager information structure */
 typedef struct SDL_SysWMinfo {
 	SDL_version version ;
 	GR_WINDOW_ID window ;	/* The display window */
@@ -119,50 +132,50 @@ typedef struct SDL_SysWMinfo {
 #define WIN32_LEAN_AND_MEAN
 #include <windows.h>
 
-/* The windows custom event structure */
+/** The windows custom event structure */
 struct SDL_SysWMmsg {
 	SDL_version version;
-	HWND hwnd;			/* The window for the message */
+	HWND hwnd;			/**< The window for the message */
-	UINT msg;			/* The type of message */
+	UINT msg;			/**< The type of message */
-	WPARAM wParam;			/* WORD message parameter */
+	WPARAM wParam;			/**< WORD message parameter */
-	LPARAM lParam;			/* LONG message parameter */
+	LPARAM lParam;			/**< LONG message parameter */
 };
 
-/* The windows custom window manager information structure */
+/** The windows custom window manager information structure */
 typedef struct SDL_SysWMinfo {
 	SDL_version version;
-	HWND window;			/* The Win32 display window */
+	HWND window;			/**< The Win32 display window */
-	HGLRC hglrc;			/* The OpenGL context, if any */
+	HGLRC hglrc;			/**< The OpenGL context, if any */
 } SDL_SysWMinfo;
 
 #elif defined(SDL_VIDEO_DRIVER_RISCOS)
 
-/* RISC OS custom event structure */
+/** RISC OS custom event structure */
 struct SDL_SysWMmsg {
 	SDL_version version;
-	int eventCode;		/* The window for the message */
+	int eventCode;		/**< The window for the message */
 	int pollBlock[64];
 };
 
-/* The RISC OS custom window manager information structure */
+/** The RISC OS custom window manager information structure */
 typedef struct SDL_SysWMinfo {
 	SDL_version version;
-	int wimpVersion;    /* Wimp version running under */
+	int wimpVersion;    /**< Wimp version running under */
-	int taskHandle;     /* The RISC OS task handle */
+	int taskHandle;     /**< The RISC OS task handle */
-	int window;		/* The RISC OS display window */
+	int window;		/**< The RISC OS display window */
 } SDL_SysWMinfo;
 
 #elif defined(SDL_VIDEO_DRIVER_PHOTON)
 #include <sys/neutrino.h>
 #include <Ph.h>
 
-/* The QNX custom event structure */
+/** The QNX custom event structure */
 struct SDL_SysWMmsg {
 	SDL_version version;
 	int data;
 };
 
-/* The QNX custom window manager information structure */
+/** The QNX custom window manager information structure */
 typedef struct SDL_SysWMinfo {
 	SDL_version version;
 	int data;
@@ -170,13 +183,13 @@ typedef struct SDL_SysWMinfo {
 
 #else
 
-/* The generic custom event structure */
+/** The generic custom event structure */
 struct SDL_SysWMmsg {
 	SDL_version version;
 	int data;
 };
 
-/* The generic custom window manager information structure */
+/** The generic custom window manager information structure */
 typedef struct SDL_SysWMinfo {
 	SDL_version version;
 	int data;
@@ -187,16 +200,18 @@ typedef struct SDL_SysWMinfo {
 #endif /* SDL_PROTOTYPES_ONLY */
 
 /* Function prototypes */
-/*
+/**
  * This function gives you custom hooks into the window manager information.
  * It fills the structure pointed to by 'info' with custom information and
  * returns 1 if the function is implemented.  If it's not implemented, or
  * the version member of the 'info' structure is invalid, it returns 0. 
  *
  * You typically use this function like this:
+ * @code
  * SDL_SysWMInfo info;
  * SDL_VERSION(&info.version);
  * if ( SDL_GetWMInfo(&info) ) { ... }
+ * @endcode
  */
 extern DECLSPEC int SDLCALL SDL_GetWMInfo(SDL_SysWMinfo *info);
 

code/SDL12/include/SDL_thread.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -23,9 +23,10 @@
 #ifndef _SDL_thread_h
 #define _SDL_thread_h
 
-/* Header for the SDL thread management routines 
+/** @file SDL_thread.h
-
+ *  Header for the SDL thread management routines 
-	These are independent of the other SDL routines.
+ *
+ *  @note These are independent of the other SDL routines.
  */
 
 #include "SDL_stdinc.h"
@@ -40,24 +41,24 @@
 extern "C" {
 #endif
 
-/* The SDL thread structure, defined in SDL_thread.c */
+/** The SDL thread structure, defined in SDL_thread.c */
 struct SDL_Thread;
 typedef struct SDL_Thread SDL_Thread;
 
-/* Create a thread */
+/** Create a thread */
-#if (defined(__WIN32__) && !defined(HAVE_LIBC)) || defined(__OS2__)
+#if ((defined(__WIN32__) && !defined(HAVE_LIBC)) || defined(__OS2__)) &&  !defined(__SYMBIAN32__)
-/*
+/**
-   We compile SDL into a DLL on OS/2. This means, that it's the DLL which
+ *  We compile SDL into a DLL on OS/2. This means, that it's the DLL which
-   creates a new thread for the calling process with the SDL_CreateThread()
+ *  creates a new thread for the calling process with the SDL_CreateThread()
-   API. There is a problem with this, that only the RTL of the SDL.DLL will
+ *  API. There is a problem with this, that only the RTL of the SDL.DLL will
-   be initialized for those threads, and not the RTL of the calling application!
+ *  be initialized for those threads, and not the RTL of the calling application!
-   To solve this, we make a little hack here.
+ *  To solve this, we make a little hack here.
-   We'll always use the caller's _beginthread() and _endthread() APIs to
+ *  We'll always use the caller's _beginthread() and _endthread() APIs to
-   start a new thread. This way, if it's the SDL.DLL which uses this API,
+ *  start a new thread. This way, if it's the SDL.DLL which uses this API,
-   then the RTL of SDL.DLL will be used to create the new thread, and if it's
+ *  then the RTL of SDL.DLL will be used to create the new thread, and if it's
-   the application, then the RTL of the application will be used.
+ *  the application, then the RTL of the application will be used.
-   So, in short:
+ *  So, in short:
-   Always use the _beginthread() and _endthread() of the calling runtime library!
+ *  Always use the _beginthread() and _endthread() of the calling runtime library!
  */
 #define SDL_PASSED_BEGINTHREAD_ENDTHREAD
 #ifndef _WIN32_WCE
@@ -92,21 +93,21 @@ extern DECLSPEC SDL_Thread * SDLCALL SDL_CreateThread(int (SDLCALL *fn)(void *),
 extern DECLSPEC SDL_Thread * SDLCALL SDL_CreateThread(int (SDLCALL *fn)(void *), void *data);
 #endif
 
-/* Get the 32-bit thread identifier for the current thread */
+/** Get the 32-bit thread identifier for the current thread */
 extern DECLSPEC Uint32 SDLCALL SDL_ThreadID(void);
 
-/* Get the 32-bit thread identifier for the specified thread,
+/** Get the 32-bit thread identifier for the specified thread,
-   equivalent to SDL_ThreadID() if the specified thread is NULL.
+ *  equivalent to SDL_ThreadID() if the specified thread is NULL.
  */
 extern DECLSPEC Uint32 SDLCALL SDL_GetThreadID(SDL_Thread *thread);
 
-/* Wait for a thread to finish.
+/** Wait for a thread to finish.
-   The return code for the thread function is placed in the area
+ *  The return code for the thread function is placed in the area
-   pointed to by 'status', if 'status' is not NULL.
+ *  pointed to by 'status', if 'status' is not NULL.
  */
 extern DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread *thread, int *status);
 
-/* Forcefully kill a thread without worrying about its state */
+/** Forcefully kill a thread without worrying about its state */
 extern DECLSPEC void SDLCALL SDL_KillThread(SDL_Thread *thread);
 
 

code/SDL12/include/SDL_timer.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -23,7 +23,9 @@
 #ifndef _SDL_timer_h
 #define _SDL_timer_h
 
-/* Header for the SDL time management routines */
+/** @file SDL_timer.h
+ *  Header for the SDL time management routines
+ */
 
 #include "SDL_stdinc.h"
 #include "SDL_error.h"
@@ -34,24 +36,26 @@
 extern "C" {
 #endif
 
-/* This is the OS scheduler timeslice, in milliseconds */
+/** This is the OS scheduler timeslice, in milliseconds */
 #define SDL_TIMESLICE		10
 
-/* This is the maximum resolution of the SDL timer on all platforms */
+/** This is the maximum resolution of the SDL timer on all platforms */
-#define TIMER_RESOLUTION	10	/* Experimentally determined */
+#define TIMER_RESOLUTION	10	/**< Experimentally determined */
 
-/* Get the number of milliseconds since the SDL library initialization.
+/**
+ * Get the number of milliseconds since the SDL library initialization.
  * Note that this value wraps if the program runs for more than ~49 days.
  */ 
 extern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void);
 
-/* Wait a specified number of milliseconds before returning */
+/** Wait a specified number of milliseconds before returning */
 extern DECLSPEC void SDLCALL SDL_Delay(Uint32 ms);
 
-/* Function prototype for the timer callback function */
+/** Function prototype for the timer callback function */
 typedef Uint32 (SDLCALL *SDL_TimerCallback)(Uint32 interval);
 
-/* Set a callback to run after the specified number of milliseconds has
+/**
+ * Set a callback to run after the specified number of milliseconds has
  * elapsed. The callback function is passed the current timer interval
  * and returns the next timer interval.  If the returned value is the 
  * same as the one passed in, the periodic alarm continues, otherwise a
@@ -68,7 +72,7 @@ typedef Uint32 (SDLCALL *SDL_TimerCallback)(Uint32 interval);
  * later on an unloaded system.  If you wanted to set a flag signaling
  * a frame update at 30 frames per second (every 33 ms), you might set a 
  * timer for 30 ms:
- *   SDL_SetTimer((33/10)*10, flag_update);
+ *   @code SDL_SetTimer((33/10)*10, flag_update); @endcode
  *
  * If you use this function, you need to pass SDL_INIT_TIMER to SDL_Init().
  *
@@ -81,11 +85,14 @@ typedef Uint32 (SDLCALL *SDL_TimerCallback)(Uint32 interval);
  */
 extern DECLSPEC int SDLCALL SDL_SetTimer(Uint32 interval, SDL_TimerCallback callback);
 
-/* New timer API, supports multiple timers
+/** @name New timer API
+ * New timer API, supports multiple timers
  * Written by Stephane Peter <megastep@lokigames.com>
  */
+/*@{*/
 
-/* Function prototype for the new timer callback function.
+/**
+ * Function prototype for the new timer callback function.
  * The callback function is passed the current timer interval and returns
  * the next timer interval.  If the returned value is the same as the one
  * passed in, the periodic alarm continues, otherwise a new alarm is
@@ -93,19 +100,22 @@ extern DECLSPEC int SDLCALL SDL_SetTimer(Uint32 interval, SDL_TimerCallback call
  */
 typedef Uint32 (SDLCALL *SDL_NewTimerCallback)(Uint32 interval, void *param);
 
-/* Definition of the timer ID type */
+/** Definition of the timer ID type */
 typedef struct _SDL_TimerID *SDL_TimerID;
 
-/* Add a new timer to the pool of timers already running.
+/** Add a new timer to the pool of timers already running.
-   Returns a timer ID, or NULL when an error occurs.
+ *  Returns a timer ID, or NULL when an error occurs.
  */
 extern DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval, SDL_NewTimerCallback callback, void *param);
 
-/* Remove one of the multiple timers knowing its ID.
+/**
+ * Remove one of the multiple timers knowing its ID.
  * Returns a boolean value indicating success.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID t);
 
+/*@}*/
+
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
 }

code/SDL12/include/SDL_types.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -20,5 +20,9 @@
     slouken@libsdl.org
 */
 
+/** @file SDL_types.h
+ *  @deprecated Use SDL_stdinc.h instead.
+ */
+
 /* DEPRECATED */
 #include "SDL_stdinc.h"

code/SDL12/include/SDL_version.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -20,7 +20,9 @@
     slouken@libsdl.org
 */
 
-/* This header defines the current SDL version */
+/** @file SDL_version.h
+ *  This header defines the current SDL version
+ */
 
 #ifndef _SDL_version_h
 #define _SDL_version_h
@@ -33,11 +35,14 @@
 extern "C" {
 #endif
 
-/* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL
+/** @name Version Number
+ *  Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL
  */
+/*@{*/
 #define SDL_MAJOR_VERSION	1
 #define SDL_MINOR_VERSION	2
-#define SDL_PATCHLEVEL		11
+#define SDL_PATCHLEVEL		14
+/*@}*/
 
 typedef struct SDL_version {
 	Uint8 major;
@@ -45,7 +50,8 @@ typedef struct SDL_version {
 	Uint8 patch;
 } SDL_version;
 
-/* This macro can be used to fill a version structure with the compile-time
+/**
+ * This macro can be used to fill a version structure with the compile-time
  * version of the SDL library.
  */
 #define SDL_VERSION(X)							\
@@ -55,24 +61,24 @@ typedef struct SDL_version {
 	(X)->patch = SDL_PATCHLEVEL;					\
 }
 
-/* This macro turns the version numbers into a numeric value:
+/** This macro turns the version numbers into a numeric value:
-   (1,2,3) -> (1203)
+ *  (1,2,3) -> (1203)
-   This assumes that there will never be more than 100 patchlevels
+ *  This assumes that there will never be more than 100 patchlevels
  */
 #define SDL_VERSIONNUM(X, Y, Z)						\
 	((X)*1000 + (Y)*100 + (Z))
 
-/* This is the version number macro for the current SDL version */
+/** This is the version number macro for the current SDL version */
 #define SDL_COMPILEDVERSION \
 	SDL_VERSIONNUM(SDL_MAJOR_VERSION, SDL_MINOR_VERSION, SDL_PATCHLEVEL)
 
-/* This macro will evaluate to true if compiled with SDL at least X.Y.Z */
+/** This macro will evaluate to true if compiled with SDL at least X.Y.Z */
 #define SDL_VERSION_ATLEAST(X, Y, Z) \
 	(SDL_COMPILEDVERSION >= SDL_VERSIONNUM(X, Y, Z))
 
-/* This function gets the version of the dynamically linked SDL library.
+/** This function gets the version of the dynamically linked SDL library.
-   it should NOT be used to fill a version structure, instead you should
+ *  it should NOT be used to fill a version structure, instead you should
-   use the SDL_Version() macro.
+ *  use the SDL_Version() macro.
  */
 extern DECLSPEC const SDL_version * SDLCALL SDL_Linked_Version(void);
 

code/SDL12/include/SDL_video.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2006 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
@@ -20,7 +20,9 @@
     slouken@libsdl.org
 */
 
-/* Header file for access to the SDL raw framebuffer window */
+/** @file SDL_video.h
+ *  Header file for access to the SDL raw framebuffer window
+ */
 
 #ifndef _SDL_video_h
 #define _SDL_video_h
@@ -35,11 +37,16 @@
 extern "C" {
 #endif
 
-/* Transparency definitions: These define alpha as the opacity of a surface */
+/** @name Transparency definitions
+ *  These define alpha as the opacity of a surface
+ */
+/*@{*/
 #define SDL_ALPHA_OPAQUE 255
 #define SDL_ALPHA_TRANSPARENT 0
+/*@}*/
 
-/* Useful data types */
+/** @name Useful data types */
+/*@{*/
 typedef struct SDL_Rect {
 	Sint16 x, y;
 	Uint16 w, h;
@@ -57,8 +64,9 @@ typedef struct SDL_Palette {
 	int       ncolors;
 	SDL_Color *colors;
 } SDL_Palette;
+/*@}*/
 
-/* Everything in the pixel format structure is read-only */
+/** Everything in the pixel format structure is read-only */
 typedef struct SDL_PixelFormat {
 	SDL_Palette *palette;
 	Uint8  BitsPerPixel;
@@ -76,128 +84,149 @@ typedef struct SDL_PixelFormat {
 	Uint32 Bmask;
 	Uint32 Amask;
 
-	/* RGB color key information */
+	/** RGB color key information */
 	Uint32 colorkey;
-	/* Alpha value information (per-surface alpha) */
+	/** Alpha value information (per-surface alpha) */
 	Uint8  alpha;
 } SDL_PixelFormat;
 
-/* This structure should be treated as read-only, except for 'pixels',
+/** This structure should be treated as read-only, except for 'pixels',
-   which, if not NULL, contains the raw pixel data for the surface.
+ *  which, if not NULL, contains the raw pixel data for the surface.
  */
 typedef struct SDL_Surface {
-	Uint32 flags;				/* Read-only */
+	Uint32 flags;				/**< Read-only */
-	SDL_PixelFormat *format;		/* Read-only */
+	SDL_PixelFormat *format;		/**< Read-only */
-	int w, h;				/* Read-only */
+	int w, h;				/**< Read-only */
-	Uint16 pitch;				/* Read-only */
+	Uint16 pitch;				/**< Read-only */
-	void *pixels;				/* Read-write */
+	void *pixels;				/**< Read-write */
-	int offset;				/* Private */
+	int offset;				/**< Private */
 
-	/* Hardware-specific surface info */
+	/** Hardware-specific surface info */
 	struct private_hwdata *hwdata;
 
-	/* clipping information */
+	/** clipping information */
-	SDL_Rect clip_rect;			/* Read-only */
+	SDL_Rect clip_rect;			/**< Read-only */
-	Uint32 unused1;				/* for binary compatibility */
+	Uint32 unused1;				/**< for binary compatibility */
 
-	/* Allow recursive locks */
+	/** Allow recursive locks */
-	Uint32 locked;				/* Private */
+	Uint32 locked;				/**< Private */
 
-	/* info for fast blit mapping to other surfaces */
+	/** info for fast blit mapping to other surfaces */
-	struct SDL_BlitMap *map;		/* Private */
+	struct SDL_BlitMap *map;		/**< Private */
 
-	/* format version, bumped at every change to invalidate blit maps */
+	/** format version, bumped at every change to invalidate blit maps */
-	unsigned int format_version;		/* Private */
+	unsigned int format_version;		/**< Private */
 
-	/* Reference count -- used when freeing surface */
+	/** Reference count -- used when freeing surface */
-	int refcount;				/* Read-mostly */
+	int refcount;				/**< Read-mostly */
 } SDL_Surface;
 
-/* These are the currently supported flags for the SDL_surface */
+/** @name SDL_Surface Flags
-/* Available for SDL_CreateRGBSurface() or SDL_SetVideoMode() */
+ *  These are the currently supported flags for the SDL_surface
-#define SDL_SWSURFACE	0x00000000	/* Surface is in system memory */
+ */
-#define SDL_HWSURFACE	0x00000001	/* Surface is in video memory */
+/*@{*/
-#define SDL_ASYNCBLIT	0x00000004	/* Use asynchronous blits if possible */
-/* Available for SDL_SetVideoMode() */
-#define SDL_ANYFORMAT	0x10000000	/* Allow any video depth/pixel-format */
-#define SDL_HWPALETTE	0x20000000	/* Surface has exclusive palette */
-#define SDL_DOUBLEBUF	0x40000000	/* Set up double-buffered video mode */
-#define SDL_FULLSCREEN	0x80000000	/* Surface is a full screen display */
-#define SDL_OPENGL      0x00000002      /* Create an OpenGL rendering context */
-#define SDL_OPENGLBLIT	0x0000000A	/* Create an OpenGL rendering context and use it for blitting */
-#define SDL_RESIZABLE	0x00000010	/* This video mode may be resized */
-#define SDL_NOFRAME	0x00000020	/* No window caption or edge frame */
-/* Used internally (read-only) */
-#define SDL_HWACCEL	0x00000100	/* Blit uses hardware acceleration */
-#define SDL_SRCCOLORKEY	0x00001000	/* Blit uses a source color key */
-#define SDL_RLEACCELOK	0x00002000	/* Private flag */
-#define SDL_RLEACCEL	0x00004000	/* Surface is RLE encoded */
-#define SDL_SRCALPHA	0x00010000	/* Blit uses source alpha blending */
-#define SDL_PREALLOC	0x01000000	/* Surface uses preallocated memory */
 
-/* Evaluates to true if the surface needs to be locked before access */
+/** Available for SDL_CreateRGBSurface() or SDL_SetVideoMode() */
+/*@{*/
+#define SDL_SWSURFACE	0x00000000	/**< Surface is in system memory */
+#define SDL_HWSURFACE	0x00000001	/**< Surface is in video memory */
+#define SDL_ASYNCBLIT	0x00000004	/**< Use asynchronous blits if possible */
+/*@}*/
+
+/** Available for SDL_SetVideoMode() */
+/*@{*/
+#define SDL_ANYFORMAT	0x10000000	/**< Allow any video depth/pixel-format */
+#define SDL_HWPALETTE	0x20000000	/**< Surface has exclusive palette */
+#define SDL_DOUBLEBUF	0x40000000	/**< Set up double-buffered video mode */
+#define SDL_FULLSCREEN	0x80000000	/**< Surface is a full screen display */
+#define SDL_OPENGL      0x00000002      /**< Create an OpenGL rendering context */
+#define SDL_OPENGLBLIT	0x0000000A	/**< Create an OpenGL rendering context and use it for blitting */
+#define SDL_RESIZABLE	0x00000010	/**< This video mode may be resized */
+#define SDL_NOFRAME	0x00000020	/**< No window caption or edge frame */
+/*@}*/
+
+/** Used internally (read-only) */
+/*@{*/
+#define SDL_HWACCEL	0x00000100	/**< Blit uses hardware acceleration */
+#define SDL_SRCCOLORKEY	0x00001000	/**< Blit uses a source color key */
+#define SDL_RLEACCELOK	0x00002000	/**< Private flag */
+#define SDL_RLEACCEL	0x00004000	/**< Surface is RLE encoded */
+#define SDL_SRCALPHA	0x00010000	/**< Blit uses source alpha blending */
+#define SDL_PREALLOC	0x01000000	/**< Surface uses preallocated memory */
+/*@}*/
+
+/*@}*/
+
+/** Evaluates to true if the surface needs to be locked before access */
 #define SDL_MUSTLOCK(surface)	\
   (surface->offset ||		\
   ((surface->flags & (SDL_HWSURFACE|SDL_ASYNCBLIT|SDL_RLEACCEL)) != 0))
 
-/* typedef for private surface blitting functions */
+/** typedef for private surface blitting functions */
 typedef int (*SDL_blit)(struct SDL_Surface *src, SDL_Rect *srcrect,
 			struct SDL_Surface *dst, SDL_Rect *dstrect);
 
 
-/* Useful for determining the video hardware capabilities */
+/** Useful for determining the video hardware capabilities */
 typedef struct SDL_VideoInfo {
-	Uint32 hw_available :1;	/* Flag: Can you create hardware surfaces? */
+	Uint32 hw_available :1;	/**< Flag: Can you create hardware surfaces? */
-	Uint32 wm_available :1;	/* Flag: Can you talk to a window manager? */
+	Uint32 wm_available :1;	/**< Flag: Can you talk to a window manager? */
 	Uint32 UnusedBits1  :6;
 	Uint32 UnusedBits2  :1;
-	Uint32 blit_hw      :1;	/* Flag: Accelerated blits HW --> HW */
+	Uint32 blit_hw      :1;	/**< Flag: Accelerated blits HW --> HW */
-	Uint32 blit_hw_CC   :1;	/* Flag: Accelerated blits with Colorkey */
+	Uint32 blit_hw_CC   :1;	/**< Flag: Accelerated blits with Colorkey */
-	Uint32 blit_hw_A    :1;	/* Flag: Accelerated blits with Alpha */
+	Uint32 blit_hw_A    :1;	/**< Flag: Accelerated blits with Alpha */
-	Uint32 blit_sw      :1;	/* Flag: Accelerated blits SW --> HW */
+	Uint32 blit_sw      :1;	/**< Flag: Accelerated blits SW --> HW */
-	Uint32 blit_sw_CC   :1;	/* Flag: Accelerated blits with Colorkey */
+	Uint32 blit_sw_CC   :1;	/**< Flag: Accelerated blits with Colorkey */
-	Uint32 blit_sw_A    :1;	/* Flag: Accelerated blits with Alpha */
+	Uint32 blit_sw_A    :1;	/**< Flag: Accelerated blits with Alpha */
-	Uint32 blit_fill    :1;	/* Flag: Accelerated color fill */
+	Uint32 blit_fill    :1;	/**< Flag: Accelerated color fill */
 	Uint32 UnusedBits3  :16;
-	Uint32 video_mem;	/* The total amount of video memory (in K) */
+	Uint32 video_mem;	/**< The total amount of video memory (in K) */
-	SDL_PixelFormat *vfmt;	/* Value: The format of the video surface */
+	SDL_PixelFormat *vfmt;	/**< Value: The format of the video surface */
-	int    current_w;	/* Value: The current video mode width */
+	int    current_w;	/**< Value: The current video mode width */
-	int    current_h;	/* Value: The current video mode height */
+	int    current_h;	/**< Value: The current video mode height */
 } SDL_VideoInfo;
 
 
-/* The most common video overlay formats.
+/** @name Overlay Formats
-   For an explanation of these pixel formats, see:
+ *  The most common video overlay formats.
-	http://www.webartz.com/fourcc/indexyuv.htm
+ *  For an explanation of these pixel formats, see:
-
+ *	http://www.webartz.com/fourcc/indexyuv.htm
-   For information on the relationship between color spaces, see:
+ *
-   http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html
+ *  For information on the relationship between color spaces, see:
+ *  http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html
  */
-#define SDL_YV12_OVERLAY  0x32315659	/* Planar mode: Y + V + U  (3 planes) */
+/*@{*/
-#define SDL_IYUV_OVERLAY  0x56555949	/* Planar mode: Y + U + V  (3 planes) */
+#define SDL_YV12_OVERLAY  0x32315659	/**< Planar mode: Y + V + U  (3 planes) */
-#define SDL_YUY2_OVERLAY  0x32595559	/* Packed mode: Y0+U0+Y1+V0 (1 plane) */
+#define SDL_IYUV_OVERLAY  0x56555949	/**< Planar mode: Y + U + V  (3 planes) */
-#define SDL_UYVY_OVERLAY  0x59565955	/* Packed mode: U0+Y0+V0+Y1 (1 plane) */
+#define SDL_YUY2_OVERLAY  0x32595559	/**< Packed mode: Y0+U0+Y1+V0 (1 plane) */
-#define SDL_YVYU_OVERLAY  0x55595659	/* Packed mode: Y0+V0+Y1+U0 (1 plane) */
+#define SDL_UYVY_OVERLAY  0x59565955	/**< Packed mode: U0+Y0+V0+Y1 (1 plane) */
+#define SDL_YVYU_OVERLAY  0x55595659	/**< Packed mode: Y0+V0+Y1+U0 (1 plane) */
+/*@}*/
 
-/* The YUV hardware video overlay */
+/** The YUV hardware video overlay */
 typedef struct SDL_Overlay {
-	Uint32 format;				/* Read-only */
+	Uint32 format;				/**< Read-only */
-	int w, h;				/* Read-only */
+	int w, h;				/**< Read-only */
-	int planes;				/* Read-only */
+	int planes;				/**< Read-only */
-	Uint16 *pitches;			/* Read-only */
+	Uint16 *pitches;			/**< Read-only */
-	Uint8 **pixels;				/* Read-write */
+	Uint8 **pixels;				/**< Read-write */
 
-	/* Hardware-specific surface info */
+	/** @name Hardware-specific surface info */
+        /*@{*/
 	struct private_yuvhwfuncs *hwfuncs;
 	struct private_yuvhwdata *hwdata;
+        /*@{*/
 
-	/* Special flags */
+	/** @name Special flags */
-	Uint32 hw_overlay :1;	/* Flag: This overlay hardware accelerated? */
+        /*@{*/
+	Uint32 hw_overlay :1;	/**< Flag: This overlay hardware accelerated? */
 	Uint32 UnusedBits :31;
+        /*@}*/
 } SDL_Overlay;
 
 
-/* Public enumeration for setting the OpenGL window attributes. */
+/** Public enumeration for setting the OpenGL window attributes. */
 typedef enum {
     SDL_GL_RED_SIZE,
     SDL_GL_GREEN_SIZE,
@@ -218,17 +247,23 @@ typedef enum {
     SDL_GL_SWAP_CONTROL
 } SDL_GLattr;
 
-/* flags for SDL_SetPalette() */
+/** @name flags for SDL_SetPalette() */
+/*@{*/
 #define SDL_LOGPAL 0x01
 #define SDL_PHYSPAL 0x02
+/*@}*/
 
 /* Function prototypes */
 
-/* These functions are used internally, and should not be used unless you
+/**
+ * @name Video Init and Quit
+ * These functions are used internally, and should not be used unless you
  * have a specific need to specify the video driver you want to use.
  * You should normally use SDL_Init() or SDL_InitSubSystem().
- *
+ */
- * SDL_VideoInit() initializes the video subsystem -- sets up a connection
+/*@{*/
+/**
+ * Initializes the video subsystem. Sets up a connection
  * to the window manager, etc, and determines the current video mode and
  * pixel format, but does not initialize a window or graphics mode.
  * Note that event handling is activated by this routine.
@@ -239,14 +274,16 @@ typedef enum {
  */
 extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name, Uint32 flags);
 extern DECLSPEC void SDLCALL SDL_VideoQuit(void);
+/*@}*/
 
-/* This function fills the given character buffer with the name of the
+/**
+ * This function fills the given character buffer with the name of the
  * video driver, and returns a pointer to it if the video driver has
  * been initialized.  It returns NULL if no driver has been initialized.
  */
 extern DECLSPEC char * SDLCALL SDL_VideoDriverName(char *namebuf, int maxlen);
 
-/*
+/**
  * This function returns a pointer to the current display surface.
  * If SDL is doing format conversion on the display surface, this
  * function returns the publicly visible surface, not the real video
@@ -254,7 +291,7 @@ extern DECLSPEC char * SDLCALL SDL_VideoDriverName(char *namebuf, int maxlen);
  */
 extern DECLSPEC SDL_Surface * SDLCALL SDL_GetVideoSurface(void);
 
-/*
+/**
  * This function returns a read-only pointer to information about the
  * video hardware.  If this is called before SDL_SetVideoMode(), the 'vfmt'
  * member of the returned structure will contain the pixel format of the
@@ -262,7 +299,7 @@ extern DECLSPEC SDL_Surface * SDLCALL SDL_GetVideoSurface(void);
  */
 extern DECLSPEC const SDL_VideoInfo * SDLCALL SDL_GetVideoInfo(void);
 
-/* 
+/**
  * Check to see if a particular video mode is supported.
  * It returns 0 if the requested mode is not supported under any bit depth,
  * or returns the bits-per-pixel of the closest available mode with the
@@ -275,7 +312,7 @@ extern DECLSPEC const SDL_VideoInfo * SDLCALL SDL_GetVideoInfo(void);
  */
 extern DECLSPEC int SDLCALL SDL_VideoModeOK(int width, int height, int bpp, Uint32 flags);
 
-/*
+/**
  * Return a pointer to an array of available screen dimensions for the
  * given format and video flags, sorted largest to smallest.  Returns 
  * NULL if there are no dimensions available for a particular format, 
@@ -286,7 +323,7 @@ extern DECLSPEC int SDLCALL SDL_VideoModeOK(int width, int height, int bpp, Uint
  */
 extern DECLSPEC SDL_Rect ** SDLCALL SDL_ListModes(SDL_PixelFormat *format, Uint32 flags);
 
-/*
+/**
  * Set up a video mode with the specified width, height and bits-per-pixel.
  *
  * If 'bpp' is 0, it is treated as the current display bits per pixel.
@@ -347,18 +384,24 @@ extern DECLSPEC SDL_Rect ** SDLCALL SDL_ListModes(SDL_PixelFormat *format, Uint3
 extern DECLSPEC SDL_Surface * SDLCALL SDL_SetVideoMode
 			(int width, int height, int bpp, Uint32 flags);
 
-/*
+/** @name SDL_Update Functions
- * Makes sure the given list of rectangles is updated on the given screen.
- * If 'x', 'y', 'w' and 'h' are all 0, SDL_UpdateRect will update the entire
- * screen.
  * These functions should not be called while 'screen' is locked.
  */
+/*@{*/
+/**
+ * Makes sure the given list of rectangles is updated on the given screen.
+ */
 extern DECLSPEC void SDLCALL SDL_UpdateRects
 		(SDL_Surface *screen, int numrects, SDL_Rect *rects);
+/**
+ * If 'x', 'y', 'w' and 'h' are all 0, SDL_UpdateRect will update the entire
+ * screen.
+ */
 extern DECLSPEC void SDLCALL SDL_UpdateRect
 		(SDL_Surface *screen, Sint32 x, Sint32 y, Uint32 w, Uint32 h);
+/*@}*/
 
-/*
+/**
  * On hardware that supports double-buffering, this function sets up a flip
  * and returns.  The hardware will wait for vertical retrace, and then swap
  * video buffers before the next video surface blit or lock will return.
@@ -370,7 +413,7 @@ extern DECLSPEC void SDLCALL SDL_UpdateRect
  */
 extern DECLSPEC int SDLCALL SDL_Flip(SDL_Surface *screen);
 
-/*
+/**
  * Set the gamma correction for each of the color channels.
  * The gamma values range (approximately) between 0.1 and 10.0
  * 
@@ -380,7 +423,7 @@ extern DECLSPEC int SDLCALL SDL_Flip(SDL_Surface *screen);
  */
 extern DECLSPEC int SDLCALL SDL_SetGamma(float red, float green, float blue);
 
-/*
+/**
  * Set the gamma translation table for the red, green, and blue channels
  * of the video hardware.  Each table is an array of 256 16-bit quantities,
  * representing a mapping between the input and output for that channel.
@@ -394,7 +437,7 @@ extern DECLSPEC int SDLCALL SDL_SetGamma(float red, float green, float blue);
  */
 extern DECLSPEC int SDLCALL SDL_SetGammaRamp(const Uint16 *red, const Uint16 *green, const Uint16 *blue);
 
-/*
+/**
  * Retrieve the current values of the gamma translation tables.
  * 
  * You must pass in valid pointers to arrays of 256 16-bit quantities.
@@ -405,7 +448,7 @@ extern DECLSPEC int SDLCALL SDL_SetGammaRamp(const Uint16 *red, const Uint16 *gr
  */
 extern DECLSPEC int SDLCALL SDL_GetGammaRamp(Uint16 *red, Uint16 *green, Uint16 *blue);
 
-/*
+/**
  * Sets a portion of the colormap for the given 8-bit surface.  If 'surface'
  * is not a palettized surface, this function does nothing, returning 0.
  * If all of the colors were set as passed to SDL_SetColors(), it will
@@ -423,7 +466,7 @@ extern DECLSPEC int SDLCALL SDL_GetGammaRamp(Uint16 *red, Uint16 *green, Uint16
 extern DECLSPEC int SDLCALL SDL_SetColors(SDL_Surface *surface, 
 			SDL_Color *colors, int firstcolor, int ncolors);
 
-/*
+/**
  * Sets a portion of the colormap for a given 8-bit surface.
  * 'flags' is one or both of:
  * SDL_LOGPAL  -- set logical palette, which controls how blits are mapped
@@ -443,31 +486,37 @@ extern DECLSPEC int SDLCALL SDL_SetPalette(SDL_Surface *surface, int flags,
 				   SDL_Color *colors, int firstcolor,
 				   int ncolors);
 
-/*
+/**
  * Maps an RGB triple to an opaque pixel value for a given pixel format
  */
 extern DECLSPEC Uint32 SDLCALL SDL_MapRGB
-			(SDL_PixelFormat *format, Uint8 r, Uint8 g, Uint8 b);
+(const SDL_PixelFormat * const format,
+ const Uint8 r, const Uint8 g, const Uint8 b);
 
-/*
+/**
  * Maps an RGBA quadruple to a pixel value for a given pixel format
  */
-extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(SDL_PixelFormat *format,
+extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA
-				   Uint8 r, Uint8 g, Uint8 b, Uint8 a);
+(const SDL_PixelFormat * const format,
+ const Uint8 r, const Uint8 g, const Uint8 b, const Uint8 a);
 
-/*
+/**
  * Maps a pixel value into the RGB components for a given pixel format
  */
-extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, SDL_PixelFormat *fmt,
+extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
+				const SDL_PixelFormat * const fmt,
 				Uint8 *r, Uint8 *g, Uint8 *b);
 
-/*
+/**
  * Maps a pixel value into the RGBA components for a given pixel format
  */
-extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel, SDL_PixelFormat *fmt,
+extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
+				const SDL_PixelFormat * const fmt,
 				Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);
 
-/*
+/** @sa SDL_CreateRGBSurface */
+#define SDL_AllocSurface    SDL_CreateRGBSurface
+/**
  * Allocate and free an RGB surface (must be called after SDL_SetVideoMode)
  * If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
  * If the depth is greater than 8 bits, the pixel format is set using the
@@ -501,16 +550,16 @@ extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel, SDL_PixelFormat *fmt,
  * reason the surface could not be placed in video memory, it will not have
  * the SDL_HWSURFACE flag set, and will be created in system memory instead.
  */
-#define SDL_AllocSurface    SDL_CreateRGBSurface
 extern DECLSPEC SDL_Surface * SDLCALL SDL_CreateRGBSurface
 			(Uint32 flags, int width, int height, int depth, 
 			Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
+/** @sa SDL_CreateRGBSurface */
 extern DECLSPEC SDL_Surface * SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
 			int width, int height, int depth, int pitch,
 			Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
 extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface *surface);
 
-/*
+/**
  * SDL_LockSurface() sets up a surface for directly accessing the pixels.
  * Between calls to SDL_LockSurface()/SDL_UnlockSurface(), you can write
  * to and read from 'surface->pixels', using the pixel format stored in 
@@ -531,7 +580,7 @@ extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface *surface);
 extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface *surface);
 extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface);
 
-/*
+/**
  * Load a surface from a seekable SDL data source (memory or file.)
  * If 'freesrc' is non-zero, the source will be closed after being read.
  * Returns the new surface, or NULL if there was an error.
@@ -539,10 +588,10 @@ extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface);
  */
 extern DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_RW(SDL_RWops *src, int freesrc);
 
-/* Convenience macro -- load a surface from a file */
+/** Convenience macro -- load a surface from a file */
 #define SDL_LoadBMP(file)	SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
 
-/*
+/**
  * Save a surface to a seekable SDL data source (memory or file.)
  * If 'freedst' is non-zero, the source will be closed after being written.
  * Returns 0 if successful or -1 if there was an error.
@@ -550,11 +599,11 @@ extern DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_RW(SDL_RWops *src, int freesrc
 extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
 		(SDL_Surface *surface, SDL_RWops *dst, int freedst);
 
-/* Convenience macro -- save a surface to a file */
+/** Convenience macro -- save a surface to a file */
 #define SDL_SaveBMP(surface, file) \
 		SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
 
-/*
+/**
  * Sets the color key (transparent pixel) in a blittable surface.
  * If 'flag' is SDL_SRCCOLORKEY (optionally OR'd with SDL_RLEACCEL), 
  * 'key' will be the transparent pixel in the source image of a blit.
@@ -566,7 +615,7 @@ extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
 extern DECLSPEC int SDLCALL SDL_SetColorKey
 			(SDL_Surface *surface, Uint32 flag, Uint32 key);
 
-/*
+/**
  * This function sets the alpha value for the entire surface, as opposed to
  * using the alpha component of each pixel. This value measures the range
  * of transparency of the surface, 0 being completely transparent to 255
@@ -583,7 +632,7 @@ extern DECLSPEC int SDLCALL SDL_SetColorKey
  */
 extern DECLSPEC int SDLCALL SDL_SetAlpha(SDL_Surface *surface, Uint32 flag, Uint8 alpha);
 
-/*
+/**
  * Sets the clipping rectangle for the destination surface in a blit.
  *
  * If the clip rectangle is NULL, clipping will be disabled.
@@ -597,14 +646,14 @@ extern DECLSPEC int SDLCALL SDL_SetAlpha(SDL_Surface *surface, Uint32 flag, Uint
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface *surface, const SDL_Rect *rect);
 
-/*
+/**
  * Gets the clipping rectangle for the destination surface in a blit.
  * 'rect' must be a pointer to a valid rectangle which will be filled
  * with the correct values.
  */
 extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface *surface, SDL_Rect *rect);
 
-/*
+/**
  * Creates a new surface of the specified format, and then copies and maps 
  * the given surface to it so the blit of the converted surface will be as 
  * fast as possible.  If this function fails, it returns NULL.
@@ -619,7 +668,7 @@ extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface *surface, SDL_Rect *rec
 extern DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurface
 			(SDL_Surface *src, SDL_PixelFormat *fmt, Uint32 flags);
 
-/*
+/**
  * This performs a fast blit from the source surface to the destination
  * surface.  It assumes that the source and destination rectangles are
  * the same size.  If either 'srcrect' or 'dstrect' are NULL, the entire
@@ -675,35 +724,38 @@ extern DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurface
  * If either of the surfaces were in video memory, and the blit returns -2,
  * the video memory was lost, so it should be reloaded with artwork and 
  * re-blitted:
-	while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
+ * @code
-		while ( SDL_LockSurface(image) < 0 )
+ *	while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
-			Sleep(10);
+ *		while ( SDL_LockSurface(image) < 0 )
-		-- Write image pixels to image->pixels --
+ *			Sleep(10);
-		SDL_UnlockSurface(image);
+ *		-- Write image pixels to image->pixels --
-	}
+ *		SDL_UnlockSurface(image);
+ *	}
+ * @endcode
+ *
  * This happens under DirectX 5.0 when the system switches away from your
  * fullscreen application.  The lock will also fail until you have access
  * to the video memory again.
- */
+ *
-/* You should call SDL_BlitSurface() unless you know exactly how SDL
+ * You should call SDL_BlitSurface() unless you know exactly how SDL
-   blitting works internally and how to use the other blit functions.
+ * blitting works internally and how to use the other blit functions.
  */
 #define SDL_BlitSurface SDL_UpperBlit
 
-/* This is the public blit function, SDL_BlitSurface(), and it performs
+/** This is the public blit function, SDL_BlitSurface(), and it performs
-   rectangle validation and clipping before passing it to SDL_LowerBlit()
+ *  rectangle validation and clipping before passing it to SDL_LowerBlit()
  */
 extern DECLSPEC int SDLCALL SDL_UpperBlit
 			(SDL_Surface *src, SDL_Rect *srcrect,
 			 SDL_Surface *dst, SDL_Rect *dstrect);
-/* This is a semi-private blit function and it performs low-level surface
+/** This is a semi-private blit function and it performs low-level surface
-   blitting only.
+ *  blitting only.
  */
 extern DECLSPEC int SDLCALL SDL_LowerBlit
 			(SDL_Surface *src, SDL_Rect *srcrect,
 			 SDL_Surface *dst, SDL_Rect *dstrect);
 
-/*
+/**
  * This function performs a fast fill of the given rectangle with 'color'
  * The given rectangle is clipped to the destination surface clip area
  * and the final fill rectangle is saved in the passed in pointer.
@@ -715,7 +767,7 @@ extern DECLSPEC int SDLCALL SDL_LowerBlit
 extern DECLSPEC int SDLCALL SDL_FillRect
 		(SDL_Surface *dst, SDL_Rect *dstrect, Uint32 color);
 
-/* 
+/**
  * This function takes a surface and copies it to a new surface of the
  * pixel format and colors of the video framebuffer, suitable for fast
  * blitting onto the display surface.  It calls SDL_ConvertSurface()
@@ -728,7 +780,7 @@ extern DECLSPEC int SDLCALL SDL_FillRect
  */
 extern DECLSPEC SDL_Surface * SDLCALL SDL_DisplayFormat(SDL_Surface *surface);
 
-/* 
+/**
  * This function takes a surface and copies it to a new surface of the
  * pixel format and colors of the video framebuffer (if possible),
  * suitable for fast alpha blitting onto the display surface.
@@ -744,38 +796,39 @@ extern DECLSPEC SDL_Surface * SDLCALL SDL_DisplayFormatAlpha(SDL_Surface *surfac
 
 
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-/* YUV video surface overlay functions                                       */
+/** @name YUV video surface overlay functions                                */ /*@{*/
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
-/* This function creates a video output overlay
+/** This function creates a video output overlay
-   Calling the returned surface an overlay is something of a misnomer because
+ *  Calling the returned surface an overlay is something of a misnomer because
-   the contents of the display surface underneath the area where the overlay
+ *  the contents of the display surface underneath the area where the overlay
-   is shown is undefined - it may be overwritten with the converted YUV data.
+ *  is shown is undefined - it may be overwritten with the converted YUV data.
  */
 extern DECLSPEC SDL_Overlay * SDLCALL SDL_CreateYUVOverlay(int width, int height,
 				Uint32 format, SDL_Surface *display);
 
-/* Lock an overlay for direct access, and unlock it when you are done */
+/** Lock an overlay for direct access, and unlock it when you are done */
 extern DECLSPEC int SDLCALL SDL_LockYUVOverlay(SDL_Overlay *overlay);
 extern DECLSPEC void SDLCALL SDL_UnlockYUVOverlay(SDL_Overlay *overlay);
 
-/* Blit a video overlay to the display surface.
+/** Blit a video overlay to the display surface.
-   The contents of the video surface underneath the blit destination are
+ *  The contents of the video surface underneath the blit destination are
-   not defined.  
+ *  not defined.  
-   The width and height of the destination rectangle may be different from
+ *  The width and height of the destination rectangle may be different from
-   that of the overlay, but currently only 2x scaling is supported.
+ *  that of the overlay, but currently only 2x scaling is supported.
  */
 extern DECLSPEC int SDLCALL SDL_DisplayYUVOverlay(SDL_Overlay *overlay, SDL_Rect *dstrect);
 
-/* Free a video overlay */
+/** Free a video overlay */
 extern DECLSPEC void SDLCALL SDL_FreeYUVOverlay(SDL_Overlay *overlay);
 
+/*@}*/
 
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-/* OpenGL support functions.                                                 */
+/** @name OpenGL support functions.                                          */ /*@{*/
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
-/*
+/**
  * Dynamically load an OpenGL library, or the default one if path is NULL
  *
  * If you do this, you need to retrieve all of the GL functions used in
@@ -783,17 +836,17 @@ extern DECLSPEC void SDLCALL SDL_FreeYUVOverlay(SDL_Overlay *overlay);
  */
 extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path);
 
-/*
+/**
  * Get the address of a GL function
  */
 extern DECLSPEC void * SDLCALL SDL_GL_GetProcAddress(const char* proc);
 
-/*
+/**
  * Set an attribute of the OpenGL subsystem before intialization.
  */
 extern DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value);
 
-/*
+/**
  * Get an attribute of the OpenGL subsystem from the windowing
  * interface, such as glX. This is of course different from getting
  * the values from SDL's internal OpenGL subsystem, which only
@@ -804,30 +857,38 @@ extern DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value);
  */
 extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int* value);
 
-/*
+/**
  * Swap the OpenGL buffers, if double-buffering is supported.
  */
 extern DECLSPEC void SDLCALL SDL_GL_SwapBuffers(void);
 
-/*
+/** @name OpenGL Internal Functions
  * Internal functions that should not be called unless you have read
  * and understood the source code for these functions.
  */
+/*@{*/
 extern DECLSPEC void SDLCALL SDL_GL_UpdateRects(int numrects, SDL_Rect* rects);
 extern DECLSPEC void SDLCALL SDL_GL_Lock(void);
 extern DECLSPEC void SDLCALL SDL_GL_Unlock(void);
+/*@}*/
+
+/*@}*/
 
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-/* These functions allow interaction with the window manager, if any.        */
+/** @name Window Manager Functions                                           */
+/** These functions allow interaction with the window manager, if any.       */ /*@{*/
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
-/*
+/**
- * Sets/Gets the title and icon text of the display window (UTF-8 encoded)
+ * Sets the title and icon text of the display window (UTF-8 encoded)
  */
 extern DECLSPEC void SDLCALL SDL_WM_SetCaption(const char *title, const char *icon);
+/**
+ * Gets the title and icon text of the display window (UTF-8 encoded)
+ */
 extern DECLSPEC void SDLCALL SDL_WM_GetCaption(char **title, char **icon);
 
-/*
+/**
  * Sets the icon for the display window.
  * This function must be called before the first call to SDL_SetVideoMode().
  * It takes an icon surface, and a mask in MSB format.
@@ -835,14 +896,14 @@ extern DECLSPEC void SDLCALL SDL_WM_GetCaption(char **title, char **icon);
  */
 extern DECLSPEC void SDLCALL SDL_WM_SetIcon(SDL_Surface *icon, Uint8 *mask);
 
-/*
+/**
  * This function iconifies the window, and returns 1 if it succeeded.
  * If the function succeeds, it generates an SDL_APPACTIVE loss event.
  * This function is a noop and returns 0 in non-windowed environments.
  */
 extern DECLSPEC int SDLCALL SDL_WM_IconifyWindow(void);
 
-/*
+/**
  * Toggle fullscreen mode without changing the contents of the screen.
  * If the display surface does not require locking before accessing
  * the pixel information, then the memory pointers will not change.
@@ -859,24 +920,25 @@ extern DECLSPEC int SDLCALL SDL_WM_IconifyWindow(void);
  */
 extern DECLSPEC int SDLCALL SDL_WM_ToggleFullScreen(SDL_Surface *surface);
 
-/*
- * This function allows you to set and query the input grab state of
- * the application.  It returns the new input grab state.
- */
 typedef enum {
 	SDL_GRAB_QUERY = -1,
 	SDL_GRAB_OFF = 0,
 	SDL_GRAB_ON = 1,
-	SDL_GRAB_FULLSCREEN	/* Used internally */
+	SDL_GRAB_FULLSCREEN	/**< Used internally */
 } SDL_GrabMode;
-/*
+/**
+ * This function allows you to set and query the input grab state of
+ * the application.  It returns the new input grab state.
+ *
  * Grabbing means that the mouse is confined to the application window,
  * and nearly all keyboard input is passed directly to the application,
  * and not interpreted by a window manager, if any.
  */
 extern DECLSPEC SDL_GrabMode SDLCALL SDL_WM_GrabInput(SDL_GrabMode mode);
 
-/* Not in public API at the moment - do not use! */
+/*@}*/
+
+/** @internal Not in public API at the moment - do not use! */
 extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src, SDL_Rect *srcrect,
                                     SDL_Surface *dst, SDL_Rect *dstrect);
                     

code/SDL12/include/begin_code.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2004 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Library General Public
@@ -20,20 +20,28 @@
     slouken@libsdl.org
 */
 
-/* This file sets things up for C dynamic library function definitions,
+/** 
-   static inlined functions, and structures aligned at 4-byte alignment.
+ *  @file begin_code.h
-   If you don't like ugly C preprocessor code, don't look at this file. :)
+ *  This file sets things up for C dynamic library function definitions,
+ *  static inlined functions, and structures aligned at 4-byte alignment.
+ *  If you don't like ugly C preprocessor code, don't look at this file. :)
  */
 
-/* This shouldn't be nested -- included it around code only. */
+/** 
+ *  @file begin_code.h
+ *  This shouldn't be nested -- included it around code only.
+ */
 #ifdef _begin_code_h
 #error Nested inclusion of begin_code.h
 #endif
 #define _begin_code_h
 
-/* Some compilers use a special export keyword */
+/** 
+ *  @def DECLSPEC
+ *  Some compilers use a special export keyword
+ */
 #ifndef DECLSPEC
-# if defined(__BEOS__)
+# if defined(__BEOS__) || defined(__HAIKU__)
 #  if defined(__GNUC__)
 #   define DECLSPEC	__declspec(dllexport)
 #  else
@@ -56,6 +64,15 @@
 #   else
 #    define DECLSPEC
 #   endif
+#  elif defined (__GNUC__) && __GNUC__ < 4
+#   /* Added support for GCC-EMX <v4.x */
+#   /* this is needed for XFree86/OS2 developement */
+#   /* F. Ambacher(anakor@snafu.de) 05.2008 */
+#   ifdef BUILD_SDL
+#    define DECLSPEC    __declspec(dllexport)
+#   else
+#    define DECLSPEC
+#   endif
 #  else
 #   define DECLSPEC
 #  endif
@@ -68,31 +85,45 @@
 # endif
 #endif
 
-/* By default SDL uses the C calling convention */
+/** 
+ *  @def SDLCALL
+ *  By default SDL uses the C calling convention
+ */
 #ifndef SDLCALL
 # if defined(__WIN32__) && !defined(__GNUC__)
 #  define SDLCALL __cdecl
+# elif defined(__OS2__)
+#  if defined (__GNUC__) && __GNUC__ < 4
+#   /* Added support for GCC-EMX <v4.x */
+#   /* this is needed for XFree86/OS2 developement */
+#   /* F. Ambacher(anakor@snafu.de) 05.2008 */
+#   define SDLCALL _cdecl
 #  else
-#ifdef __OS2__
+#   /* On other compilers on OS/2, we use the _System calling convention */
-/* But on OS/2, we use the _System calling convention */
+#   /* to be compatible with every compiler */
-/* to be compatible with every compiler */
 #   define SDLCALL _System
+#  endif
 # else
 #  define SDLCALL
 # endif
-#endif
 #endif /* SDLCALL */
 
-/* Removed DECLSPEC on Symbian OS because SDL cannot be a DLL in EPOC */
 #ifdef __SYMBIAN32__ 
+#ifndef EKA2 
 #undef DECLSPEC
 #define DECLSPEC
+#elif !defined(__WINS__)
+#undef DECLSPEC
+#define DECLSPEC __declspec(dllexport)
+#endif /* !EKA2 */
 #endif /* __SYMBIAN32__ */
 
-/* Force structure packing at 4 byte alignment.
+/**
-   This is necessary if the header is included in code which has structure
+ *  @file begin_code.h
-   packing set to an alternate value, say for loading structures from disk.
+ *  Force structure packing at 4 byte alignment.
-   The packing is reset to the previous value in close_code.h
+ *  This is necessary if the header is included in code which has structure
+ *  packing set to an alternate value, say for loading structures from disk.
+ *  The packing is reset to the previous value in close_code.h 
  */
 #if defined(_MSC_VER) || defined(__MWERKS__) || defined(__BORLANDC__)
 #ifdef _MSC_VER
@@ -107,7 +138,10 @@
 #pragma enumsalwaysint on
 #endif /* Compiler needs structure packing set */
 
-/* Set up compiler-specific options for inlining functions */
+/**
+ *  @def SDL_INLINE_OKAY
+ *  Set up compiler-specific options for inlining functions
+ */
 #ifndef SDL_INLINE_OKAY
 #ifdef __GNUC__
 #define SDL_INLINE_OKAY
@@ -116,29 +150,36 @@
 #if defined(_MSC_VER) || defined(__BORLANDC__) || \
     defined(__DMC__) || defined(__SC__) || \
     defined(__WATCOMC__) || defined(__LCC__) || \
-    defined(__DECC)
+    defined(__DECC) || defined(__EABI__)
 #ifndef __inline__
 #define __inline__	__inline
 #endif
 #define SDL_INLINE_OKAY
 #else
 #if !defined(__MRC__) && !defined(_SGI_SOURCE)
+#ifndef __inline__
 #define __inline__ inline
+#endif
 #define SDL_INLINE_OKAY
 #endif /* Not a funky compiler */
 #endif /* Visual C++ */
 #endif /* GNU C */
 #endif /* SDL_INLINE_OKAY */
 
-/* If inlining isn't supported, remove "__inline__", turning static
+/**
-   inlined functions into static functions (resulting in code bloat
+ *  @def __inline__
-   in all files which include the offending header files)
+ *  If inlining isn't supported, remove "__inline__", turning static
+ *  inlined functions into static functions (resulting in code bloat
+ *  in all files which include the offending header files)
  */
 #ifndef SDL_INLINE_OKAY
 #define __inline__
 #endif
 
-/* Apparently this is needed by several Windows compilers */
+/**
+ *  @def NULL
+ *  Apparently this is needed by several Windows compilers
+ */
 #if !defined(__MACH__)
 #ifndef NULL
 #ifdef __cplusplus

code/SDL12/include/close_code.h

@@ -1,6 +1,6 @@
 /*
     SDL - Simple DirectMedia Layer
-    Copyright (C) 1997-2004 Sam Lantinga
+    Copyright (C) 1997-2009 Sam Lantinga
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Library General Public
@@ -20,13 +20,18 @@
     slouken@libsdl.org
 */
 
-/* This file reverses the effects of begin_code.h and should be included
+/**
-   after you finish any function and structure declarations in your headers
+ *  @file close_code.h
+ *  This file reverses the effects of begin_code.h and should be included
+ *  after you finish any function and structure declarations in your headers
  */
 
 #undef _begin_code_h
 
-/* Reset structure packing at previous byte alignment */
+/**
+ *  @file close_code.h
+ *  Reset structure packing at previous byte alignment
+ */
 #if defined(_MSC_VER) || defined(__MWERKS__) || defined(__WATCOMC__)  || defined(__BORLANDC__)
 #ifdef __BORLANDC__
 #pragma nopackwarning

code/libs/win32/libSDL.la

@@ -1,5 +1,5 @@
 # libSDL.la - a libtool library file
-# Generated by ltmain.sh - GNU libtool 1.5.22 (1.1220.2.365 2005/12/18 22:14:06)
+# Generated by ltmain.sh (GNU libtool) 2.2.6
 #
 # Please DO NOT delete this file!
 # It is necessary for linking the library.
@@ -13,13 +13,19 @@ library_names='libSDL.dll.a'
 # The name of the static archive.
 old_library='libSDL.a'
 
+# Linker flags that can not go in dependency_libs.
+inherited_linker_flags=''
+
 # Libraries that this one depends upon.
 dependency_libs=' -luser32 -lgdi32 -lwinmm -ldxguid'
 
+# Names of additional weak libraries provided by this library
+weak_library_names=''
+
 # Version information for libSDL.
 current=11
 age=11
-revision=1
+revision=3
 
 # Is this an already installed library?
 installed=yes
@@ -32,4 +38,4 @@ dlopen=''
 dlpreopen=''
 
 # Directory that this library needs to be installed in:
-libdir='/Users/hercules/tmp/SDL-1.2.12/lib'
+libdir='/usr/local/lib'