/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
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
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);
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
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
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
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
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
extern "C" {
#endif
-/* The calculated values in this structure are calculated by SDL_OpenAudio() */
+/**
+ * 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.
+ * 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
+ * CPU speed. Smaller values yield faster response time, but can lead
+ * to underflow if the application is doing heavy processing and cannot
+ * fill the audio buffer in time. A stereo sample consists of both right
+ * 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
+ * calculated by SDL_OpenAudio().
+ * - '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
+ * 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
+ * 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.
- '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.
- */
+ 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;
-/* 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 */
+/**
+ * @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
-/* Native audio byte ordering */
+/**
+ * @name Native audio byte ordering
+ */
+/*@{*/
#if SDL_BYTEORDER == SDL_LIL_ENDIAN
#define AUDIO_U16SYS AUDIO_U16LSB
#define AUDIO_S16SYS AUDIO_S16LSB
#define AUDIO_U16SYS AUDIO_U16MSB
#define AUDIO_S16SYS AUDIO_S16MSB
#endif
+/*@}*/
+
+/*@}*/
-/* A structure to hold a set of audio conversion filters and buffers */
+/** 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 */
+ 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 */
+ int filter_index; /**< Current audio conversion function */
} SDL_AudioCVT;
/* Function prototypes */
-/* These functions are used internally, and should not be used unless you
+/**
+ * @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
+/**
+ * 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
* 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.
- * 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
- * CPU speed. Smaller values yield faster response time, but can lead
- * to underflow if the application is doing heavy processing and cannot
- * fill the audio buffer in time. A stereo sample consists of both right
- * 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
- * calculated by SDL_OpenAudio().
- * '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
- * 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
- * function.
- *
* 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
*/
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
*/
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.
*/
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);
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
slouken@libsdl.org
*/
+/**
+ * @file SDL_byteorder.h
+ * @deprecated Use SDL_endian.h instead
+ */
+
/* DEPRECATED */
#include "SDL_endian.h"
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
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
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,
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 */
-
- /* 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 */
+ 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 */
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; \
*(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);
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
/* Enable various audio drivers */
#define SDL_AUDIO_DRIVER_COREAUDIO 1
-#define SDL_AUDIO_DRIVER_SNDMGR 1
#define SDL_AUDIO_DRIVER_DISK 1
#define SDL_AUDIO_DRIVER_DUMMY 1
#else
#define SDL_VIDEO_DRIVER_QUARTZ 1
#endif
+#define SDL_VIDEO_DRIVER_DGA 1
+#define SDL_VIDEO_DRIVER_X11 1
+#define SDL_VIDEO_DRIVER_X11_DGAMOUSE 1
+#define SDL_VIDEO_DRIVER_X11_DYNAMIC "/usr/X11R6/lib/libX11.6.dylib"
+#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XEXT "/usr/X11R6/lib/libXext.6.dylib"
+#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XRANDR "/usr/X11R6/lib/libXrandr.2.dylib"
+#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XRENDER "/usr/X11R6/lib/libXrender.1.dylib"
+#define SDL_VIDEO_DRIVER_X11_VIDMODE 1
+#define SDL_VIDEO_DRIVER_X11_XINERAMA 1
+#define SDL_VIDEO_DRIVER_X11_XME 1
+#define SDL_VIDEO_DRIVER_X11_XRANDR 1
+#define SDL_VIDEO_DRIVER_X11_XV 1
/* Enable OpenGL support */
#define SDL_VIDEO_OPENGL 1
+#define SDL_VIDEO_OPENGL_GLX 1
+
+/* Disable screensaver */
+#define SDL_VIDEO_DISABLE_SCREENSAVER 1
/* Enable assembly routines */
#define SDL_ASSEMBLY_ROUTINES 1
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
#define SDL_VIDEO_OPENGL_WGL 1
#endif
+/* Disable screensaver */
+#define SDL_VIDEO_DISABLE_SCREENSAVER 1
+
/* Enable assembly routines (Win64 doesn't have inline asm) */
#ifndef _WIN64
#define SDL_ASSEMBLY_ROUTINES 1
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
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
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++ */
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
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__) || \
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)
Uint32 hi, lo;
/* Separate into high and low 32-bit values and swap them */
- lo = (Uint32)(x&0xFFFFFFFF);
+ lo = SDL_static_cast(Uint32, x & 0xFFFFFFFF);
x >>= 32;
- hi = (Uint32)(x&0xFFFFFFFF);
+ hi = SDL_static_cast(Uint32, x & 0xFFFFFFFF);
x = SDL_Swap32(lo);
x <<= 32;
x |= SDL_Swap32(hi);
#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)
#define SDL_SwapBE32(X) (X)
#define SDL_SwapBE64(X) (X)
#endif
+/*@}*/
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
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
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 {
SDL_LASTERROR
} SDL_errorcode;
extern DECLSPEC void SDLCALL SDL_Error(SDL_errorcode code);
-
+/*@}*/
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
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
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),
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 {
SDL_SysWMmsg *msg;
} SDL_SysWMEvent;
-/* General event structure */
+/** General event structure */
typedef union SDL_Event {
Uint8 type;
SDL_ActiveEvent active;
/* 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
}
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
slouken@libsdl.org
*/
+/** @file SDL_getenv.h
+ * @deprecated Use SDL_stdinc.h instead
+ */
+
/* DEPRECATED */
#include "SDL_stdinc.h"
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
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
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
#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);
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
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
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);
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
#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,
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,
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,
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,
SDLK_END = 279,
SDLK_PAGEUP = 280,
SDLK_PAGEDOWN = 281,
+ /*@}*/
- /* Function keys */
+ /** @name Function keys */
+ /*@{*/
SDLK_F1 = 282,
SDLK_F2 = 283,
SDLK_F3 = 284,
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,
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,
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
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
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++ */
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
#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__)) || \
#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"
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"
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
#endif
#include "close_code.h"
#endif
+/*@}*/
#endif /* Need to redefine main()? */
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
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
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
*/
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
*/
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.
*
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
*/
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
#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
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
#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"
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.
+ */
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
}
#include "close_code.h"
#endif /* _SDL_mutex_h */
+
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
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"
#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_
#endif
#endif /* NO_SDL_GLEXT */
+/*@}*/
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
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
#undef __BEOS__
#define __BEOS__ 1
#endif
+#if defined(__HAIKU__)
+#undef __HAIKU__
+#define __HAIKU__ 1
+#endif
#if defined(bsdi) || defined(__bsdi) || defined(__bsdi__)
#undef __BSDI__
#define __BSDI__ 1
#undef __DREAMCAST__
#define __DREAMCAST__ 1
#endif
-#if defined(__FreeBSD__) || defined(__DragonFly__)
+#if defined(__FreeBSD__) || defined(__FreeBSD_kernel__) || defined(__DragonFly__)
#undef __FREEBSD__
#define __FREEBSD__ 1
#endif
+#if defined(__HAIKU__)
+#undef __HAIKU__
+#define __HAIKU__ 1
+#endif
#if defined(hpux) || defined(__hpux) || defined(__hpux__)
#undef __HPUX__
#define __HPUX__ 1
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
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
#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.
-
- 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
+ * 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.
+ */
+
+/** @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))
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
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
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 'num' objects each of size 'objsize' 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;
} 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);
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 */
+/*@}*/
+
+/** @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 */
+/*@}*/
-/* Macros to easily read and write from an SDL_RWops structure */
+/** @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
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
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
#ifdef HAVE_CTYPE_H
# include <ctype.h>
#endif
-#ifdef HAVE_ICONV_H
+#if defined(HAVE_ICONV) && defined(HAVE_ICONV_H)
# include <iconv.h>
#endif
-/* The number of elements in an array */
+/** The number of elements in an array */
#define SDL_arraysize(array) (sizeof(array)/sizeof(array[0]))
#define SDL_TABLESIZE(table) SDL_arraysize(table)
-/* Basic data types */
-typedef enum SDL_bool {
+/* Use proper C++ casts when compiled as C++ to be compatible with the option
+ -Wold-style-cast of GCC (and -Werror=old-style-cast in GCC 4.2 and above. */
+#ifdef __cplusplus
+#define SDL_reinterpret_cast(type, expression) reinterpret_cast<type>(expression)
+#define SDL_static_cast(type, expression) static_cast<type>(expression)
+#else
+#define SDL_reinterpret_cast(type, expression) ((type)(expression))
+#define SDL_static_cast(type, expression) ((type)(expression))
+#endif
+
+/** @name Basic data types */
+/*@{*/
+typedef enum {
SDL_FALSE = 0,
SDL_TRUE = 1
} SDL_bool;
} 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]
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
#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++ */
"cld\n\t" \
"rep ; stosl\n\t" \
: "=&D" (u0), "=&a" (u1), "=&c" (u2) \
- : "0" (dst), "1" (val), "2" ((Uint32)(len)) \
+ : "0" (dst), "1" (val), "2" (SDL_static_cast(Uint32, len)) \
: "memory" ); \
} while(0)
#endif
do { \
unsigned _count = (len); \
unsigned _n = (_count + 3) / 4; \
- Uint32 *_p = (Uint32 *)(dst); \
+ Uint32 *_p = SDL_static_cast(Uint32 *, dst); \
Uint32 _val = (val); \
+ if (len == 0) break; \
switch (_count % 4) { \
case 0: do { *_p++ = _val; \
case 3: *_p++ = _val; \
"movsb\n" \
"2:" \
: "=&c" (u0), "=&D" (u1), "=&S" (u2) \
- : "0" ((unsigned)(len)/4), "q" (len), "1" (dst),"2" (src) \
+ : "0" (SDL_static_cast(unsigned, len)/4), "q" (len), "1" (dst),"2" (src) \
: "memory" ); \
} while(0)
#endif
"cld\n\t" \
"rep ; movsl" \
: "=&c" (ecx), "=&D" (edi), "=&S" (esi) \
- : "0" ((unsigned)(len)), "1" (dst), "2" (src) \
+ : "0" (SDL_static_cast(unsigned, len)), "1" (dst), "2" (src) \
: "memory" ); \
} while(0)
#endif
#define SDL_revcpy(dst, src, len) \
do { \
int u0, u1, u2; \
- char *dstp = (char *)(dst); \
- char *srcp = (char *)(src); \
+ char *dstp = SDL_static_cast(char *, dst); \
+ char *srcp = SDL_static_cast(char *, src); \
int n = (len); \
if ( n >= 4 ) { \
__asm__ __volatile__ ( \
"std\n\t" \
"rep ; movsl\n\t" \
+ "cld\n\t" \
: "=&c" (u0), "=&D" (u1), "=&S" (u2) \
: "0" (n >> 2), \
"1" (dstp+(n-4)), "2" (srcp+(n-4)) \
extern DECLSPEC int SDLCALL SDL_vsnprintf(char *text, size_t maxlen, const char *fmt, va_list ap);
#endif
-/* The SDL implementation of iconv() returns these error codes */
+/** @name SDL_ICONV Error Codes
+ * The SDL implementation of iconv() returns these error codes
+ */
+/*@{*/
#define SDL_ICONV_ERROR (size_t)-1
#define SDL_ICONV_E2BIG (size_t)-2
#define SDL_ICONV_EILSEQ (size_t)-3
#define SDL_ICONV_EINVAL (size_t)-4
+/*@}*/
-#ifdef HAVE_ICONV
+#if defined(HAVE_ICONV) && defined(HAVE_ICONV_H)
#define SDL_iconv_t iconv_t
#define SDL_iconv_open iconv_open
#define SDL_iconv_close iconv_close
extern DECLSPEC 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)
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
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
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;
#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;
} 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 */
-
- /* Introduced in SDL 1.2.12 */
- Display *gfxdisplay; /* The X11 display to which rendering is done */
+ /*@}*/
+
+ /** @name Introduced in SDL 1.0.2 */
+ /*@{*/
+ Window fswindow; /**< The X11 fullscreen window */
+ Window wmwindow; /**< The X11 managed input window */
+ /*@}*/
+
+ /** @name Introduced in SDL 1.2.12 */
+ /*@{*/
+ Display *gfxdisplay; /**< The X11 display to which rendering is done */
+ /*@}*/
} x11;
} info;
} SDL_SysWMinfo;
#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 */
#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;
#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;
#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);
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
#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"
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! */
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);
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
#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"
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
* 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().
*
*/
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
*/
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
}
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
slouken@libsdl.org
*/
+/** @file SDL_types.h
+ * @deprecated Use SDL_stdinc.h instead.
+ */
+
/* DEPRECATED */
#include "SDL_stdinc.h"
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
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
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 13
+#define SDL_PATCHLEVEL 14
+/*@}*/
typedef struct SDL_version {
Uint8 major;
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) \
(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);
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
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
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;
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;
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 */
-
- /* Hardware-specific surface info */
+ 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 */
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 */
-
-/* Evaluates to true if the surface needs to be locked before access */
+/** @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 */
+/*@}*/
+
+/** 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 */
-
- /* Hardware-specific surface info */
+ Uint32 format; /**< Read-only */
+ int w, h; /**< Read-only */
+ int planes; /**< Read-only */
+ Uint16 *pitches; /**< Read-only */
+ Uint8 **pixels; /**< Read-write */
+
+ /** @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,
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.
*/
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
*/
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
*/
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
*/
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,
*/
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.
extern DECLSPEC SDL_Surface * SDLCALL SDL_SetVideoMode
(int width, int height, int bpp, Uint32 flags);
-/*
- * 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.
+/** @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.
+ */
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.
*/
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
*
*/
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.
*/
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.
*/
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
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
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, SDL_PixelFormat *fmt,
+extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
+ const SDL_PixelFormat * const fmt,
Uint8 *r, Uint8 *g, Uint8 *b);
-/*
+/**
* Maps a pixel value into the RGBA components for a given pixel format
*/
-extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel, SDL_PixelFormat *fmt,
- Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);
+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
* 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
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.
*/
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.
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.
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
*/
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.
*/
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.
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
* 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.
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()
*/
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.
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-/* 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
*/
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
*/
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.
*/
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.
*/
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);
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2004 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
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__)
+# if defined(__BEOS__) || defined(__HAIKU__)
# if defined(__GNUC__)
# define DECLSPEC __declspec(dllexport)
# else
# else
# define DECLSPEC
# endif
+# elif defined (__GNUC__) && __GNUC__ < 4
+# /* Added support for GCC-EMX <v4.x */
+# /* this is needed for XFree86/OS2 developement */
+# /* F. Ambacher(anakor@snafu.de) 05.2008 */
+# ifdef BUILD_SDL
+# define DECLSPEC __declspec(dllexport)
+# else
+# define DECLSPEC
+# endif
# else
# define DECLSPEC
# endif
# 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
-#else
-#ifdef __OS2__
-/* But on OS/2, we use the _System calling convention */
-/* to be compatible with every compiler */
-#define SDLCALL _System
-#else
-#define SDLCALL
-#endif
-#endif
+# if defined(__WIN32__) && !defined(__GNUC__)
+# define SDLCALL __cdecl
+# elif defined(__OS2__)
+# if defined (__GNUC__) && __GNUC__ < 4
+# /* Added support for GCC-EMX <v4.x */
+# /* this is needed for XFree86/OS2 developement */
+# /* F. Ambacher(anakor@snafu.de) 05.2008 */
+# define SDLCALL _cdecl
+# else
+# /* On other compilers on OS/2, we use the _System calling convention */
+# /* to be compatible with every compiler */
+# define SDLCALL _System
+# endif
+# else
+# define SDLCALL
+# endif
#endif /* SDLCALL */
#ifdef __SYMBIAN32__
#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
#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
#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
/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2004 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
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
<key>CFBundlePackageType</key>
<string>FMWK</string>
<key>CFBundleShortVersionString</key>
- <string>1.2.13</string>
+ <string>1.2.14</string>
<key>CFBundleSignature</key>
<string>SDLX</string>
<key>CFBundleVersion</key>
- <string>1.2.13</string>
+ <string>1.2.14</string>
</dict>
</plist>
+++ /dev/null
-{
- IBClasses = (
- {CLASS = FirstResponder; LANGUAGE = ObjC; SUPERCLASS = NSObject; },
- {
- ACTIONS = {makeFullscreen = id; quit = id; };
- CLASS = SDLMain;
- LANGUAGE = ObjC;
- SUPERCLASS = NSObject;
- }
- );
- IBVersion = 1;
-}
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist SYSTEM "file://localhost/System/Library/DTDs/PropertyList.dtd">
-<plist version="0.9">
-<dict>
- <key>IBDocumentLocation</key>
- <string>49 97 356 240 0 0 987 746 </string>
- <key>IBMainMenuLocation</key>
- <string>20 515 195 44 0 46 800 532 </string>
- <key>IBUserGuides</key>
- <dict/>
-</dict>
-</plist>
projects / xonotic / xonotic.git / commitdiff