Mercurial > sdl-ios-xcode
changeset 4217:4c4113c2162c SDL-1.2
Fixed bug #706
Ken Bull 2009-02-25 13:22:02 PST
Adds Doxygen support for all headers (except config and boilerplate headers) in
the include folder for SDL-1.2 revision 4446.
While in general SDL is quite thoroughly commented, none of these comments are
correctly formatted for Doxygen and are generally inconsistent in their
formatting.
| author | Sam Lantinga <slouken@libsdl.org> |
|---|---|
| date | Mon, 21 Sep 2009 09:38:10 +0000 |
| parents | 5b99971a27b4 |
| children | 50b4ab8f8271 |
| files | include/SDL.h include/SDL_active.h include/SDL_audio.h include/SDL_byteorder.h include/SDL_cdrom.h include/SDL_cpuinfo.h include/SDL_endian.h include/SDL_error.h include/SDL_events.h include/SDL_getenv.h include/SDL_joystick.h include/SDL_keyboard.h include/SDL_keysym.h include/SDL_loadso.h include/SDL_main.h include/SDL_mouse.h include/SDL_mutex.h include/SDL_opengl.h include/SDL_platform.h include/SDL_quit.h include/SDL_rwops.h include/SDL_stdinc.h include/SDL_syswm.h include/SDL_thread.h include/SDL_timer.h include/SDL_types.h include/SDL_version.h include/SDL_video.h include/begin_code.h include/close_code.h include/doxyfile |
| diffstat | 31 files changed, 2234 insertions(+), 936 deletions(-) [+] |
line wrap: on
line diff
--- a/include/SDL.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL.h Mon Sep 21 09:38:10 2009 +0000 @@ -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,41 +49,46 @@ 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_EVENTTHREAD 0x01000000 /* Not supported on all OS's */ +#define SDL_INIT_NOPARACHUTE 0x00100000 /**< Don't catch fatal signals */ +#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 - * 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) +/** 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 - been initialized. - If 'flags' is 0, it returns a mask of all initialized subsystems. -*/ +/** This function returns mask of the specified subsystems which have + * been initialized. + * 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 - * dynamically linked library. You should call it upon all exit conditions. +/** 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);
--- a/include/SDL_active.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_active.h Mon Sep 21 09:38:10 2009 +0000 @@ -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 */ -#define SDL_APPMOUSEFOCUS 0x01 /* The app has mouse coverage */ -#define SDL_APPINPUTFOCUS 0x02 /* The app has input focus */ -#define SDL_APPACTIVE 0x04 /* The application is active */ +/** @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_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
--- a/include/SDL_audio.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_audio.h Mon Sep 21 09:38:10 2009 +0000 @@ -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->format' should be the desired audio format. - * 'desired->samples' is the desired size of the audio buffer, in samples. + * - 'desired->freq' should be the desired audio frequency in samples-per-second. + * - 'desired->format' should be the desired audio format. + * - '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 @@ * 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 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 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_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);
--- a/include/SDL_byteorder.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_byteorder.h Mon Sep 21 09:38:10 2009 +0000 @@ -20,5 +20,10 @@ slouken@libsdl.org */ +/** + * @file SDL_byteorder.h + * @deprecated Use SDL_endian.h instead + */ + /* DEPRECATED */ #include "SDL_endian.h"
--- a/include/SDL_cdrom.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_cdrom.h Mon Sep 21 09:38:10 2009 +0000 @@ -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 - for CD-ROM drives, and load appropriate drivers. -*/ +/** + * @file SDL_cdrom.h + * 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 @@ 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 type; /* Data or audio track */ + Uint8 id; /**< Track number */ + Uint8 type; /**< Data or audio track */ Uint16 unused; - Uint32 length; /* Length, in frames, of this track */ - Uint32 offset; /* Offset, in frames, from start of disk */ + Uint32 length; /**< Length, in frames, of this track */ + 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 */ - CDstatus status; /* Current drive status */ + int id; /**< Private drive identifier */ + CDstatus status; /**< Current drive status */ - /* 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 cur_frame; /* Current frame offset within current track */ + /** 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 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 @@ *(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: - "/dev/cdrom" - "E:" - "/dev/disk/ide/1/master" -*/ +/** + * Returns a human-readable, system-dependent identifier for the CD-ROM. + * Example: + * - "/dev/cdrom" + * - "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 - becomes the default CD used when other CD functions are passed a NULL - CD-ROM handle. - Drives are numbered starting with 0. Drive 0 is the system default CD-ROM. -*/ +/** + * 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 + * becomes the default CD used when other CD functions are passed a NULL + * 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 - play position of the CD will be stored in the SDL_CD structure. -*/ +/** + * 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 + * 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 - until the end of the CD. This function will skip data tracks. - This function should only be called after calling SDL_CDStatus() to - get track information about the CD. - For example: - // Play entire CD: - if ( CD_INDRIVE(SDL_CDStatus(cdrom)) ) - SDL_CDPlayTracks(cdrom, 0, 0, 0, 0); - // Play last track: - if ( CD_INDRIVE(SDL_CDStatus(cdrom)) ) { - SDL_CDPlayTracks(cdrom, cdrom->numtracks-1, 0, 0, 0); - } - // Play first and second track and 10 seconds of third track: - if ( CD_INDRIVE(SDL_CDStatus(cdrom)) ) - SDL_CDPlayTracks(cdrom, 0, 0, 2, 10); - - This function returns 0, or -1 if there was an error. -*/ +/** + * 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 + * until the end of the CD. This function will skip data tracks. + * This function should only be called after calling SDL_CDStatus() to + * get track information about the CD. + * For example: + * @code + * // Play entire CD: + * if ( CD_INDRIVE(SDL_CDStatus(cdrom)) ) + * SDL_CDPlayTracks(cdrom, 0, 0, 0, 0); + * // Play last track: + * if ( CD_INDRIVE(SDL_CDStatus(cdrom)) ) { + * SDL_CDPlayTracks(cdrom, cdrom->numtracks-1, 0, 0, 0); + * } + * // Play first and second track and 10 seconds of third track: + * if ( CD_INDRIVE(SDL_CDStatus(cdrom)) ) + * 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);
--- a/include/SDL_cpuinfo.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_cpuinfo.h Mon Sep 21 09:38:10 2009 +0000 @@ -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++ */
--- a/include/SDL_endian.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_endian.h Mon Sep 21 09:38:10 2009 +0000 @@ -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,11 +57,14 @@ extern "C" { #endif -/* Use inline functions for compilers that support them, and static - 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. -*/ +/** + * @name SDL_Swap Functions + * Use inline functions for compilers that support them, and static + * 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 */) static __inline__ Uint16 SDL_Swap16(Uint16 x) @@ -161,14 +171,18 @@ #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 - the fake 64-bit datatype that SDL provides when it compiles user code. -*/ + * 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. + */ #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) @@ -184,6 +198,7 @@ #define SDL_SwapBE32(X) (X) #define SDL_SwapBE64(X) (X) #endif +/*@}*/ /* Ends C function definitions when using C++ */ #ifdef __cplusplus
--- a/include/SDL_error.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_error.h Mon Sep 21 09:38:10 2009 +0000 @@ -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 @@ SDL_LASTERROR } SDL_errorcode; extern DECLSPEC void SDLCALL SDL_Error(SDL_errorcode code); - +/*@}*/ /* Ends C function definitions when using C++ */ #ifdef __cplusplus
--- a/include/SDL_events.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_events.h Mon Sep 21 09:38:10 2009 +0000 @@ -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_ACTIVEEVENT, /* Application loses/gains visibility */ - SDL_KEYDOWN, /* Keys pressed */ - SDL_KEYUP, /* Keys released */ - SDL_MOUSEMOTION, /* Mouse moved */ - SDL_MOUSEBUTTONDOWN, /* Mouse button pressed */ - SDL_MOUSEBUTTONUP, /* Mouse button released */ - SDL_JOYAXISMOTION, /* Joystick axis motion */ - SDL_JOYBALLMOTION, /* Joystick trackball motion */ - SDL_JOYHATMOTION, /* Joystick hat position change */ - SDL_JOYBUTTONDOWN, /* Joystick button pressed */ - SDL_JOYBUTTONUP, /* Joystick button released */ - SDL_QUIT, /* User-requested quit */ - SDL_SYSWMEVENT, /* System specific event */ - SDL_EVENT_RESERVEDA, /* Reserved for future use.. */ - SDL_EVENT_RESERVEDB, /* Reserved for future use.. */ - SDL_VIDEORESIZE, /* User resized video mode */ - SDL_VIDEOEXPOSE, /* Screen needs to be redrawn */ - SDL_EVENT_RESERVED2, /* Reserved for future use.. */ - SDL_EVENT_RESERVED3, /* Reserved for future use.. */ - SDL_EVENT_RESERVED4, /* Reserved for future use.. */ - SDL_EVENT_RESERVED5, /* Reserved for future use.. */ - SDL_EVENT_RESERVED6, /* Reserved for future use.. */ - SDL_EVENT_RESERVED7, /* Reserved for future use.. */ - /* Events SDL_USEREVENT through SDL_MAXEVENTS-1 are for your use */ + SDL_NOEVENT = 0, /**< Unused (do not remove) */ + SDL_ACTIVEEVENT, /**< Application loses/gains visibility */ + SDL_KEYDOWN, /**< Keys pressed */ + SDL_KEYUP, /**< Keys released */ + SDL_MOUSEMOTION, /**< Mouse moved */ + SDL_MOUSEBUTTONDOWN, /**< Mouse button pressed */ + SDL_MOUSEBUTTONUP, /**< Mouse button released */ + SDL_JOYAXISMOTION, /**< Joystick axis motion */ + SDL_JOYBALLMOTION, /**< Joystick trackball motion */ + SDL_JOYHATMOTION, /**< Joystick hat position change */ + SDL_JOYBUTTONDOWN, /**< Joystick button pressed */ + SDL_JOYBUTTONUP, /**< Joystick button released */ + SDL_QUIT, /**< User-requested quit */ + SDL_SYSWMEVENT, /**< System specific event */ + SDL_EVENT_RESERVEDA, /**< Reserved for future use.. */ + SDL_EVENT_RESERVEDB, /**< Reserved for future use.. */ + SDL_VIDEORESIZE, /**< User resized video mode */ + SDL_VIDEOEXPOSE, /**< Screen needs to be redrawn */ + SDL_EVENT_RESERVED2, /**< Reserved for future use.. */ + SDL_EVENT_RESERVED3, /**< Reserved for future use.. */ + SDL_EVENT_RESERVED4, /**< Reserved for future use.. */ + SDL_EVENT_RESERVED5, /**< Reserved for future use.. */ + SDL_EVENT_RESERVED6, /**< Reserved for future use.. */ + SDL_EVENT_RESERVED7, /**< Reserved for future use.. */ + /** Events SDL_USEREVENT through SDL_MAXEVENTS-1 are for your use */ SDL_USEREVENT = 24, - /* This last event is only for bounding internal arrays - It is the number of bits in the event mask datatype -- Uint32 + /** This last event is only for bounding internal arrays + * 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 @@ 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 gain; /* Whether given states were gained or lost (1/0) */ - Uint8 state; /* A mask of the focus states */ + Uint8 type; /**< SDL_ACTIVEEVENT */ + Uint8 gain; /**< Whether given states were gained or lost (1/0) */ + 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 which; /* The keyboard device index */ - Uint8 state; /* SDL_PRESSED or SDL_RELEASED */ + Uint8 type; /**< SDL_KEYDOWN or SDL_KEYUP */ + Uint8 which; /**< The keyboard device index */ + 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 which; /* The mouse device index */ - Uint8 state; /* The current button state */ - Uint16 x, y; /* The X/Y coordinates of the mouse */ - Sint16 xrel; /* The relative motion in the X direction */ - Sint16 yrel; /* The relative motion in the Y direction */ + Uint8 type; /**< SDL_MOUSEMOTION */ + Uint8 which; /**< The mouse device index */ + Uint8 state; /**< The current button state */ + Uint16 x, y; /**< The X/Y coordinates of the mouse */ + Sint16 xrel; /**< The relative motion in the X 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 which; /* The mouse device index */ - Uint8 button; /* The mouse button index */ - Uint8 state; /* SDL_PRESSED or SDL_RELEASED */ - Uint16 x, y; /* The X/Y coordinates of the mouse at press time */ + Uint8 type; /**< SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */ + Uint8 which; /**< The mouse device index */ + Uint8 button; /**< The mouse button index */ + Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + 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 which; /* The joystick device index */ - Uint8 axis; /* The joystick axis index */ - Sint16 value; /* The axis value (range: -32768 to 32767) */ + Uint8 type; /**< SDL_JOYAXISMOTION */ + Uint8 which; /**< The joystick device index */ + Uint8 axis; /**< The joystick axis index */ + 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 which; /* The joystick device index */ - Uint8 ball; /* The joystick trackball index */ - Sint16 xrel; /* The relative motion in the X direction */ - Sint16 yrel; /* The relative motion in the Y direction */ + Uint8 type; /**< SDL_JOYBALLMOTION */ + Uint8 which; /**< The joystick device index */ + Uint8 ball; /**< The joystick trackball index */ + Sint16 xrel; /**< The relative motion in the X 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 which; /* The joystick device index */ - Uint8 hat; /* The joystick hat index */ - Uint8 value; /* The hat position value: - SDL_HAT_LEFTUP SDL_HAT_UP SDL_HAT_RIGHTUP - SDL_HAT_LEFT SDL_HAT_CENTERED SDL_HAT_RIGHT - SDL_HAT_LEFTDOWN SDL_HAT_DOWN SDL_HAT_RIGHTDOWN - Note that zero means the POV is centered. - */ + Uint8 type; /**< SDL_JOYHATMOTION */ + Uint8 which; /**< The joystick device index */ + Uint8 hat; /**< The joystick hat index */ + Uint8 value; /**< The hat position value: + * SDL_HAT_LEFTUP SDL_HAT_UP SDL_HAT_RIGHTUP + * SDL_HAT_LEFT SDL_HAT_CENTERED SDL_HAT_RIGHT + * SDL_HAT_LEFTDOWN SDL_HAT_DOWN SDL_HAT_RIGHTDOWN + * 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 which; /* The joystick device index */ - Uint8 button; /* The joystick button index */ - Uint8 state; /* SDL_PRESSED or SDL_RELEASED */ + Uint8 type; /**< SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP */ + Uint8 which; /**< The joystick device index */ + Uint8 button; /**< The joystick button index */ + Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ } SDL_JoyButtonEvent; -/* The "window resized" event - When you get this event, you are responsible for setting a new video - mode with the new width and height. +/** The "window resized" event + * When you get this event, you are responsible for setting a new video + * mode with the new width and height. */ typedef struct SDL_ResizeEvent { - Uint8 type; /* SDL_VIDEORESIZE */ - int w; /* New width */ - int h; /* New height */ + Uint8 type; /**< SDL_VIDEORESIZE */ + int w; /**< New width */ + 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 */ - int code; /* User defined event code */ - void *data1; /* User defined data pointer */ - void *data2; /* User defined data pointer */ + Uint8 type; /**< SDL_USEREVENT through SDL_NUMEVENTS-1 */ + int code; /**< User defined event code */ + void *data1; /**< 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 @@ SDL_SysWMmsg *msg; } SDL_SysWMEvent; -/* General event structure */ +/** General event structure */ typedef union SDL_Event { Uint8 type; SDL_ActiveEvent active; @@ -237,97 +244,109 @@ /* Function prototypes */ -/* Pumps the event loop, gathering events from the input devices. - This function updates the event queue and internal input device state. - This should only be run in the thread that sets the video mode. -*/ +/** Pumps the event loop, gathering events from the input devices. + * This function updates the event queue and internal input device state. + * 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 - 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. +/** 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 + * 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 - 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. +/** 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 + * 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. - This function returns 0 on success, or -1 if the event queue was full - or there was some other error. +/** Add an event to the event queue. + * This function returns 0 on success, or -1 if the event queue was full + * or there was some other error. */ extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event *event); -/* - 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: -*/ +/** @name Event Filtering */ +/*@{*/ typedef int (SDLCALL *SDL_EventFilter)(const SDL_Event *event); -/* - 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 - internal state will still be updated. This allows selective filtering of - dynamically arriving events. - - WARNING: Be very careful of what you do in the event filter function, as - it may run in a different thread! - - 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. -*/ +/** + * 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: + * @code typedef int (SDLCALL *SDL_EventFilter)(const SDL_Event *event); @endcode + * + * 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 + * internal state will still be updated. This allows selective filtering of + * dynamically arriving events. + * + * @warning Be very careful of what you do in the event filter function, as + * it may run in a different thread! + * + * 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. - If there is no event filter set, this function returns NULL. -*/ +/** + * Return the current event filter - can be used to "chain" filters. + * If there is no event filter set, this function returns NULL. + */ extern DECLSPEC SDL_EventFilter SDLCALL SDL_GetEventFilter(void); +/*@}*/ -/* - 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. -*/ +/** @name Event State */ +/*@{*/ #define SDL_QUERY -1 #define SDL_IGNORE 0 #define SDL_DISABLE 0 #define SDL_ENABLE 1 +/*@}*/ + +/** +* 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 }
--- a/include/SDL_getenv.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_getenv.h Mon Sep 21 09:38:10 2009 +0000 @@ -20,5 +20,9 @@ slouken@libsdl.org */ +/** @file SDL_getenv.h + * @deprecated Use SDL_stdinc.h instead + */ + /* DEPRECATED */ #include "SDL_stdinc.h"
--- a/include/SDL_joystick.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_joystick.h Mon Sep 21 09:38:10 2009 +0000 @@ -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 - with the SDL_INIT_JOYSTICK flag. This causes SDL to scan the system - for joysticks, and load appropriate drivers. -*/ +/** @file SDL_joystick.h + * @note In order to use these functions, SDL_Init() must have been called + * 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 - * The return value is one of the following positions: +/** + * @name Hat 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 @@ #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);
--- a/include/SDL_keyboard.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_keyboard.h Mon Sep 21 09:38:10 2009 +0000 @@ -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 - - 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, - this is a UNICODE character corresponding to the keypress. If the - high 9 bits of the character are 0, then this maps to the equivalent - ASCII character: - char ch; - if ( (keysym.unicode & 0xFF80) == 0 ) { - ch = keysym.unicode & 0x7F; - } else { - An international character.. - } +/** 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 'unicode' translated character is only available when character + * translation is enabled by the SDL_EnableUNICODE() API. If non-zero, + * this is a UNICODE character corresponding to the keypress. If the + * high 9 bits of the character are 0, then this maps to the equivalent + * ASCII character: + * @code + * char ch; + * if ( (keysym.unicode & 0xFF80) == 0 ) { + * ch = keysym.unicode & 0x7F; + * } else { + * An international character.. + * } + * @endcode */ typedef struct SDL_keysym { - Uint8 scancode; /* hardware specific scancode */ - SDLKey sym; /* SDL virtual keysym */ - SDLMod mod; /* current key modifiers */ - Uint16 unicode; /* translated character */ + Uint8 scancode; /**< hardware specific scancode */ + SDLKey sym; /**< SDL virtual keysym */ + SDLMod mod; /**< current key modifiers */ + 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 -/* - * If 'delay' is set to 0, keyboard repeat is disabled. +/** + * 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);
--- a/include/SDL_keysym.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_keysym.h Mon Sep 21 09:38:10 2009 +0000 @@ -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. - To support international keyboards, we use the range 0xA1 - 0xFF - as international virtual keycodes. We'll follow in the footsteps of X11... - The names of the keys +/** What we really want is a mapping of every raw key on the keyboard. + * To support international keyboards, we use the range 0xA1 - 0xFF + * as international virtual keycodes. We'll follow in the footsteps of X11... + * @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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ SDLK_LALT = 308, SDLK_RMETA = 309, SDLK_LMETA = 310, - SDLK_LSUPER = 311, /* Left "Windows" key */ - SDLK_RSUPER = 312, /* Right "Windows" key */ - SDLK_MODE = 313, /* "Alt Gr" key */ - SDLK_COMPOSE = 314, /* Multi-key compose key */ + SDLK_LSUPER = 311, /**< Left "Windows" key */ + SDLK_RSUPER = 312, /**< Right "Windows" key */ + SDLK_MODE = 313, /**< "Alt Gr" 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_EURO = 321, /* Some european keyboards */ - SDLK_UNDO = 322, /* Atari keyboard has Undo */ + SDLK_POWER = 320, /**< Power Macintosh power key */ + SDLK_EURO = 321, /**< Some european keyboards */ + 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,
--- a/include/SDL_loadso.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_loadso.h Mon Sep 21 09:38:10 2009 +0000 @@ -20,22 +20,24 @@ slouken@libsdl.org */ -/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -/* System dependent library loading routines */ +/** @file SDL_loadso.h + * System dependent library loading routines + */ -/* Some things to keep in mind: - - These functions only work on C function names. Other languages may - have name mangling and intrinsic language support that varies from - compiler to compiler. - - Make sure you declare your function pointers with the same calling - convention as the actual library function. Your code will crash - mysteriously if you do not do this. - - Avoid namespace collisions. If you load a symbol from the library, - it is not defined whether or not it goes into the global symbol - namespace for the application. If it does and it conflicts with - symbols in your code or other shared libraries, you will not get - the results you expect. :) -*/ +/** @file SDL_loadso.h + * Some things to keep in mind: + * - These functions only work on C function names. Other languages may + * have name mangling and intrinsic language support that varies from + * compiler to compiler. + * - Make sure you declare your function pointers with the same calling + * convention as the actual library function. Your code will crash + * mysteriously if you do not do this. + * - Avoid namespace collisions. If you load a symbol from the library, + * it is not defined whether or not it goes into the global symbol + * namespace for the application. If it does and it conflicts with + * symbols in your code or other shared libraries, you will not get + * the results you expect. :) + */ #ifndef _SDL_loadso_h @@ -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++ */
--- a/include/SDL_main.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_main.h Mon Sep 21 09:38:10 2009 +0000 @@ -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, - and should be declared like this: -#ifdef __cplusplus -extern "C" -#endif - int main(int argc, char *argv[]) - { - } +/** The application's main() function must be called with C linkage, + * and should be declared like this: + * @code + * #ifdef __cplusplus + * extern "C" + * #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" { #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 "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 @@ #endif #include "close_code.h" #endif +/*@}*/ #endif /* Need to redefine main()? */
--- a/include/SDL_mouse.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_mouse.h Mon Sep 21 09:38:10 2009 +0000 @@ -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 */ - Sint16 hot_x, hot_y; /* The "tip" of the cursor */ - Uint8 *data; /* B/W cursor data */ - Uint8 *mask; /* B/W cursor mask */ - Uint8 *save[2]; /* Place to save cursor area */ - WMcursor *wm_cursor; /* Window-manager cursor */ + SDL_Rect area; /**< The area of the mouse cursor */ + Sint16 hot_x, hot_y; /**< The "tip" of the cursor */ + Uint8 *data; /**< B/W cursor data */ + Uint8 *mask; /**< B/W cursor mask */ + Uint8 *save[2]; /**< Place to save cursor area */ + 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 @@ */ 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_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 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 int SDLCALL SDL_ShowCursor(int toggle); -/* Used as a mask when testing buttons in buttonstate - Button 1: Left mouse button - Button 2: Middle mouse button - Button 3: Right mouse button - Button 4: Mouse wheel up (may also be a real button) - Button 5: Mouse wheel down (may also be a real button) +/*@{*/ +/** Used as a mask when testing buttons in buttonstate + * Button 1: Left mouse button + * Button 2: Middle mouse button + * Button 3: Right mouse 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 @@ -129,7 +132,7 @@ #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
--- a/include/SDL_mutex.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_mutex.h Mon Sep 21 09:38:10 2009 +0000 @@ -23,10 +23,11 @@ #ifndef _SDL_mutex_h #define _SDL_mutex_h -/* Functions to provide thread synchronization primitives - - These are independent of the other SDL routines. -*/ +/** @file SDL_mutex.h + * Functions to provide thread synchronization primitives + * + * @note These are independent of the other SDL routines. + */ #include "SDL_stdinc.h" #include "SDL_error.h" @@ -37,122 +38,135 @@ extern "C" { #endif -/* Synchronization functions which can time out return this value - if they time out. -*/ +/** Synchronization functions which can time out return this value + * 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. */ -#define SDL_UnlockMutex(m) SDL_mutexV(m) 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, - SDL_MUTEX_TIMEDOUT if the wait would block, and -1 on error. -*/ +/** Non-blocking variant of SDL_SemWait(). + * @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 - the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait does not succeed in - 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. -*/ +/** 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 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. + */ extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem *sem, Uint32 ms); -/* Atomically increases the semaphore's count (not blocking), returns 0, - or -1 on error. +/** Atomically increases the semaphore's count (not blocking). + * @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, - returns 0 or -1 on error. +/** Restart one of the threads that are waiting on the condition variable, + * @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, - returns 0 or -1 on error. +/** Restart all threads that are waiting on the condition variable, + * @return 0 or -1 on error. */ extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond *cond); -/* Wait on the condition variable, unlocking the provided mutex. - The mutex must be locked before entering this function! - The mutex is re-locked once the condition variable is signaled. - Returns 0 when it is signaled, or -1 on error. +/** Wait on the condition variable, unlocking the provided mutex. + * The mutex must be locked before entering this function! + * The mutex is re-locked once the condition variable is signaled. + * @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 - variable is signaled, SDL_MUTEX_TIMEDOUT if the condition is not - signaled in 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. -*/ +/** Waits for at most 'ms' milliseconds, and returns 0 if the condition + * variable is signaled, SDL_MUTEX_TIMEDOUT if the condition is not + * signaled in 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. + */ 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 @@ #include "close_code.h" #endif /* _SDL_mutex_h */ +
--- a/include/SDL_opengl.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_opengl.h Mon Sep 21 09:38:10 2009 +0000 @@ -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. - 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" +/** @name GLext.h + * This file taken from "GLext.h" from the Jeff Molofee OpenGL tutorials. + * 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 @@ #endif #endif /* NO_SDL_GLEXT */ +/*@}*/ \ No newline at end of file
--- a/include/SDL_platform.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_platform.h Mon Sep 21 09:38:10 2009 +0000 @@ -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
--- a/include/SDL_quit.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_quit.h Mon Sep 21 09:38:10 2009 +0000 @@ -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" -/* - 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. - 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 - complete, but have no effect. +/** @file SDL_quit.h + * 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. + * 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 + * complete, but have no effect. + * + * SDL_Init() installs signal handlers for SIGINT (keyboard interrupt) + * and SIGTERM (system termination request), if handlers do not already + * exist, that generate SDL_QUITEVENT events as well. There is no way + * to determine the cause of an SDL_QUITEVENT, but setting a signal + * handler in your application will override the default generation of + * quit events for that signal. + */ - SDL_Init() installs signal handlers for SIGINT (keyboard interrupt) - and SIGTERM (system termination request), if handlers do not already - exist, that generate SDL_QUITEVENT events as well. There is no way - to determine the cause of an SDL_QUITEVENT, but setting a signal - handler in your application will override the default generation of - 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))
--- a/include/SDL_rwops.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_rwops.h Mon Sep 21 09:38:10 2009 +0000 @@ -20,9 +20,10 @@ slouken@libsdl.org */ -/* This file provides a general interface for SDL to read and write - data sources. It can easily be extended to files, memory, etc. -*/ +/** @file SDL_rwops.h + * 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 #define _SDL_rwops_h @@ -36,28 +37,28 @@ 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_SET, SEEK_CUR, SEEK_END - Returns the final offset in the data source. + /** Seek to 'offset' relative to whence, one of stdio's whence values: + * SEEK_SET, SEEK_CUR, SEEK_END + * Returns the final offset in the data source. */ int (SDLCALL *seek)(struct SDL_RWops *context, int offset, int whence); - /* Read up to 'maxnum' objects each of size 'size' from the data - source to the area pointed at by 'ptr'. - Returns the number of objects read, or -1 if the read failed. + /** Read up to 'maxnum' objects each of size 'size' from the data + * source to the area pointed at by 'ptr'. + * 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 - pointed at by 'ptr' to data source. - Returns 'num', or -1 if the write failed. + /** Write exactly 'num' objects each of size 'objsize' from the area + * pointed at by 'ptr' to data source. + * 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; @@ -92,7 +93,8 @@ } 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); @@ -106,34 +108,43 @@ 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) - +/*@}*/ -/* Read an item of the specified endianness and return in native format */ +/** @name 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
--- a/include/SDL_stdinc.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_stdinc.h Mon Sep 21 09:38:10 2009 +0000 @@ -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 @@ -72,11 +74,12 @@ # 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 */ +/** @name Basic data types */ +/*@{*/ typedef enum SDL_bool { SDL_FALSE = 0, SDL_TRUE = 1 @@ -102,7 +105,10 @@ } 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] @@ -114,12 +120,14 @@ 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. - For both Watcom C/C++ and Borland C/C++ the compiler option that makes - enums having the size of an int must be enabled. - This is "-b" for Borland C/C++ and "-ei" for Watcom C/C++ (v11). -*/ +/** @name Enum Size Check + * Check to make sure enums are the size of ints, for structure packing. + * For both Watcom C/C++ and Borland C/C++ the compiler option that makes + * 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__ #pragma enumsalwaysint on @@ -132,7 +140,7 @@ #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++ */ @@ -565,11 +573,15 @@ 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 #define SDL_iconv_t iconv_t @@ -581,9 +593,9 @@ extern DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd); #endif extern DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft); -/* This function converts a string between encodings in one pass, returning a - 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, const char *inbuf, size_t inbytesleft); #define SDL_iconv_utf8_locale(S) SDL_iconv_string("", "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)
--- a/include/SDL_syswm.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_syswm.h Mon Sep 21 09:38:10 2009 +0000 @@ -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,11 +37,12 @@ extern "C" { #endif -/* Your application has access to a special type of event 'SDL_SYSWMEVENT', - which contains window-manager specific information and arrives whenever - an unhandled window event occurs. This event is ignored by default, but - you can enable it with SDL_EventState() -*/ +/** @file SDL_syswm.h + * Your application has access to a special type of event 'SDL_SYSWMEVENT', + * which contains window-manager specific information and arrives whenever + * 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; typedef struct SDL_SysWMinfo SDL_SysWMinfo; @@ -60,12 +63,12 @@ #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,32 +77,38 @@ } event; }; -/* The UNIX custom window manager information structure. - When this structure is returned, it holds information about which - low level system it is using, and will be one of SDL_SYSWM_TYPE. +/** The UNIX custom window manager information structure. + * When this structure is returned, it holds information about which + * 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 */ - Window window; /* The X11 display window */ - /* These locking functions should be called around - any X11 functions using the display variable, - but not the gfxdisplay variable. - They lock the event thread, so should not be - called around event functions or from event filters. + Display *display; /**< The X11 display */ + Window window; /**< The X11 display window */ + /** These locking functions should be called around + * any X11 functions using the display variable, + * but not the gfxdisplay variable. + * 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 */ - Window fswindow; /* The X11 fullscreen window */ - Window wmwindow; /* The X11 managed input window */ + /** @name Introduced in SDL 1.0.2 */ + /*@{*/ + Window fswindow; /**< The X11 fullscreen window */ + Window wmwindow; /**< The X11 managed input window */ + /*@}*/ - /* Introduced in SDL 1.2.12 */ - Display *gfxdisplay; /* The X11 display to which rendering is done */ + /** @name Introduced in SDL 1.2.12 */ + /*@{*/ + Display *gfxdisplay; /**< The X11 display to which rendering is done */ + /*@}*/ } x11; } info; } SDL_SysWMinfo; @@ -107,13 +116,13 @@ #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 */ @@ -123,50 +132,50 @@ #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 */ - UINT msg; /* The type of message */ - WPARAM wParam; /* WORD message parameter */ - LPARAM lParam; /* LONG message parameter */ + HWND hwnd; /**< The window for the message */ + UINT msg; /**< The type of message */ + WPARAM wParam; /**< WORD 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 */ - HGLRC hglrc; /* The OpenGL context, if any */ + HWND window; /**< The Win32 display window */ + 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 taskHandle; /* The RISC OS task handle */ - int window; /* The RISC OS display window */ + int wimpVersion; /**< Wimp version running under */ + int taskHandle; /**< The RISC OS task handle */ + 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; @@ -174,13 +183,13 @@ #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; @@ -191,16 +200,18 @@ #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);
--- a/include/SDL_thread.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_thread.h Mon Sep 21 09:38:10 2009 +0000 @@ -23,10 +23,11 @@ #ifndef _SDL_thread_h #define _SDL_thread_h -/* Header for the SDL thread management routines - - These are independent of the other SDL routines. -*/ +/** @file SDL_thread.h + * Header for the SDL thread management routines + * + * @note These are independent of the other SDL routines. + */ #include "SDL_stdinc.h" #include "SDL_error.h" @@ -40,25 +41,25 @@ 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__)) && !defined(__SYMBIAN32__) -/* - 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() - 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! - To solve this, we make a little hack here. - 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, - 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. - So, in short: - Always use the _beginthread() and _endthread() of the calling runtime library! -*/ +/** + * 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() + * 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! + * To solve this, we make a little hack here. + * 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, + * 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. + * So, in short: + * Always use the _beginthread() and _endthread() of the calling runtime library! + */ #define SDL_PASSED_BEGINTHREAD_ENDTHREAD #ifndef _WIN32_WCE #include <process.h> /* This has _beginthread() and _endthread() defined! */ @@ -92,21 +93,21 @@ 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, - equivalent to SDL_ThreadID() if the specified thread is NULL. +/** Get the 32-bit thread identifier for the specified thread, + * 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. - The return code for the thread function is placed in the area - pointed to by 'status', if 'status' is not NULL. +/** Wait for a thread to finish. + * The return code for the thread function is placed in the area + * 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);
--- a/include/SDL_timer.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_timer.h Mon Sep 21 09:38:10 2009 +0000 @@ -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 */ -#define TIMER_RESOLUTION 10 /* Experimentally determined */ +/** This is the maximum resolution of the SDL timer on all platforms */ +#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 @@ * 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 @@ */ 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 @@ */ 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. - Returns a timer ID, or NULL when an error occurs. +/** Add a new timer to the pool of timers already running. + * 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 }
--- a/include/SDL_types.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_types.h Mon Sep 21 09:38:10 2009 +0000 @@ -20,5 +20,9 @@ slouken@libsdl.org */ +/** @file SDL_types.h + * @deprecated Use SDL_stdinc.h instead. + */ + /* DEPRECATED */ #include "SDL_stdinc.h"
--- a/include/SDL_version.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_version.h Mon Sep 21 09:38:10 2009 +0000 @@ -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 14 +/*@}*/ typedef struct SDL_version { Uint8 major; @@ -45,7 +50,8 @@ 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 @@ (X)->patch = SDL_PATCHLEVEL; \ } -/* This macro turns the version numbers into a numeric value: - (1,2,3) -> (1203) - This assumes that there will never be more than 100 patchlevels -*/ +/** This macro turns the version numbers into a numeric value: + * (1,2,3) -> (1203) + * 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. - it should NOT be used to fill a version structure, instead you should - use the SDL_Version() macro. +/** This function gets the version of the dynamically linked SDL library. + * it should NOT be used to fill a version structure, instead you should + * use the SDL_Version() macro. */ extern DECLSPEC const SDL_version * SDLCALL SDL_Linked_Version(void);
--- a/include/SDL_video.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/SDL_video.h Mon Sep 21 09:38:10 2009 +0000 @@ -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 @@ 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 @@ 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', - which, if not NULL, contains the raw pixel data for the surface. -*/ +/** This structure should be treated as read-only, except for 'pixels', + * which, if not NULL, contains the raw pixel data for the surface. + */ typedef struct SDL_Surface { - Uint32 flags; /* Read-only */ - SDL_PixelFormat *format; /* Read-only */ - int w, h; /* Read-only */ - Uint16 pitch; /* Read-only */ - void *pixels; /* Read-write */ - int offset; /* Private */ + Uint32 flags; /**< Read-only */ + SDL_PixelFormat *format; /**< Read-only */ + int w, h; /**< Read-only */ + Uint16 pitch; /**< Read-only */ + void *pixels; /**< Read-write */ + int offset; /**< Private */ - /* Hardware-specific surface info */ + /** Hardware-specific surface info */ struct private_hwdata *hwdata; - /* clipping information */ - SDL_Rect clip_rect; /* Read-only */ - Uint32 unused1; /* for binary compatibility */ + /** clipping information */ + SDL_Rect clip_rect; /**< Read-only */ + Uint32 unused1; /**< for binary compatibility */ - /* Allow recursive locks */ - Uint32 locked; /* Private */ + /** Allow recursive locks */ + Uint32 locked; /**< Private */ - /* info for fast blit mapping to other surfaces */ - struct SDL_BlitMap *map; /* Private */ + /** info for fast blit mapping to other surfaces */ + struct SDL_BlitMap *map; /**< Private */ - /* format version, bumped at every change to invalidate blit maps */ - unsigned int format_version; /* Private */ + /** format version, bumped at every change to invalidate blit maps */ + unsigned int format_version; /**< Private */ - /* Reference count -- used when freeing surface */ - int refcount; /* Read-mostly */ + /** Reference count -- used when freeing surface */ + int refcount; /**< Read-mostly */ } SDL_Surface; -/* These are the currently supported flags for the SDL_surface */ -/* 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 */ +/** @name SDL_Surface Flags + * These are the currently supported flags for the SDL_surface + */ +/*@{*/ + +/** 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 */ +/*@}*/ -/* Evaluates to true if the surface needs to be locked before access */ +/** 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 wm_available :1; /* Flag: Can you talk to a window manager? */ + Uint32 hw_available :1; /**< Flag: Can you create hardware surfaces? */ + 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_CC :1; /* Flag: Accelerated blits with Colorkey */ - Uint32 blit_hw_A :1; /* Flag: Accelerated blits with Alpha */ - Uint32 blit_sw :1; /* Flag: Accelerated blits SW --> HW */ - Uint32 blit_sw_CC :1; /* Flag: Accelerated blits with Colorkey */ - Uint32 blit_sw_A :1; /* Flag: Accelerated blits with Alpha */ - Uint32 blit_fill :1; /* Flag: Accelerated color fill */ + Uint32 blit_hw :1; /**< Flag: Accelerated blits HW --> HW */ + Uint32 blit_hw_CC :1; /**< Flag: Accelerated blits with Colorkey */ + Uint32 blit_hw_A :1; /**< Flag: Accelerated blits with Alpha */ + Uint32 blit_sw :1; /**< Flag: Accelerated blits SW --> HW */ + Uint32 blit_sw_CC :1; /**< Flag: Accelerated blits with Colorkey */ + Uint32 blit_sw_A :1; /**< Flag: Accelerated blits with Alpha */ + Uint32 blit_fill :1; /**< Flag: Accelerated color fill */ Uint32 UnusedBits3 :16; - Uint32 video_mem; /* The total amount of video memory (in K) */ - SDL_PixelFormat *vfmt; /* Value: The format of the video surface */ - int current_w; /* Value: The current video mode width */ - int current_h; /* Value: The current video mode height */ + Uint32 video_mem; /**< The total amount of video memory (in K) */ + SDL_PixelFormat *vfmt; /**< Value: The format of the video surface */ + int current_w; /**< Value: The current video mode width */ + int current_h; /**< Value: The current video mode height */ } SDL_VideoInfo; -/* The most common video overlay formats. - 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 +/** @name Overlay Formats + * The most common video overlay formats. + * 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 */ -#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_YUY2_OVERLAY 0x32595559 /* Packed mode: Y0+U0+Y1+V0 (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) */ +/*@{*/ +#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_YUY2_OVERLAY 0x32595559 /**< Packed mode: Y0+U0+Y1+V0 (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 */ - int w, h; /* Read-only */ - int planes; /* Read-only */ - Uint16 *pitches; /* Read-only */ - Uint8 **pixels; /* Read-write */ + Uint32 format; /**< Read-only */ + int w, h; /**< Read-only */ + int planes; /**< Read-only */ + Uint16 *pitches; /**< Read-only */ + Uint8 **pixels; /**< Read-write */ - /* Hardware-specific surface info */ + /** @name Hardware-specific surface info */ + /*@{*/ struct private_yuvhwfuncs *hwfuncs; struct private_yuvhwdata *hwdata; + /*@{*/ - /* Special flags */ - Uint32 hw_overlay :1; /* Flag: This overlay hardware accelerated? */ + /** @name Special flags */ + /*@{*/ + 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 @@ 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 @@ */ 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 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 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 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 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_Surface * SDLCALL SDL_SetVideoMode (int width, int height, int bpp, Uint32 flags); -/* +/** @name SDL_Update Functions + * These functions should not be called while 'screen' is locked. + */ +/*@{*/ +/** * 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. */ 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 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_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_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_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_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,35 +486,37 @@ 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 (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 (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, 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, 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 @@ -505,16 +550,16 @@ * 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 @@ -535,7 +580,7 @@ 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. @@ -543,10 +588,10 @@ */ 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. @@ -554,11 +599,11 @@ 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. @@ -570,7 +615,7 @@ 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 @@ -587,7 +632,7 @@ */ 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. @@ -601,14 +646,14 @@ */ 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. @@ -623,7 +668,7 @@ 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 @@ -679,35 +724,38 @@ * 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 ) { - while ( SDL_LockSurface(image) < 0 ) - Sleep(10); - -- Write image pixels to image->pixels -- - SDL_UnlockSurface(image); - } + * @code + * while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) { + * while ( SDL_LockSurface(image) < 0 ) + * Sleep(10); + * -- 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 + * blitting works internally and how to use the other blit functions. */ -/* You should call SDL_BlitSurface() unless you know exactly how SDL - 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 - rectangle validation and clipping before passing it to SDL_LowerBlit() -*/ +/** This is the public blit function, SDL_BlitSurface(), and it performs + * 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 - blitting only. -*/ +/** This is a semi-private blit function and it performs low-level surface + * 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. @@ -719,7 +767,7 @@ 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() @@ -732,7 +780,7 @@ */ 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. @@ -748,38 +796,39 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -/* YUV video surface overlay functions */ +/** @name YUV video surface overlay functions */ /*@{*/ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -/* This function creates a video output overlay - Calling the returned surface an overlay is something of a misnomer because - 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. -*/ +/** This function creates a video output overlay + * Calling the returned surface an overlay is something of a misnomer because + * 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. + */ 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. - The contents of the video surface underneath the blit destination are - not defined. - The width and height of the destination rectangle may be different from - that of the overlay, but currently only 2x scaling is supported. -*/ +/** Blit a video overlay to the display surface. + * The contents of the video surface underneath the blit destination are + * not defined. + * The width and height of the destination rectangle may be different from + * 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 @@ -787,17 +836,17 @@ */ 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 @@ -808,30 +857,38 @@ */ 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. @@ -839,14 +896,14 @@ */ 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. @@ -863,24 +920,25 @@ */ 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);
--- a/include/begin_code.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/begin_code.h Mon Sep 21 09:38:10 2009 +0000 @@ -20,18 +20,26 @@ slouken@libsdl.org */ -/* 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. :) -*/ +/** + * @file begin_code.h + * 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__) || defined(__HAIKU__) # if defined(__GNUC__) @@ -77,7 +85,10 @@ # 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 @@ -107,10 +118,12 @@ #endif /* !EKA2 */ #endif /* __SYMBIAN32__ */ -/* Force structure packing at 4 byte alignment. - 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 +/** + * @file begin_code.h + * Force structure packing at 4 byte alignment. + * 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 @@ -125,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 @@ -150,15 +166,20 @@ #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 - in all files which include the offending header files) -*/ +/** + * @def __inline__ + * 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
--- a/include/close_code.h Mon Sep 21 09:27:08 2009 +0000 +++ b/include/close_code.h Mon Sep 21 09:38:10 2009 +0000 @@ -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
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/include/doxyfile Mon Sep 21 09:38:10 2009 +0000 @@ -0,0 +1,946 @@ +# Doxyfile 1.2.16 + +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project +# +# All text after a hash (#) is considered a comment and will be ignored +# The format is: +# TAG = value [value, ...] +# For lists items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (" ") + +#--------------------------------------------------------------------------- +# General configuration options +#--------------------------------------------------------------------------- + +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded +# by quotes) that should identify the project. + +PROJECT_NAME = SDL + +# The PROJECT_NUMBER tag can be used to enter a project or revision number. +# This could be handy for archiving the generated documentation or +# if some version control system is used. + +PROJECT_NUMBER = 1.2.14 + +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) +# base path where the generated documentation will be put. +# If a relative path is entered, it will be relative to the location +# where doxygen was started. If left blank the current directory will be used. + +OUTPUT_DIRECTORY = docs + +# The OUTPUT_LANGUAGE tag is used to specify the language in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all constant output in the proper language. +# The default language is English, other supported languages are: +# Brazilian, Chinese, Chinese-Traditional, Croatian, Czech, Danish, Dutch, +# Finnish, French, German, Greek, Hungarian, Italian, Japanese, Korean, +# Norwegian, Polish, Portuguese, Romanian, Russian, Slovak, Slovene, +# Spanish, Swedish and Ukrainian. + +OUTPUT_LANGUAGE = English + +# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in +# documentation are documented, even if no documentation was available. +# Private class members and static file members will be hidden unless +# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES + +EXTRACT_ALL = NO + +# If the EXTRACT_PRIVATE tag is set to YES all private members of a class +# will be included in the documentation. + +EXTRACT_PRIVATE = NO + +# If the EXTRACT_STATIC tag is set to YES all static members of a file +# will be included in the documentation. + +EXTRACT_STATIC = NO + +# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) +# defined locally in source files will be included in the documentation. +# If set to NO only classes defined in header files are included. + +EXTRACT_LOCAL_CLASSES = NO + +# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all +# undocumented members of documented classes, files or namespaces. +# If set to NO (the default) these members will be included in the +# various overviews, but no documentation section is generated. +# This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_MEMBERS = NO + +# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. +# If set to NO (the default) these class will be included in the various +# overviews. This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_CLASSES = NO + +# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will +# include brief member descriptions after the members that are listed in +# the file and class documentation (similar to JavaDoc). +# Set to NO to disable this. + +BRIEF_MEMBER_DESC = YES + +# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend +# the brief description of a member or function before the detailed description. +# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# brief descriptions will be completely suppressed. + +REPEAT_BRIEF = YES + +# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then +# Doxygen will generate a detailed section even if there is only a brief +# description. + +ALWAYS_DETAILED_SEC = NO + +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all inherited +# members of a class in the documentation of that class as if those members were +# ordinary class members. Constructors, destructors and assignment operators of +# the base classes will not be shown. + +INLINE_INHERITED_MEMB = NO + +# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full +# path before files name in the file list and in the header files. If set +# to NO the shortest path that makes the file name unique will be used. + +FULL_PATH_NAMES = NO + +# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag +# can be used to strip a user defined part of the path. Stripping is +# only done if one of the specified strings matches the left-hand part of +# the path. It is allowed to use relative paths in the argument list. + +STRIP_FROM_PATH = + +# The INTERNAL_DOCS tag determines if documentation +# that is typed after a \internal command is included. If the tag is set +# to NO (the default) then the documentation will be excluded. +# Set it to YES to include the internal documentation. + +INTERNAL_DOCS = NO + +# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct +# doxygen to hide any special comment blocks from generated source code +# fragments. Normal C and C++ comments will always remain visible. + +STRIP_CODE_COMMENTS = YES + +# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate +# file names in lower case letters. If set to YES upper case letters are also +# allowed. This is useful if you have classes or files whose names only differ +# in case and if your file system supports case sensitive file names. Windows +# users are adviced to set this option to NO. + +CASE_SENSE_NAMES = YES + +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter +# (but less readable) file names. This can be useful is your file systems +# doesn't support long names like on DOS, Mac, or CD-ROM. + +SHORT_NAMES = NO + +# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen +# will show members with their full class and namespace scopes in the +# documentation. If set to YES the scope will be hidden. + +HIDE_SCOPE_NAMES = NO + +# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen +# will generate a verbatim copy of the header file for each class for +# which an include is specified. Set to NO to disable this. + +VERBATIM_HEADERS = YES + +# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen +# will put list of the files that are included by a file in the documentation +# of that file. + +SHOW_INCLUDE_FILES = YES + +# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen +# will interpret the first line (until the first dot) of a JavaDoc-style +# comment as the brief description. If set to NO, the JavaDoc +# comments will behave just like the Qt-style comments (thus requiring an +# explict @brief command for a brief description. + +JAVADOC_AUTOBRIEF = NO + +# If the DETAILS_AT_TOP tag is set to YES then Doxygen +# will output the detailed description near the top, like JavaDoc. +# If set to NO, the detailed description appears after the member +# documentation. + +DETAILS_AT_TOP = NO + +# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented +# member inherits the documentation from any documented member that it +# reimplements. + +INHERIT_DOCS = YES + +# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] +# is inserted in the documentation for inline members. + +INLINE_INFO = YES + +# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen +# will sort the (detailed) documentation of file and class members +# alphabetically by member name. If set to NO the members will appear in +# declaration order. + +SORT_MEMBER_DOCS = YES + +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC +# tag is set to YES, then doxygen will reuse the documentation of the first +# member in the group (if any) for the other members of the group. By default +# all members of a group must be documented explicitly. + +DISTRIBUTE_GROUP_DOC = NO + +# The TAB_SIZE tag can be used to set the number of spaces in a tab. +# Doxygen uses this value to replace tabs by spaces in code fragments. + +TAB_SIZE = 4 + +# The GENERATE_TODOLIST tag can be used to enable (YES) or +# disable (NO) the todo list. This list is created by putting \todo +# commands in the documentation. + +GENERATE_TODOLIST = YES + +# The GENERATE_TESTLIST tag can be used to enable (YES) or +# disable (NO) the test list. This list is created by putting \test +# commands in the documentation. + +GENERATE_TESTLIST = YES + +# The GENERATE_BUGLIST tag can be used to enable (YES) or +# disable (NO) the bug list. This list is created by putting \bug +# commands in the documentation. + +GENERATE_BUGLIST = YES + +# This tag can be used to specify a number of aliases that acts +# as commands in the documentation. An alias has the form "name=value". +# For example adding "sideeffect=\par Side Effects:\n" will allow you to +# put the command \sideeffect (or @sideeffect) in the documentation, which +# will result in a user defined paragraph with heading "Side Effects:". +# You can put \n's in the value part of an alias to insert newlines. + +ALIASES = + +# The ENABLED_SECTIONS tag can be used to enable conditional +# documentation sections, marked by \if sectionname ... \endif. + +ENABLED_SECTIONS = + +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines +# the initial value of a variable or define consist of for it to appear in +# the documentation. If the initializer consists of more lines than specified +# here it will be hidden. Use a value of 0 to hide initializers completely. +# The appearance of the initializer of individual variables and defines in the +# documentation can be controlled using \showinitializer or \hideinitializer +# command in the documentation regardless of this setting. + +MAX_INITIALIZER_LINES = 30 + +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources +# only. Doxygen will then generate output that is more tailored for C. +# For instance some of the names that are used will be different. The list +# of all members will be omitted, etc. + +OPTIMIZE_OUTPUT_FOR_C = YES + +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java sources +# only. Doxygen will then generate output that is more tailored for Java. +# For instance namespaces will be presented as packages, qualified scopes +# will look different, etc. + +OPTIMIZE_OUTPUT_JAVA = NO + +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated +# at the bottom of the documentation of classes and structs. If set to YES the +# list will mention the files that were used to generate the documentation. + +SHOW_USED_FILES = YES + +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- + +# The QUIET tag can be used to turn on/off the messages that are generated +# by doxygen. Possible values are YES and NO. If left blank NO is used. + +QUIET = NO + +# The WARNINGS tag can be used to turn on/off the warning messages that are +# generated by doxygen. Possible values are YES and NO. If left blank +# NO is used. + +WARNINGS = YES + +# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings +# for undocumented members. If EXTRACT_ALL is set to YES then this flag will +# automatically be disabled. + +WARN_IF_UNDOCUMENTED = YES + +# The WARN_FORMAT tag determines the format of the warning messages that +# doxygen can produce. The string should contain the $file, $line, and $text +# tags, which will be replaced by the file and line number from which the +# warning originated and the warning text. + +WARN_FORMAT = "$file:$line: $text" + +# The WARN_LOGFILE tag can be used to specify a file to which warning +# and error messages should be written. If left blank the output is written +# to stderr. + +WARN_LOGFILE = + +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- + +# The INPUT tag can be used to specify the files and/or directories that contain +# documented source files. You may enter file names like "myfile.cpp" or +# directories like "/usr/src/myproject". Separate the files or directories +# with spaces. + +INPUT = include + +# If the value of the INPUT tag contains directories, you can use the +# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank the following patterns are tested: +# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp +# *.h++ *.idl *.odl + +FILE_PATTERNS = *.h + +# The RECURSIVE tag can be used to turn specify whether or not subdirectories +# should be searched for input files as well. Possible values are YES and NO. +# If left blank NO is used. + +RECURSIVE = NO + +# The EXCLUDE tag can be used to specify files and/or directories that should +# excluded from the INPUT source files. This way you can easily exclude a +# subdirectory from a directory tree whose root is specified with the INPUT tag. + +EXCLUDE = + +# The EXCLUDE_SYMLINKS tag can be used select whether or not files or directories +# that are symbolic links (a Unix filesystem feature) are excluded from the input. + +EXCLUDE_SYMLINKS = NO + +# If the value of the INPUT tag contains directories, you can use the +# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude +# certain files from those directories. + +EXCLUDE_PATTERNS = + +# The EXAMPLE_PATH tag can be used to specify one or more files or +# directories that contain example code fragments that are included (see +# the \include command). + +EXAMPLE_PATH = + +# If the value of the EXAMPLE_PATH tag contains directories, you can use the +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank all files are included. + +EXAMPLE_PATTERNS = + +# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be +# searched for input files to be used with the \include or \dontinclude +# commands irrespective of the value of the RECURSIVE tag. +# Possible values are YES and NO. If left blank NO is used. + +EXAMPLE_RECURSIVE = NO + +# The IMAGE_PATH tag can be used to specify one or more files or +# directories that contain image that are included in the documentation (see +# the \image command). + +IMAGE_PATH = + +# The INPUT_FILTER tag can be used to specify a program that doxygen should +# invoke to filter for each input file. Doxygen will invoke the filter program +# by executing (via popen()) the command <filter> <input-file>, where <filter> +# is the value of the INPUT_FILTER tag, and <input-file> is the name of an +# input file. Doxygen will then use the output that the filter program writes +# to standard output. + +INPUT_FILTER = + +# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using +# INPUT_FILTER) will be used to filter the input files when producing source +# files to browse. + +FILTER_SOURCE_FILES = NO + +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- + +# If the SOURCE_BROWSER tag is set to YES then a list of source files will +# be generated. Documented entities will be cross-referenced with these sources. + +SOURCE_BROWSER = NO + +# Setting the INLINE_SOURCES tag to YES will include the body +# of functions and classes directly in the documentation. + +INLINE_SOURCES = NO + +# If the REFERENCED_BY_RELATION tag is set to YES (the default) +# then for each documented function all documented +# functions referencing it will be listed. + +REFERENCED_BY_RELATION = YES + +# If the REFERENCES_RELATION tag is set to YES (the default) +# then for each documented function all documented entities +# called/used by that function will be listed. + +REFERENCES_RELATION = YES + +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- + +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index +# of all compounds will be generated. Enable this if the project +# contains a lot of classes, structs, unions or interfaces. + +ALPHABETICAL_INDEX = NO + +# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then +# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns +# in which this list will be split (can be a number in the range [1..20]) + +COLS_IN_ALPHA_INDEX = 5 + +# In case all classes in a project start with a common prefix, all +# classes will be put under the same header in the alphabetical index. +# The IGNORE_PREFIX tag can be used to specify one or more prefixes that +# should be ignored while generating the index headers. + +IGNORE_PREFIX = + +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- + +# If the GENERATE_HTML tag is set to YES (the default) Doxygen will +# generate HTML output. + +GENERATE_HTML = YES + +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `html' will be used as the default path. + +HTML_OUTPUT = html + +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for +# each generated HTML page (for example: .htm,.php,.asp). If it is left blank +# doxygen will generate files with .html extension. + +HTML_FILE_EXTENSION = .html + +# The HTML_HEADER tag can be used to specify a personal HTML header for +# each generated HTML page. If it is left blank doxygen will generate a +# standard header. + +HTML_HEADER = + +# The HTML_FOOTER tag can be used to specify a personal HTML footer for +# each generated HTML page. If it is left blank doxygen will generate a +# standard footer. + +HTML_FOOTER = + +# The HTML_STYLESHEET tag can be used to specify a user defined cascading +# style sheet that is used by each HTML page. It can be used to +# fine-tune the look of the HTML output. If the tag is left blank doxygen +# will generate a default style sheet + +HTML_STYLESHEET = + +# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, +# files or namespaces will be aligned in HTML using tables. If set to +# NO a bullet list will be used. + +HTML_ALIGN_MEMBERS = YES + +# If the GENERATE_HTMLHELP tag is set to YES, additional index files +# will be generated that can be used as input for tools like the +# Microsoft HTML help workshop to generate a compressed HTML help file (.chm) +# of the generated HTML documentation. + +GENERATE_HTMLHELP = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag +# controls if a separate .chi index file is generated (YES) or that +# it should be included in the master .chm file (NO). + +GENERATE_CHI = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag +# controls whether a binary table of contents is generated (YES) or a +# normal table of contents (NO) in the .chm file. + +BINARY_TOC = NO + +# The TOC_EXPAND flag can be set to YES to add extra items for group members +# to the contents of the Html help documentation and to the tree view. + +TOC_EXPAND = NO + +# The DISABLE_INDEX tag can be used to turn on/off the condensed index at +# top of each HTML page. The value NO (the default) enables the index and +# the value YES disables it. + +DISABLE_INDEX = NO + +# This tag can be used to set the number of enum values (range [1..20]) +# that doxygen will group on one line in the generated HTML documentation. + +ENUM_VALUES_PER_LINE = 4 + +# If the GENERATE_TREEVIEW tag is set to YES, a side panel will be +# generated containing a tree-like index structure (just like the one that +# is generated for HTML Help). For this to work a browser that supports +# JavaScript and frames is required (for instance Mozilla, Netscape 4.0+, +# or Internet explorer 4.0+). Note that for large projects the tree generation +# can take a very long time. In such cases it is better to disable this feature. +# Windows users are probably better off using the HTML help feature. + +GENERATE_TREEVIEW = NO + +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be +# used to set the initial width (in pixels) of the frame in which the tree +# is shown. + +TREEVIEW_WIDTH = 250 + +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- + +# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will +# generate Latex output. + +GENERATE_LATEX = NO + +# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `latex' will be used as the default path. + +LATEX_OUTPUT = latex + +# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be invoked. If left blank `latex' will be used as the default command name. + +LATEX_CMD_NAME = latex + +# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to +# generate index for LaTeX. If left blank `makeindex' will be used as the +# default command name. + +MAKEINDEX_CMD_NAME = makeindex + +# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact +# LaTeX documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_LATEX = NO + +# The PAPER_TYPE tag can be used to set the paper type that is used +# by the printer. Possible values are: a4, a4wide, letter, legal and +# executive. If left blank a4wide will be used. + +PAPER_TYPE = a4wide + +# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX +# packages that should be included in the LaTeX output. + +EXTRA_PACKAGES = + +# The LATEX_HEADER tag can be used to specify a personal LaTeX header for +# the generated latex document. The header should contain everything until +# the first chapter. If it is left blank doxygen will generate a +# standard header. Notice: only use this tag if you know what you are doing! + +LATEX_HEADER = + +# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated +# is prepared for conversion to pdf (using ps2pdf). The pdf file will +# contain links (just like the HTML output) instead of page references +# This makes the output suitable for online browsing using a pdf viewer. + +PDF_HYPERLINKS = NO + +# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of +# plain latex in the generated Makefile. Set this option to YES to get a +# higher quality PDF documentation. + +USE_PDFLATEX = NO + +# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. +# command to the generated LaTeX files. This will instruct LaTeX to keep +# running if errors occur, instead of asking the user for help. +# This option is also used when generating formulas in HTML. + +LATEX_BATCHMODE = NO + +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- + +# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output +# The RTF output is optimised for Word 97 and may not look very pretty with +# other RTF readers or editors. + +GENERATE_RTF = YES + +# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `rtf' will be used as the default path. + +RTF_OUTPUT = rtf + +# If the COMPACT_RTF tag is set to YES Doxygen generates more compact +# RTF documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_RTF = NO + +# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated +# will contain hyperlink fields. The RTF file will +# contain links (just like the HTML output) instead of page references. +# This makes the output suitable for online browsing using WORD or other +# programs which support those fields. +# Note: wordpad (write) and others do not support links. + +RTF_HYPERLINKS = NO + +# Load stylesheet definitions from file. Syntax is similar to doxygen's +# config file, i.e. a series of assigments. You only have to provide +# replacements, missing definitions are set to their default value. + +RTF_STYLESHEET_FILE = + +# Set optional variables used in the generation of an rtf document. +# Syntax is similar to doxygen's config file. + +RTF_EXTENSIONS_FILE = + +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- + +# If the GENERATE_MAN tag is set to YES (the default) Doxygen will +# generate man pages + +GENERATE_MAN = YES + +# The MAN_OUTPUT tag is used to specify where the man pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `man' will be used as the default path. + +MAN_OUTPUT = man + +# The MAN_EXTENSION tag determines the extension that is added to +# the generated man pages (default is the subroutine's section .3) + +MAN_EXTENSION = .3 + +# If the MAN_LINKS tag is set to YES and Doxygen generates man output, +# then it will generate one additional man file for each entity +# documented in the real man page(s). These additional files +# only source the real man page, but without them the man command +# would be unable to find the correct page. The default is NO. + +MAN_LINKS = YES + +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- + +# If the GENERATE_XML tag is set to YES Doxygen will +# generate an XML file that captures the structure of +# the code including all documentation. Note that this +# feature is still experimental and incomplete at the +# moment. + +GENERATE_XML = NO + +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- + +# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will +# generate an AutoGen Definitions (see autogen.sf.net) file +# that captures the structure of the code including all +# documentation. Note that this feature is still experimental +# and incomplete at the moment. + +GENERATE_AUTOGEN_DEF = NO + +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- + +# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will +# evaluate all C-preprocessor directives found in the sources and include +# files. + +ENABLE_PREPROCESSING = YES + +# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro +# names in the source code. If set to NO (the default) only conditional +# compilation will be performed. Macro expansion can be done in a controlled +# way by setting EXPAND_ONLY_PREDEF to YES. + +MACRO_EXPANSION = YES + +# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES +# then the macro expansion is limited to the macros specified with the +# PREDEFINED and EXPAND_AS_PREDEFINED tags. + +EXPAND_ONLY_PREDEF = YES + +# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files +# in the INCLUDE_PATH (see below) will be search if a #include is found. + +SEARCH_INCLUDES = YES + +# The INCLUDE_PATH tag can be used to specify one or more directories that +# contain include files that are not input files but should be processed by +# the preprocessor. + +INCLUDE_PATH = + +# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard +# patterns (like *.h and *.hpp) to filter out the header-files in the +# directories. If left blank, the patterns specified with FILE_PATTERNS will +# be used. + +INCLUDE_FILE_PATTERNS = + +# The PREDEFINED tag can be used to specify one or more macro names that +# are defined before the preprocessor is started (similar to the -D option of +# gcc). The argument of the tag is a list of macros of the form: name +# or name=definition (no spaces). If the definition and the = are +# omitted =1 is assumed. + +PREDEFINED = DOXYGEN_SHOULD_IGNORE_THIS=1 SDLCALL= SNDDECLSPEC= + +# If the MACRO_EXPANSION and EXPAND_PREDEF_ONLY tags are set to YES then +# this tag can be used to specify a list of macro names that should be expanded. +# The macro definition that is found in the sources will be used. +# Use the PREDEFINED tag if you want to use a different macro definition. + +EXPAND_AS_DEFINED = + +# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then +# doxygen's preprocessor will remove all function-like macros that are alone +# on a line and do not end with a semicolon. Such function macros are typically +# used for boiler-plate code, and will confuse the parser if not removed. + +SKIP_FUNCTION_MACROS = YES + +#--------------------------------------------------------------------------- +# Configuration::addtions related to external references +#--------------------------------------------------------------------------- + +# The TAGFILES tag can be used to specify one or more tagfiles. + +TAGFILES = + +# When a file name is specified after GENERATE_TAGFILE, doxygen will create +# a tag file that is based on the input files it reads. + +GENERATE_TAGFILE = + +# If the ALLEXTERNALS tag is set to YES all external classes will be listed +# in the class index. If set to NO only the inherited external classes +# will be listed. + +ALLEXTERNALS = NO + +# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed +# in the modules index. If set to NO, only the current project's groups will +# be listed. + +EXTERNAL_GROUPS = YES + +# The PERL_PATH should be the absolute path and name of the perl script +# interpreter (i.e. the result of `which perl'). + +PERL_PATH = /usr/bin/perl + +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- + +# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will +# generate a inheritance diagram (in Html, RTF and LaTeX) for classes with base or +# super classes. Setting the tag to NO turns the diagrams off. Note that this +# option is superceded by the HAVE_DOT option below. This is only a fallback. It is +# recommended to install and use dot, since it yields more powerful graphs. + +CLASS_DIAGRAMS = NO + +# If set to YES, the inheritance and collaboration graphs will hide +# inheritance and usage relations if the target is undocumented +# or is not a class. + +HIDE_UNDOC_RELATIONS = YES + +# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is +# available from the path. This tool is part of Graphviz, a graph visualization +# toolkit from AT&T and Lucent Bell Labs. The other options in this section +# have no effect if this option is set to NO (the default) + +HAVE_DOT = NO + +# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect inheritance relations. Setting this tag to YES will force the +# the CLASS_DIAGRAMS tag to NO. + +CLASS_GRAPH = NO + +# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect implementation dependencies (inheritance, containment, and +# class references variables) of the class with other documented classes. + +COLLABORATION_GRAPH = NO + +# If set to YES, the inheritance and collaboration graphs will show the +# relations between templates and their instances. + +TEMPLATE_RELATIONS = NO + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT +# tags are set to YES then doxygen will generate a graph for each documented +# file showing the direct and indirect include dependencies of the file with +# other documented files. + +INCLUDE_GRAPH = NO + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and +# HAVE_DOT tags are set to YES then doxygen will generate a graph for each +# documented header file showing the documented files that directly or +# indirectly include this file. + +INCLUDED_BY_GRAPH = YES + +# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen +# will graphical hierarchy of all classes instead of a textual one. + +GRAPHICAL_HIERARCHY = YES + +# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images +# generated by dot. Possible values are png, jpg, or gif +# If left blank png will be used. + +DOT_IMAGE_FORMAT = png + +# The tag DOT_PATH can be used to specify the path where the dot tool can be +# found. If left blank, it is assumed the dot tool can be found on the path. + +DOT_PATH = + +# The DOTFILE_DIRS tag can be used to specify one or more directories that +# contain dot files that are included in the documentation (see the +# \dotfile command). + +DOTFILE_DIRS = + +# The MAX_DOT_GRAPH_WIDTH tag can be used to set the maximum allowed width +# (in pixels) of the graphs generated by dot. If a graph becomes larger than +# this value, doxygen will try to truncate the graph, so that it fits within +# the specified constraint. Beware that most browsers cannot cope with very +# large images. + +MAX_DOT_GRAPH_WIDTH = 1024 + +# The MAX_DOT_GRAPH_HEIGHT tag can be used to set the maximum allows height +# (in pixels) of the graphs generated by dot. If a graph becomes larger than +# this value, doxygen will try to truncate the graph, so that it fits within +# the specified constraint. Beware that most browsers cannot cope with very +# large images. + +MAX_DOT_GRAPH_HEIGHT = 1024 + +# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will +# generate a legend page explaining the meaning of the various boxes and +# arrows in the dot generated graphs. + +GENERATE_LEGEND = YES + +# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will +# remove the intermedate dot files that are used to generate +# the various graphs. + +DOT_CLEANUP = YES + +#--------------------------------------------------------------------------- +# Configuration::addtions related to the search engine +#--------------------------------------------------------------------------- + +# The SEARCHENGINE tag specifies whether or not a search engine should be +# used. If set to NO the values of all tags below this one will be ignored. + +SEARCHENGINE = NO + +# The CGI_NAME tag should be the name of the CGI script that +# starts the search engine (doxysearch) with the correct parameters. +# A script with this name will be generated by doxygen. + +CGI_NAME = search.cgi + +# The CGI_URL tag should be the absolute URL to the directory where the +# cgi binaries are located. See the documentation of your http daemon for +# details. + +CGI_URL = + +# The DOC_URL tag should be the absolute URL to the directory where the +# documentation is located. If left blank the absolute path to the +# documentation, with file:// prepended to it, will be used. + +DOC_URL = + +# The DOC_ABSPATH tag should be the absolute path to the directory where the +# documentation is located. If left blank the directory on the local machine +# will be used. + +DOC_ABSPATH = + +# The BIN_ABSPATH tag must point to the directory where the doxysearch binary +# is installed. + +BIN_ABSPATH = /usr/local/bin/ + +# The EXT_DOC_PATHS tag can be used to specify one or more paths to +# documentation generated for other projects. This allows doxysearch to search +# the documentation for these projects as well. + +EXT_DOC_PATHS =