Skip to content

L
libSDL
Commit 1106b669 authored by Sam Lantinga's avatar Sam Lantinga
Browse files
Options

Fixed bug #706 

 Ken Bull      2009-02-25 13:22:02 PST

Adds Doxygen support for all headers (except config and boilerplate headers) in
the include folder for SDL-1.2 revision 4446.

While in general SDL is quite thoroughly commented, none of these comments are
correctly formatted for Doxygen and are generally inconsistent in their
formatting.

--HG--
branch : SDL-1.2
extra : convert_revision : svn%3Ac70aab31-4412-0410-b14c-859654838e24/branches/SDL-1.2%403857
parent 2e1e7fc4
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 2218 additions and 920 deletions
include/SDL.h
View file @ 1106b669
......@@ -20,7 +20,9 @@
slouken@libsdl.org
*/
/* Main include header for the SDL library */
/** @file SDL.h
* Main include header for the SDL library
*/
#ifndef _SDL_H
#define _SDL_H
......@@ -47,41 +49,46 @@
extern "C" {
#endif
/* As of version 0.5, SDL is loaded dynamically into the application */
/** @file SDL.h
* @note As of version 0.5, SDL is loaded dynamically into the application
*/
/* These are the flags which may be passed to SDL_Init() -- you should
specify the subsystems which you will be using in your application.
*/
/** @name SDL_INIT Flags
* These are the flags which may be passed to SDL_Init() -- you should
* specify the subsystems which you will be using in your application.
*/
/*@{*/
#define SDL_INIT_TIMER 0x00000001
#define SDL_INIT_AUDIO 0x00000010
#define SDL_INIT_VIDEO 0x00000020
#define SDL_INIT_CDROM 0x00000100
#define SDL_INIT_JOYSTICK 0x00000200
#define SDL_INIT_NOPARACHUTE 0x00100000 /* Don't catch fatal signals */
#define SDL_INIT_EVENTTHREAD 0x01000000 /* Not supported on all OS's */
#define SDL_INIT_NOPARACHUTE 0x00100000 /**< Don't catch fatal signals */
#define SDL_INIT_EVENTTHREAD 0x01000000 /**< Not supported on all OS's */
#define SDL_INIT_EVERYTHING 0x0000FFFF
/*@}*/
/* This function loads the SDL dynamically linked library and initializes
* the subsystems specified by 'flags' (and those satisfying dependencies)
* Unless the SDL_INIT_NOPARACHUTE flag is set, it will install cleanup
* signal handlers for some commonly ignored fatal signals (like SIGSEGV)
/** This function loads the SDL dynamically linked library and initializes
* the subsystems specified by 'flags' (and those satisfying dependencies)
* Unless the SDL_INIT_NOPARACHUTE flag is set, it will install cleanup
* signal handlers for some commonly ignored fatal signals (like SIGSEGV)
*/
extern DECLSPEC int SDLCALL SDL_Init(Uint32 flags);
/* This function initializes specific SDL subsystems */
/** This function initializes specific SDL subsystems */
extern DECLSPEC int SDLCALL SDL_InitSubSystem(Uint32 flags);
/* This function cleans up specific SDL subsystems */
/** This function cleans up specific SDL subsystems */
extern DECLSPEC void SDLCALL SDL_QuitSubSystem(Uint32 flags);
/* This function returns mask of the specified subsystems which have
been initialized.
If 'flags' is 0, it returns a mask of all initialized subsystems.
*/
/** This function returns mask of the specified subsystems which have
* been initialized.
* If 'flags' is 0, it returns a mask of all initialized subsystems.
*/
extern DECLSPEC Uint32 SDLCALL SDL_WasInit(Uint32 flags);
/* This function cleans up all initialized subsystems and unloads the
* dynamically linked library. You should call it upon all exit conditions.
/** This function cleans up all initialized subsystems and unloads the
* dynamically linked library. You should call it upon all exit conditions.
*/
extern DECLSPEC void SDLCALL SDL_Quit(void);
......
include/SDL_active.h
View file @ 1106b669
......@@ -20,7 +20,10 @@
slouken@libsdl.org
*/
/* Include file for SDL application focus event handling */
/**
* @file SDL_active.h
* Include file for SDL application focus event handling
*/
#ifndef _SDL_active_h
#define _SDL_active_h
......@@ -34,13 +37,15 @@
extern "C" {
#endif
/* The available application states */
#define SDL_APPMOUSEFOCUS 0x01 /* The app has mouse coverage */
#define SDL_APPINPUTFOCUS 0x02 /* The app has input focus */
#define SDL_APPACTIVE 0x04 /* The application is active */
/** @name The available application states */
/*@{*/
#define SDL_APPMOUSEFOCUS 0x01 /**< The app has mouse coverage */
#define SDL_APPINPUTFOCUS 0x02 /**< The app has input focus */
#define SDL_APPACTIVE 0x04 /**< The application is active */
/*@}*/
/* Function prototypes */
/*
/**
* This function returns the current state of the application, which is a
* bitwise combination of SDL_APPMOUSEFOCUS, SDL_APPINPUTFOCUS, and
* SDL_APPACTIVE. If SDL_APPACTIVE is set, then the user is able to
......
include/SDL_audio.h
View file @ 1106b669
This diff is collapsed.
include/SDL_byteorder.h
View file @ 1106b669
......@@ -20,5 +20,10 @@
slouken@libsdl.org
*/
/**
* @file SDL_byteorder.h
* @deprecated Use SDL_endian.h instead
*/
/* DEPRECATED */
#include "SDL_endian.h"
include/SDL_cdrom.h
View file @ 1106b669
......@@ -20,7 +20,10 @@
slouken@libsdl.org
*/
/* This is the CD-audio control API for Simple DirectMedia Layer */
/**
* @file SDL_cdrom.h
* This is the CD-audio control API for Simple DirectMedia Layer
*/
#ifndef _SDL_cdrom_h
#define _SDL_cdrom_h
......@@ -34,19 +37,25 @@
extern "C" {
#endif
/* In order to use these functions, SDL_Init() must have been called
with the SDL_INIT_CDROM flag. This causes SDL to scan the system
for CD-ROM drives, and load appropriate drivers.
*/
/**
* @file SDL_cdrom.h
* In order to use these functions, SDL_Init() must have been called
* with the SDL_INIT_CDROM flag. This causes SDL to scan the system
* for CD-ROM drives, and load appropriate drivers.
*/
/* The maximum number of CD-ROM tracks on a disk */
/** The maximum number of CD-ROM tracks on a disk */
#define SDL_MAX_TRACKS 99
/* The types of CD-ROM track possible */
/** @name Track Types
* The types of CD-ROM track possible
*/
/*@{*/
#define SDL_AUDIO_TRACK 0x00
#define SDL_DATA_TRACK 0x04
/*@}*/
/* The possible states which a CD-ROM drive can be in. */
/** The possible states which a CD-ROM drive can be in. */
typedef enum {
CD_TRAYEMPTY,
CD_STOPPED,
......@@ -55,30 +64,35 @@ typedef enum {
CD_ERROR = -1
} CDstatus;
/* Given a status, returns true if there's a disk in the drive */
/** Given a status, returns true if there's a disk in the drive */
#define CD_INDRIVE(status) ((int)(status) > 0)
typedef struct SDL_CDtrack {
Uint8 id; /* Track number */
Uint8 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; \
......@@ -89,76 +103,93 @@ typedef struct SDL_CD {
*(M) = value; \
}
#define MSF_TO_FRAMES(M, S, F) ((M)*60*CD_FPS+(S)*CD_FPS+(F))
/*@}*/
/* CD-audio API functions: */
/* Returns the number of CD-ROM drives on the system, or -1 if
SDL_Init() has not been called with the SDL_INIT_CDROM flag.
/**
* Returns the number of CD-ROM drives on the system, or -1 if
* SDL_Init() has not been called with the SDL_INIT_CDROM flag.
*/
extern DECLSPEC int SDLCALL SDL_CDNumDrives(void);
/* Returns a human-readable, system-dependent identifier for the CD-ROM.
Example:
"/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);
......
include/SDL_cpuinfo.h
View file @ 1106b669
......@@ -20,8 +20,10 @@
slouken@libsdl.org
*/
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/* CPU feature detection for SDL */
/**
* @file SDL_cpuinfo.h
* CPU feature detection for SDL
*/
#ifndef _SDL_cpuinfo_h
#define _SDL_cpuinfo_h
......@@ -34,36 +36,28 @@
extern "C" {
#endif
/* This function returns true if the CPU has the RDTSC instruction
*/
/** This function returns true if the CPU has the RDTSC instruction */
extern DECLSPEC SDL_bool SDLCALL SDL_HasRDTSC(void);
/* This function returns true if the CPU has MMX features
*/
/** This function returns true if the CPU has MMX features */
extern DECLSPEC SDL_bool SDLCALL SDL_HasMMX(void);
/* This function returns true if the CPU has MMX Ext. features
*/
/** This function returns true if the CPU has MMX Ext. features */
extern DECLSPEC SDL_bool SDLCALL SDL_HasMMXExt(void);
/* This function returns true if the CPU has 3DNow features
*/
/** This function returns true if the CPU has 3DNow features */
extern DECLSPEC SDL_bool SDLCALL SDL_Has3DNow(void);
/* This function returns true if the CPU has 3DNow! Ext. features
*/
/** This function returns true if the CPU has 3DNow! Ext. features */
extern DECLSPEC SDL_bool SDLCALL SDL_Has3DNowExt(void);
/* This function returns true if the CPU has SSE features
*/
/** This function returns true if the CPU has SSE features */
extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE(void);
/* This function returns true if the CPU has SSE2 features
*/
/** This function returns true if the CPU has SSE2 features */
extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE2(void);
/* This function returns true if the CPU has AltiVec features
*/
/** This function returns true if the CPU has AltiVec features */
extern DECLSPEC SDL_bool SDLCALL SDL_HasAltiVec(void);
/* Ends C function definitions when using C++ */
......
include/SDL_endian.h
View file @ 1106b669
......@@ -20,16 +20,23 @@
slouken@libsdl.org
*/
/* Functions for reading and writing endian-specific values */
/**
* @file SDL_endian.h
* Functions for reading and writing endian-specific values
*/
#ifndef _SDL_endian_h
#define _SDL_endian_h
#include "SDL_stdinc.h"
/* The two types of endianness */
/** @name SDL_ENDIANs
* The two types of endianness
*/
/*@{*/
#define SDL_LIL_ENDIAN 1234
#define SDL_BIG_ENDIAN 4321
/*@}*/
#ifndef SDL_BYTEORDER /* Not defined in SDL_config.h? */
#if defined(__hppa__) || \
......@@ -50,11 +57,14 @@
extern "C" {
#endif
/* Use inline functions for compilers that support them, and static
functions for those that do not. Because these functions become
static for compilers that do not support inline functions, this
header should only be included in files that actually use them.
*/
/**
* @name SDL_Swap Functions
* Use inline functions for compilers that support them, and static
* functions for those that do not. Because these functions become
* static for compilers that do not support inline functions, this
* header should only be included in files that actually use them.
*/
/*@{*/
#if defined(__GNUC__) && defined(__i386__) && \
!(__GNUC__ == 2 && __GNUC_MINOR__ <= 95 /* broken gcc version */)
static __inline__ Uint16 SDL_Swap16(Uint16 x)
......@@ -161,14 +171,18 @@ static __inline__ Uint64 SDL_Swap64(Uint64 x)
#endif
#else
/* This is mainly to keep compilers from complaining in SDL code.
If there is no real 64-bit datatype, then compilers will complain about
the fake 64-bit datatype that SDL provides when it compiles user code.
*/
* If there is no real 64-bit datatype, then compilers will complain about
* the fake 64-bit datatype that SDL provides when it compiles user code.
*/
#define SDL_Swap64(X) (X)
#endif /* SDL_HAS_64BIT_TYPE */
/*@}*/
/* Byteswap item from the specified endianness to the native endianness */
/**
* @name SDL_SwapLE and SDL_SwapBE Functions
* Byteswap item from the specified endianness to the native endianness
*/
/*@{*/
#if SDL_BYTEORDER == SDL_LIL_ENDIAN
#define SDL_SwapLE16(X) (X)
#define SDL_SwapLE32(X) (X)
......@@ -184,6 +198,7 @@ static __inline__ Uint64 SDL_Swap64(Uint64 x)
#define SDL_SwapBE32(X) (X)
#define SDL_SwapBE64(X) (X)
#endif
/*@}*/
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
......
include/SDL_error.h
View file @ 1106b669
......@@ -20,7 +20,10 @@
slouken@libsdl.org
*/
/* Simple error message routines for SDL */
/**
* @file SDL_error.h
* Simple error message routines for SDL
*/
#ifndef _SDL_error_h
#define _SDL_error_h
......@@ -33,12 +36,20 @@
extern "C" {
#endif
/* Public functions */
/**
* @name Public functions
*/
/*@{*/
extern DECLSPEC void SDLCALL SDL_SetError(const char *fmt, ...);
extern DECLSPEC char * SDLCALL SDL_GetError(void);
extern DECLSPEC void SDLCALL SDL_ClearError(void);
/*@}*/
/* Private error message function - used internally */
/**
* @name Private functions
* @internal Private error message function - used internally
*/
/*@{*/
#define SDL_OutOfMemory() SDL_Error(SDL_ENOMEM)
#define SDL_Unsupported() SDL_Error(SDL_UNSUPPORTED)
typedef enum {
......@@ -50,7 +61,7 @@ typedef enum {
SDL_LASTERROR
} SDL_errorcode;
extern DECLSPEC void SDLCALL SDL_Error(SDL_errorcode code);
/*@}*/
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
......
include/SDL_events.h
View file @ 1106b669
This diff is collapsed.
include/SDL_getenv.h
View file @ 1106b669
......@@ -20,5 +20,9 @@
slouken@libsdl.org
*/
/** @file SDL_getenv.h
* @deprecated Use SDL_stdinc.h instead
*/
/* DEPRECATED */
#include "SDL_stdinc.h"
include/SDL_joystick.h
View file @ 1106b669
......@@ -20,7 +20,9 @@
slouken@libsdl.org
*/
/* Include file for SDL joystick event handling */
/** @file SDL_joystick.h
* Include file for SDL joystick event handling
*/
#ifndef _SDL_joystick_h
#define _SDL_joystick_h
......@@ -34,97 +36,108 @@
extern "C" {
#endif
/* In order to use these functions, SDL_Init() must have been called
with the SDL_INIT_JOYSTICK flag. This causes SDL to scan the system
for joysticks, and load appropriate drivers.
*/
/** @file SDL_joystick.h
* @note In order to use these functions, SDL_Init() must have been called
* with the SDL_INIT_JOYSTICK flag. This causes SDL to scan the system
* for joysticks, and load appropriate drivers.
*/
/* The joystick structure used to identify an SDL joystick */
/** The joystick structure used to identify an SDL joystick */
struct _SDL_Joystick;
typedef struct _SDL_Joystick SDL_Joystick;
/* Function prototypes */
/*
/**
* Count the number of joysticks attached to the system
*/
extern DECLSPEC int SDLCALL SDL_NumJoysticks(void);
/*
/**
* Get the implementation dependent name of a joystick.
*
* This can be called before any joysticks are opened.
* If no name can be found, this function returns NULL.
*/
extern DECLSPEC const char * SDLCALL SDL_JoystickName(int device_index);
/*
* Open a joystick for use - the index passed as an argument refers to
/**
* Open a joystick for use.
*
* @param[in] device_index
* The index passed as an argument refers to
* the N'th joystick on the system. This index is the value which will
* identify this joystick in future joystick events.
*
* This function returns a joystick identifier, or NULL if an error occurred.
* @return This function returns a joystick identifier, or NULL if an error occurred.
*/
extern DECLSPEC SDL_Joystick * SDLCALL SDL_JoystickOpen(int device_index);
/*
/**
* Returns 1 if the joystick has been opened, or 0 if it has not.
*/
extern DECLSPEC int SDLCALL SDL_JoystickOpened(int device_index);
/*
/**
* Get the device index of an opened joystick.
*/
extern DECLSPEC int SDLCALL SDL_JoystickIndex(SDL_Joystick *joystick);
/*
/**
* Get the number of general axis controls on a joystick
*/
extern DECLSPEC int SDLCALL SDL_JoystickNumAxes(SDL_Joystick *joystick);
/*
/**
* Get the number of trackballs on a joystick
*
* Joystick trackballs have only relative motion events associated
* with them and their state cannot be polled.
*/
extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(SDL_Joystick *joystick);
/*
/**
* Get the number of POV hats on a joystick
*/
extern DECLSPEC int SDLCALL SDL_JoystickNumHats(SDL_Joystick *joystick);
/*
/**
* Get the number of buttons on a joystick
*/
extern DECLSPEC int SDLCALL SDL_JoystickNumButtons(SDL_Joystick *joystick);
/*
/**
* Update the current state of the open joysticks.
*
* This is called automatically by the event loop if any joystick
* events are enabled.
*/
extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void);
/*
/**
* Enable/disable joystick event polling.
*
* If joystick events are disabled, you must call SDL_JoystickUpdate()
* yourself and check the state of the joystick when you want joystick
* information.
* The state can be one of SDL_QUERY, SDL_ENABLE or SDL_IGNORE.
*
* @param[in] state The state can be one of SDL_QUERY, SDL_ENABLE or SDL_IGNORE.
*/
extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state);
/*
/**
* Get the current state of an axis control on a joystick
* The state is a value ranging from -32768 to 32767.
* The axis indices start at index 0.
*
* @param[in] axis The axis indices start at index 0.
*
* @return The state is a value ranging from -32768 to 32767.
*/
extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick *joystick, int axis);
/*
* Get the current state of a POV hat on a joystick
* The return value is one of the following positions:
/**
* @name Hat Positions
* The return value of SDL_JoystickGetHat() is one of the following positions:
*/
/*@{*/
#define SDL_HAT_CENTERED 0x00
#define SDL_HAT_UP 0x01
#define SDL_HAT_RIGHT 0x02
......@@ -134,25 +147,32 @@ extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick *joystick, int a
#define SDL_HAT_RIGHTDOWN (SDL_HAT_RIGHT|SDL_HAT_DOWN)
#define SDL_HAT_LEFTUP (SDL_HAT_LEFT|SDL_HAT_UP)
#define SDL_HAT_LEFTDOWN (SDL_HAT_LEFT|SDL_HAT_DOWN)
/*
* The hat indices start at index 0.
/*@}*/
/**
* Get the current state of a POV hat on a joystick
*
* @param[in] hat The hat indices start at index 0.
*/
extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick *joystick, int hat);
/*
/**
* Get the ball axis change since the last poll
* This returns 0, or -1 if you passed it invalid parameters.
* The ball indices start at index 0.
*
* @param[in] ball The ball indices start at index 0.
*
* @return This returns 0, or -1 if you passed it invalid parameters.
*/
extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick *joystick, int ball, int *dx, int *dy);
/*
/**
* Get the current state of a button on a joystick
* The button indices start at index 0.
*
* @param[in] button The button indices start at index 0.
*/
extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick *joystick, int button);
/*
/**
* Close a joystick previously opened with SDL_JoystickOpen()
*/
extern DECLSPEC void SDLCALL SDL_JoystickClose(SDL_Joystick *joystick);
......
include/SDL_keyboard.h
View file @ 1106b669
......@@ -20,7 +20,9 @@
slouken@libsdl.org
*/
/* Include file for SDL keyboard event handling */
/** @file SDL_keyboard.h
* Include file for SDL keyboard event handling
*/
#ifndef _SDL_keyboard_h
#define _SDL_keyboard_h
......@@ -35,78 +37,90 @@
extern "C" {
#endif
/* Keysym structure
- The scancode is hardware dependent, and should not be used by general
applications. If no hardware scancode is available, it will be 0.
- The 'unicode' translated character is only available when character
translation is enabled by the SDL_EnableUNICODE() API. If non-zero,
this is a UNICODE character corresponding to the keypress. If the
high 9 bits of the character are 0, then this maps to the equivalent
ASCII character:
char ch;
if ( (keysym.unicode & 0xFF80) == 0 ) {
ch = keysym.unicode & 0x7F;
} else {
An international character..
}
/** Keysym structure
*
* - The scancode is hardware dependent, and should not be used by general
* applications. If no hardware scancode is available, it will be 0.
*
* - The 'unicode' translated character is only available when character
* translation is enabled by the SDL_EnableUNICODE() API. If non-zero,
* this is a UNICODE character corresponding to the keypress. If the
* high 9 bits of the character are 0, then this maps to the equivalent
* ASCII character:
* @code
* char ch;
* if ( (keysym.unicode & 0xFF80) == 0 ) {
* ch = keysym.unicode & 0x7F;
* } else {
* An international character..
* }
* @endcode
*/
typedef struct SDL_keysym {
Uint8 scancode; /* hardware specific scancode */
SDLKey sym; /* SDL virtual keysym */
SDLMod mod; /* current key modifiers */
Uint16 unicode; /* translated character */
Uint8 scancode; /**< hardware specific scancode */
SDLKey sym; /**< SDL virtual keysym */
SDLMod mod; /**< current key modifiers */
Uint16 unicode; /**< translated character */
} SDL_keysym;
/* This is the mask which refers to all hotkey bindings */
/** This is the mask which refers to all hotkey bindings */
#define SDL_ALL_HOTKEYS 0xFFFFFFFF
/* Function prototypes */
/*
/**
* Enable/Disable UNICODE translation of keyboard input.
*
* This translation has some overhead, so translation defaults off.
*
* @param[in] enable
* If 'enable' is 1, translation is enabled.
* If 'enable' is 0, translation is disabled.
* If 'enable' is -1, the translation state is not changed.
* It returns the previous state of keyboard translation.
*
* @return It returns the previous state of keyboard translation.
*/
extern DECLSPEC int SDLCALL SDL_EnableUNICODE(int enable);
/*
* Enable/Disable keyboard repeat. Keyboard repeat defaults to off.
* 'delay' is the initial delay in ms between the time when a key is
* pressed, and keyboard repeat begins.
* 'interval' is the time in ms between keyboard repeat events.
*/
#define SDL_DEFAULT_REPEAT_DELAY 500
#define SDL_DEFAULT_REPEAT_INTERVAL 30
/*
* If 'delay' is set to 0, keyboard repeat is disabled.
/**
* Enable/Disable keyboard repeat. Keyboard repeat defaults to off.
*
* @param[in] delay
* 'delay' is the initial delay in ms between the time when a key is
* pressed, and keyboard repeat begins.
*
* @param[in] interval
* 'interval' is the time in ms between keyboard repeat events.
*
* If 'delay' is set to 0, keyboard repeat is disabled.
*/
extern DECLSPEC int SDLCALL SDL_EnableKeyRepeat(int delay, int interval);
extern DECLSPEC void SDLCALL SDL_GetKeyRepeat(int *delay, int *interval);
/*
/**
* Get a snapshot of the current state of the keyboard.
* Returns an array of keystates, indexed by the SDLK_* syms.
* Used:
* Usage:
* @code
* Uint8 *keystate = SDL_GetKeyState(NULL);
* if ( keystate[SDLK_RETURN] ) ... <RETURN> is pressed.
* if ( keystate[SDLK_RETURN] ) //... \<RETURN> is pressed.
* @endcode
*/
extern DECLSPEC Uint8 * SDLCALL SDL_GetKeyState(int *numkeys);
/*
/**
* Get the current key modifier state
*/
extern DECLSPEC SDLMod SDLCALL SDL_GetModState(void);
/*
* Set the current key modifier state
/**
* Set the current key modifier state.
* This does not change the keyboard state, only the key modifier flags.
*/
extern DECLSPEC void SDLCALL SDL_SetModState(SDLMod modstate);
/*
/**
* Get the name of an SDL virtual keysym
*/
extern DECLSPEC char * SDLCALL SDL_GetKeyName(SDLKey key);
......
include/SDL_keysym.h
View file @ 1106b669
......@@ -23,14 +23,16 @@
#ifndef _SDL_keysym_h
#define _SDL_keysym_h
/* What we really want is a mapping of every raw key on the keyboard.
To support international keyboards, we use the range 0xA1 - 0xFF
as international virtual keycodes. We'll follow in the footsteps of X11...
The names of the keys
/** What we really want is a mapping of every raw key on the keyboard.
* To support international keyboards, we use the range 0xA1 - 0xFF
* as international virtual keycodes. We'll follow in the footsteps of X11...
* @brief The names of the keys
*/
typedef enum {
/* The keyboard syms have been cleverly chosen to map to ASCII */
/** @name ASCII mapped keysyms
* The keyboard syms have been cleverly chosen to map to ASCII
*/
/*@{*/
SDLK_UNKNOWN = 0,
SDLK_FIRST = 0,
SDLK_BACKSPACE = 8,
......@@ -108,8 +110,10 @@ typedef enum {
SDLK_z = 122,
SDLK_DELETE = 127,
/* End of ASCII mapped keysyms */
/*@}*/
/* International keyboard syms */
/** @name International keyboard syms */
/*@{*/
SDLK_WORLD_0 = 160, /* 0xA0 */
SDLK_WORLD_1 = 161,
SDLK_WORLD_2 = 162,
......@@ -206,8 +210,10 @@ typedef enum {
SDLK_WORLD_93 = 253,
SDLK_WORLD_94 = 254,
SDLK_WORLD_95 = 255, /* 0xFF */
/*@}*/
/* Numeric keypad */
/** @name Numeric keypad */
/*@{*/
SDLK_KP0 = 256,
SDLK_KP1 = 257,
SDLK_KP2 = 258,
......@@ -225,8 +231,10 @@ typedef enum {
SDLK_KP_PLUS = 270,
SDLK_KP_ENTER = 271,
SDLK_KP_EQUALS = 272,
/*@}*/
/* Arrows + Home/End pad */
/** @name Arrows + Home/End pad */
/*@{*/
SDLK_UP = 273,
SDLK_DOWN = 274,
SDLK_RIGHT = 275,
......@@ -236,8 +244,10 @@ typedef enum {
SDLK_END = 279,
SDLK_PAGEUP = 280,
SDLK_PAGEDOWN = 281,
/*@}*/
/* Function keys */
/** @name Function keys */
/*@{*/
SDLK_F1 = 282,
SDLK_F2 = 283,
SDLK_F3 = 284,
......@@ -253,8 +263,10 @@ typedef enum {
SDLK_F13 = 294,
SDLK_F14 = 295,
SDLK_F15 = 296,
/*@}*/
/* Key state modifier keys */
/** @name Key state modifier keys */
/*@{*/
SDLK_NUMLOCK = 300,
SDLK_CAPSLOCK = 301,
SDLK_SCROLLOCK = 302,
......@@ -266,27 +278,30 @@ typedef enum {
SDLK_LALT = 308,
SDLK_RMETA = 309,
SDLK_LMETA = 310,
SDLK_LSUPER = 311, /* Left "Windows" key */
SDLK_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,
......
include/SDL_loadso.h
View file @ 1106b669
......@@ -20,22 +20,24 @@
slouken@libsdl.org
*/
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/* System dependent library loading routines */
/** @file SDL_loadso.h
* System dependent library loading routines
*/
/* Some things to keep in mind:
- These functions only work on C function names. Other languages may
have name mangling and intrinsic language support that varies from
compiler to compiler.
- Make sure you declare your function pointers with the same calling
convention as the actual library function. Your code will crash
mysteriously if you do not do this.
- Avoid namespace collisions. If you load a symbol from the library,
it is not defined whether or not it goes into the global symbol
namespace for the application. If it does and it conflicts with
symbols in your code or other shared libraries, you will not get
the results you expect. :)
*/
/** @file SDL_loadso.h
* Some things to keep in mind:
* - These functions only work on C function names. Other languages may
* have name mangling and intrinsic language support that varies from
* compiler to compiler.
* - Make sure you declare your function pointers with the same calling
* convention as the actual library function. Your code will crash
* mysteriously if you do not do this.
* - Avoid namespace collisions. If you load a symbol from the library,
* it is not defined whether or not it goes into the global symbol
* namespace for the application. If it does and it conflicts with
* symbols in your code or other shared libraries, you will not get
* the results you expect. :)
*/
#ifndef _SDL_loadso_h
......@@ -50,19 +52,21 @@
extern "C" {
#endif
/* This function dynamically loads a shared object and returns a pointer
/**
* This function dynamically loads a shared object and returns a pointer
* to the object handle (or NULL if there was an error).
* The 'sofile' parameter is a system dependent name of the object file.
*/
extern DECLSPEC void * SDLCALL SDL_LoadObject(const char *sofile);
/* Given an object handle, this function looks up the address of the
/**
* Given an object handle, this function looks up the address of the
* named function in the shared object and returns it. This address
* is no longer valid after calling SDL_UnloadObject().
*/
extern DECLSPEC void * SDLCALL SDL_LoadFunction(void *handle, const char *name);
/* Unload a shared object from memory */
/** Unload a shared object from memory */
extern DECLSPEC void SDLCALL SDL_UnloadObject(void *handle);
/* Ends C function definitions when using C++ */
......
include/SDL_main.h
View file @ 1106b669
......@@ -25,7 +25,9 @@
#include "SDL_stdinc.h"
/* Redefine main() on Win32 and MacOS so that it is called by winmain.c */
/** @file SDL_main.h
* Redefine main() on Win32 and MacOS so that it is called by winmain.c
*/
#if defined(__WIN32__) || \
(defined(__MWERKS__) && !defined(__BEOS__)) || \
......@@ -38,22 +40,25 @@
#define C_LINKAGE
#endif /* __cplusplus */
/* The application's main() function must be called with C linkage,
and should be declared like this:
#ifdef __cplusplus
extern "C"
#endif
int main(int argc, char *argv[])
{
}
/** The application's main() function must be called with C linkage,
* and should be declared like this:
* @code
* #ifdef __cplusplus
* extern "C"
* #endif
* int main(int argc, char *argv[])
* {
* }
* @endcode
*/
#define main SDL_main
/* The prototype for the application's main() function */
/** The prototype for the application's main() function */
extern C_LINKAGE int SDL_main(int argc, char *argv[]);
/* From the SDL library code -- needed for registering the app on Win32 */
/** @name From the SDL library code -- needed for registering the app on Win32 */
/*@{*/
#ifdef __WIN32__
#include "begin_code.h"
......@@ -61,19 +66,21 @@ extern C_LINKAGE int SDL_main(int argc, char *argv[]);
extern "C" {
#endif
/* This should be called from your WinMain() function, if any */
/** This should be called from your WinMain() function, if any */
extern DECLSPEC void SDLCALL SDL_SetModuleHandle(void *hInst);
/* This can also be called, but is no longer necessary */
/** This can also be called, but is no longer necessary */
extern DECLSPEC int SDLCALL SDL_RegisterApp(char *name, Uint32 style, void *hInst);
/* This can also be called, but is no longer necessary (SDL_Quit calls it) */
/** This can also be called, but is no longer necessary (SDL_Quit calls it) */
extern DECLSPEC void SDLCALL SDL_UnregisterApp(void);
#ifdef __cplusplus
}
#endif
#include "close_code.h"
#endif
/*@}*/
/* From the SDL library code -- needed for registering QuickDraw on MacOS */
/** @name From the SDL library code -- needed for registering QuickDraw on MacOS */
/*@{*/
#if defined(__MACOS__)
#include "begin_code.h"
......@@ -81,10 +88,10 @@ extern DECLSPEC void SDLCALL SDL_UnregisterApp(void);
extern "C" {
#endif
/* Forward declaration so we don't need to include QuickDraw.h */
/** Forward declaration so we don't need to include QuickDraw.h */
struct QDGlobals;
/* This should be called from your main() function, if any */
/** This should be called from your main() function, if any */
extern DECLSPEC void SDLCALL SDL_InitQuickDraw(struct QDGlobals *the_qd);
#ifdef __cplusplus
......@@ -92,6 +99,7 @@ extern DECLSPEC void SDLCALL SDL_InitQuickDraw(struct QDGlobals *the_qd);
#endif
#include "close_code.h"
#endif
/*@}*/
#endif /* Need to redefine main()? */
......
include/SDL_mouse.h
View file @ 1106b669
......@@ -20,7 +20,9 @@
slouken@libsdl.org
*/
/* Include file for SDL mouse event handling */
/** @file SDL_mouse.h
* Include file for SDL mouse event handling
*/
#ifndef _SDL_mouse_h
#define _SDL_mouse_h
......@@ -35,18 +37,18 @@
extern "C" {
#endif
typedef struct WMcursor WMcursor; /* Implementation dependent */
typedef struct WMcursor WMcursor; /**< Implementation dependent */
typedef struct SDL_Cursor {
SDL_Rect area; /* The area of the mouse cursor */
Sint16 hot_x, hot_y; /* The "tip" of the cursor */
Uint8 *data; /* B/W cursor data */
Uint8 *mask; /* B/W cursor mask */
Uint8 *save[2]; /* Place to save cursor area */
WMcursor *wm_cursor; /* Window-manager cursor */
SDL_Rect area; /**< The area of the mouse cursor */
Sint16 hot_x, hot_y; /**< The "tip" of the cursor */
Uint8 *data; /**< B/W cursor data */
Uint8 *mask; /**< B/W cursor mask */
Uint8 *save[2]; /**< Place to save cursor area */
WMcursor *wm_cursor; /**< Window-manager cursor */
} SDL_Cursor;
/* Function prototypes */
/*
/**
* Retrieve the current state of the mouse.
* The current button state is returned as a button bitmask, which can
* be tested using the SDL_BUTTON(X) macros, and x and y are set to the
......@@ -54,7 +56,7 @@ typedef struct SDL_Cursor {
*/
extern DECLSPEC Uint8 SDLCALL SDL_GetMouseState(int *x, int *y);
/*
/**
* Retrieve the current state of the mouse.
* The current button state is returned as a button bitmask, which can
* be tested using the SDL_BUTTON(X) macros, and x and y are set to the
......@@ -62,12 +64,12 @@ extern DECLSPEC Uint8 SDLCALL SDL_GetMouseState(int *x, int *y);
*/
extern DECLSPEC Uint8 SDLCALL SDL_GetRelativeMouseState(int *x, int *y);
/*
/**
* Set the position of the mouse cursor (generates a mouse motion event)
*/
extern DECLSPEC void SDLCALL SDL_WarpMouse(Uint16 x, Uint16 y);
/*
/**
* Create a cursor using the specified data and mask (in MSB format).
* The cursor width must be a multiple of 8 bits.
*
......@@ -83,24 +85,24 @@ extern DECLSPEC void SDLCALL SDL_WarpMouse(Uint16 x, Uint16 y);
extern DECLSPEC SDL_Cursor * SDLCALL SDL_CreateCursor
(Uint8 *data, Uint8 *mask, int w, int h, int hot_x, int hot_y);
/*
/**
* Set the currently active cursor to the specified one.
* If the cursor is currently visible, the change will be immediately
* represented on the display.
*/
extern DECLSPEC void SDLCALL SDL_SetCursor(SDL_Cursor *cursor);
/*
/**
* Returns the currently active cursor.
*/
extern DECLSPEC SDL_Cursor * SDLCALL SDL_GetCursor(void);
/*
/**
* Deallocates a cursor created with SDL_CreateCursor().
*/
extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor *cursor);
/*
/**
* Toggle whether or not the cursor is shown on the screen.
* The cursor start off displayed, but can be turned off.
* SDL_ShowCursor() returns 1 if the cursor was being displayed
......@@ -109,12 +111,13 @@ extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor *cursor);
*/
extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
/* Used as a mask when testing buttons in buttonstate
Button 1: Left mouse button
Button 2: Middle mouse button
Button 3: Right mouse button
Button 4: Mouse wheel up (may also be a real button)
Button 5: Mouse wheel down (may also be a real button)
/*@{*/
/** Used as a mask when testing buttons in buttonstate
* Button 1: Left mouse button
* Button 2: Middle mouse button
* Button 3: Right mouse button
* Button 4: Mouse wheel up (may also be a real button)
* Button 5: Mouse wheel down (may also be a real button)
*/
#define SDL_BUTTON(X) (1 << ((X)-1))
#define SDL_BUTTON_LEFT 1
......@@ -129,7 +132,7 @@ extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
#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
......
include/SDL_mutex.h
View file @ 1106b669
......@@ -23,10 +23,11 @@
#ifndef _SDL_mutex_h
#define _SDL_mutex_h
/* Functions to provide thread synchronization primitives
These are independent of the other SDL routines.
*/
/** @file SDL_mutex.h
* Functions to provide thread synchronization primitives
*
* @note These are independent of the other SDL routines.
*/
#include "SDL_stdinc.h"
#include "SDL_error.h"
......@@ -37,122 +38,135 @@
extern "C" {
#endif
/* Synchronization functions which can time out return this value
if they time out.
*/
/** Synchronization functions which can time out return this value
* if they time out.
*/
#define SDL_MUTEX_TIMEDOUT 1
/* This is the timeout value which corresponds to never time out */
/** This is the timeout value which corresponds to never time out */
#define SDL_MUTEX_MAXWAIT (~(Uint32)0)
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/* Mutex functions */
/** @name Mutex functions */ /*@{*/
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/* The SDL mutex structure, defined in SDL_mutex.c */
/** The SDL mutex structure, defined in SDL_mutex.c */
struct SDL_mutex;
typedef struct SDL_mutex SDL_mutex;
/* Create a mutex, initialized unlocked */
/** Create a mutex, initialized unlocked */
extern DECLSPEC SDL_mutex * SDLCALL SDL_CreateMutex(void);
/* Lock the mutex (Returns 0, or -1 on error) */
#define SDL_LockMutex(m) SDL_mutexP(m)
/** Lock the mutex
* @return 0, or -1 on error
*/
extern DECLSPEC int SDLCALL SDL_mutexP(SDL_mutex *mutex);
/* Unlock the mutex (Returns 0, or -1 on error)
It is an error to unlock a mutex that has not been locked by
the current thread, and doing so results in undefined behavior.
*/
#define SDL_UnlockMutex(m) SDL_mutexV(m)
/** Unlock the mutex
* @return 0, or -1 on error
*
* It is an error to unlock a mutex that has not been locked by
* the current thread, and doing so results in undefined behavior.
*/
extern DECLSPEC int SDLCALL SDL_mutexV(SDL_mutex *mutex);
/* Destroy a mutex */
/** Destroy a mutex */
extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex *mutex);
/*@}*/
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/* Semaphore functions */
/** @name Semaphore functions */ /*@{*/
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/* The SDL semaphore structure, defined in SDL_sem.c */
/** The SDL semaphore structure, defined in SDL_sem.c */
struct SDL_semaphore;
typedef struct SDL_semaphore SDL_sem;
/* Create a semaphore, initialized with value, returns NULL on failure. */
/** Create a semaphore, initialized with value, returns NULL on failure. */
extern DECLSPEC SDL_sem * SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
/* Destroy a semaphore */
/** Destroy a semaphore */
extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem *sem);
/* This function suspends the calling thread until the semaphore pointed
/**
* This function suspends the calling thread until the semaphore pointed
* to by sem has a positive count. It then atomically decreases the semaphore
* count.
*/
extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem *sem);
/* Non-blocking variant of SDL_SemWait(), returns 0 if the wait succeeds,
SDL_MUTEX_TIMEDOUT if the wait would block, and -1 on error.
*/
/** Non-blocking variant of SDL_SemWait().
* @return 0 if the wait succeeds,
* SDL_MUTEX_TIMEDOUT if the wait would block, and -1 on error.
*/
extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem *sem);
/* Variant of SDL_SemWait() with a timeout in milliseconds, returns 0 if
the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait does not succeed in
the allotted time, and -1 on error.
On some platforms this function is implemented by looping with a delay
of 1 ms, and so should be avoided if possible.
*/
/** Variant of SDL_SemWait() with a timeout in milliseconds, returns 0 if
* the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait does not succeed in
* the allotted time, and -1 on error.
*
* On some platforms this function is implemented by looping with a delay
* of 1 ms, and so should be avoided if possible.
*/
extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem *sem, Uint32 ms);
/* Atomically increases the semaphore's count (not blocking), returns 0,
or -1 on error.
/** Atomically increases the semaphore's count (not blocking).
* @return 0, or -1 on error.
*/
extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem *sem);
/* Returns the current count of the semaphore */
/** Returns the current count of the semaphore */
extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem *sem);
/*@}*/
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/* Condition variable functions */
/** @name Condition_variable_functions */ /*@{*/
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/* The SDL condition variable structure, defined in SDL_cond.c */
/*@{*/
/** The SDL condition variable structure, defined in SDL_cond.c */
struct SDL_cond;
typedef struct SDL_cond SDL_cond;
/*@}*/
/* Create a condition variable */
/** Create a condition variable */
extern DECLSPEC SDL_cond * SDLCALL SDL_CreateCond(void);
/* Destroy a condition variable */
/** Destroy a condition variable */
extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond *cond);
/* Restart one of the threads that are waiting on the condition variable,
returns 0 or -1 on error.
/** Restart one of the threads that are waiting on the condition variable,
* @return 0 or -1 on error.
*/
extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond *cond);
/* Restart all threads that are waiting on the condition variable,
returns 0 or -1 on error.
/** Restart all threads that are waiting on the condition variable,
* @return 0 or -1 on error.
*/
extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond *cond);
/* Wait on the condition variable, unlocking the provided mutex.
The mutex must be locked before entering this function!
The mutex is re-locked once the condition variable is signaled.
Returns 0 when it is signaled, or -1 on error.
/** Wait on the condition variable, unlocking the provided mutex.
* The mutex must be locked before entering this function!
* The mutex is re-locked once the condition variable is signaled.
* @return 0 when it is signaled, or -1 on error.
*/
extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond *cond, SDL_mutex *mut);
/* Waits for at most 'ms' milliseconds, and returns 0 if the condition
variable is signaled, SDL_MUTEX_TIMEDOUT if the condition is not
signaled in the allotted time, and -1 on error.
On some platforms this function is implemented by looping with a delay
of 1 ms, and so should be avoided if possible.
*/
/** Waits for at most 'ms' milliseconds, and returns 0 if the condition
* variable is signaled, SDL_MUTEX_TIMEDOUT if the condition is not
* signaled in the allotted time, and -1 on error.
* On some platforms this function is implemented by looping with a delay
* of 1 ms, and so should be avoided if possible.
*/
extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond *cond, SDL_mutex *mutex, Uint32 ms);
/*@}*/
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}
......@@ -160,3 +174,4 @@ extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond *cond, SDL_mutex *mutex
#include "close_code.h"
#endif /* _SDL_mutex_h */
include/SDL_opengl.h
View file @ 1106b669
......@@ -20,7 +20,9 @@
slouken@libsdl.org
*/
/* This is a simple file to encapsulate the OpenGL API headers */
/** @file SDL_opengl.h
* This is a simple file to encapsulate the OpenGL API headers
*/
#include "SDL_config.h"
......@@ -48,10 +50,12 @@
#undef __glext_h_
#endif
/* This file taken from "GLext.h" from the Jeff Molofee OpenGL tutorials.
It is included here because glext.h is not available on some systems.
If you don't want this version included, simply define "NO_SDL_GLEXT"
/** @name GLext.h
* This file taken from "GLext.h" from the Jeff Molofee OpenGL tutorials.
* It is included here because glext.h is not available on some systems.
* If you don't want this version included, simply define "NO_SDL_GLEXT"
*/
/*@{*/
#ifndef NO_SDL_GLEXT
#if !defined(__glext_h_) && !defined(GL_GLEXT_LEGACY)
#define __glext_h_
......@@ -6549,3 +6553,4 @@ typedef void (APIENTRYP PFNGLSTRINGMARKERGREMEDYPROC) (GLsizei len, const GLvoid
#endif
#endif /* NO_SDL_GLEXT */
/*@}*/
\ No newline at end of file
include/SDL_platform.h
View file @ 1106b669
......@@ -20,7 +20,9 @@
slouken@libsdl.org
*/
/* Try to get a standard set of platform defines */
/** @file SDL_platform.h
* Try to get a standard set of platform defines
*/
#ifndef _SDL_platform_h
#define _SDL_platform_h
......
include/SDL_quit.h
View file @ 1106b669
......@@ -20,7 +20,9 @@
slouken@libsdl.org
*/
/* Include file for SDL quit event handling */
/** @file SDL_quit.h
* Include file for SDL quit event handling
*/
#ifndef _SDL_quit_h
#define _SDL_quit_h
......@@ -28,22 +30,25 @@
#include "SDL_stdinc.h"
#include "SDL_error.h"
/*
An SDL_QUITEVENT is generated when the user tries to close the application
window. If it is ignored or filtered out, the window will remain open.
If it is not ignored or filtered, it is queued normally and the window
is allowed to close. When the window is closed, screen updates will
complete, but have no effect.
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))
......
include/SDL_rwops.h
View file @ 1106b669
......@@ -20,9 +20,10 @@
slouken@libsdl.org
*/
/* This file provides a general interface for SDL to read and write
data sources. It can easily be extended to files, memory, etc.
*/
/** @file SDL_rwops.h
* This file provides a general interface for SDL to read and write
* data sources. It can easily be extended to files, memory, etc.
*/
#ifndef _SDL_rwops_h
#define _SDL_rwops_h
......@@ -36,28 +37,28 @@
extern "C" {
#endif
/* This is the read/write operation structure -- very basic */
/** This is the read/write operation structure -- very basic */
typedef struct SDL_RWops {
/* Seek to 'offset' relative to whence, one of stdio's whence values:
SEEK_SET, SEEK_CUR, SEEK_END
Returns the final offset in the data source.
/** Seek to 'offset' relative to whence, one of stdio's whence values:
* SEEK_SET, SEEK_CUR, SEEK_END
* Returns the final offset in the data source.
*/
int (SDLCALL *seek)(struct SDL_RWops *context, int offset, int whence);
/* Read up to 'maxnum' objects each of size 'size' from the data
source to the area pointed at by 'ptr'.
Returns the number of objects read, or -1 if the read failed.
/** Read up to 'maxnum' objects each of size 'size' from the data
* source to the area pointed at by 'ptr'.
* Returns the number of objects read, or -1 if the read failed.
*/
int (SDLCALL *read)(struct SDL_RWops *context, void *ptr, int size, int maxnum);
/* Write exactly 'num' objects each of size 'objsize' from the area
pointed at by 'ptr' to data source.
Returns 'num', or -1 if the write failed.
/** Write exactly 'num' objects each of size 'objsize' from the area
* pointed at by 'ptr' to data source.
* Returns 'num', or -1 if the write failed.
*/
int (SDLCALL *write)(struct SDL_RWops *context, const void *ptr, int size, int num);
/* Close and free an allocated SDL_FSops structure */
/** Close and free an allocated SDL_FSops structure */
int (SDLCALL *close)(struct SDL_RWops *context);
Uint32 type;
......@@ -92,7 +93,8 @@ typedef struct SDL_RWops {
} SDL_RWops;
/* Functions to create SDL_RWops structures from various data sources */
/** @name Functions to create SDL_RWops structures from various data sources */
/*@{*/
extern DECLSPEC SDL_RWops * SDLCALL SDL_RWFromFile(const char *file, const char *mode);
......@@ -106,34 +108,43 @@ extern DECLSPEC SDL_RWops * SDLCALL SDL_RWFromConstMem(const void *mem, int size
extern DECLSPEC SDL_RWops * SDLCALL SDL_AllocRW(void);
extern DECLSPEC void SDLCALL SDL_FreeRW(SDL_RWops *area);
#define RW_SEEK_SET 0 /* Seek from the beginning of data */
#define RW_SEEK_CUR 1 /* Seek relative to current read point */
#define RW_SEEK_END 2 /* Seek relative to the end of data */
/*@}*/
/** @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
......
include/SDL_stdinc.h
View file @ 1106b669
......@@ -20,7 +20,9 @@
slouken@libsdl.org
*/
/* This is a general header that includes C language support */
/** @file SDL_stdinc.h
* This is a general header that includes C language support
*/
#ifndef _SDL_stdinc_h
#define _SDL_stdinc_h
......@@ -72,11 +74,12 @@
# include <iconv.h>
#endif
/* The number of elements in an array */
/** The number of elements in an array */
#define SDL_arraysize(array) (sizeof(array)/sizeof(array[0]))
#define SDL_TABLESIZE(table) SDL_arraysize(table)
/* Basic data types */
/** @name Basic data types */
/*@{*/
typedef enum SDL_bool {
SDL_FALSE = 0,
SDL_TRUE = 1
......@@ -102,7 +105,10 @@ typedef struct {
} Uint64, Sint64;
#endif
/* Make sure the types really have the right sizes */
/*@}*/
/** @name Make sure the types really have the right sizes */
/*@{*/
#define SDL_COMPILE_TIME_ASSERT(name, x) \
typedef int SDL_dummy_ ## name[(x) * 2 - 1]
......@@ -114,12 +120,14 @@ SDL_COMPILE_TIME_ASSERT(uint32, sizeof(Uint32) == 4);
SDL_COMPILE_TIME_ASSERT(sint32, sizeof(Sint32) == 4);
SDL_COMPILE_TIME_ASSERT(uint64, sizeof(Uint64) == 8);
SDL_COMPILE_TIME_ASSERT(sint64, sizeof(Sint64) == 8);
/* Check to make sure enums are the size of ints, for structure packing.
For both Watcom C/C++ and Borland C/C++ the compiler option that makes
enums having the size of an int must be enabled.
This is "-b" for Borland C/C++ and "-ei" for Watcom C/C++ (v11).
*/
/*@}*/
/** @name Enum Size Check
* Check to make sure enums are the size of ints, for structure packing.
* For both Watcom C/C++ and Borland C/C++ the compiler option that makes
* enums having the size of an int must be enabled.
* This is "-b" for Borland C/C++ and "-ei" for Watcom C/C++ (v11).
*/
/* Enable enums always int in CodeWarrior (for MPW use "-enum int") */
#ifdef __MWERKS__
#pragma enumsalwaysint on
......@@ -132,7 +140,7 @@ typedef enum {
#ifndef __NDS__
SDL_COMPILE_TIME_ASSERT(enum, sizeof(SDL_DUMMY_ENUM) == sizeof(int));
#endif
/*@}*/
#include "begin_code.h"
/* Set up for C function definitions, even when using C++ */
......@@ -565,11 +573,15 @@ extern DECLSPEC int SDLCALL SDL_snprintf(char *text, size_t maxlen, const char *
extern DECLSPEC int SDLCALL SDL_vsnprintf(char *text, size_t maxlen, const char *fmt, va_list ap);
#endif
/* The SDL implementation of iconv() returns these error codes */
/** @name SDL_ICONV Error Codes
* The SDL implementation of iconv() returns these error codes
*/
/*@{*/
#define SDL_ICONV_ERROR (size_t)-1
#define SDL_ICONV_E2BIG (size_t)-2
#define SDL_ICONV_EILSEQ (size_t)-3
#define SDL_ICONV_EINVAL (size_t)-4
/*@}*/
#ifdef HAVE_ICONV
#define SDL_iconv_t iconv_t
......@@ -581,9 +593,9 @@ extern DECLSPEC SDL_iconv_t SDLCALL SDL_iconv_open(const char *tocode, const cha
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)
......
include/SDL_syswm.h
View file @ 1106b669
......@@ -20,7 +20,9 @@
slouken@libsdl.org
*/
/* Include file for SDL custom system window manager hooks */
/** @file SDL_syswm.h
* Include file for SDL custom system window manager hooks
*/
#ifndef _SDL_syswm_h
#define _SDL_syswm_h
......@@ -35,11 +37,12 @@
extern "C" {
#endif
/* Your application has access to a special type of event 'SDL_SYSWMEVENT',
which contains window-manager specific information and arrives whenever
an unhandled window event occurs. This event is ignored by default, but
you can enable it with SDL_EventState()
*/
/** @file SDL_syswm.h
* Your application has access to a special type of event 'SDL_SYSWMEVENT',
* which contains window-manager specific information and arrives whenever
* an unhandled window event occurs. This event is ignored by default, but
* you can enable it with SDL_EventState()
*/
#ifdef SDL_PROTOTYPES_ONLY
struct SDL_SysWMinfo;
typedef struct SDL_SysWMinfo SDL_SysWMinfo;
......@@ -60,12 +63,12 @@ typedef struct SDL_SysWMinfo SDL_SysWMinfo;
#undef Cursor
#endif
/* These are the various supported subsystems under UNIX */
/** These are the various supported subsystems under UNIX */
typedef enum {
SDL_SYSWM_X11
} SDL_SYSWM_TYPE;
/* The UNIX custom event structure */
/** The UNIX custom event structure */
struct SDL_SysWMmsg {
SDL_version version;
SDL_SYSWM_TYPE subsystem;
......@@ -74,32 +77,38 @@ struct SDL_SysWMmsg {
} 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;
......@@ -107,13 +116,13 @@ typedef struct SDL_SysWMinfo {
#elif defined(SDL_VIDEO_DRIVER_NANOX)
#include <microwin/nano-X.h>
/* The generic custom event structure */
/** The generic custom event structure */
struct SDL_SysWMmsg {
SDL_version version;
int data;
};
/* The windows custom window manager information structure */
/** The windows custom window manager information structure */
typedef struct SDL_SysWMinfo {
SDL_version version ;
GR_WINDOW_ID window ; /* The display window */
......@@ -123,50 +132,50 @@ typedef struct SDL_SysWMinfo {
#define WIN32_LEAN_AND_MEAN
#include <windows.h>
/* The windows custom event structure */
/** The windows custom event structure */
struct SDL_SysWMmsg {
SDL_version version;
HWND hwnd; /* The window for the message */
UINT msg; /* The type of message */
WPARAM wParam; /* WORD message parameter */
LPARAM lParam; /* LONG message parameter */
HWND hwnd; /**< The window for the message */
UINT msg; /**< The type of message */
WPARAM wParam; /**< WORD message parameter */
LPARAM lParam; /**< LONG message parameter */
};
/* The windows custom window manager information structure */
/** The windows custom window manager information structure */
typedef struct SDL_SysWMinfo {
SDL_version version;
HWND window; /* The Win32 display window */
HGLRC hglrc; /* The OpenGL context, if any */
HWND window; /**< The Win32 display window */
HGLRC hglrc; /**< The OpenGL context, if any */
} SDL_SysWMinfo;
#elif defined(SDL_VIDEO_DRIVER_RISCOS)
/* RISC OS custom event structure */
/** RISC OS custom event structure */
struct SDL_SysWMmsg {
SDL_version version;
int eventCode; /* The window for the message */
int eventCode; /**< The window for the message */
int pollBlock[64];
};
/* The RISC OS custom window manager information structure */
/** The RISC OS custom window manager information structure */
typedef struct SDL_SysWMinfo {
SDL_version version;
int wimpVersion; /* Wimp version running under */
int taskHandle; /* The RISC OS task handle */
int window; /* The RISC OS display window */
int wimpVersion; /**< Wimp version running under */
int taskHandle; /**< The RISC OS task handle */
int window; /**< The RISC OS display window */
} SDL_SysWMinfo;
#elif defined(SDL_VIDEO_DRIVER_PHOTON)
#include <sys/neutrino.h>
#include <Ph.h>
/* The QNX custom event structure */
/** The QNX custom event structure */
struct SDL_SysWMmsg {
SDL_version version;
int data;
};
/* The QNX custom window manager information structure */
/** The QNX custom window manager information structure */
typedef struct SDL_SysWMinfo {
SDL_version version;
int data;
......@@ -174,13 +183,13 @@ typedef struct SDL_SysWMinfo {
#else
/* The generic custom event structure */
/** The generic custom event structure */
struct SDL_SysWMmsg {
SDL_version version;
int data;
};
/* The generic custom window manager information structure */
/** The generic custom window manager information structure */
typedef struct SDL_SysWMinfo {
SDL_version version;
int data;
......@@ -191,16 +200,18 @@ typedef struct SDL_SysWMinfo {
#endif /* SDL_PROTOTYPES_ONLY */
/* Function prototypes */
/*
/**
* This function gives you custom hooks into the window manager information.
* It fills the structure pointed to by 'info' with custom information and
* returns 1 if the function is implemented. If it's not implemented, or
* the version member of the 'info' structure is invalid, it returns 0.
*
* You typically use this function like this:
* @code
* SDL_SysWMInfo info;
* SDL_VERSION(&info.version);
* if ( SDL_GetWMInfo(&info) ) { ... }
* @endcode
*/
extern DECLSPEC int SDLCALL SDL_GetWMInfo(SDL_SysWMinfo *info);
......
include/SDL_thread.h
View file @ 1106b669
......@@ -23,10 +23,11 @@
#ifndef _SDL_thread_h
#define _SDL_thread_h
/* Header for the SDL thread management routines
These are independent of the other SDL routines.
*/
/** @file SDL_thread.h
* Header for the SDL thread management routines
*
* @note These are independent of the other SDL routines.
*/
#include "SDL_stdinc.h"
#include "SDL_error.h"
......@@ -40,25 +41,25 @@
extern "C" {
#endif
/* The SDL thread structure, defined in SDL_thread.c */
/** The SDL thread structure, defined in SDL_thread.c */
struct SDL_Thread;
typedef struct SDL_Thread SDL_Thread;
/* Create a thread */
/** Create a thread */
#if ((defined(__WIN32__) && !defined(HAVE_LIBC)) || defined(__OS2__)) && !defined(__SYMBIAN32__)
/*
We compile SDL into a DLL on OS/2. This means, that it's the DLL which
creates a new thread for the calling process with the SDL_CreateThread()
API. There is a problem with this, that only the RTL of the SDL.DLL will
be initialized for those threads, and not the RTL of the calling application!
To solve this, we make a little hack here.
We'll always use the caller's _beginthread() and _endthread() APIs to
start a new thread. This way, if it's the SDL.DLL which uses this API,
then the RTL of SDL.DLL will be used to create the new thread, and if it's
the application, then the RTL of the application will be used.
So, in short:
Always use the _beginthread() and _endthread() of the calling runtime library!
*/
/**
* We compile SDL into a DLL on OS/2. This means, that it's the DLL which
* creates a new thread for the calling process with the SDL_CreateThread()
* API. There is a problem with this, that only the RTL of the SDL.DLL will
* be initialized for those threads, and not the RTL of the calling application!
* To solve this, we make a little hack here.
* We'll always use the caller's _beginthread() and _endthread() APIs to
* start a new thread. This way, if it's the SDL.DLL which uses this API,
* then the RTL of SDL.DLL will be used to create the new thread, and if it's
* the application, then the RTL of the application will be used.
* So, in short:
* Always use the _beginthread() and _endthread() of the calling runtime library!
*/
#define SDL_PASSED_BEGINTHREAD_ENDTHREAD
#ifndef _WIN32_WCE
#include <process.h> /* This has _beginthread() and _endthread() defined! */
......@@ -92,21 +93,21 @@ extern DECLSPEC SDL_Thread * SDLCALL SDL_CreateThread(int (SDLCALL *fn)(void *),
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);
......
include/SDL_timer.h
View file @ 1106b669
......@@ -23,7 +23,9 @@
#ifndef _SDL_timer_h
#define _SDL_timer_h
/* Header for the SDL time management routines */
/** @file SDL_timer.h
* Header for the SDL time management routines
*/
#include "SDL_stdinc.h"
#include "SDL_error.h"
......@@ -34,24 +36,26 @@
extern "C" {
#endif
/* This is the OS scheduler timeslice, in milliseconds */
/** This is the OS scheduler timeslice, in milliseconds */
#define SDL_TIMESLICE 10
/* This is the maximum resolution of the SDL timer on all platforms */
#define TIMER_RESOLUTION 10 /* Experimentally determined */
/** This is the maximum resolution of the SDL timer on all platforms */
#define TIMER_RESOLUTION 10 /**< Experimentally determined */
/* Get the number of milliseconds since the SDL library initialization.
/**
* Get the number of milliseconds since the SDL library initialization.
* Note that this value wraps if the program runs for more than ~49 days.
*/
extern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void);
/* Wait a specified number of milliseconds before returning */
/** Wait a specified number of milliseconds before returning */
extern DECLSPEC void SDLCALL SDL_Delay(Uint32 ms);
/* Function prototype for the timer callback function */
/** Function prototype for the timer callback function */
typedef Uint32 (SDLCALL *SDL_TimerCallback)(Uint32 interval);
/* Set a callback to run after the specified number of milliseconds has
/**
* Set a callback to run after the specified number of milliseconds has
* elapsed. The callback function is passed the current timer interval
* and returns the next timer interval. If the returned value is the
* same as the one passed in, the periodic alarm continues, otherwise a
......@@ -68,7 +72,7 @@ typedef Uint32 (SDLCALL *SDL_TimerCallback)(Uint32 interval);
* later on an unloaded system. If you wanted to set a flag signaling
* a frame update at 30 frames per second (every 33 ms), you might set a
* timer for 30 ms:
* SDL_SetTimer((33/10)*10, flag_update);
* @code SDL_SetTimer((33/10)*10, flag_update); @endcode
*
* If you use this function, you need to pass SDL_INIT_TIMER to SDL_Init().
*
......@@ -81,11 +85,14 @@ typedef Uint32 (SDLCALL *SDL_TimerCallback)(Uint32 interval);
*/
extern DECLSPEC int SDLCALL SDL_SetTimer(Uint32 interval, SDL_TimerCallback callback);
/* New timer API, supports multiple timers
/** @name New timer API
* New timer API, supports multiple timers
* Written by Stephane Peter <megastep@lokigames.com>
*/
/*@{*/
/* Function prototype for the new timer callback function.
/**
* Function prototype for the new timer callback function.
* The callback function is passed the current timer interval and returns
* the next timer interval. If the returned value is the same as the one
* passed in, the periodic alarm continues, otherwise a new alarm is
......@@ -93,19 +100,22 @@ extern DECLSPEC int SDLCALL SDL_SetTimer(Uint32 interval, SDL_TimerCallback call
*/
typedef Uint32 (SDLCALL *SDL_NewTimerCallback)(Uint32 interval, void *param);
/* Definition of the timer ID type */
/** Definition of the timer ID type */
typedef struct _SDL_TimerID *SDL_TimerID;
/* Add a new timer to the pool of timers already running.
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
}
......
include/SDL_types.h
View file @ 1106b669
......@@ -20,5 +20,9 @@
slouken@libsdl.org
*/
/** @file SDL_types.h
* @deprecated Use SDL_stdinc.h instead.
*/
/* DEPRECATED */
#include "SDL_stdinc.h"
include/SDL_version.h
View file @ 1106b669
......@@ -20,7 +20,9 @@
slouken@libsdl.org
*/
/* This header defines the current SDL version */
/** @file SDL_version.h
* This header defines the current SDL version
*/
#ifndef _SDL_version_h
#define _SDL_version_h
......@@ -33,11 +35,14 @@
extern "C" {
#endif
/* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL
*/
/** @name Version Number
* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL
*/
/*@{*/
#define SDL_MAJOR_VERSION 1
#define SDL_MINOR_VERSION 2
#define SDL_PATCHLEVEL 14
/*@}*/
typedef struct SDL_version {
Uint8 major;
......@@ -45,7 +50,8 @@ typedef struct SDL_version {
Uint8 patch;
} SDL_version;
/* This macro can be used to fill a version structure with the compile-time
/**
* This macro can be used to fill a version structure with the compile-time
* version of the SDL library.
*/
#define SDL_VERSION(X) \
......@@ -55,24 +61,24 @@ typedef struct SDL_version {
(X)->patch = SDL_PATCHLEVEL; \
}
/* This macro turns the version numbers into a numeric value:
(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);
......
include/SDL_video.h
View file @ 1106b669
This diff is collapsed.
include/begin_code.h
View file @ 1106b669
......@@ -20,18 +20,26 @@
slouken@libsdl.org
*/
/* This file sets things up for C dynamic library function definitions,
static inlined functions, and structures aligned at 4-byte alignment.
If you don't like ugly C preprocessor code, don't look at this file. :)
*/
/**
* @file begin_code.h
* This file sets things up for C dynamic library function definitions,
* static inlined functions, and structures aligned at 4-byte alignment.
* If you don't like ugly C preprocessor code, don't look at this file. :)
*/
/* This shouldn't be nested -- included it around code only. */
/**
* @file begin_code.h
* This shouldn't be nested -- included it around code only.
*/
#ifdef _begin_code_h
#error Nested inclusion of begin_code.h
#endif
#define _begin_code_h
/* Some compilers use a special export keyword */
/**
* @def DECLSPEC
* Some compilers use a special export keyword
*/
#ifndef DECLSPEC
# if defined(__BEOS__) || defined(__HAIKU__)
# if defined(__GNUC__)
......@@ -77,7 +85,10 @@
# endif
#endif
/* By default SDL uses the C calling convention */
/**
* @def SDLCALL
* By default SDL uses the C calling convention
*/
#ifndef SDLCALL
# if defined(__WIN32__) && !defined(__GNUC__)
# define SDLCALL __cdecl
......@@ -107,10 +118,12 @@
#endif /* !EKA2 */
#endif /* __SYMBIAN32__ */
/* Force structure packing at 4 byte alignment.
This is necessary if the header is included in code which has structure
packing set to an alternate value, say for loading structures from disk.
The packing is reset to the previous value in close_code.h
/**
* @file begin_code.h
* Force structure packing at 4 byte alignment.
* This is necessary if the header is included in code which has structure
* packing set to an alternate value, say for loading structures from disk.
* The packing is reset to the previous value in close_code.h
*/
#if defined(_MSC_VER) || defined(__MWERKS__) || defined(__BORLANDC__)
#ifdef _MSC_VER
......@@ -125,7 +138,10 @@
#pragma enumsalwaysint on
#endif /* Compiler needs structure packing set */
/* Set up compiler-specific options for inlining functions */
/**
* @def SDL_INLINE_OKAY
* Set up compiler-specific options for inlining functions
*/
#ifndef SDL_INLINE_OKAY
#ifdef __GNUC__
#define SDL_INLINE_OKAY
......@@ -150,15 +166,20 @@
#endif /* GNU C */
#endif /* SDL_INLINE_OKAY */
/* If inlining isn't supported, remove "__inline__", turning static
inlined functions into static functions (resulting in code bloat
in all files which include the offending header files)
*/
/**
* @def __inline__
* If inlining isn't supported, remove "__inline__", turning static
* inlined functions into static functions (resulting in code bloat
* in all files which include the offending header files)
*/
#ifndef SDL_INLINE_OKAY
#define __inline__
#endif
/* Apparently this is needed by several Windows compilers */
/**
* @def NULL
* Apparently this is needed by several Windows compilers
*/
#if !defined(__MACH__)
#ifndef NULL
#ifdef __cplusplus
......
include/close_code.h
View file @ 1106b669
......@@ -20,13 +20,18 @@
slouken@libsdl.org
*/
/* This file reverses the effects of begin_code.h and should be included
after you finish any function and structure declarations in your headers
*/
/**
* @file close_code.h
* This file reverses the effects of begin_code.h and should be included
* after you finish any function and structure declarations in your headers
*/
#undef _begin_code_h
/* Reset structure packing at previous byte alignment */
/**
* @file close_code.h
* Reset structure packing at previous byte alignment
*/
#if defined(_MSC_VER) || defined(__MWERKS__) || defined(__WATCOMC__) || defined(__BORLANDC__)
#ifdef __BORLANDC__
#pragma nopackwarning
......
include/doxyfile 0 → 100644
View file @ 1106b669
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment