encounter
/
SDL
mirror of https://github.com/encounter/SDL.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

First shot at merging the wiki documentation into the headers.

This commit is contained in:
Ryan C. Gordon 2021-03-21 14:18:39 -04:00
parent 3c78c211d5
commit 3f40396d33
No known key found for this signature in database
GPG Key ID: FA148B892AB48044
39 changed files with 7487 additions and 3073 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
include/SDL.h
View File

@ -93,37 +93,121 @@ extern "C" {
/* @} */
/**
* This function initializes the subsystems specified by \c flags
* Initialize the SDL library.
*
* SDL_Init() simply forwards to calling SDL_InitSubSystem(). Therefore, the
* two may be used interchangeably. Though for readability of your code
* SDL_InitSubSystem() might be preferred.
*
* The file I/O (for example: SDL_RWFromFile) and threading (SDL_CreateThread)
* subsystems are initialized by default. Message boxes
* (SDL_ShowSimpleMessageBox) also attempt to work without initializing the
* video subsystem, in hopes of being useful in showing an error dialog when
* SDL_Init fails. You must specifically initialize other subsystems if you
* use them in your application.
*
* Logging (such as SDL_Log) works without initialization, too.
*
* `flags` may be any of the following OR'd together:
*
* - `SDL_INIT_TIMER`: timer subsystem
* - `SDL_INIT_AUDIO`: audio subsystem
* - `SDL_INIT_VIDEO`: video subsystem; automatically initializes the events
* subsystem
* - `SDL_INIT_JOYSTICK`: joystick subsystem; automatically initializes the
* events subsystem
* - `SDL_INIT_HAPTIC`: haptic (force feedback) subsystem
* - `SDL_INIT_GAMECONTROLLER`: controller subsystem; automatically
* initializes the joystick subsystem
* - `SDL_INIT_EVENTS`: events subsystem
* - `SDL_INIT_EVERYTHING`: all of the above subsystems
* - `SDL_INIT_NOPARACHUTE`: compatibility; this flag is ignored
*
* Subsystem initialization is ref-counted, you must call SDL_QuitSubSystem()
* for each SDL_InitSubSystem() to correctly shutdown a subsystem manually (or
* call SDL_Quit() to force shutdown). If a subsystem is already loaded then
* this call will increase the ref-count and return.
*
* \param flags subsystem initialization flags
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_InitSubSystem
* \sa SDL_Quit
* \sa SDL_SetMainReady
* \sa SDL_WasInit
*/
extern DECLSPEC int SDLCALL SDL_Init(Uint32 flags);
/**
* This function initializes specific SDL subsystems
* Compatibility function to initialize the SDL library.
*
* Subsystem initialization is ref-counted, you must call
* SDL_QuitSubSystem() for each SDL_InitSubSystem() to correctly
* shutdown a subsystem manually (or call SDL_Quit() to force shutdown).
* If a subsystem is already loaded then this call will
* increase the ref-count and return.
* In SDL2, this function and SDL_Init() are interchangeable.
*
* \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_Init
* \sa SDL_Quit
* \sa SDL_QuitSubSystem
*/
extern DECLSPEC int SDLCALL SDL_InitSubSystem(Uint32 flags);
/**
* This function cleans up specific SDL subsystems
* Shut down specific SDL subsystems.
*
* If you start a subsystem using a call to that subsystem's init function
* (for example SDL_VideoInit()) instead of SDL_Init() or SDL_InitSubSystem(),
* SDL_QuitSubSystem() and SDL_WasInit() will not work. You will need to use
* that subsystem's quit function (SDL_VideoQuit()) directly instead. But
* generally, you should not be using those functions directly anyhow; use
* SDL_Init() instead.
*
* You still need to call SDL_Quit() even if you close all open subsystems
* with SDL_QuitSubSystem().
*
* \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
*
* \sa SDL_InitSubSystem
* \sa SDL_Quit
*/
extern DECLSPEC void SDLCALL SDL_QuitSubSystem(Uint32 flags);
/**
* This function returns a mask of the specified subsystems which have
* previously been initialized.
* Get a mask of the specified subsystems which are currently initialized.
*
* If \c flags is 0, it returns a mask of all initialized subsystems.
* \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
* \returns If `flags` is 0 it returns a mask of all initialized subsystems,
* otherwise it returns the initialization status of the specified
* subsystems.
*
* The return value does not include SDL_INIT_NOPARACHUTE.
*
* \sa SDL_Init
* \sa SDL_InitSubSystem
*/
extern DECLSPEC Uint32 SDLCALL SDL_WasInit(Uint32 flags);
/**
* This function cleans up all initialized subsystems. You should
* call it upon all exit conditions.
* Clean up all initialized subsystems.
*
* You should call this function even if you have already shutdown each
* initialized subsystem with SDL_QuitSubSystem(). It is safe to call this
* function even in the case of errors in initialization.
*
* If you start a subsystem using a call to that subsystem's init function
* (for example SDL_VideoInit()) instead of SDL_Init() or SDL_InitSubSystem(),
* then you must use that subsystem's quit function (SDL_VideoQuit()) to shut
* it down before calling SDL_Quit(). But generally, you should not be using
* those functions directly anyhow; use SDL_Init() instead.
*
* You can use this function with atexit() to ensure that it is run when your
* application is shutdown, but it is not wise to do this from a library or
* other dynamically loaded code.
*
* \sa SDL_Init
* \sa SDL_QuitSubSystem
*/
extern DECLSPEC void SDLCALL SDL_Quit(void);

95
include/SDL_assert.h
View File

@ -193,67 +193,93 @@ typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)(
const SDL_AssertData* data, void* userdata);
/**
* \brief Set an application-defined assertion handler.
* Set an application-defined assertion handler.
*
* This allows an app to show its own assertion UI and/or force the
* response to an assertion failure. If the app doesn't provide this, SDL
* will try to do the right thing, popping up a system-specific GUI dialog,
* and probably minimizing any fullscreen windows.
* This function allows an application to show its own assertion UI and/or
* force the response to an assertion failure. If the application doesn't
* provide this, SDL will try to do the right thing, popping up a
* system-specific GUI dialog, and probably minimizing any fullscreen windows.
*
* The function prototype for `handler` is:
*
* ```c
* SDL_AssertState YourAssertionHandler(const SDL_AssertData* data, void* userdata)
* ```
*
* where `YourAssertionHandler` is the name of your function and its
* parameters are:
*
* - `data`: a pointer to the SDL_AssertData structure corresponding to the
* current assertion
* - `userdata`: what was passed as `userdata` to SDL_SetAssertionHandler()
*
* This callback should return an SDL_AssertState value indicating how to
* handle the assertion failure.
*
* This callback may fire from any thread, but it runs wrapped in a mutex, so
* it will only fire from one thread at a time.
*
* Setting the callback to NULL restores SDL's original internal handler.
*
* This callback is NOT reset to SDL's internal handler upon SDL_Quit()!
*
* Return SDL_AssertState value of how to handle the assertion failure.
* \param handler the function to call when an assertion fails or NULL for the
* default handler
* \param userdata a pointer that is passed to `handler`
*
* \param handler Callback function, called when an assertion fails.
* \param userdata A pointer passed to the callback as-is.
* \sa SDL_GetAssertionHandler
*/
extern DECLSPEC void SDLCALL SDL_SetAssertionHandler(
SDL_AssertionHandler handler,
void *userdata);
/**
* \brief Get the default assertion handler.
* Get the default assertion handler.
*
* This returns the function pointer that is called by default when an
* assertion is triggered. This is an internal function provided by SDL,
* that is used for assertions when SDL_SetAssertionHandler() hasn't been
* used to provide a different function.
* assertion is triggered. This is an internal function provided by SDL, that
* is used for assertions when SDL_SetAssertionHandler() hasn't been used to
* provide a different function.
*
* \return The default SDL_AssertionHandler that is called when an assert triggers.
* \returns the default SDL_AssertionHandler that is called when an assert
* triggers.
*
* \since This function is available since SDL 2.0.2.
*
* \sa SDL_GetAssertionHandler
*/
extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetDefaultAssertionHandler(void);
/**
* \brief Get the current assertion handler.
* Get the current assertion handler.
*
* This returns the function pointer that is called when an assertion is
* triggered. This is either the value last passed to
* SDL_SetAssertionHandler(), or if no application-specified function is
* set, is equivalent to calling SDL_GetDefaultAssertionHandler().
* SDL_SetAssertionHandler(), or if no application-specified function is set,
* is equivalent to calling SDL_GetDefaultAssertionHandler().
*
* \param puserdata Pointer to a void*, which will store the "userdata"
* pointer that was passed to SDL_SetAssertionHandler().
* This value will always be NULL for the default handler.
* If you don't care about this data, it is safe to pass
* a NULL pointer to this function to ignore it.
* \return The SDL_AssertionHandler that is called when an assert triggers.
* The parameter `puserdata` is a pointer to a void*, which will store the
* "userdata" pointer that was passed to SDL_SetAssertionHandler(). This value
* will always be NULL for the default handler. If you don't care about this
* data, it is safe to pass a NULL pointer to this function to ignore it.
*
* \param puserdata pointer which is filled with the "userdata" pointer that
* was passed to SDL_SetAssertionHandler()
* \returns the SDL_AssertionHandler that is called when an assert triggers.
*
* \since This function is available since SDL 2.0.2.
*
* \sa SDL_SetAssertionHandler
*/
extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetAssertionHandler(void **puserdata);
/**
* \brief Get a list of all assertion failures.
* Get a list of all assertion failures.
*
* Get all assertions triggered since last call to SDL_ResetAssertionReport(),
* or the start of the program.
* This function gets all assertions triggered since the last call to
* SDL_ResetAssertionReport(), or the start of the program.
*
* The proper way to examine this data looks something like this:
*
* <code>
* ```c
* const SDL_AssertData *item = SDL_GetAssertionReport();
* while (item) {
* printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\\n",
@ -262,17 +288,22 @@ extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetAssertionHandler(void **puse
* item->always_ignore ? "yes" : "no");
* item = item->next;
* }
* </code>
* ```
*
* \returns a list of all failed assertions or NULL if the list is empty. This
* memory should not be modified or freed by the application.
*
* \return List of all assertions.
* \sa SDL_ResetAssertionReport
*/
extern DECLSPEC const SDL_AssertData * SDLCALL SDL_GetAssertionReport(void);
/**
* \brief Reset the list of all assertion failures.
* Clear the list of all assertion failures.
*
* Reset list of all assertions triggered.
* This function will clear the list of all assertions triggered up to that
* point. Immediately following this call, SDL_GetAssertionReport will return
* no items. In addition, any previously-triggered assertions will be reset to
* a trigger_count of zero, and their always_ignore state will be false.
*
* \sa SDL_GetAssertionReport
*/

134
include/SDL_atomic.h
View File

@ -89,25 +89,47 @@ extern "C" {
typedef int SDL_SpinLock;
/**
* \brief Try to lock a spin lock by setting it to a non-zero value.
* Try to lock a spin lock by setting it to a non-zero value.
*
* \param lock Points to the lock.
* ***Please note that spinlocks are dangerous if you don't know what you're
* doing. Please be careful using any sort of spinlock!***
*
* \return SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already held.
* \param lock a pointer to a lock variable
* \returns SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already
* held.
*
* \sa SDL_AtomicLock
* \sa SDL_AtomicUnlock
*/
extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTryLock(SDL_SpinLock *lock);
/**
* \brief Lock a spin lock by setting it to a non-zero value.
* Lock a spin lock by setting it to a non-zero value.
*
* \param lock Points to the lock.
* ***Please note that spinlocks are dangerous if you don't know what you're
* doing. Please be careful using any sort of spinlock!***
*
* \param lock a pointer to a lock variable
*
* \sa SDL_AtomicTryLock
* \sa SDL_AtomicUnlock
*/
extern DECLSPEC void SDLCALL SDL_AtomicLock(SDL_SpinLock *lock);
/**
* \brief Unlock a spin lock by setting it to 0. Always returns immediately
* Unlock a spin lock by setting it to 0.
*
* \param lock Points to the lock.
* Always returns immediately.
*
* ***Please note that spinlocks are dangerous if you don't know what you're
* doing. Please be careful using any sort of spinlock!***
*
* \param lock a pointer to a lock variable
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_AtomicLock
* \sa SDL_AtomicTryLock
*/
extern DECLSPEC void SDLCALL SDL_AtomicUnlock(SDL_SpinLock *lock);
@ -216,32 +238,68 @@ typedef void (*SDL_KernelMemoryBarrierFunc)();
typedef struct { int value; } SDL_atomic_t;
/**
* \brief Set an atomic variable to a new value if it is currently an old value.
* Set an atomic variable to a new value if it is
* currently an old value.
*
* \return SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise.
* ***Note: If you don't know what this function is for, you shouldn't use
* it!***
*
* \note If you don't know what this function is for, you shouldn't use it!
*/
* \param a a pointer to an SDL_atomic_t variable to be modified
* \param oldval the old value
* \param newval the new value
* \returns SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_AtomicCASPtr
* \sa SDL_AtomicGet
* \sa SDL_AtomicSet
*/
extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCAS(SDL_atomic_t *a, int oldval, int newval);
/**
* \brief Set an atomic variable to a value.
* Set an atomic variable to a value.
*
* \return The previous value of the atomic variable.
* This function also acts as a full memory barrier.
*
* ***Note: If you don't know what this function is for, you shouldn't use
* it!***
*
* \param a a pointer to an SDL_atomic_t variable to be modified
* \param v the desired value
* \returns the previous value of the atomic variable.
*
* \sa SDL_AtomicGet
*/
extern DECLSPEC int SDLCALL SDL_AtomicSet(SDL_atomic_t *a, int v);
/**
* \brief Get the value of an atomic variable
* Get the value of an atomic variable.
*
* ***Note: If you don't know what this function is for, you shouldn't use
* it!***
*
* \param a a pointer to an SDL_atomic_t variable
* \returns the current value of an atomic variable.
*
* \sa SDL_AtomicSet
*/
extern DECLSPEC int SDLCALL SDL_AtomicGet(SDL_atomic_t *a);
/**
* \brief Add to an atomic variable.
* Add to an atomic variable.
*
* \return The previous value of the atomic variable.
* This function also acts as a full memory barrier.
*
* \note This same style can be used for any number operation
* ***Note: If you don't know what this function is for, you shouldn't use
* it!***
*
* \param a a pointer to an SDL_atomic_t variable to be modified
* \param v the desired value to add
* \returns the previous value of the atomic variable.
*
* \sa SDL_AtomicDecRef
* \sa SDL_AtomicIncRef
*/
extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_atomic_t *a, int v);
@ -263,23 +321,51 @@ extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_atomic_t *a, int v);
#endif
/**
* \brief Set a pointer to a new value if it is currently an old value.
* Set a pointer to a new value if it is currently an old
* value.
*
* \return SDL_TRUE if the pointer was set, SDL_FALSE otherwise.
* ***Note: If you don't know what this function is for, you shouldn't use
* it!***
*
* \note If you don't know what this function is for, you shouldn't use it!
*/
* \param a a pointer to a pointer
* \param oldval the old pointer value
* \param newval the new pointer value
* \returns SDL_TRUE if the pointer was set, SDL_FALSE otherwise.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_AtomicCAS
* \sa SDL_AtomicGetPtr
* \sa SDL_AtomicSetPtr
*/
extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCASPtr(void **a, void *oldval, void *newval);
/**
* \brief Set a pointer to a value atomically.
* Set a pointer to a value atomically.
*
* \return The previous value of the pointer.
* ***Note: If you don't know what this function is for, you shouldn't use
* it!***
*
* \param a a pointer to a pointer
* \param v the desired pointer value
* \returns the previous value of the pointer.
*
* \sa SDL_AtomicCASPtr
* \sa SDL_AtomicGetPtr
*/
extern DECLSPEC void* SDLCALL SDL_AtomicSetPtr(void **a, void* v);
/**
* \brief Get the value of a pointer atomically.
* Get the value of a pointer atomically.
*
* ***Note: If you don't know what this function is for, you shouldn't use
* it!***
*
* \param a a pointer to a pointer
* \returns the current value of a pointer.
*
* \sa SDL_AtomicCASPtr
* \sa SDL_AtomicSetPtr
*/
extern DECLSPEC void* SDLCALL SDL_AtomicGetPtr(void **a);

704
include/SDL_audio.h
View File

@ -19,6 +19,8 @@
3. This notice may not be removed or altered from any source distribution.
*/
/* !!! FIXME: several functions in here need Doxygen comments. */
/**
* \file SDL_audio.h
*
@ -265,55 +267,69 @@ extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
/* @} */
/**
* This function returns the name of the current audio driver, or NULL
* if no driver has been initialized.
* Get the name of the current audio driver.
*
* The returned string points to internal static memory and thus never becomes
* invalid, even if you quit the audio subsystem and initialize a new driver
* (although such a case would return a different static string from another
* call to this function, of course). As such, you should not modify or free
* the returned string.
*
* \returns the name of the current audio driver or NULL if no driver has been
* initialized.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_AudioInit
*/
extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
/**
* 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 \c obtained. If \c obtained is NULL, the audio
* data passed to the callback function will be guaranteed to be in the
* requested format, and will be automatically converted to the hardware
* audio format if necessary. This function returns -1 if it failed
* to open the audio device, or couldn't set up the audio thread.
* This function is a legacy means of opening the audio device.
*
* When filling in the desired audio spec structure,
* - \c desired->freq should be the desired audio frequency in samples-per-
* second.
* - \c desired->format should be the desired audio format.
* - \c 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: \code ms = (samples*1000)/freq \endcode
* - \c desired->size is the size in bytes of the audio buffer, and is
* calculated by SDL_OpenAudio().
* - \c desired->silence is the value used to set the buffer to silence,
* and is calculated by SDL_OpenAudio().
* - \c 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. Alternately, you may pass a NULL
* pointer here, and call SDL_QueueAudio() with some frequency, to queue
* more audio samples to be played (or for capture devices, call
* SDL_DequeueAudio() with some frequency, to obtain audio samples).
* - \c desired->userdata is passed as the first parameter to your callback
* function. If you passed a NULL callback, this value is ignored.
* This function remains for compatibility with SDL 1.2, but also because it's
* slightly easier to use than the new functions in SDL 2.0. The new, more
* powerful, and preferred way to do this is SDL_OpenAudioDevice().
*
* The audio device starts out playing silence when it's opened, and should
* be enabled for playing by calling \c 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.
* This function is roughly equivalent to:
*
* ```c++
* SDL_OpenAudioDevice(NULL, 0, desired, obtained, SDL_AUDIO_ALLOW_ANY_CHANGE);
* ```
*
* With two notable exceptions:
*
* - If `obtained` is NULL, we use `desired` (and allow no changes), which
* means desired will be modified to have the correct values for silence, etc,
* and SDL will convert any differences between your app's specific request
* and the hardware behind the scenes.
*
* - The return value is always success or failure, and not a device ID, which
* means you can only have one device open at a time with this function.
*
* \param desired an SDL_AudioSpec structure representing the desired output
* format. Please refer to the SDL_OpenAudioDevice documentation
* for details on how to prepare this structure.
* \param obtained an SDL_AudioSpec structure filled in with the actual
* parameters, or NULL.
* \returns This function opens the audio device with the desired parameters,
* and returns 0 if successful, placing the actual hardware
* parameters in the structure pointed to by `obtained`.
*
* If `obtained` is NULL, the audio data passed to the callback
* function will be guaranteed to be in the requested format, and
* will be automatically converted to the actual hardware audio
* format if necessary. If `obtained` is NULL, `desired` will
* have fields modified.
*
* This function returns a negative error code on failure to open the
* audio device or failure to set up the audio thread; call
* SDL_GetError() for more information.
*
* \sa SDL_CloseAudio
* \sa SDL_LockAudio
* \sa SDL_PauseAudio
* \sa SDL_UnlockAudio
*/
extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
SDL_AudioSpec * obtained);
@ -330,49 +346,97 @@ extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
typedef Uint32 SDL_AudioDeviceID;
/**
* Get the number of available devices exposed by the current driver.
* Only valid after a successfully initializing the audio subsystem.
* Returns -1 if an explicit list of devices can't be determined; this is
* not an error. For example, if SDL is set up to talk to a remote audio
* server, it can't list every one available on the Internet, but it will
* still allow a specific host to be specified to SDL_OpenAudioDevice().
* Get the number of built-in audio devices.
*
* This function is only valid after successfully initializing the audio
* subsystem.
*
* Note that audio capture support is not implemented as of SDL 2.0.4, so the
* `iscapture` parameter is for future expansion and should always be zero
* for now.
*
* This function will return -1 if an explicit list of devices can't be
* determined. Returning -1 is not an error. For example, if SDL is set up to
* talk to a remote audio server, it can't list every one available on the
* Internet, but it will still allow a specific host to be specified in
* SDL_OpenAudioDevice().
*
* In many common cases, when this function returns a value <= 0, it can still
* successfully open the default device (NULL for first argument of
* SDL_OpenAudioDevice()).
*
* This function may trigger a complete redetect of available hardware. It
* should not be called for each iteration of a loop, but rather once at the
* start of a loop:
*
* ```c++
* // Don't do this:
* for (int i = 0; i < SDL_GetNumAudioDevices(0); i++)
*
* // do this instead:
* const int count = SDL_GetNumAudioDevices(0);
* for (int i = 0; i < count; ++i) { do_something_here(); }
* ```
*
* \param iscapture zero to request playback devices, non-zero to request
* recording devices
* \returns the number of available devices exposed by the current driver or
* -1 if an explicit list of devices can't be determined. A return
* value of -1 does not necessarily mean an error condition.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_GetAudioDeviceName
* \sa SDL_OpenAudioDevice
*/
extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture);
/**
* Get the human-readable name of a specific audio device.
* Must be a value between 0 and (number of audio devices-1).
* Only valid after a successfully initializing the audio subsystem.
* The values returned by this function reflect the latest call to
* SDL_GetNumAudioDevices(); recall that function to redetect available
*
* This function is only valid after successfully initializing the audio
* subsystem. The values returned by this function reflect the latest call to
* SDL_GetNumAudioDevices(); re-call that function to redetect available
* hardware.
*
* The string returned by this function is UTF-8 encoded, read-only, and
* managed internally. You are not to free it. If you need to keep the
* string for any length of time, you should make your own copy of it, as it
* will be invalid next time any of several other SDL functions is called.
* managed internally. You are not to free it. If you need to keep the string
* for any length of time, you should make your own copy of it, as it will be
* invalid next time any of several other SDL functions are called.
*
* \param index the index of the audio device; valid values range from 0 to
* SDL_GetNumAudioDevices() - 1
* \param iscapture non-zero to query the list of recording devices, zero to
* query the list of output devices.
* \returns the name of the audio device at the requested index, or NULL on
* error.
*
* \sa SDL_GetNumAudioDevices
*/
extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index,
int iscapture);
/**
* Get the audio format of a specific audio device.
* Must be a value between 0 and (number of audio devices-1).
* Only valid after a successfully initializing the audio subsystem.
* The values returned by this function reflect the latest call to
* SDL_GetNumAudioDevices(); recall that function to redetect available
* Get the preferred audio format of a specific audio device.
*
* This function is only valid after a successfully initializing the audio
* subsystem. The values returned by this function reflect the latest call to
* SDL_GetNumAudioDevices(); re-call that function to redetect available
* hardware.
*
* The spec will be filled with the sample rate, sample format, and channel
* `spec` will be filled with the sample rate, sample format, and channel
* count. All other values in the structure are filled with 0. When the
* supported struct members are 0, SDL was unable to get the property from the
* backend.
*
* \return 0 on success, nonzero on error
* \param index the index of the audio device; valid values range from 0 to
* SDL_GetNumAudioDevices() - 1
* \param iscapture non-zero to query the list of recording devices, zero to
* query the list of output devices.
* \param spec The SDL_AudioSpec to be initialized by this function.
* \returns 0 on success, nonzero on error
*
* \sa SDL_GetNumAudioDevices
*/
extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
int iscapture,
@ -380,17 +444,116 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
/**
* Open a specific audio device. Passing in a device name of NULL requests
* the most reasonable default (and is equivalent to calling SDL_OpenAudio()).
* Open a specific audio device.
*
* The device name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but
* SDL_OpenAudio(), unlike this function, always acts on device ID 1. As such,
* this function will never return a 1 so as not to conflict with the legacy
* function.
*
* Please note that SDL 2.0 before 2.0.5 did not support recording; as such,
* this function would fail if `iscapture` was not zero. Starting with SDL
* 2.0.5, recording is implemented and this value can be non-zero.
*
* Passing in a `device` name of NULL requests the most reasonable default
* (and is equivalent to what SDL_OpenAudio() does to choose a device). The
* `device` name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but
* some drivers allow arbitrary and driver-specific strings, such as a
* hostname/IP address for a remote audio server, or a filename in the
* diskaudio driver.
*
* \return 0 on error, a valid device ID that is >= 2 on success.
* When filling in the desired audio spec structure:
*
* SDL_OpenAudio(), unlike this function, always acts on device ID 1.
* - `desired->freq` should be the frequency in sample-frames-per-second (Hz).
*
* - `desired->format` should be the audio format (`AUDIO_S16SYS`, etc).
*
* - `desired->samples` is the desired size of the audio buffer, in
* _sample frames_ (with stereo output, two samples--left and right--would
* make a single sample frame). 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 reduce
* latency, but can lead to underflow if the application is doing heavy
* processing and cannot fill the audio buffer in time. Note that the
* number of sample frames is directly related to time by the following
* formula: `ms = (sampleframes*1000)/freq`
*
* - `desired->size` is the size in _bytes_ of the audio buffer, and is
* calculated by SDL_OpenAudioDevice(). You don't initialize this.
*
* - `desired->silence` is the value used to set the buffer to silence,
* and is calculated by SDL_OpenAudioDevice(). You don't initialize this.
*
* - `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_LockAudioDevice()
* and SDL_UnlockAudioDevice() in your code. Alternately, you may pass a NULL
* pointer here, and call SDL_QueueAudio() with some frequency, to queue
* more audio samples to be played (or for capture devices, call
* SDL_DequeueAudio() with some frequency, to obtain audio samples).
*
* - `desired->userdata` is passed as the first parameter to your callback
* function. If you passed a NULL callback, this value is ignored.
*
* `allowed_changes` can have the following flags OR'd together:
*
* - `SDL_AUDIO_ALLOW_FREQUENCY_CHANGE`
* - `SDL_AUDIO_ALLOW_FORMAT_CHANGE`
* - `SDL_AUDIO_ALLOW_CHANNELS_CHANGE`
* - `SDL_AUDIO_ALLOW_ANY_CHANGE`
*
* These flags specify how SDL should behave when a device cannot offer a
* specific feature. If the application requests a feature that the hardware
* doesn't offer, SDL will always try to get the closest equivalent.
*
* For example, if you ask for float32 audio format, but the sound card only
* supports int16, SDL will set the hardware to int16. If you had set
* SDL_AUDIO_ALLOW_FORMAT_CHANGE, SDL will change the format in the
* `obtained` structure. If that flag was *not* set, SDL will prepare to
* convert your callback's float32 audio to int16 before feeding it to the
* hardware and will keep the originally requested format in the `obtained`
* structure.
*
* If your application can only handle one specific data format, pass a zero
* for `allowed_changes` and let SDL transparently handle any differences.
*
* An opened audio device starts out paused, and should be enabled for playing
* by calling SDL_PauseAudioDevice(devid, 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.
*
* The audio callback runs in a separate thread in most cases; you can prevent
* race conditions between your callback and other threads without fully
* pausing playback with SDL_LockAudioDevice(). For more information about the
* callback, see SDL_AudioSpec.
*
* \param device a UTF-8 string reported by SDL_GetAudioDeviceName() or a
* driver-specific name as appropriate. NULL requests the most
* reasonable default device.
* \param iscapture non-zero to specify a device should be opened for
* recording, not playback
* \param desired an SDL_AudioSpec structure representing the desired output
* format; see SDL_OpenAudio() for more information
* \param obtained an SDL_AudioSpec structure filled in with the actual output
* format; see SDL_OpenAudio() for more information
* \param allowed_changes 0, or one or more flags OR'd together
* \returns a valid device ID that is > 0 on success or 0 on failure; call
* SDL_GetError() for more information.
*
* For compatibility with SDL 1.2, this will never return 1, since
* SDL reserves that ID for the legacy SDL_OpenAudio() function.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_CloseAudioDevice
* \sa SDL_GetAudioDeviceName
* \sa SDL_LockAudioDevice
* \sa SDL_OpenAudio
* \sa SDL_PauseAudioDevice
* \sa SDL_UnlockAudioDevice
*/
extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(const char
*device,
@ -418,9 +581,7 @@ typedef enum
SDL_AUDIO_PAUSED
} SDL_AudioStatus;
extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void);
extern DECLSPEC SDL_AudioStatus SDLCALL
SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
/* @} *//* Audio State */
/**
@ -439,56 +600,79 @@ extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
/* @} *//* Pause audio functions */
/**
* \brief Load the audio data of a WAVE file into memory
* Load the audio data of a WAVE file into memory.
*
* Loading a WAVE file requires \c src, \c spec, \c audio_buf and \c audio_len
* Loading a WAVE file requires `src`, `spec`, `audio_buf` and `audio_len`
* to be valid pointers. The entire data portion of the file is then loaded
* into memory and decoded if necessary.
*
* If \c freesrc is non-zero, the data source gets automatically closed and
* If `freesrc` is non-zero, the data source gets automatically closed and
* freed before the function returns.
*
* Supported are RIFF WAVE files with the formats PCM (8, 16, 24, and 32 bits),
* IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and A-law and
* µ-law (8 bits). Other formats are currently unsupported and cause an error.
* Supported formats are RIFF WAVE files with the formats PCM (8, 16, 24, and
* 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits),
* and A-law and mu-law (8 bits). Other formats are currently unsupported and
* cause an error.
*
* If this function succeeds, the pointer returned by it is equal to \c spec
* If this function succeeds, the pointer returned by it is equal to `spec`
* and the pointer to the audio data allocated by the function is written to
* \c audio_buf and its length in bytes to \c audio_len. The \ref SDL_AudioSpec
* members \c freq, \c channels, and \c format are set to the values of the
* audio data in the buffer. The \c samples member is set to a sane default and
* all others are set to zero.
* `audio_buf` and its length in bytes to `audio_len`. The SDL_AudioSpec
* members `freq`, `channels`, and `format` are set to the values of the
* audio data in the buffer. The `samples` member is set to a sane default
* and all others are set to zero.
*
* It's necessary to use SDL_FreeWAV() to free the audio data returned in
* \c audio_buf when it is no longer used.
* `audio_buf` when it is no longer used.
*
* Because of the underspecification of the Waveform format, there are many
* Because of the underspecification of the .WAV format, there are many
* problematic files in the wild that cause issues with strict decoders. To
* provide compatibility with these files, this decoder is lenient in regards
* to the truncation of the file, the fact chunk, and the size of the RIFF
* chunk. The hints SDL_HINT_WAVE_RIFF_CHUNK_SIZE, SDL_HINT_WAVE_TRUNCATION,
* and SDL_HINT_WAVE_FACT_CHUNK can be used to tune the behavior of the
* chunk. The hints `SDL_HINT_WAVE_RIFF_CHUNK_SIZE`, `SDL_HINT_WAVE_TRUNCATION`,
* and `SDL_HINT_WAVE_FACT_CHUNK` can be used to tune the behavior of the
* loading process.
*
* Any file that is invalid (due to truncation, corruption, or wrong values in
* the headers), too big, or unsupported causes an error. Additionally, any
* critical I/O error from the data source will terminate the loading process
* with an error. The function returns NULL on error and in all cases (with the
* exception of \c src being NULL), an appropriate error message will be set.
* exception of `src` being NULL), an appropriate error message will be set.
*
* It is required that the data source supports seeking.
*
* Example:
* \code
* SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...);
* \endcode
* ```c++
* SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, &spec, &buf, &len);
* ```
*
* \param src The data source with the WAVE data
* \param freesrc A integer value that makes the function close the data source if non-zero
* \param spec A pointer filled with the audio format of the audio data
* \param audio_buf A pointer filled with the audio data allocated by the function
* Note that the SDL_LoadWAV macro does this same thing for you, but in a less
* messy way:
*
* ```c++
* SDL_LoadWAV("sample.wav", &spec, &buf, &len);
* ```
*
* \param src The data source for the WAVE data
* \param freesrc If non-zero, SDL will _always_ free the data source
* \param spec An SDL_AudioSpec that will be filled in with the wave file's
* format details
* \param audio_buf A pointer filled with the audio data, allocated by the function.
* \param audio_len A pointer filled with the length of the audio data buffer in bytes
* \return NULL on error, or non-NULL on success.
* \returns This function, if successfully called, returns `spec`, which will
* be filled with the audio data format of the wave source data.
* `audio_buf` will be filled with a pointer to an allocated buffer
* containing the audio data, and `audio_len` is filled with the
* length of that audio buffer in bytes.
*
* This function returns NULL if the .WAV file cannot be opened, uses
* an unknown data format, or is corrupt; call SDL_GetError() for
* more information.
*
* When the application is done with the data returned in
* `audio_buf`, it should call SDL_FreeWAV() to dispose of it.
*
* \sa SDL_FreeWAV
* \sa SDL_LoadWAV
*/
extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
int freesrc,
@ -504,18 +688,50 @@ extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
/**
* This function frees data previously allocated with SDL_LoadWAV_RW()
* Free data previously allocated with SDL_LoadWAV() or SDL_LoadWAV_RW().
*
* After a WAVE file has been opened with SDL_LoadWAV() or SDL_LoadWAV_RW()
* its data can eventually be freed with SDL_FreeWAV(). It is safe to call
* this function with a NULL pointer.
*
* \param audio_buf a pointer to the buffer created by SDL_LoadWAV() or
* SDL_LoadWAV_RW()
*
* \sa SDL_LoadWAV
* \sa 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 \c cvt structure with information needed
* by SDL_ConvertAudio() to convert a buffer of audio data from one format
* to the other. An unsupported format causes an error and -1 will be returned.
* Initialize an SDL_AudioCVT structure for conversion.
*
* \return 0 if no conversion is needed, 1 if the audio filter is set up,
* or -1 on error.
* Before an SDL_AudioCVT structure can be used to convert audio data it must
* be initialized with source and destination information.
*
* This function will zero out every field of the SDL_AudioCVT, so it must be
* called before the application fills in the final buffer information.
*
* Once this function has returned successfully, and reported that a
* conversion is necessary, the application fills in the rest of the fields in
* SDL_AudioCVT, now that it knows how large a buffer it needs to allocate,
* and then can call SDL_ConvertAudio() to complete the conversion.
*
* \param cvt an SDL_AudioCVT structure filled in with audio conversion
* information
* \param src_format the source format of the audio data; for more info see
* SDL_AudioFormat
* \param src_channels the number of channels in the source
* \param src_rate the frequency (sample-frames-per-second) of the source
* \param dst_format the destination format of the audio data; for more info
* see SDL_AudioFormat
* \param dst_channels the number of channels in the destination
* \param dst_rate the frequency (sample-frames-per-second) of the
* destination
* \returns 1 if the audio filter is prepared, 0 if no conversion is needed,
* or a negative error code on failure; call SDL_GetError() for more
* information.
*
* \sa SDL_ConvertAudio
*/
extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
SDL_AudioFormat src_format,
@ -526,16 +742,40 @@ extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
int dst_rate);
/**
* Once you have initialized the \c cvt structure using SDL_BuildAudioCVT(),
* created an audio buffer \c cvt->buf, and filled it with \c cvt->len bytes of
* audio data in the source format, this function will convert it in-place
* Convert audio data to a desired audio format.
*
* This function does the actual audio data conversion, after the application
* has called SDL_BuildAudioCVT() to prepare the conversion information and
* then filled in the buffer details.
*
* Once the application has initialized the `cvt` structure using
* SDL_BuildAudioCVT(), allocated an audio buffer and filled it with audio
* data in the source format, this function will convert the buffer, in-place,
* to the desired format.
*
* The data conversion may expand the size of the audio data, so the buffer
* \c cvt->buf should be allocated after the \c cvt structure is initialized by
* SDL_BuildAudioCVT(), and should be \c cvt->len*cvt->len_mult bytes long.
* The data conversion may go through several passes; any given pass may
* possibly temporarily increase the size of the data. For example, SDL might
* expand 16-bit data to 32 bits before resampling to a lower frequency,
* shrinking the data size after having grown it briefly. Since the supplied
* buffer will be both the source and destination, converting as necessary
* in-place, the application must allocate a buffer that will fully contain
* the data during its largest conversion pass. After SDL_BuildAudioCVT()
* returns, the application should set the `cvt->len` field to the size, in
* bytes, of the source data, and allocate a buffer that is
* `cvt->len * cvt->len_mult` bytes long for the `buf` field.
*
* \return 0 on success or -1 if \c cvt->buf is NULL.
* The source data should be copied into this buffer before the call to
* SDL_ConvertAudio(). Upon successful return, this buffer will contain the
* converted audio, and `cvt->len_cvt` will be the size of the converted data,
* in bytes. Any bytes in the buffer past `cvt->len_cvt` are undefined once
* this function returns.
*
* \param cvt an SDL_AudioCVT structure that was previously set up by
* SDL_BuildAudioCVT().
* \returns 0 if the conversion was completed successfully or a negative error
* code on failure; call SDL_GetError() for more information.
*
* \sa SDL_BuildAudioCVT
*/
extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt);
@ -551,7 +791,7 @@ struct _SDL_AudioStream;
typedef struct _SDL_AudioStream SDL_AudioStream;
/**
* Create a new audio stream
* Create a new audio stream.
*
* \param src_format The format of the source audio
* \param src_channels The number of channels of the source audio
@ -559,7 +799,7 @@ typedef struct _SDL_AudioStream SDL_AudioStream;
* \param dst_format The format of the desired audio output
* \param dst_channels The number of channels of the desired audio output
* \param dst_rate The sampling rate of the desired audio output
* \return 0 on success, or -1 on error.
* \returns 0 on success, or -1 on error.
*
* \sa SDL_AudioStreamPut
* \sa SDL_AudioStreamGet
@ -576,12 +816,12 @@ extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioForm
const int dst_rate);
/**
* Add data to be converted/resampled to the stream
* Add data to be converted/resampled to the stream.
*
* \param stream The stream the audio data is being added to
* \param buf A pointer to the audio data to add
* \param len The number of bytes to write to the stream
* \return 0 on success, or -1 on error.
* \returns 0 on success, or -1 on error.
*
* \sa SDL_NewAudioStream
* \sa SDL_AudioStreamGet
@ -598,7 +838,7 @@ extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const vo
* \param stream The stream the audio is being requested from
* \param buf A buffer to fill with audio data
* \param len The maximum number of bytes to fill
* \return The number of bytes read from the stream, or -1 on error
* \returns the number of bytes read from the stream, or -1 on error
*
* \sa SDL_NewAudioStream
* \sa SDL_AudioStreamPut
@ -667,19 +907,55 @@ extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream);
#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.
* This function is a legacy means of mixing audio.
*
* This function is equivalent to calling
*
* ```c++
* SDL_MixAudioFormat(dst, src, format, len, volume);
* ```
*
* where `format` is the obtained format of the audio device from the legacy
* SDL_OpenAudio() function.
*
* \param dst the destination for the mixed audio
* \param src the source audio buffer to be mixed
* \param len the length of the audio buffer in bytes
* \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
* for full audio volume
*
* \sa SDL_MixAudioFormat
*/
extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
Uint32 len, int volume);
/**
* This works like SDL_MixAudio(), but you specify the audio format instead of
* using the format of audio device 1. Thus it can be used when no audio
* device is open at all.
* Mix audio data in a specified format.
*
* This takes an audio buffer `src` of `len` bytes of `format` data and
* mixes it into `dst`, performing addition, volume adjustment, and overflow
* clipping. The buffer pointed to by `dst` must also be `len` bytes of
* `format` data.
*
* This is provided for convenience -- you can mix your own audio data.
*
* Do not use this function for mixing together more than two streams of
* sample data. The output from repeated application of this function may be
* distorted by clipping, because there is no accumulator with greater range
* than the input (not to mention this being an inefficient way of doing it).
*
* It is a common misconception that this function is required to write audio
* data to an output stream in an audio callback. While you can do that,
* SDL_MixAudioFormat() is really only needed when you're mixing a single
* audio stream with a volume adjustment.
*
* \param dst the destination for the mixed audio
* \param src the source audio buffer to be mixed
* \param format the SDL_AudioFormat structure representing the desired audio
* format
* \param len the length of the audio buffer in bytes
* \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
* for full audio volume
*/
extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
const Uint8 * src,
@ -689,159 +965,161 @@ extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
/**
* Queue more audio on non-callback devices.
*
* (If you are looking to retrieve queued audio from a non-callback capture
* device, you want SDL_DequeueAudio() instead. This will return -1 to
* signify an error if you use it with capture devices.)
* If you are looking to retrieve queued audio from a non-callback capture
* device, you want SDL_DequeueAudio() instead. SDL_QueueAudio() will return
* -1 to signify an error if you use it with capture devices.
*
* SDL offers two ways to feed audio to the device: you can either supply a
* callback that SDL triggers with some frequency to obtain more audio
* (pull method), or you can supply no callback, and then SDL will expect
* you to supply data at regular intervals (push method) with this function.
* callback that SDL triggers with some frequency to obtain more audio (pull
* method), or you can supply no callback, and then SDL will expect you to
* supply data at regular intervals (push method) with this function.
*
* There are no limits on the amount of data you can queue, short of
* exhaustion of address space. Queued data will drain to the device as
* necessary without further intervention from you. If the device needs
* audio but there is not enough queued, it will play silence to make up
* the difference. This means you will have skips in your audio playback
* if you aren't routinely queueing sufficient data.
* necessary without further intervention from you. If the device needs audio
* but there is not enough queued, it will play silence to make up the
* difference. This means you will have skips in your audio playback if you
* aren't routinely queueing sufficient data.
*
* This function copies the supplied data, so you are safe to free it when
* the function returns. This function is thread-safe, but queueing to the
* same device from two threads at once does not promise which buffer will
* be queued first.
* This function copies the supplied data, so you are safe to free it when the
* function returns. This function is thread-safe, but queueing to the same
* device from two threads at once does not promise which buffer will be
* queued first.
*
* You may not queue audio on a device that is using an application-supplied
* callback; doing so returns an error. You have to use the audio callback
* or queue audio with this function, but not both.
* callback; doing so returns an error. You have to use the audio callback or
* queue audio with this function, but not both.
*
* You should not call SDL_LockAudio() on the device before queueing; SDL
* handles locking internally for this function.
*
* \param dev The device ID to which we will queue audio.
* \param data The data to queue to the device for later playback.
* \param len The number of bytes (not samples!) to which (data) points.
* \return 0 on success, or -1 on error.
* \param dev the device ID to which we will queue audio
* \param data the data to queue to the device for later playback
* \param len the number of bytes (not samples!) to which `data` points
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.4.
*
* \sa SDL_GetQueuedAudioSize
* \sa SDL_ClearQueuedAudio
* \sa SDL_GetQueuedAudioSize
*/
extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *data, Uint32 len);
/**
* Dequeue more audio on non-callback devices.
*
* (If you are looking to queue audio for output on a non-callback playback
* device, you want SDL_QueueAudio() instead. This will always return 0
* if you use it with playback devices.)
* If you are looking to queue audio for output on a non-callback playback
* device, you want SDL_QueueAudio() instead. SDL_DequeueAudio() will always
* return 0 if you use it with playback devices.
*
* SDL offers two ways to retrieve audio from a capture device: you can
* either supply a callback that SDL triggers with some frequency as the
* device records more audio data, (push method), or you can supply no
* callback, and then SDL will expect you to retrieve data at regular
* intervals (pull method) with this function.
* SDL offers two ways to retrieve audio from a capture device: you can either
* supply a callback that SDL triggers with some frequency as the device
* records more audio data, (push method), or you can supply no callback, and
* then SDL will expect you to retrieve data at regular intervals (pull
* method) with this function.
*
* There are no limits on the amount of data you can queue, short of
* exhaustion of address space. Data from the device will keep queuing as
* necessary without further intervention from you. This means you will
* eventually run out of memory if you aren't routinely dequeueing data.
*
* Capture devices will not queue data when paused; if you are expecting
* to not need captured audio for some length of time, use
* SDL_PauseAudioDevice() to stop the capture device from queueing more
* data. This can be useful during, say, level loading times. When
* unpaused, capture devices will start queueing data from that point,
* having flushed any capturable data available while paused.
* Capture devices will not queue data when paused; if you are expecting to
* not need captured audio for some length of time, use SDL_PauseAudioDevice()
* to stop the capture device from queueing more data. This can be useful
* during, say, level loading times. When unpaused, capture devices will start
* queueing data from that point, having flushed any capturable data available
* while paused.
*
* This function is thread-safe, but dequeueing from the same device from
* two threads at once does not promise which thread will dequeued data
* first.
* This function is thread-safe, but dequeueing from the same device from two
* threads at once does not promise which thread will dequeue data first.
*
* You may not dequeue audio from a device that is using an
* application-supplied callback; doing so returns an error. You have to use
* the audio callback, or dequeue audio with this function, but not both.
*
* You should not call SDL_LockAudio() on the device before queueing; SDL
* You should not call SDL_LockAudio() on the device before dequeueing; SDL
* handles locking internally for this function.
*
* \param dev The device ID from which we will dequeue audio.
* \param data A pointer into where audio data should be copied.
* \param len The number of bytes (not samples!) to which (data) points.
* \return number of bytes dequeued, which could be less than requested.
* \param dev the device ID from which we will dequeue audio
* \param data a pointer into where audio data should be copied
* \param len the number of bytes (not samples!) to which (data) points
* \returns number of bytes dequeued, which could be less than requested; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.5.
*
* \sa SDL_GetQueuedAudioSize
* \sa SDL_ClearQueuedAudio
* \sa SDL_GetQueuedAudioSize
*/
extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *data, Uint32 len);
/**
* Get the number of bytes of still-queued audio.
*
* For playback device:
* For playback devices: this is the number of bytes that have been queued
* for playback with SDL_QueueAudio(), but have not yet been sent to the
* hardware.
*
* This is the number of bytes that have been queued for playback with
* SDL_QueueAudio(), but have not yet been sent to the hardware. This
* number may shrink at any time, so this only informs of pending data.
* Once we've sent it to the hardware, this function can not decide the exact
* byte boundary of what has been played. It's possible that we just gave the
* hardware several kilobytes right before you called this function, but it
* hasn't played any of it yet, or maybe half of it, etc.
*
* Once we've sent it to the hardware, this function can not decide the
* exact byte boundary of what has been played. It's possible that we just
* gave the hardware several kilobytes right before you called this
* function, but it hasn't played any of it yet, or maybe half of it, etc.
* For capture devices, this is the number of bytes that have been captured by
* the device and are waiting for you to dequeue. This number may grow at any
* time, so this only informs of the lower-bound of available data.
*
* For capture devices:
*
* This is the number of bytes that have been captured by the device and
* are waiting for you to dequeue. This number may grow at any time, so
* this only informs of the lower-bound of available data.
*
* You may not queue audio on a device that is using an application-supplied
* callback; calling this function on such a device always returns 0.
* You have to queue audio with SDL_QueueAudio()/SDL_DequeueAudio(), or use
* the audio callback, but not both.
* You may not queue or dequeue audio on a device that is using an
* application-supplied callback; calling this function on such a device
* always returns 0. You have to use the audio callback or queue audio, but
* not both.
*
* You should not call SDL_LockAudio() on the device before querying; SDL
* handles locking internally for this function.
*
* \param dev The device ID of which we will query queued audio size.
* \return Number of bytes (not samples!) of queued audio.
* \param dev the device ID of which we will query queued audio size
* \returns the number of bytes (not samples!) of queued audio.
*
* \since This function is available since SDL 2.0.4.
*
* \sa SDL_QueueAudio
* \sa SDL_ClearQueuedAudio
* \sa SDL_QueueAudio
* \sa SDL_DequeueAudio
*/
extern DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev);
/**
* Drop any queued audio data. For playback devices, this is any queued data
* still waiting to be submitted to the hardware. For capture devices, this
* is any data that was queued by the device that hasn't yet been dequeued by
* the application.
* Drop any queued audio data waiting to be sent to the hardware.
*
* Immediately after this call, SDL_GetQueuedAudioSize() will return 0. For
* playback devices, the hardware will start playing silence if more audio
* isn't queued. Unpaused capture devices will start filling the queue again
* as soon as they have more data available (which, depending on the state
* of the hardware and the thread, could be before this function call
* returns!).
* output devices, the hardware will start playing silence if more audio isn't
* queued. For capture devices, the hardware will start filling the empty
* queue with new data if the capture device isn't paused.
*
* This will not prevent playback of queued audio that's already been sent
* to the hardware, as we can not undo that, so expect there to be some
* fraction of a second of audio that might still be heard. This can be
* useful if you want to, say, drop any pending music during a level change
* in your game.
* This will not prevent playback of queued audio that's already been sent to
* the hardware, as we can not undo that, so expect there to be some fraction
* of a second of audio that might still be heard. This can be useful if you
* want to, say, drop any pending music or any unprocessed microphone input
* during a level change in your game.
*
* You may not queue audio on a device that is using an application-supplied
* callback; calling this function on such a device is always a no-op.
* You have to queue audio with SDL_QueueAudio()/SDL_DequeueAudio(), or use
* the audio callback, but not both.
* You may not queue or dequeue audio on a device that is using an
* application-supplied callback; calling this function on such a device
* always returns 0. You have to use the audio callback or queue audio, but
* not both.
*
* You should not call SDL_LockAudio() on the device before clearing the
* queue; SDL handles locking internally for this function.
*
* This function always succeeds and thus returns void.
*
* \param dev The device ID of which to clear the audio queue.
* \param dev the device ID of which to clear the audio queue
*
* \since This function is available since SDL 2.0.4.
*
* \sa SDL_QueueAudio
* \sa SDL_GetQueuedAudioSize
* \sa SDL_QueueAudio
* \sa SDL_DequeueAudio
*/
extern DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev);
@ -862,7 +1140,17 @@ extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev);
/* @} *//* Audio lock functions */
/**
* This function shuts down audio processing and closes the audio device.
* This function is a legacy means of closing the audio device.
*
* This function is equivalent to calling
*
* ```c++
* SDL_CloseAudioDevice(1);
* ```
*
* and is only useful if you used the legacy SDL_OpenAudio() function.
*
* \sa SDL_OpenAudio
*/
extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);

109
include/SDL_blendmode.h
View File

@ -91,19 +91,106 @@ typedef enum
} SDL_BlendFactor;
/**
* \brief Create a custom blend mode, which may or may not be supported by a given renderer
* Compose a custom blend mode for renderers.
*
* \param srcColorFactor source color factor
* \param dstColorFactor destination color factor
* \param colorOperation color operation
* \param srcAlphaFactor source alpha factor
* \param dstAlphaFactor destination alpha factor
* \param alphaOperation alpha operation
* The functions SDL_SetRenderDrawBlendMode and SDL_SetTextureBlendMode accept
* the SDL_BlendMode returned by this function if the renderer supports it.
*
* The result of the blend mode operation will be:
* dstRGB = dstRGB * dstColorFactor colorOperation srcRGB * srcColorFactor
* and
* dstA = dstA * dstAlphaFactor alphaOperation srcA * srcAlphaFactor
* A blend mode controls how the pixels from a drawing operation (source) get
* combined with the pixels from the render target (destination). First, the
* components of the source and destination pixels get multiplied with their
* blend factors. Then, the blend operation takes the two products and
* calculates the result that will get stored in the render target.
*
* Expressed in pseudocode, it would look like this:
*
* ```c
* dstRGB = colorOperation(srcRGB * srcColorFactor, dstRGB * dstColorFactor);
* dstA = alphaOperation(srcA * srcAlphaFactor, dstA * dstAlphaFactor);
* ```
*
* Where the functions `colorOperation(src, dst)` and
* `alphaOperation(src, dst)` can return one of the following:
*
* - `src + dst`
*
* - `src - dst`
*
* - `dst - src`
*
* - `min(src, dst)`
*
* - `max(src, dst)`
*
* The red, green, and blue components are always multiplied with the first,
* second, and third components of the SDL_BlendFactor, respectively. The
* fourth component is not used.
*
* The alpha component is always multiplied with the fourth component of the
* SDL_BlendFactor. The other components are not used in the alpha
* calculation.
*
* Support for these blend modes varies for each renderer. To check if a
* specific SDL_BlendMode is supported, create a renderer and pass it to
* either SDL_SetRenderDrawBlendMode or SDL_SetTextureBlendMode. They will
* return with an error if the blend mode is not supported.
*
* This list describes the support of custom blend modes for each renderer in
* SDL 2.0.6. All renderers support the four blend modes listed in the
* SDL_BlendMode enumeration.
*
* - **direct3d**: Supports `SDL_BLENDOPERATION_ADD` with all factors.
*
* - **direct3d11**: Supports all operations with all factors. However, some
* factors produce unexpected results with `SDL_BLENDOPERATION_MINIMUM` and
* `SDL_BLENDOPERATION_MAXIMUM`.
*
* - **opengl**: Supports the `SDL_BLENDOPERATION_ADD` operation with all
* factors. OpenGL versions 1.1, 1.2, and 1.3 do not work correctly with
* SDL 2.0.6.
*
* - **opengles**: Supports the `SDL_BLENDOPERATION_ADD` operation with all
* factors. Color and alpha factors need to be the same. OpenGL ES 1
* implementation specific: May also support `SDL_BLENDOPERATION_SUBTRACT`
* and `SDL_BLENDOPERATION_REV_SUBTRACT`. May support color and alpha
* operations being different from each other. May support color and alpha
* factors being different from each other.
*
* - **opengles2**: Supports the `SDL_BLENDOPERATION_ADD`,
* `SDL_BLENDOPERATION_SUBTRACT`, `SDL_BLENDOPERATION_REV_SUBTRACT` operations
* with all factors.
*
* - **psp**: No custom blend mode support.
*
* - **software**: No custom blend mode support.
*
* Some renderers do not provide an alpha component for the default render
* target. The `SDL_BLENDFACTOR_DST_ALPHA` and
* `SDL_BLENDFACTOR_ONE_MINUS_DST_ALPHA` factors do not have an effect in this
* case.
*
* \param srcColorFactor the SDL_BlendFactor applied to the red, green, and
* blue components of the source pixels
* \param dstColorFactor the SDL_BlendFactor applied to the red, green, and
* blue components of the destination pixels
* \param colorOperation the SDL_BlendOperation used to combine the red,
* green, and blue components of the source and
* destination pixels
* \param srcAlphaFactor the SDL_BlendFactor applied to the alpha component of
* the source pixels
* \param dstAlphaFactor the SDL_BlendFactor applied to the alpha component of
* the destination pixels
* \param alphaOperation the SDL_BlendOperation used to combine the alpha
* component of the source and destination pixels
* \returns an SDL_BlendMode that represents the chosen factors and
* operations.
*
* \since This function is available in SDL 2.0.6.
*
* \sa SDL_SetRenderDrawBlendMode
* \sa SDL_GetRenderDrawBlendMode
* \sa SDL_SetTextureBlendMode
* \sa SDL_GetTextureBlendMode
*/
extern DECLSPEC SDL_BlendMode SDLCALL SDL_ComposeCustomBlendMode(SDL_BlendFactor srcColorFactor,
SDL_BlendFactor dstColorFactor,

30
include/SDL_clipboard.h
View File

@ -39,23 +39,41 @@ extern "C" {
/* Function prototypes */
/**
* \brief Put UTF-8 text into the clipboard
* Put UTF-8 text into the clipboard.
*
* \sa SDL_GetClipboardText()
* \param text the text to store in the clipboard
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_GetClipboardText
* \sa SDL_HasClipboardText
*/
extern DECLSPEC int SDLCALL SDL_SetClipboardText(const char *text);
/**
* \brief Get UTF-8 text from the clipboard, which must be freed with SDL_free()
* Get UTF-8 text from the clipboard, which must be freed with SDL_free().
*
* \sa SDL_SetClipboardText()
* This functions returns NULL if there was not enough memory left for a copy
* of the clipboard's content.
*
* \returns the clipboard text on success or NULL on failure; call
* SDL_GetError() for more information. Caller must call SDL_free()
* on the returned pointer when done with it.
*
* \sa SDL_HasClipboardText
* \sa SDL_SetClipboardText
*/
extern DECLSPEC char * SDLCALL SDL_GetClipboardText(void);
/**
* \brief Returns a flag indicating whether the clipboard exists and contains a text string that is non-empty
* Query whether the clipboard exists and contains a non-empty text string.
*
* \sa SDL_GetClipboardText()
* \returns SDL_TRUE if the clipboard has text, or SDL_FALSE if it does not.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_GetClipboardText
* \sa SDL_SetClipboardText
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasClipboardText(void);

273
include/SDL_cpuinfo.h
View File

@ -117,95 +117,296 @@ extern "C" {
#define SDL_CACHELINE_SIZE 128
/**
* This function returns the number of CPU cores available.
* Get the number of CPU cores available.
*
* \returns the total number of logical CPU cores. On CPUs that include
* technologies such as hyperthreading, the number of logical cores
* may be more than the number of physical cores.
*
* \since This function is available since SDL 2.0.0.
*/
extern DECLSPEC int SDLCALL SDL_GetCPUCount(void);
/**
* This function returns the L1 cache line size of the CPU
* Determine the L1 cache line size of the CPU.
*
* This is useful for determining multi-threaded structure padding
* or SIMD prefetch sizes.
* This is useful for determining multi-threaded structure padding or SIMD
* prefetch sizes.
*
* \returns the L1 cache line size of the CPU, in bytes.
*
* \since This function is available since SDL 2.0.0.
*/
extern DECLSPEC int SDLCALL SDL_GetCPUCacheLineSize(void);
/**
* This function returns true if the CPU has the RDTSC instruction.
* Determine whether the CPU has the RDTSC instruction.
*
* This always returns false on CPUs that aren't using Intel instruction sets.
*
* \returns SDL_TRUE if the CPU has the RDTSC instruction or SDL_FALSE if not.
*
* \sa SDL_Has3DNow
* \sa SDL_HasAltiVec
* \sa SDL_HasAVX
* \sa SDL_HasAVX2
* \sa SDL_HasMMX
* \sa SDL_HasSSE
* \sa SDL_HasSSE2
* \sa SDL_HasSSE3
* \sa SDL_HasSSE41
* \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasRDTSC(void);
/**
* This function returns true if the CPU has AltiVec features.
* Determine whether the CPU has AltiVec features.
*
* This always returns false on CPUs that aren't using PowerPC instruction sets.
*
* \returns SDL_TRUE if the CPU has AltiVec features or SDL_FALSE if not.
*
* \sa SDL_Has3DNow
* \sa SDL_HasAVX
* \sa SDL_HasAVX2
* \sa SDL_HasMMX
* \sa SDL_HasRDTSC
* \sa SDL_HasSSE
* \sa SDL_HasSSE2
* \sa SDL_HasSSE3
* \sa SDL_HasSSE41
* \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasAltiVec(void);
/**
* This function returns true if the CPU has MMX features.
* Determine whether the CPU has MMX features.
*
* This always returns false on CPUs that aren't using Intel instruction sets.
*
* \returns SDL_TRUE if the CPU has MMX features or SDL_FALSE if not.
*
* \sa SDL_Has3DNow
* \sa SDL_HasAltiVec
* \sa SDL_HasAVX
* \sa SDL_HasAVX2
* \sa SDL_HasRDTSC
* \sa SDL_HasSSE
* \sa SDL_HasSSE2
* \sa SDL_HasSSE3
* \sa SDL_HasSSE41
* \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasMMX(void);
/**
* This function returns true if the CPU has 3DNow! features.
* Determine whether the CPU has 3DNow! features.
*
* This always returns false on CPUs that aren't using AMD instruction sets.
*
* \returns SDL_TRUE if the CPU has 3DNow! features or SDL_FALSE if not.
*
* \sa SDL_HasAltiVec
* \sa SDL_HasAVX
* \sa SDL_HasAVX2
* \sa SDL_HasMMX
* \sa SDL_HasRDTSC
* \sa SDL_HasSSE
* \sa SDL_HasSSE2
* \sa SDL_HasSSE3
* \sa SDL_HasSSE41
* \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_Has3DNow(void);
/**
* This function returns true if the CPU has SSE features.
* Determine whether the CPU has SSE features.
*
* This always returns false on CPUs that aren't using Intel instruction sets.
*
* \returns SDL_TRUE if the CPU has SSE features or SDL_FALSE if not.
*
* \sa SDL_Has3DNow
* \sa SDL_HasAltiVec
* \sa SDL_HasAVX
* \sa SDL_HasAVX2
* \sa SDL_HasMMX
* \sa SDL_HasRDTSC
* \sa SDL_HasSSE2
* \sa SDL_HasSSE3
* \sa SDL_HasSSE41
* \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE(void);
/**
* This function returns true if the CPU has SSE2 features.
* Determine whether the CPU has SSE2 features.
*
* This always returns false on CPUs that aren't using Intel instruction sets.
*
* \returns SDL_TRUE if the CPU has SSE2 features or SDL_FALSE if not.
*
* \sa SDL_Has3DNow
* \sa SDL_HasAltiVec
* \sa SDL_HasAVX
* \sa SDL_HasAVX2
* \sa SDL_HasMMX
* \sa SDL_HasRDTSC
* \sa SDL_HasSSE
* \sa SDL_HasSSE3
* \sa SDL_HasSSE41
* \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE2(void);
/**
* This function returns true if the CPU has SSE3 features.
* Determine whether the CPU has SSE3 features.
*
* This always returns false on CPUs that aren't using Intel instruction sets.
*
* \returns SDL_TRUE if the CPU has SSE3 features or SDL_FALSE if not.
*
* \sa SDL_Has3DNow
* \sa SDL_HasAltiVec
* \sa SDL_HasAVX
* \sa SDL_HasAVX2
* \sa SDL_HasMMX
* \sa SDL_HasRDTSC
* \sa SDL_HasSSE
* \sa SDL_HasSSE2
* \sa SDL_HasSSE41
* \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE3(void);
/**
* This function returns true if the CPU has SSE4.1 features.
* Determine whether the CPU has SSE4.1 features.
*
* This always returns false on CPUs that aren't using Intel instruction sets.
*
* \returns SDL_TRUE if the CPU has SSE4.1 features or SDL_FALSE if not.
*
* \sa SDL_Has3DNow
* \sa SDL_HasAltiVec
* \sa SDL_HasAVX
* \sa SDL_HasAVX2
* \sa SDL_HasMMX
* \sa SDL_HasRDTSC
* \sa SDL_HasSSE
* \sa SDL_HasSSE2
* \sa SDL_HasSSE3
* \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE41(void);
/**
* This function returns true if the CPU has SSE4.2 features.
* Determine whether the CPU has SSE4.2 features.
*
* This always returns false on CPUs that aren't using Intel instruction sets.
*
* \returns SDL_TRUE if the CPU has SSE4.2 features or SDL_FALSE if not.
*
* \sa SDL_Has3DNow
* \sa SDL_HasAltiVec
* \sa SDL_HasAVX
* \sa SDL_HasAVX2
* \sa SDL_HasMMX
* \sa SDL_HasRDTSC
* \sa SDL_HasSSE
* \sa SDL_HasSSE2
* \sa SDL_HasSSE3
* \sa SDL_HasSSE41
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE42(void);
/**
* This function returns true if the CPU has AVX features.
* Determine whether the CPU has AVX features.
*
* This always returns false on CPUs that aren't using Intel instruction sets.
*
* \returns SDL_TRUE if the CPU has AVX features or SDL_FALSE if not.
*
* \since This function is available since SDL 2.0.2.
*
* \sa SDL_Has3DNow
* \sa SDL_HasAltiVec
* \sa SDL_HasAVX2
* \sa SDL_HasMMX
* \sa SDL_HasRDTSC
* \sa SDL_HasSSE
* \sa SDL_HasSSE2
* \sa SDL_HasSSE3
* \sa SDL_HasSSE41
* \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX(void);
/**
* This function returns true if the CPU has AVX2 features.
* Determine whether the CPU has AVX2 features.
*
* This always returns false on CPUs that aren't using Intel instruction sets.
*
* \returns SDL_TRUE if the CPU has AVX2 features or SDL_FALSE if not.
*
* \since This function is available since SDL 2.0.4.
*
* \sa SDL_Has3DNow
* \sa SDL_HasAltiVec
* \sa SDL_HasAVX
* \sa SDL_HasMMX
* \sa SDL_HasRDTSC
* \sa SDL_HasSSE
* \sa SDL_HasSSE2
* \sa SDL_HasSSE3
* \sa SDL_HasSSE41
* \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX2(void);
/**
* This function returns true if the CPU has AVX-512F (foundation) features.
* Determine whether the CPU has AVX-512F (foundation) features.
*
* This always returns false on CPUs that aren't using Intel instruction sets.
*
* \returns SDL_TRUE if the CPU has AVX-512F features or SDL_FALSE if not.
*
* \sa SDL_HasAVX
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX512F(void);
/**
* This function returns true if the CPU has ARM SIMD (ARMv6) features.
* Determine whether the CPU has ARM SIMD (ARMv6) features.
*
* This is different from ARM NEON, which is a different instruction set.
*
* This always returns false on CPUs that aren't using ARM instruction sets.
*
* \returns SDL_TRUE if the CPU has ARM SIMD features or SDL_FALSE if not.
*
* \sa SDL_HasNEON
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasARMSIMD(void);
/**
* This function returns true if the CPU has NEON (ARM SIMD) features.
* Determine whether the CPU has NEON (ARM SIMD) features.
*
* This always returns false on CPUs that aren't using ARM instruction sets.
*
* \returns SDL_TRUE if the CPU has ARM NEON features or SDL_FALSE if not.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasNEON(void);
/**
* This function returns the amount of RAM configured in the system, in MB.
* Get the amount of RAM configured in the system.
*
* \returns the amount of RAM configured in the system in MB.
*
* \since This function is available since SDL 2.0.1.
*/
extern DECLSPEC int SDLCALL SDL_GetSystemRAM(void);
/**
* \brief Report the alignment this system needs for SIMD allocations.
* Report the alignment this system needs for SIMD allocations.
*
* This will return the minimum number of bytes to which a pointer must be
* aligned to be compatible with SIMD instructions on the current machine.
@ -215,11 +416,13 @@ extern DECLSPEC int SDLCALL SDL_GetSystemRAM(void);
* SDL_HasAVX512F(), then it might return 16 for the SSE support it sees and
* not 64 for the AVX-512 instructions that exist but SDL doesn't know about.
* Plan accordingly.
*
* \returns Alignment in bytes needed for available, known SIMD instructions.
*/
extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void);
/**
* \brief Allocate memory in a SIMD-friendly way.
* Allocate memory in a SIMD-friendly way.
*
* This will allocate a block of memory that is suitable for use with SIMD
* instructions. Specifically, it will be properly aligned and padded for
@ -242,11 +445,12 @@ extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void);
* set with memory allocated through here.
*
* SDL_AllocSIMD(0) will return a non-NULL pointer, assuming the system isn't
* out of memory.
* out of memory, but you are not allowed to dereference it (because you only
* own zero bytes of that buffer).
*
* \param len The length, in bytes, of the block to allocated. The actual
* \param len The length, in bytes, of the block to allocate. The actual
* allocated block might be larger due to padding, etc.
* \return Pointer to newly-allocated block, NULL if out of memory.
* \returns Pointer to newly-allocated block, NULL if out of memory.
*
* \sa SDL_SIMDAlignment
* \sa SDL_SIMDRealloc
@ -255,7 +459,7 @@ extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void);
extern DECLSPEC void * SDLCALL SDL_SIMDAlloc(const size_t len);
/**
* \brief Reallocate memory obtained from SDL_SIMDAlloc
* Reallocate memory obtained from SDL_SIMDAlloc
*
* It is not valid to use this function on a pointer from anything but
* SDL_SIMDAlloc(). It can't be used on pointers from malloc, realloc,
@ -263,12 +467,12 @@ extern DECLSPEC void * SDLCALL SDL_SIMDAlloc(const size_t len);
*
* \param mem The pointer obtained from SDL_SIMDAlloc. This function also
* accepts NULL, at which point this function is the same as
* calling SDL_realloc with a NULL pointer.
* calling SDL_SIMDAlloc with a NULL pointer.
* \param len The length, in bytes, of the block to allocated. The actual
* allocated block might be larger due to padding, etc. Passing 0
* will return a non-NULL pointer, assuming the system isn't out of
* memory.
* \return Pointer to newly-reallocated block, NULL if out of memory.
* \returns Pointer to newly-reallocated block, NULL if out of memory.
*
* \sa SDL_SIMDAlignment
* \sa SDL_SIMDAlloc
@ -277,20 +481,27 @@ extern DECLSPEC void * SDLCALL SDL_SIMDAlloc(const size_t len);
extern DECLSPEC void * SDLCALL SDL_SIMDRealloc(void *mem, const size_t len);
/**
* \brief Deallocate memory obtained from SDL_SIMDAlloc
* Deallocate memory obtained from SDL_SIMDAlloc
*
* It is not valid to use this function on a pointer from anything but
* SDL_SIMDAlloc(). It can't be used on pointers from malloc, realloc,
* SDL_malloc, memalign, new[], etc.
* SDL_SIMDAlloc() or SDL_SIMDRealloc(). It can't be used on pointers from
* malloc, realloc, SDL_malloc, memalign, new[], etc.
*
* However, SDL_SIMDFree(NULL) is a legal no-op.
*
* The memory pointed to by `ptr` is no longer valid for access upon return,
* and may be returned to the system or reused by a future allocation.
* The pointer passed to this function is no longer safe to dereference once
* this function returns, and should be discarded.
*
* \param ptr The pointer, returned from SDL_SIMDAlloc or SDL_SIMDRealloc,
* to deallocate. NULL is a legal no-op.
*
* \sa SDL_SIMDAlloc
* \sa SDL_SIMDRealloc
*/
extern DECLSPEC void SDLCALL SDL_SIMDFree(void *ptr);
/* vi: set ts=4 sw=4 expandtab: */
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}

68
include/SDL_error.h
View File

@ -40,41 +40,83 @@ extern "C" {
/**
* \brief Set the error message for the current thread
* Set the SDL error message for the current thread.
*
* \return -1, there is no error handling for this function
* Calling this function will replace any previous error message that was set.
*
* This function always returns -1, since SDL frequently uses -1 to signify
* an failing result, leading to this idiom:
*
* ```c
* if (error_code) {
* return SDL_SetError("This operation has failed: %d", error_code);
* }
* ```
*
* \param fmt a printf()-style message format string
* \param ... additional parameters matching % tokens in the `fmt` string,
* if any
* \returns always -1.
*
* \sa SDL_ClearError
* \sa SDL_GetError
*/
extern DECLSPEC int SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
/**
* \brief Get the last error message that was set
* Retrieve a message about the last error that occurred on the current thread.
*
* SDL API functions may set error messages and then succeed, so you should
* only use the error value if a function fails.
* It is possible for multiple errors to occur before calling SDL_GetError().
* Only the last error is returned.
*
* This returns a pointer to a static buffer for convenience and should not
* be called by multiple threads simultaneously.
* The message is only applicable when an SDL function has signaled an error.
* You must check the return values of SDL function calls to determine when
* to appropriately call SDL_GetError(). You should _not_ use the results
* of SDL_GetError() to decide if an error has occurred! Sometimes SDL will
* set an error string even when reporting success.
*
* \return a pointer to the last error message that was set
* SDL will _not_ clear the error string for successful API calls. You _must_
* check return values for failure cases before you can assume the error
* string applies.
*
* Error strings are set per-thread, so an error set in a different thread
* will not interfere with the current thread's operation.
*
* The returned string is internally allocated and must not be freed by the
* application.
*
* \returns a message with information about the specific error that occurred,
* or an empty string if there hasn't been an error message set since
* the last call to SDL_ClearError(). The message is only applicable when an
* SDL function has signaled an error. You must check the return
* values of SDL function calls to determine when to appropriately
* call SDL_GetError().
*
* \sa SDL_ClearError
* \sa SDL_SetError
*/
extern DECLSPEC const char *SDLCALL SDL_GetError(void);
/**
* \brief Get the last error message that was set for the current thread
* Get the last error message that was set for the current thread.
*
* SDL API functions may set error messages and then succeed, so you should
* only use the error value if a function fails.
* This allows the caller to copy the error string into a provided buffer,
* but otherwise operates exactly the same as SDL_GetError().
*
* \param errstr A buffer to fill with the last error message that was set
* for the current thread
* \param maxlen The size of the buffer pointed to by the errstr parameter
* \returns The pointer passed in as the `errstr` parameter.
*
* \return errstr
* \sa SDL_GetError
*/
extern DECLSPEC char * SDLCALL SDL_GetErrorMsg(char *errstr, int maxlen);
/**
* \brief Clear the error message for the current thread
* Clear any previous error message for this thread.
*
* \sa SDL_GetError
* \sa SDL_SetError
*/
extern DECLSPEC void SDLCALL SDL_ClearError(void);

395
include/SDL_events.h
View File

@ -50,7 +50,7 @@ extern "C" {
#define SDL_PRESSED 1
/**
* \brief The types of events that can be delivered.
* The types of events that can be delivered.
*/
typedef enum
{
@ -637,11 +637,24 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == 56);
/* Function prototypes */
/**
* Pumps the event loop, gathering events from the input devices.
* Pump 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.
* **WARNING**: This should only be run in the thread that initialized the
* video subsystem, and for extra safety, you should consider only doing those
* things on the main thread in any case.
*
* SDL_PumpEvents() gathers all the pending input information from devices and
* places it in the event queue. Without calls to SDL_PumpEvents() no events
* would ever be placed on the queue. Often the need for calls to
* SDL_PumpEvents() is hidden from the user since SDL_PollEvent() and
* SDL_WaitEvent() implicitly call SDL_PumpEvents(). However, if you are not
* polling or waiting for events (e.g. you are filtering them), then you must
* call SDL_PumpEvents() to force an event queue update.
*
* \sa SDL_PollEvent
* \sa SDL_WaitEvent
*/
extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
@ -654,22 +667,42 @@ typedef enum
} SDL_eventaction;
/**
* Checks the event queue for messages and optionally returns them.
* Check the event queue for messages and optionally return them.
*
* If \c action is ::SDL_ADDEVENT, up to \c numevents events will be added to
* the back of the event queue.
* `action` may be any of the following:
*
* If \c action is ::SDL_PEEKEVENT, up to \c numevents events at the front
* of the event queue, within the specified minimum and maximum type,
* will be returned and will not be removed from the queue.
* - `SDL_ADDEVENT`: up to `numevents` events will be added to the back of
* the event queue.
*
* If \c action is ::SDL_GETEVENT, up to \c numevents events at the front
* of the event queue, within the specified minimum and maximum type,
* will be returned and will be removed from the queue.
* - `SDL_PEEKEVENT`: `numevents` events at the front of the event queue,
* within the specified minimum and maximum type, will be returned to the
* caller and will _not_ be removed from the queue.
*
* \return The number of events actually stored, or -1 if there was an error.
* - `SDL_GETEVENT`: up to `numevents` events at the front of the event queue,
* within the specified minimum and maximum type, will be returned to the
* caller and will be removed from the queue.
*
* You may have to call SDL_PumpEvents() before calling this function.
* Otherwise, the events may not be ready to be filtered when you call
* SDL_PeepEvents().
*
* This function is thread-safe.
*
* \param events destination buffer for the retrieved events
* \param numevents if action is SDL_ADDEVENT, the number of events to add
* back to the event queue; if action is SDL_PEEKEVENT or
* SDL_GETEVENT, the maximum number of events to retrieve
* \param action action to take; see [[#action|Remarks]] for details
* \param minType minimum value of the event type to be considered;
* SDL_FIRSTEVENT is a safe choice
* \param maxType maximum value of the event type to be considered;
* SDL_LASTEVENT is a safe choice
* \returns the number of events actually stored or a negative error code on
* failure; call SDL_GetError() for more information.
*
* \sa SDL_PollEvent
* \sa SDL_PumpEvents
* \sa SDL_PushEvent
*/
extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
SDL_eventaction action,
@ -677,113 +710,330 @@ extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
/* @} */
/**
* Checks to see if certain event types are in the event queue.
* Check for the existence of a certain event type in the event queue.
*
* If you need to check for a range of event types, use SDL_HasEvents()
* instead.
*
* \param type the type of event to be queried; see SDL_EventType for details
* \returns SDL_TRUE if events matching `type` are present, or SDL_FALSE if
* events matching `type` are not present.
*
* \sa SDL_HasEvents
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type);
/**
* Check for the existence of certain event types in the event queue.
*
* If you need to check for a single event type, use SDL_HasEvent() instead.
*
* \param minType the low end of event type to be queried, inclusive; see
* SDL_EventType for details
* \param maxType the high end of event type to be queried, inclusive; see
* SDL_EventType for details
* \returns SDL_TRUE if events with type >= `minType` and <= `maxType` are
* present, or SDL_FALSE if not.
*
* \sa SDL_HasEvents
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType);
/**
* This function clears events from the event queue
* Clear events of a specific type from the event queue.
*
* This will unconditionally remove any events from the queue that match
* `type`. If you need to remove a range of event types, use SDL_FlushEvents()
* instead.
*
* It's also normal to just ignore events you don't care about in your event
* loop without calling this function.
*
* This function only affects currently queued events. If you want to make
* sure that all pending OS events are flushed, you can call SDL_PumpEvents()
* on the main thread immediately before the flush call.
*
* \param type the type of event to be cleared; see SDL_EventType for details
*
* \sa SDL_FlushEvents
*/
extern DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type);
/**
* Clear events of a range of types from the event queue.
*
* This will unconditionally remove any events from the queue that are in the
* range of `minType` to `maxType`, inclusive. If you need to remove a single
* event type, use SDL_FlushEvent() instead.
*
* It's also normal to just ignore events you don't care about in your event
* loop without calling this function.
*
* This function only affects currently queued events. If you want to make
* sure that all pending OS events are flushed, you can call SDL_PumpEvents()
* on the main thread immediately before the flush call.
*
* \param minType the low end of event type to be cleared, inclusive; see
* SDL_EventType for details
* \param maxType the high end of event type to be cleared, inclusive; see
* SDL_EventType for details
*
* \sa SDL_FlushEvent
*/
extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
/**
* \brief Polls for currently pending events.
* Poll for currently pending events.
*
* \return 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 the SDL_Event structure pointed to by `event`. The 1 returned
* refers to this event, immediately stored in the SDL Event structure -- not
* an event to follow.
*
* \param event If not NULL, the next event is removed from the queue and
* stored in that area.
* If `event` is NULL, it simply returns 1 if there is an event in the queue,
* but will not remove it from the queue.
*
* As this function implicitly calls SDL_PumpEvents(), you can only call this
* function in the thread that set the video mode.
*
* SDL_PollEvent() is the favored way of receiving system events since it can
* be done from the main loop and does not suspend the main loop while waiting
* on an event to be posted.
*
* The common practice is to fully process the event queue once every frame,
* usually as a first step before updating the game's state:
*
* ```c
* while (game_is_still_running) {
* SDL_Event event;
* while (SDL_PollEvent(&event)) { // poll until all events are handled!
* // decide what to do with this event.
* }
*
* // update game state, draw the current frame
* }
* ```
*
* \param event the SDL_Event structure to be filled with the next event from
* the queue, or NULL
* \returns 1 if there is a pending event or 0 if there are none available.
*
* \sa SDL_GetEventFilter
* \sa SDL_PeepEvents
* \sa SDL_PushEvent
* \sa SDL_SetEventFilter
* \sa SDL_WaitEvent
* \sa SDL_WaitEventTimeout
*/
extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
/**
* \brief Waits indefinitely for the next available event.
* Wait indefinitely for the next available event.
*
* \return 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 the SDL_Event structure pointed to by `event`.
*
* \param event If not NULL, the next event is removed from the queue and
* stored in that area.
* As this function implicitly calls SDL_PumpEvents(), you can only call this
* function in the thread that initialized the video subsystem.
*
* \param event the SDL_Event structure to be filled in with the next event
* from the queue, or NULL
* \returns 1 on success or 0 if there was an error while waiting for events;
* call SDL_GetError() for more information.
*
* \sa SDL_PollEvent
* \sa SDL_PumpEvents
* \sa SDL_WaitEventTimeout
*/
extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
/**
* \brief Waits until the specified timeout (in milliseconds) for the next
* available event.
* Wait until the specified timeout (in milliseconds) for
* the next available event.
*
* \return 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 the SDL_Event structure pointed to by `event`.
*
* \param event If not NULL, the next event is removed from the queue and
* stored in that area.
* \param timeout The timeout (in milliseconds) to wait for next event.
* As this function implicitly calls SDL_PumpEvents(), you can only call this
* function in the thread that initialized the video subsystem.
*
* \param event the SDL_Event structure to be filled in with the next event
* from the queue, or NULL
* \param timeout the maximum number of milliseconds to wait for the next
* available event
* \returns 1 on success or 0 if there was an error while waiting for events;
* call SDL_GetError() for more information. This also returns 0 if
* the timeout elapsed without an event arriving.
*
* \sa SDL_PollEvent
* \sa SDL_PumpEvents
* \sa SDL_WaitEvent
*/
extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event,
int timeout);
/**
* \brief Add an event to the event queue.
* Add an event to the event queue.
*
* \return 1 on success, 0 if the event was filtered, or -1 if the event queue
* was full or there was some other error.
* The event queue can actually be used as a two way communication channel.
* Not only can events be read from the queue, but the user can also push
* their own events onto it. `event` is a pointer to the event structure you
* wish to push onto the queue. The event is copied into the queue, and the
* caller may dispose of the memory pointed to after SDL_PushEvent() returns.
*
* Note: Pushing device input events onto the queue doesn't modify the state
* of the device within SDL.
*
* This function is thread-safe, and can be called from other threads safely.
*
* Note: Events pushed onto the queue with SDL_PushEvent() get passed through
* the event filter but events added with SDL_PeepEvents() do not.
*
* For pushing application-specific events, please use SDL_RegisterEvents() to
* get an event type that does not conflict with other code that also wants
* its own custom event types.
*
* \param event the SDL_Event to be added to the queue
* \returns 1 on success, 0 if the event was filtered, or a negative error
* code on failure; call SDL_GetError() for more information. A
* common reason for error is the event queue being full.
*
* \sa SDL_PeepEvents
* \sa SDL_PollEvent
* \sa SDL_RegisterEvents
*/
extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
/**
* A function pointer used for callbacks that watch the event queue.
*
* \param userdata what was passed as `userdata` to SDL_SetEventFilter()
* or SDL_AddEventWatch, etc
* \param event the event that triggered the callback
* \returns Filters return 1 to permit event to be added to the queue, and
* 0 to disallow it. When used with SDL_AddEventWatch, the return
* value is ignored.
*
* \sa SDL_SetEventFilter
* \sa SDL_AddEventWatch
*/
typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
/**
* Sets up a filter to process all events before they change internal state and
* Set up a filter to process all events before they change internal state and
* are posted to the internal event queue.
*
* The filter is prototyped as:
* \code
* int SDL_EventFilter(void *userdata, SDL_Event * event);
* \endcode
* If the filter function returns 1 when called, 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.
*
* 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!
*
* \warning Be very careful of what you do in the event filter function, as
* it may run in a different thread!
* On platforms that support it, if the quit event is generated by an
* interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the
* application at the next event poll.
*
* There is one caveat when dealing with the ::SDL_QuitEvent event type. The
* event filter is only called when the window manager desires to close the
* application window. If the event filter returns 1, then the window will
* be closed, otherwise the window will remain open if possible.
*
* If the quit event is generated by an interrupt signal, it will bypass the
* internal queue and be delivered to the application at the next event poll.
* Note: Disabled events never make it to the event filter function; see
* SDL_EventState().
*
* Note: If you just want to inspect events without filtering, you should use
* SDL_AddEventWatch() instead.
*
* Note: Events pushed onto the queue with SDL_PushEvent() get passed through
* the event filter, but events pushed onto the queue with SDL_PeepEvents() do
* not.
*
* \param filter An SDL_EventFilter function to call when an event happens
* \param userdata a pointer that is passed to `filter`
*
* \sa SDL_AddEventWatch
* \sa SDL_EventState
* \sa SDL_GetEventFilter
* \sa SDL_PeepEvents
* \sa SDL_PushEvent
*/
extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
void *userdata);
/**
* Return the current event filter - can be used to "chain" filters.
* If there is no event filter set, this function returns SDL_FALSE.
* Query the current event filter.
*
* This function can be used to "chain" filters, by saving the existing filter
* before replacing it with a function that will call that saved filter.
*
* \param filter the current callback function will be stored here
* \param userdata the pointer that is passed to the current event filter will
* be stored here
* \returns SDL_TRUE on success or SDL_FALSE if there is no event filter set.
*
* \sa SDL_SetEventFilter
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
void **userdata);
/**
* Add a function which is called when an event is added to the queue.
* Add a callback to be triggered when an event is added to the event queue.
*
* `filter` will be called when an event happens, and its return value is
* ignored.
*
* **WARNING**: Be very careful of what you do in the event filter function,
* as it may run in a different thread!
*
* If the quit event is generated by a signal (e.g. SIGINT), it will bypass
* the internal queue and be delivered to the watch callback immediately, and
* arrive at the next event poll.
*
* Note: the callback is called for events posted by the user through
* SDL_PushEvent(), but not for disabled events, nor for events by a filter
* callback set with SDL_SetEventFilter(), nor for events posted by the user
* through SDL_PeepEvents().
*
* \param filter an SDL_EventFilter function to call when an event happens.
* \param userdata a pointer that is passed to `filter`
*
* \sa SDL_DelEventWatch
* \sa SDL_SetEventFilter
*/
extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter,
void *userdata);
/**
* Remove an event watch function added with SDL_AddEventWatch()
* Remove an event watch callback added with
* SDL_AddEventWatch().
*
* This function takes the same input as SDL_AddEventWatch() to identify and
* delete the corresponding callback.
*
* \param filter the function originally passed to SDL_AddEventWatch()
* \param userdata the pointer originally passed to SDL_AddEventWatch()
*
* \sa SDL_AddEventWatch
*/
extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter,
void *userdata);
/**
* Run the filter function on the current event queue, removing any
* events for which the filter returns 0.
* Run a specific filter function on the current event
* queue, removing any events for which the filter returns 0.
*
* See SDL_SetEventFilter() for more information. Unlike SDL_SetEventFilter(),
* this function does not change the filter permanently, it only uses the
* supplied filter until this function returns.
*
* \param filter the SDL_EventFilter function to call when an event happens
* \param userdata a pointer that is passed to `filter`
*
* \sa SDL_GetEventFilter
* \sa SDL_SetEventFilter
*/
extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
void *userdata);
@ -795,24 +1045,45 @@ extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
#define SDL_ENABLE 1
/**
* This function allows you to set the state of processing certain events.
* - If \c state is set to ::SDL_IGNORE, that event will be automatically
* dropped from the event queue and will not be filtered.
* - If \c state is set to ::SDL_ENABLE, that event will be processed
* normally.
* - If \c state is set to ::SDL_QUERY, SDL_EventState() will return the
* current processing state of the specified event.
* Set the state of processing events by type.
*
* `state` may be any of the following:
*
* - `SDL_QUERY`: returns the current processing state of the specified event
*
* - `SDL_IGNORE` (aka `SDL_DISABLE`): the event will automatically be dropped
* from the event queue and will not be filtered
*
* - `SDL_ENABLE`: the event will be processed normally
*
* \param type the type of event; see SDL_EventType for details
* \param state how to process the event
* \returns `SDL_DISABLE` or `SDL_ENABLE`, representing the processing state
* of the event before this function makes any changes to it.
*
* \sa SDL_GetEventState
*/
extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state);
/* @} */
#define SDL_GetEventState(type) SDL_EventState(type, SDL_QUERY)
/**
* This function allocates a set of user-defined events, and returns
* the beginning event number for that set of events.
* Allocate a set of user-defined events, and return the beginning event
* number for that set of events.
*
* If there aren't enough user-defined events left, this function
* returns (Uint32)-1
* Calling this function with `numevents` <= 0 is an error and will return
* (Uint32)-1.
*
* Note, (Uint32)-1 means the maximum unsigned 32-bit integer value (or
* 0xFFFFFFFF), but is clearer to write.
*
* \param numevents the number of events to be allocated
* \returns The beginning event number, or (Uint32)-1 if there are not enough
* user-defined events left.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_PushEvent
*/
extern DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);

106
include/SDL_filesystem.h
View File

@ -38,32 +38,49 @@ extern "C" {
#endif
/**
* \brief Get the path where the application resides.
* Get the directory where the application was run from.
*
* Get the "base path". This is the directory where the application was run
* from, which is probably the installation directory, and may or may not
* be the process's current working directory.
* This is not necessarily a fast call, so you should call this once near
* startup and save the string if you need it.
*
* This returns an absolute path in UTF-8 encoding, and is guaranteed to
* end with a path separator ('\\' on Windows, '/' most other places).
* **Mac OS X and iOS Specific Functionality**: If the application is in a
* ".app" bundle, this function returns the Resource directory (e.g.
* MyApp.app/Contents/Resources/). This behaviour can be overridden by adding
* a property to the Info.plist file. Adding a string key with the name
* SDL_FILESYSTEM_BASE_DIR_TYPE with a supported value will change the
* behaviour.
*
* The pointer returned by this function is owned by you. Please call
* SDL_free() on the pointer when you are done with it, or it will be a
* memory leak. This is not necessarily a fast call, though, so you should
* call this once near startup and save the string if you need it.
* Supported values for the SDL_FILESYSTEM_BASE_DIR_TYPE property (Given an
* application in /Applications/SDLApp/MyApp.app):
*
* Some platforms can't determine the application's path, and on other
* platforms, this might be meaningless. In such cases, this function will
* return NULL.
* - `resource`: bundle resource directory (the default). For example:
* `/Applications/SDLApp/MyApp.app/Contents/Resources`
*
* \return String of base dir in UTF-8 encoding, or NULL on error.
* - `bundle`: the Bundle directory. Fpr example:
* `/Applications/SDLApp/MyApp.app/`
*
* - `parent`: the containing directory of the bundle. For example:
* `/Applications/SDLApp/`
*
* The returned path is guaranteed to end with a path separator ('\' on
* Windows, '/' on most other platforms).
*
* The pointer returned is owned by the caller. Please call SDL_free() on
* the pointer when done with it.
*
* \returns an absolute path in UTF-8 encoding to the application data
* directory. NULL will be returned on error or when the platform
* doesn't implement this functionality, call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 2.0.1.
*
* \sa SDL_GetPrefPath
*/
extern DECLSPEC char *SDLCALL SDL_GetBasePath(void);
/**
* \brief Get the user-and-app-specific path where files can be written.
* Get the user-and-app-specific path where files can be written.
*
* Get the "pref dir". This is meant to be where users can write personal
* files (preferences and save games, etc) that are specific to your
@ -74,52 +91,49 @@ extern DECLSPEC char *SDLCALL SDL_GetBasePath(void);
* path to the directory in UTF-8 encoding.
*
* On Windows, the string might look like:
* "C:\\Users\\bob\\AppData\\Roaming\\My Company\\My Program Name\\"
*
* On Linux, the string might look like:
* "/home/bob/.local/share/My Program Name/"
* `C:\\Users\\bob\\AppData\\Roaming\\My Company\\My Program Name\\`
*
* On Linux, the string might look like"
*
* `/home/bob/.local/share/My Program Name/`
*
* On Mac OS X, the string might look like:
* "/Users/bob/Library/Application Support/My Program Name/"
*
* (etc.)
* `/Users/bob/Library/Application Support/My Program Name/`
*
* You specify the name of your organization (if it's not a real organization,
* your name or an Internet domain you own might do) and the name of your
* application. These should be untranslated proper names.
* You should assume the path returned by this function is the only safe place
* to write files (and that SDL_GetBasePath(), while it might be writable, or
* even the parent of the returned path, isn't where you should be writing
* things).
*
* Both the org and app strings may become part of a directory name, so
* please follow these rules:
* Both the org and app strings may become part of a directory name, so please
* follow these rules:
*
* - Try to use the same org string (_including case-sensitivity_) for all
* your applications that use this function.
*
* - Try to use the same org string (including case-sensitivity) for
* all your applications that use this function.
* - Always use a unique app string for each one, and make sure it never
* changes for an app once you've decided on it.
*
* - Unicode characters are legal, as long as it's UTF-8 encoded, but...
* - ...only use letters, numbers, and spaces. Avoid punctuation like
* "Game Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient.
*
* This returns an absolute path in UTF-8 encoding, and is guaranteed to
* end with a path separator ('\\' on Windows, '/' most other places).
* - ...only use letters, numbers, and spaces. Avoid punctuation like "Game
* Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient.
*
* The pointer returned by this function is owned by you. Please call
* SDL_free() on the pointer when you are done with it, or it will be a
* memory leak. This is not necessarily a fast call, though, so you should
* call this once near startup and save the string if you need it.
* The returned path is guaranteed to end with a path separator ('\' on
* Windows, '/' on most other platforms).
*
* You should assume the path returned by this function is the only safe
* place to write files (and that SDL_GetBasePath(), while it might be
* writable, or even the parent of the returned path, aren't where you
* should be writing things).
* The pointer returned is owned by the caller. Please call SDL_free() on
* the pointer when done with it.
*
* Some platforms can't determine the pref path, and on other
* platforms, this might be meaningless. In such cases, this function will
* return NULL.
* \param org the name of your organization
* \param app the name of your application
* \returns a UTF-8 string of the user directory in platform-dependent
* notation. NULL if there's a problem (creating directory failed,
* etc.).
*
* \param org The name of your organization.
* \param app The name of your application.
* \return UTF-8 string of user dir in platform-dependent notation. NULL
* if there's a problem (creating directory failed, etc).
* \since This function is available since SDL 2.0.1.
*
* \sa SDL_GetBasePath
*/

450
include/SDL_gamecontroller.h
View File

@ -124,12 +124,32 @@ typedef struct SDL_GameControllerButtonBind
*/
/**
* Load a set of mappings from a seekable SDL data stream (memory or file), filtered by the current SDL_GetPlatform()
* A community sourced database of controllers is available at https://raw.github.com/gabomdq/SDL_GameControllerDB/master/gamecontrollerdb.txt
* Load a set of Game Controller mappings from a seekable SDL data stream.
*
* If \c freerw is non-zero, the stream will be closed after being read.
* You can call this function several times, if needed, to load different
* database files.
*
* \return number of mappings added, -1 on error
* If a new mapping is loaded for an already known controller GUID, the later
* version will overwrite the one currently loaded.
*
* Mappings not belonging to the current platform or with no platform field
* specified will be ignored (i.e. mappings for Linux will be ignored in
* Windows, etc).
*
* This function will load the text database entirely in memory before
* processing it, so take this into consideration if you are in a memory
* constrained environment.
*
* \param rw the data stream for the mappings to be added
* \param freerw non-zero to close the stream after being read
* \returns the number of mappings added or -1 on error; call SDL_GetError()
* for more information.
*
* \since This function is available since SDL 2.0.2.
*
* \sa SDL_GameControllerAddMapping
* \sa SDL_GameControllerAddMappingsFromFile
* \sa SDL_GameControllerMappingForGUID
*/
extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw, int freerw);
@ -141,124 +161,267 @@ extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw,
#define SDL_GameControllerAddMappingsFromFile(file) SDL_GameControllerAddMappingsFromRW(SDL_RWFromFile(file, "rb"), 1)
/**
* Add or update an existing mapping configuration
* Add support for controllers that SDL is unaware of or
* to cause an existing controller to have a different binding.
*
* \return 1 if mapping is added, 0 if updated, -1 on error
* The mapping string has the format "GUID,name,mapping", where GUID is the
* string value from SDL_JoystickGetGUIDString(), name is the human readable
* string for the device and mappings are controller mappings to joystick
* ones. Under Windows there is a reserved GUID of "xinput" that covers all
* XInput devices. The mapping format for joystick is: {| |bX |a joystick
* button, index X |- |hX.Y |hat X with value Y |- |aX |axis X of the joystick
* |} Buttons can be used as a controller axes and vice versa.
*
* This string shows an example of a valid mapping for a controller:
*
* ```
* "341a3608000000000000504944564944,Afterglow PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7"
* ```
*
* \param mappingString the mapping string
* \returns 1 if a new mapping is added, 0 if an existing mapping is updated,
* -1 on error; call SDL_GetError() for more information.
*
* \sa SDL_GameControllerMapping
* \sa SDL_GameControllerMappingForGUID
*/
extern DECLSPEC int SDLCALL SDL_GameControllerAddMapping(const char* mappingString);
/**
* Get the number of mappings installed
* Get the number of mappings installed.
*
* \return the number of mappings
* \returns the number of mappings.
*/
extern DECLSPEC int SDLCALL SDL_GameControllerNumMappings(void);
/**
* Get the mapping at a particular index.
*
* \return the mapping string. Must be freed with SDL_free(). Returns NULL if the index is out of range.
* \returns the mapping string. Must be freed with SDL_free().
* Returns NULL if the index is out of range.
*/
extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForIndex(int mapping_index);
/**
* Get a mapping string for a GUID
* Get the game controller mapping string for a given GUID.
*
* \return the mapping string. Must be freed with SDL_free(). Returns NULL if no mapping is available
* The returned string must be freed with SDL_free().
*
* \param guid a structure containing the GUID for which a mapping is desired
* \returns a mapping string or NULL on error; call SDL_GetError() for more
* information.
*
* \sa SDL_JoystickGetDeviceGUID
* \sa SDL_JoystickGetGUID
*/
extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForGUID(SDL_JoystickGUID guid);
/**
* Get a mapping string for an open GameController
* Get the current mapping of a Game Controller.
*
* \return the mapping string. Must be freed with SDL_free(). Returns NULL if no mapping is available
* The returned string must be freed with SDL_free().
*
* Details about mappings are discussed with SDL_GameControllerAddMapping().
*
* \param gamecontroller the game controller you want to get the current
* mapping for
* \returns a string that has the controller's mapping or NULL if no mapping
* is available; call SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_GameControllerAddMapping
* \sa SDL_GameControllerMappingForGUID
*/
extern DECLSPEC char * SDLCALL SDL_GameControllerMapping(SDL_GameController *gamecontroller);
/**
* Is the joystick on this index supported by the game controller interface?
* Check if the given joystick is supported by the game controller interface.
*
* `joystick_index` is the same as the `device_index` passed to
* SDL_JoystickOpen().
*
* \param joystick_index the device_index of a device, up to
* SDL_NumJoysticks()
* \returns SDL_TRUE if the given joystick is supported by the game controller
* interface, SDL_FALSE if it isn't or it's an invalid index.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_GameControllerNameForIndex
* \sa SDL_GameControllerOpen
*/
extern DECLSPEC SDL_bool SDLCALL SDL_IsGameController(int joystick_index);
/**
* Get the implementation dependent name of a game controller.
* This can be called before any controllers are opened.
* If no name can be found, this function returns NULL.
* Get the implementation dependent name for the game
* controller.
*
* This function can be called before any controllers are opened.
*
* `joystick_index` is the same as the `device_index` passed to
* SDL_JoystickOpen().
*
* \param joystick_index the device_index of a device, from zero to
* SDL_NumJoysticks()-1
* \returns the implementation-dependent name for the game controller, or NULL
* if there is no name or the index is invalid.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_GameControllerName
* \sa SDL_GameControllerOpen
* \sa SDL_IsGameController
*/
extern DECLSPEC const char *SDLCALL SDL_GameControllerNameForIndex(int joystick_index);
/**
* Get the type of a game controller.
*
* This can be called before any controllers are opened.
*
* \param joystick_index the device_index of a device, from zero to
* SDL_NumJoysticks()-1
* \returns the controller type.
*/
extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerTypeForIndex(int joystick_index);
/**
* Get the mapping of a game controller.
*
* This can be called before any controllers are opened.
*
* \return the mapping string. Must be freed with SDL_free(). Returns NULL if no mapping is available
* \param joystick_index the device_index of a device, from zero to
* SDL_NumJoysticks()-1
* \returns the mapping string. Must be freed with SDL_free(). Returns NULL
* if no mapping is available.
*/
extern DECLSPEC char *SDLCALL SDL_GameControllerMappingForDeviceIndex(int joystick_index);
/**
* Open a game controller for use.
* The index passed as an argument refers to the N'th game controller on the system.
* This index is not the value which will identify this controller in future
* controller events. The joystick's instance id (::SDL_JoystickID) will be
* used there instead.
*
* \return A controller identifier, or NULL if an error occurred.
* `joystick_index` is the same as the `device_index` passed to
* SDL_JoystickOpen().
*
* The index passed as an argument refers to the N'th game controller on the
* system. This index is not the value which will identify this controller in
* future controller events. The joystick's instance id (SDL_JoystickID) will
* be used there instead.
*
* \param joystick_index the device_index of a device, up to
* SDL_NumJoysticks()
* \returns a gamecontroller identifier or NULL if an error occurred; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_GameControllerClose
* \sa SDL_GameControllerNameForIndex
* \sa SDL_IsGameController
*/
extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerOpen(int joystick_index);
/**
* Return the SDL_GameController associated with an instance id.
* Get the SDL_GameController associated with an instance id.
*
* \param joyid the instance id to get the SDL_GameController for
* \returns an SDL_GameController on success or NULL on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.4.
*/
extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromInstanceID(SDL_JoystickID joyid);
/**
* Return the SDL_GameController associated with a player index.
* Get the SDL_GameController associated with a player index.
*
* Please note that the player index is _not_ the device index, nor is it
* the instance id!
*
* \param player_index the player index, which is not the device index or
* the instance id!
* \returns the SDL_GameController associated with a player index.
*
* \sa SDL_GameControllerGetPlayerIndex
* \sa SDL_GameControllerSetPlayerIndex
*/
extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromPlayerIndex(int player_index);
/**
* Return the name for this currently opened controller
* Get the implementation-dependent name for an opened game controller.
*
* This is the same name as returned by SDL_GameControllerNameForIndex(), but
* it takes a controller identifier instead of the (unstable) device index.
*
* \param gamecontroller a game controller identifier previously returned by
* SDL_GameControllerOpen()
* \returns the implementation dependent name for the game controller, or NULL
* if there is no name or the identifier passed is invalid.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_GameControllerNameForIndex
* \sa SDL_GameControllerOpen
*/
extern DECLSPEC const char *SDLCALL SDL_GameControllerName(SDL_GameController *gamecontroller);
/**
* Return the type of this currently opened controller
* Get the type of this currently opened controller
*
* This is the same name as returned by SDL_GameControllerTypeForIndex(), but
* it takes a controller identifier instead of the (unstable) device index.
*
* \param gamecontroller the game controller object to query.
* \returns the controller type.
*/
extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerGetType(SDL_GameController *gamecontroller);
/**
* Get the player index of an opened game controller, or -1 if it's not available
* Get the player index of an opened game controller.
*
* For XInput controllers this returns the XInput user index.
*
* \param gamecontroller the game controller object to query.
* \returns player index for controller, or -1 if it's not available.
*/
extern DECLSPEC int SDLCALL SDL_GameControllerGetPlayerIndex(SDL_GameController *gamecontroller);
/**
* Set the player index of an opened game controller
* Set the player index of an opened game controller.
*
* \param gamecontroller the game controller object to adjust.
* \param player_index Player index to assign to this controller.
*/
extern DECLSPEC void SDLCALL SDL_GameControllerSetPlayerIndex(SDL_GameController *gamecontroller, int player_index);
/**
* Get the USB vendor ID of an opened controller, if available.
*
* If the vendor ID isn't available this function returns 0.
*
* \param gamecontroller the game controller object to query.
* \return USB vendor ID, or zero if unavailable.
*/
extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetVendor(SDL_GameController *gamecontroller);
/**
* Get the USB product ID of an opened controller, if available.
*
* If the product ID isn't available this function returns 0.
*
* \param gamecontroller the game controller object to query.
* \return USB product ID, or zero if unavailable.
*/
extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProduct(SDL_GameController *gamecontroller);
/**
* Get the product version of an opened controller, if available.
*
* If the product version isn't available this function returns 0.
*
* \param gamecontroller the game controller object to query.
* \return USB product version, or zero if unavailable.
*/
extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProductVersion(SDL_GameController *gamecontroller);
@ -266,36 +429,70 @@ extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProductVersion(SDL_GameContr
* Get the serial number of an opened controller, if available.
*
* Returns the serial number of the controller, or NULL if it is not available.
*
* \param gamecontroller the game controller object to query.
* \return Serial number, or NULL if unavailable.
*/
extern DECLSPEC const char * SDLCALL SDL_GameControllerGetSerial(SDL_GameController *gamecontroller);
/**
* Returns SDL_TRUE if the controller has been opened and currently connected,
* or SDL_FALSE if it has not.
* Check if a controller has been opened and is currently connected.
*
* \param gamecontroller a game controller identifier previously returned by
* SDL_GameControllerOpen()
* \returns SDL_TRUE if the controller has been opened and is currently
* connected, or SDL_FALSE if not.
*
* \sa SDL_GameControllerClose
* \sa SDL_GameControllerOpen
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerGetAttached(SDL_GameController *gamecontroller);
/**
* Get the underlying joystick object used by a controller
* Get the Joystick ID from a Game Controller.
*
* This function will give you a SDL_Joystick object, which allows you to use
* the SDL_Joystick functions with a SDL_GameController object. This would be
* useful for getting a joystick's position at any given time, even if it
* hasn't moved (moving it would produce an event, which would have the axis'
* value).
*
* The pointer returned is owned by the SDL_GameController. You should not
* call SDL_JoystickClose() on it, for example, since doing so will likely
* cause SDL to crash.
*
* \param gamecontroller the game controller object that you want to get a
* joystick from
* \returns a SDL_Joystick object; call SDL_GetError() for more information.
*/
extern DECLSPEC SDL_Joystick *SDLCALL SDL_GameControllerGetJoystick(SDL_GameController *gamecontroller);
/**
* Enable/disable controller event polling.
* Query or change current state of Game Controller events.
*
* If controller events are disabled, you must call SDL_GameControllerUpdate()
* yourself and check the state of the controller when you want controller
* information.
*
* The state can be one of ::SDL_QUERY, ::SDL_ENABLE or ::SDL_IGNORE.
* Any number can be passed to SDL_GameControllerEventState(), but only -1, 0,
* and 1 will have any effect. Other numbers will just be returned.
*
* \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`
* \returns the same value passed to the function, with exception to -1
* (SDL_QUERY), which will return the current state.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_JoystickEventState
*/
extern DECLSPEC int SDLCALL SDL_GameControllerEventState(int state);
/**
* Update the current state of the open game controllers.
* Manually pump game controller updates if not using the loop.
*
* This is called automatically by the event loop if any game controller
* events are enabled.
* This function is called automatically by the event loop if events are
* enabled. Under such circumstances, it will not be necessary to call this
* function.
*/
extern DECLSPEC void SDLCALL SDL_GameControllerUpdate(void);
@ -322,24 +519,61 @@ typedef enum
} SDL_GameControllerAxis;
/**
* turn this string into a axis mapping
* Convert a string into SDL_GameControllerAxis enum.
*
* This function is called internally to translate SDL_GameController mapping
* strings for the underlying joystick device into the consistent
* SDL_GameController mapping. You do not normally need to call this function
* unless you are parsing SDL_GameController mappings in your own code.
*
* \param str string representing a SDL_GameController axis
* \returns the SDL_GameControllerAxis enum corresponding to the input string,
* or `SDL_CONTROLLER_AXIS_INVALID` if no match was found.
*
* \sa SDL_GameControllerGetStringForAxis
*/
extern DECLSPEC SDL_GameControllerAxis SDLCALL SDL_GameControllerGetAxisFromString(const char *pchString);
extern DECLSPEC SDL_GameControllerAxis SDLCALL SDL_GameControllerGetAxisFromString(const char *str);
/**
* turn this axis enum into a string mapping
* Convert from an SDL_GameControllerAxis enum to a string.
*
* The caller should not SDL_free() the returned string.
*
* \param axis an enum value for a given SDL_GameControllerAxis
* \returns a string for the given axis, or NULL if an invalid axis is
* specified. The string returned is of the format used by
* SDL_GameController mapping strings.
*
* \sa SDL_GameControllerGetAxisFromString
*/
extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForAxis(SDL_GameControllerAxis axis);
/**
* Get the SDL joystick layer binding for this controller button mapping
* Get the SDL joystick layer binding for a controller axis mapping.
*
* \param gamecontroller a game controller
* \param axis an axis enum value (one of the SDL_GameControllerAxis values)
* \returns a SDL_GameControllerButtonBind describing the bind. On
* failure (like the given Controller axis doesn't exist on the
* device), its `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_GameControllerGetBindForButton
*/
extern DECLSPEC SDL_GameControllerButtonBind SDLCALL
SDL_GameControllerGetBindForAxis(SDL_GameController *gamecontroller,
SDL_GameControllerAxis axis);
/**
* Return whether a game controller has a given axis
* Query whether a game controller has a given axis.
*
* This merely reports whether the controller's mapping defined this axis, as
* that is all the information SDL has about the physical device.
*
* \param gamecontroller a game controller
* \param axis an axis enum value (an SDL_GameControllerAxis value)
* \returns SDL_TRUE if the controller has this axis, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL
SDL_GameControllerHasAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis);
@ -347,10 +581,19 @@ SDL_GameControllerHasAxis(SDL_GameController *gamecontroller, SDL_GameController
/**
* Get the current state of an axis control on a game controller.
*
* The state is a value ranging from -32768 to 32767 (except for the triggers,
* which range from 0 to 32767).
*
* The axis indices start at index 0.
*
* The state is a value ranging from -32768 to 32767. Triggers, however, range
* from 0 to 32767 (they never return a negative value).
*
* \param gamecontroller a game controller
* \param axis an axis index (one of the SDL_GameControllerAxis values)
* \returns axis state (including 0) on success or 0 (also) on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_GameControllerGetButton
*/
extern DECLSPEC Sint16 SDLCALL
SDL_GameControllerGetAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis);
@ -386,24 +629,62 @@ typedef enum
} SDL_GameControllerButton;
/**
* turn this string into a button mapping
* Convert a string into an SDL_GameControllerButton enum.
*
* This function is called internally to translate SDL_GameController mapping
* strings for the underlying joystick device into the consistent
* SDL_GameController mapping. You do not normally need to call this function
* unless you are parsing SDL_GameController mappings in your own code.
*
* \param str string representing a SDL_GameController axis
* \returns the SDL_GameControllerButton enum corresponding to the input
* string, or `SDL_CONTROLLER_AXIS_INVALID` if no match was found.
*
*/
extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFromString(const char *pchString);
extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFromString(const char *str);
/**
* turn this button enum into a string mapping
* Convert from an SDL_GameControllerButton enum to a string.
*
* The caller should not SDL_free() the returned string.
*
* \param button an enum value for a given SDL_GameControllerButton
* \returns a string for the given button, or NULL if an invalid axis is
* specified. The string returned is of the format used by
* SDL_GameController mapping strings.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_GameControllerGetButtonFromString
*/
extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForButton(SDL_GameControllerButton button);
/**
* Get the SDL joystick layer binding for this controller button mapping
* Get the SDL joystick layer binding for a controller button mapping.
*
* \param gamecontroller a game controller
* \param button an button enum value (an SDL_GameControllerButton value)
* \returns a SDL_GameControllerButtonBind describing the bind. On
* failure (like the given Controller button doesn't exist on the
* device), its `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_GameControllerGetBindForAxis
*/
extern DECLSPEC SDL_GameControllerButtonBind SDLCALL
SDL_GameControllerGetBindForButton(SDL_GameController *gamecontroller,
SDL_GameControllerButton button);
/**
* Return whether a game controller has a given button
* Query whether a game controller has a given button.
*
* This merely reports whether the controller's mapping defined this button,
* as that is all the information SDL has about the physical device.
*
* \param gamecontroller a game controller
* \param button a button enum value (an SDL_GameControllerButton value)
* \returns SDL_TRUE if the controller has this button, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasButton(SDL_GameController *gamecontroller,
SDL_GameControllerButton button);
@ -411,7 +692,14 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasButton(SDL_GameController
/**
* Get the current state of a button on a game controller.
*
* The button indices start at index 0.
* \param gamecontroller a game controller
* \param button a button index (one of the SDL_GameControllerButton values)
* \returns 1 for pressed state or 0 for not pressed state or error; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_GameControllerGetAxis
*/
extern DECLSPEC Uint8 SDLCALL SDL_GameControllerGetButton(SDL_GameController *gamecontroller,
SDL_GameControllerButton button);
@ -437,28 +725,28 @@ extern DECLSPEC int SDLCALL SDL_GameControllerGetTouchpadFinger(SDL_GameControll
* \param gamecontroller The controller to query
* \param type The type of sensor to query
*
* \return SDL_TRUE if the sensor exists, SDL_FALSE otherwise.
* \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasSensor(SDL_GameController *gamecontroller, SDL_SensorType type);
/**
* Set whether data reporting for a game controller sensor is enabled
* Set whether data reporting for a game controller sensor is enabled.
*
* \param gamecontroller The controller to update
* \param type The type of sensor to enable/disable
* \param enabled Whether data reporting should be enabled
*
* \return 0 or -1 if an error occurred.
* \returns 0 or -1 if an error occurred.
*/
extern DECLSPEC int SDLCALL SDL_GameControllerSetSensorEnabled(SDL_GameController *gamecontroller, SDL_SensorType type, SDL_bool enabled);
/**
* Query whether sensor data reporting is enabled for a game controller
* Query whether sensor data reporting is enabled for a game controller.
*
* \param gamecontroller The controller to query
* \param type The type of sensor to query
*
* \return SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise.
* \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerIsSensorEnabled(SDL_GameController *gamecontroller, SDL_SensorType type);
@ -472,64 +760,76 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerIsSensorEnabled(SDL_GameContr
* \param type The type of sensor to query
* \param data A pointer filled with the current sensor state
* \param num_values The number of values to write to data
*
* \return 0 or -1 if an error occurred.
*/
extern DECLSPEC int SDLCALL SDL_GameControllerGetSensorData(SDL_GameController *gamecontroller, SDL_SensorType type, float *data, int num_values);
/**
* Start a rumble effect
* Each call to this function cancels any previous rumble effect, and calling it with 0 intensity stops any rumbling.
* Start a rumble effect on a game controller.
*
* Each call to this function cancels any previous rumble effect, and calling
* it with 0 intensity stops any rumbling.
*
* \param gamecontroller The controller to vibrate
* \param low_frequency_rumble The intensity of the low frequency (left) rumble motor, from 0 to 0xFFFF
* \param high_frequency_rumble The intensity of the high frequency (right) rumble motor, from 0 to 0xFFFF
* \param low_frequency_rumble The intensity of the low frequency (left)
* rumble motor, from 0 to 0xFFFF
* \param high_frequency_rumble The intensity of the high frequency (right)
* rumble motor, from 0 to 0xFFFF
* \param duration_ms The duration of the rumble effect, in milliseconds
*
* \return 0, or -1 if rumble isn't supported on this controller
* \returns 0, or -1 if rumble isn't supported on this controller
*/
extern DECLSPEC int SDLCALL SDL_GameControllerRumble(SDL_GameController *gamecontroller, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms);
/**
* Start a rumble effect in the game controller's triggers
* Each call to this function cancels any previous trigger rumble effect, and calling it with 0 intensity stops any rumbling.
* Start a rumble effect in the game controller's triggers.
*
* Each call to this function cancels any previous trigger rumble effect, and
* calling it with 0 intensity stops any rumbling.
*
* Note that this is rumbling of the _triggers_ and not the game controller as
* a whole. The first controller to offer this feature was the PlayStation 5's
* DualShock 5.
*
* \param gamecontroller The controller to vibrate
* \param left_rumble The intensity of the left trigger rumble motor, from 0 to 0xFFFF
* \param left_rumble The intensity of the left trigger rumble motor, from 0
* to 0xFFFF
* \param right_rumble The intensity of the right trigger rumble motor, from 0 to 0xFFFF
* \param duration_ms The duration of the rumble effect, in milliseconds
*
* \return 0, or -1 if rumble isn't supported on this controller
* \returns 0, or -1 if trigger rumble isn't supported on this controller
*/
extern DECLSPEC int SDLCALL SDL_GameControllerRumbleTriggers(SDL_GameController *gamecontroller, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms);
/**
* Return whether a controller has an LED
* Query whether a game controller has an LED.
*
* \param gamecontroller The controller to query
*
* \return SDL_TRUE, or SDL_FALSE if this controller does not have a modifiable LED
* \returns SDL_TRUE, or SDL_FALSE if this controller does not have a
* modifiable LED
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasLED(SDL_GameController *gamecontroller);
/**
* Update a controller's LED color.
* Update a game controller's LED color.
*
* \param gamecontroller The controller to update
* \param red The intensity of the red LED
* \param green The intensity of the green LED
* \param blue The intensity of the blue LED
*
* \return 0, or -1 if this controller does not have a modifiable LED
* \returns 0, or -1 if this controller does not have a modifiable LED
*/
extern DECLSPEC int SDLCALL SDL_GameControllerSetLED(SDL_GameController *gamecontroller, Uint8 red, Uint8 green, Uint8 blue);
/**
* Close a controller previously opened with SDL_GameControllerOpen().
* Close a game controller previously opened with SDL_GameControllerOpen().
*
* \param gamecontroller a game controller identifier previously returned by
* SDL_GameControllerOpen()
*
* \sa SDL_GameControllerOpen
*/
extern DECLSPEC void SDLCALL SDL_GameControllerClose(SDL_GameController *gamecontroller);
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}

40
include/SDL_gesture.h
View File

@ -46,36 +46,66 @@ typedef Sint64 SDL_GestureID;
/* Function prototypes */
/**
* \brief Begin Recording a gesture on the specified touch, or all touches (-1)
* Begin recording a gesture on a specified touch device or all touch devices.
*
* If the parameter `touchId` is -1 (i.e., all devices), this function will
* always return 1, regardless of whether there actually are any devices.
*
* \param touchId the touch device id, or -1 for all touch devices
* \returns 1 on success or 0 if the specified device could not be found.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_GetTouchDevice
*/
extern DECLSPEC int SDLCALL SDL_RecordGesture(SDL_TouchID touchId);
/**
* \brief Save all currently loaded Dollar Gesture templates
* Save all currently loaded Dollar Gesture templates.
*
* \param dst a SDL_RWops to save to
* \returns the number of saved templates on success or 0 on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_LoadDollarTemplates
* \sa SDL_SaveDollarTemplate
*/
extern DECLSPEC int SDLCALL SDL_SaveAllDollarTemplates(SDL_RWops *dst);
/**
* \brief Save a currently loaded Dollar Gesture template
* Save a currently loaded Dollar Gesture template.
*
* \param gestureId a gesture id
* \param dst a SDL_RWops to save to
* \returns 1 on success or 0 on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_LoadDollarTemplates
* \sa SDL_SaveAllDollarTemplates
*/
extern DECLSPEC int SDLCALL SDL_SaveDollarTemplate(SDL_GestureID gestureId,SDL_RWops *dst);
/**
* \brief Load Dollar Gesture templates from a file
* Load Dollar Gesture templates from a file.
*
* \param touchId a touch id
* \param src a SDL_RWops to load from
* \returns the number of loaded templates on success or a negative error code
* (or 0) on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_SaveAllDollarTemplates
* \sa SDL_SaveDollarTemplate
*/
extern DECLSPEC int SDLCALL SDL_LoadDollarTemplates(SDL_TouchID touchId, SDL_RWops *src);
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}

366
include/SDL_haptic.h
View File

@ -821,65 +821,82 @@ typedef union SDL_HapticEffect
/* Function prototypes */
/**
* \brief Count the number of haptic devices attached to the system.
* Count the number of haptic devices attached to the system.
*
* \return Number of haptic devices detected on the system.
* \returns the number of haptic devices detected on the system or a negative
* error code on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_HapticName
*/
extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
/**
* \brief Get the implementation dependent name of a haptic device.
* Get the implementation dependent name of a haptic device.
*
* This can be called before any joysticks are opened.
* If no name can be found, this function returns NULL.
* This can be called before any joysticks are opened. If no name can be
* found, this function returns NULL.
*
* \param device_index Index of the device to get its name.
* \return Name of the device or NULL on error.
* \param device_index index of the device to query.
* \returns the name of the device or NULL on failure; call SDL_GetError() for
* more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_NumHaptics
*/
extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
/**
* \brief Opens a haptic device for use.
* Open a haptic device for use.
*
* The index passed as an argument refers to the N'th haptic device on this
* system.
*
* When opening a haptic device, its gain will be set to maximum and
* autocenter will be disabled. To modify these values use
* SDL_HapticSetGain() and SDL_HapticSetAutocenter().
* autocenter will be disabled. To modify these values use SDL_HapticSetGain()
* and SDL_HapticSetAutocenter().
*
* \param device_index Index of the device to open.
* \return Device identifier or NULL on error.
* \param device_index index of the device to open
* \returns the device identifier or NULL on failure; call SDL_GetError() for
* more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_HapticIndex
* \sa SDL_HapticOpenFromMouse
* \sa SDL_HapticOpenFromJoystick
* \sa SDL_HapticClose
* \sa SDL_HapticSetGain
* \sa SDL_HapticSetAutocenter
* \sa SDL_HapticIndex
* \sa SDL_HapticOpenFromJoystick
* \sa SDL_HapticOpenFromMouse
* \sa SDL_HapticPause
* \sa SDL_HapticSetAutocenter
* \sa SDL_HapticSetGain
* \sa SDL_HapticStopAll
*/
extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index);
/**
* \brief Checks if the haptic device at index has been opened.
* Check if the haptic device at the designated index has been opened.
*
* \param device_index Index to check to see if it has been opened.
* \return 1 if it has been opened or 0 if it hasn't.
* \param device_index the index of the device to query
* \returns 1 if it has been opened, 0 if it hasn't or on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_HapticOpen
* \sa SDL_HapticIndex
* \sa SDL_HapticOpen
*/
extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index);
/**
* \brief Gets the index of a haptic device.
* Get the index of a haptic device.
*
* \param haptic Haptic device to get the index of.
* \return The index of the haptic device or -1 on error.
* \param haptic the SDL_Haptic device to query
* \returns the index of the specified haptic device or a negative error code
* on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_HapticOpen
* \sa SDL_HapticOpened
@ -887,72 +904,88 @@ extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index);
extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic);
/**
* \brief Gets whether or not the current mouse has haptic capabilities.
* Query whether or not the current mouse has haptic capabilities.
*
* \return SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.
* \returns SDL_TRUE if the mouse is haptic or SDL_FALSE if it isn't.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_HapticOpenFromMouse
*/
extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void);
/**
* \brief Tries to open a haptic device from the current mouse.
* Try to open a haptic device from the current mouse.
*
* \return The haptic device identifier or NULL on error.
* \returns the haptic device identifier or NULL on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_MouseIsHaptic
* \sa SDL_HapticOpen
* \sa SDL_MouseIsHaptic
*/
extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void);
/**
* \brief Checks to see if a joystick has haptic features.
* Query if a joystick has haptic features.
*
* \param joystick Joystick to test for haptic capabilities.
* \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
* or -1 if an error occurred.
* \param joystick the SDL_Joystick to test for haptic capabilities
* \returns SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't, or a
* negative error code on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_HapticOpenFromJoystick
*/
extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
/**
* \brief Opens a haptic device for use from a joystick device.
* Open a haptic device for use from a joystick device.
*
* You must still close the haptic device separately. It will not be closed
* with the joystick.
*
* When opening from a joystick you should first close the haptic device before
* When opened from a joystick you should first close the haptic device before
* closing the joystick device. If not, on some implementations the haptic
* device will also get unallocated and you'll be unable to use force feedback
* on that device.
*
* \param joystick Joystick to create a haptic device from.
* \return A valid haptic device identifier on success or NULL on error.
* \param joystick the SDL_Joystick to create a haptic device from
* \returns a valid haptic device identifier on success or NULL on failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_HapticOpen
* \sa SDL_HapticClose
* \sa SDL_HapticOpen
* \sa SDL_JoystickIsHaptic
*/
extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *
joystick);
/**
* \brief Closes a haptic device previously opened with SDL_HapticOpen().
* Close a haptic device previously opened with SDL_HapticOpen().
*
* \param haptic Haptic device to close.
* \param haptic the SDL_Haptic device to close
*
* \sa SDL_HapticOpen
*/
extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
/**
* \brief Returns the number of effects a haptic device can store.
* Get the number of effects a haptic device can store.
*
* On some platforms this isn't fully supported, and therefore is an
* approximation. Always check to see if your created effect was actually
* created and do not rely solely on SDL_HapticNumEffects().
*
* \param haptic The haptic device to query effect max.
* \return The number of effects the haptic device can store or
* -1 on error.
* \param haptic the SDL_Haptic device to query
* \returns the number of effects the haptic device can store or a negative
* error code on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_HapticNumEffectsPlaying
* \sa SDL_HapticQuery
@ -960,15 +993,17 @@ extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
/**
* \brief Returns the number of effects a haptic device can play at the same
* time.
* Get the number of effects a haptic device can play at
* the same time.
*
* This is not supported on all platforms, but will always return a value.
* Added here for the sake of completeness.
*
* \param haptic The haptic device to query maximum playing effects.
* \return The number of effects the haptic device can play at the same time
* or -1 on error.
* \param haptic the SDL_Haptic device to query maximum playing effects
* \returns the number of effects the haptic device can play at the same time
* or a negative error code on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_HapticNumEffects
* \sa SDL_HapticQuery
@ -976,123 +1011,144 @@ extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic);
/**
* \brief Gets the haptic device's supported features in bitwise manner.
* Get the haptic device's supported features in bitwise manner.
*
* Example:
* \code
* if (SDL_HapticQuery(haptic) & SDL_HAPTIC_CONSTANT) {
* printf("We have constant haptic effect!\n");
* }
* \endcode
* \param haptic the SDL_Haptic device to query
* \returns a list of supported haptic features in bitwise manner (OR'd), or 0
* on failure; call SDL_GetError() for more information.
*
* \param haptic The haptic device to query.
* \return Haptic features in bitwise manner (OR'd).
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_HapticNumEffects
* \sa SDL_HapticEffectSupported
* \sa SDL_HapticNumEffects
*/
extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic);
/**
* \brief Gets the number of haptic axes the device has.
* Get the number of haptic axes the device has.
*
* \sa SDL_HapticDirection
* The number of haptic axes might be useful if working with the
* SDL_HapticDirection effect.
*
* \param haptic the SDL_Haptic device to query
* \returns the number of axes on success or a negative error code on failure;
* call SDL_GetError() for more information.
*/
extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic);
/**
* \brief Checks to see if effect is supported by haptic.
* Check to see if an effect is supported by a haptic
* device.
*
* \param haptic Haptic device to check on.
* \param effect Effect to check to see if it is supported.
* \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
* \param haptic the SDL_Haptic device to query
* \param effect the desired effect to query
* \returns SDL_TRUE if effect is supported, SDL_FALSE if it isn't, or a
* negative error code on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_HapticQuery
* \sa SDL_HapticNewEffect
* \sa SDL_HapticQuery
*/
extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic,
SDL_HapticEffect *
effect);
/**
* \brief Creates a new haptic effect on the device.
* Create a new haptic effect on a specified device.
*
* \param haptic Haptic device to create the effect on.
* \param effect Properties of the effect to create.
* \return The identifier of the effect on success or -1 on error.
* \param haptic an SDL_Haptic device to create the effect on
* \param effect an SDL_HapticEffect structure containing the properties of
* the effect to create
* \returns the ID of the effect on success or a negative error code on
* failure; call SDL_GetError() for more information.
*
* \sa SDL_HapticUpdateEffect
* \sa SDL_HapticRunEffect
* \sa SDL_HapticDestroyEffect
* \sa SDL_HapticRunEffect
* \sa SDL_HapticUpdateEffect
*/
extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic,
SDL_HapticEffect * effect);
/**
* \brief Updates the properties of an effect.
* Update the properties of an effect.
*
* Can be used dynamically, although behavior when dynamically changing
* direction may be strange. Specifically the effect may reupload itself
* and start playing from the start. You cannot change the type either when
* direction may be strange. Specifically the effect may re-upload itself and
* start playing from the start. You also cannot change the type either when
* running SDL_HapticUpdateEffect().
*
* \param haptic Haptic device that has the effect.
* \param effect Identifier of the effect to update.
* \param data New effect properties to use.
* \return 0 on success or -1 on error.
* \param haptic the SDL_Haptic device that has the effect
* \param effect the identifier of the effect to update
* \param data an SDL_HapticEffect structure containing the new effect
* properties to use
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_HapticDestroyEffect
* \sa SDL_HapticNewEffect
* \sa SDL_HapticRunEffect
* \sa SDL_HapticDestroyEffect
*/
extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic,
int effect,
SDL_HapticEffect * data);
/**
* \brief Runs the haptic effect on its associated haptic device.
* Run the haptic effect on its associated haptic device.
*
* If iterations are ::SDL_HAPTIC_INFINITY, it'll run the effect over and over
* repeating the envelope (attack and fade) every time. If you only want the
* effect to last forever, set ::SDL_HAPTIC_INFINITY in the effect's length
* parameter.
* To repeat the effect over and over indefinitely, set `iterations` to
* `SDL_HAPTIC_INFINITY`. (Repeats the envelope - attack and fade.) To make
* one instance of the effect last indefinitely (so the effect does not fade),
* set the effect's `length` in its structure/union to `SDL_HAPTIC_INFINITY`
* instead.
*
* \param haptic Haptic device to run the effect on.
* \param effect Identifier of the haptic effect to run.
* \param iterations Number of iterations to run the effect. Use
* ::SDL_HAPTIC_INFINITY for infinity.
* \return 0 on success or -1 on error.
* \param haptic the SDL_Haptic device to run the effect on
* \param effect the ID of the haptic effect to run
* \param iterations the number of iterations to run the effect; use
* `SDL_HAPTIC_INFINITY` to repeat forever
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_HapticStopEffect
* \sa SDL_HapticDestroyEffect
* \sa SDL_HapticGetEffectStatus
* \sa SDL_HapticStopEffect
*/
extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic,
int effect,
Uint32 iterations);
/**
* \brief Stops the haptic effect on its associated haptic device.
* Stop the haptic effect on its associated haptic device.
* *
* \param haptic the SDL_Haptic device to stop the effect on
* \param effect the ID of the haptic effect to stop
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \param haptic Haptic device to stop the effect on.
* \param effect Identifier of the effect to stop.
* \return 0 on success or -1 on error.
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_HapticRunEffect
* \sa SDL_HapticDestroyEffect
* \sa SDL_HapticRunEffect
*/
extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic,
int effect);
/**
* \brief Destroys a haptic effect on the device.
* Destroy a haptic effect on the device.
*
* This will stop the effect if it's running. Effects are automatically
* destroyed when the device is closed.
*
* \param haptic Device to destroy the effect on.
* \param effect Identifier of the effect to destroy.
* \param haptic the SDL_Haptic device to destroy the effect on
* \param effect the ID of the haptic effect to destroy
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_HapticNewEffect
*/
@ -1100,13 +1156,17 @@ extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic,
int effect);
/**
* \brief Gets the status of the current effect on the haptic device.
* Get the status of the current effect on the specified
* haptic device.
*
* Device must support the ::SDL_HAPTIC_STATUS feature.
* Device must support the SDL_HAPTIC_STATUS feature.
*
* \param haptic Haptic device to query the effect status on.
* \param effect Identifier of the effect to query its status.
* \return 0 if it isn't playing, 1 if it is playing or -1 on error.
* \param haptic the SDL_Haptic device to query for the effect status on
* \param effect the ID of the haptic effect to query its status
* \returns 0 if it isn't playing, 1 if it is playing, or a negative error
* code on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_HapticRunEffect
* \sa SDL_HapticStopEffect
@ -1115,34 +1175,38 @@ extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic,
int effect);
/**
* \brief Sets the global gain of the device.
* Set the global gain of the specified haptic device.
*
* Device must support the ::SDL_HAPTIC_GAIN feature.
* Device must support the SDL_HAPTIC_GAIN feature.
*
* The user may specify the maximum gain by setting the environment variable
* SDL_HAPTIC_GAIN_MAX which should be between 0 and 100. All calls to
* SDL_HapticSetGain() will scale linearly using SDL_HAPTIC_GAIN_MAX as the
* `SDL_HAPTIC_GAIN_MAX` which should be between 0 and 100. All calls to
* SDL_HapticSetGain() will scale linearly using `SDL_HAPTIC_GAIN_MAX` as the
* maximum.
*
* \param haptic Haptic device to set the gain on.
* \param gain Value to set the gain to, should be between 0 and 100.
* \return 0 on success or -1 on error.
* \param haptic the SDL_Haptic device to set the gain on
* \param gain value to set the gain to, should be between 0 and 100 (0 - 100)
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_HapticQuery
*/
extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
/**
* \brief Sets the global autocenter of the device.
* Set the global autocenter of the device.
*
* Autocenter should be between 0 and 100. Setting it to 0 will disable
* autocentering.
*
* Device must support the ::SDL_HAPTIC_AUTOCENTER feature.
* Device must support the SDL_HAPTIC_AUTOCENTER feature.
*
* \param haptic Haptic device to set autocentering on.
* \param autocenter Value to set autocenter to, 0 disables autocentering.
* \return 0 on success or -1 on error.
* \param haptic the SDL_Haptic device to set autocentering on
* \param autocenter value to set autocenter to (0-100)
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_HapticQuery
*/
@ -1150,46 +1214,51 @@ extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic,
int autocenter);
/**
* \brief Pauses a haptic device.
* Pause a haptic device.
*
* Device must support the ::SDL_HAPTIC_PAUSE feature. Call
* Device must support the `SDL_HAPTIC_PAUSE` feature. Call
* SDL_HapticUnpause() to resume playback.
*
* Do not modify the effects nor add new ones while the device is paused.
* That can cause all sorts of weird errors.
* Do not modify the effects nor add new ones while the device is paused. That
* can cause all sorts of weird errors.
*
* \param haptic Haptic device to pause.
* \return 0 on success or -1 on error.
* \param haptic the SDL_Haptic device to pause
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_HapticUnpause
*/
extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic);
/**
* \brief Unpauses a haptic device.
* Unpause a haptic device.
*
* Call to unpause after SDL_HapticPause().
*
* \param haptic Haptic device to unpause.
* \return 0 on success or -1 on error.
* \param haptic the SDL_Haptic device to unpause
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_HapticPause
*/
extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic);
/**
* \brief Stops all the currently playing effects on a haptic device.
* Stop all the currently playing effects on a haptic device.
*
* \param haptic Haptic device to stop.
* \return 0 on success or -1 on error.
* \param haptic the SDL_Haptic device to stop
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*/
extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic);
/**
* \brief Checks to see if rumble is supported on a haptic device.
* Check whether rumble is supported on a haptic device.
*
* \param haptic Haptic device to check to see if it supports rumble.
* \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
* \param haptic haptic device to check for rumble support
* \returns SDL_TRUE if effect is supported, SDL_FALSE if it isn't, or a
* negative error code on failure; call SDL_GetError() for more
* information.
*
* \sa SDL_HapticRumbleInit
* \sa SDL_HapticRumblePlay
@ -1198,41 +1267,46 @@ extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic);
extern DECLSPEC int SDLCALL SDL_HapticRumbleSupported(SDL_Haptic * haptic);
/**
* \brief Initializes the haptic device for simple rumble playback.
* Initialize a haptic device for simple rumble playback.
*
* \param haptic Haptic device to initialize for simple rumble playback.
* \return 0 on success or -1 on error.
* \param haptic the haptic device to initialize for simple rumble playback
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_HapticOpen
* \sa SDL_HapticRumbleSupported
* \sa SDL_HapticRumblePlay
* \sa SDL_HapticRumbleStop
* \sa SDL_HapticRumbleSupported
*/
extern DECLSPEC int SDLCALL SDL_HapticRumbleInit(SDL_Haptic * haptic);
/**
* \brief Runs simple rumble on a haptic device
* Run a simple rumble effect on a haptic device.
*
* \param haptic Haptic device to play rumble effect on.
* \param strength Strength of the rumble to play as a 0-1 float value.
* \param length Length of the rumble to play in milliseconds.
* \return 0 on success or -1 on error.
* \param haptic the haptic device to play the rumble effect on
* \param strength strength of the rumble to play as a 0-1 float value
* \param length length of the rumble to play in milliseconds
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_HapticRumbleSupported
* \sa SDL_HapticRumbleInit
* \sa SDL_HapticRumbleStop
* \sa SDL_HapticRumbleSupported
*/
extern DECLSPEC int SDLCALL SDL_HapticRumblePlay(SDL_Haptic * haptic, float strength, Uint32 length );
/**
* \brief Stops the simple rumble on a haptic device.
* Stop the simple rumble on a haptic device.
*
* \param haptic Haptic to stop the rumble on.
* \return 0 on success or -1 on error.
* \param haptic the haptic device to stop the rumble effect on
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_HapticRumbleSupported
* \sa SDL_HapticRumbleInit
* \sa SDL_HapticRumblePlay
* \sa SDL_HapticRumbleSupported
*/
extern DECLSPEC int SDLCALL SDL_HapticRumbleStop(SDL_Haptic * haptic);

86
include/SDL_hints.h
View File

@ -1671,71 +1671,113 @@ typedef enum
/**
* \brief Set a hint with a specific priority
* Set a hint with a specific priority.
*
* The priority controls the behavior when setting a hint that already
* has a value. Hints will replace existing hints of their priority and
* lower. Environment variables are considered to have override priority.
* The priority controls the behavior when setting a hint that already has a
* value. Hints will replace existing hints of their priority and lower.
* Environment variables are considered to have override priority.
*
* \return SDL_TRUE if the hint was set, SDL_FALSE otherwise
* \param name the hint to set
* \param value the value of the hint variable
* \param priority the SDL_HintPriority level for the hint
* \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise.
*
* \sa SDL_GetHint
* \sa SDL_SetHint
*/
extern DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name,
const char *value,
SDL_HintPriority priority);
/**
* \brief Set a hint with normal priority
* Set a hint with normal priority.
*
* \return SDL_TRUE if the hint was set, SDL_FALSE otherwise
* Hints will not be set if there is an existing override hint or environment
* variable that takes precedence. You can use SDL_SetHintWithPriority() to
* set the hint with override priority instead.
*
* \param name the hint to set
* \param value the value of the hint variable
* \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise.
*
* \sa SDL_GetHint
* \sa SDL_SetHintWithPriority
*/
extern DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name,
const char *value);
/**
* \brief Get a hint
* Get the value of a hint.
*
* \return The string value of a hint variable.
* \param name the hint to query
* \returns the string value of a hint or NULL if the hint isn't set.
*
* \sa SDL_SetHint
* \sa SDL_SetHintWithPriority
*/
extern DECLSPEC const char * SDLCALL SDL_GetHint(const char *name);
/**
* \brief Get a hint
* Get the boolean value of a hint variable.
*
* \return The boolean value of a hint variable.
* \param name the name of the hint to get the boolean value from
* \param default_value the value to return if the hint does not exist
* \returns the boolean value of a hint or the provided default value if the
* hint does not exist.
*
* \since This function is available since SDL 2.0.5.
*
* \sa SDL_GetHint
* \sa SDL_SetHint
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bool default_value);
/**
* \brief type definition of the hint callback function.
* Type definition of the hint callback function.
*
* \param userdata what was passed as `userdata` to SDL_AddHintCallback()
* \param name what was passed as `name` to SDL_AddHintCallback()
* \param oldValue the previous hint value
* \param newValue the new value hint is to be set to
*/
typedef void (SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const char *oldValue, const char *newValue);
/**
* \brief Add a function to watch a particular hint
* Add a function to watch a particular hint.
*
* \param name The hint to watch
* \param callback The function to call when the hint value changes
* \param userdata A pointer to pass to the callback function
* \param name the hint to watch
* \param callback An SDL_HintCallback function that will be called when the
* hint value changes
* \param userdata a pointer to pass to the callback function
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_DelHintCallback
*/
extern DECLSPEC void SDLCALL SDL_AddHintCallback(const char *name,
SDL_HintCallback callback,
void *userdata);
/**
* \brief Remove a function watching a particular hint
* Remove a function watching a particular hint.
*
* \param name The hint being watched
* \param callback The function being called when the hint value changes
* \param userdata A pointer being passed to the callback function
* \param name the hint being watched
* \param callback An SDL_HintCallback function that will be called when the
* hint value changes
* \param userdata a pointer being passed to the callback function
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_AddHintCallback
*/
extern DECLSPEC void SDLCALL SDL_DelHintCallback(const char *name,
SDL_HintCallback callback,
void *userdata);
/**
* \brief Clear all hints
* Clear all hints.
*
* This function is called during SDL_Quit() to free stored hints.
* This function is automatically called during SDL_Quit().
*/
extern DECLSPEC void SDLCALL SDL_ClearHints(void);

461
include/SDL_joystick.h
View File

@ -30,10 +30,12 @@
* The term "instance_id" is the current instantiation of a joystick device in the system, if the joystick is removed and then re-inserted
* then it will get a new instance_id, instance_id's are monotonically increasing identifiers of a joystick plugged in.
*
* The term "player_index" is the number assigned to a player on a specific
* controller. For XInput controllers this returns the XInput user index.
* Many joysticks will not be able to supply this information.
*
* The term JoystickGUID is a stable 128-bit identifier for a joystick device that does not change over time, it identifies class of
* the device (a X360 wired controller for example). This identifier is platform dependent.
*
*
*/
#ifndef SDL_joystick_h_
@ -124,17 +126,43 @@ typedef enum
* and game controller events will not be delivered.
*/
extern DECLSPEC void SDLCALL SDL_LockJoysticks(void);
/**
* Unlocking for multi-threaded access to the joystick API
*
* If you are using the joystick API or handling events from multiple threads
* you should use these locking functions to protect access to the joysticks.
*
* In particular, you are guaranteed that the joystick list won't change, so
* the API functions that take a joystick index will be valid, and joystick
* and game controller events will not be delivered.
*/
extern DECLSPEC void SDLCALL SDL_UnlockJoysticks(void);
/**
* Count the number of joysticks attached to the system right now
* Count the number of joysticks attached to the system.
*
* \returns the number of attached joysticks on success or a negative error
* code on failure; call SDL_GetError() for more information.
*
* \sa SDL_JoystickName
* \sa SDL_JoystickOpen
*/
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.
*
* \param device_index the index of the joystick to query (the N'th joystick
* on the system)
* \returns the name of the selected joystick. If no name can be found, this
* function returns NULL; call SDL_GetError() for more information.
*
* \sa SDL_JoystickName
* \sa SDL_JoystickOpen
*/
extern DECLSPEC const char *SDLCALL SDL_JoystickNameForIndex(int device_index);
@ -145,69 +173,129 @@ extern DECLSPEC const char *SDLCALL SDL_JoystickNameForIndex(int device_index);
extern DECLSPEC int SDLCALL SDL_JoystickGetDevicePlayerIndex(int device_index);
/**
* Return the GUID for the joystick at this index
* This can be called before any joysticks are opened.
* Get the implementation-dependent GUID for the joystick
* at a given device index.
*
* This function can be called before any joysticks are opened.
*
* \param device_index the index of the joystick to query (the N'th joystick
* on the system
* \returns the GUID of the selected joystick. If called on an invalid index,
* this function returns a zero GUID
*
* \sa SDL_JoystickGetGUID
* \sa SDL_JoystickGetGUIDString
*/
extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetDeviceGUID(int device_index);
/**
* Get the USB vendor ID of a joystick, if available.
*
* This can be called before any joysticks are opened.
* If the vendor ID isn't available this function returns 0.
*
* \param device_index the index of the joystick to query (the N'th joystick
* on the system
* \returns the USB vendor ID of the selected joystick. If called on an
* invalid index, this function returns zero
*/
extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceVendor(int device_index);
/**
* Get the USB product ID of a joystick, if available.
*
* This can be called before any joysticks are opened.
* If the product ID isn't available this function returns 0.
*
* \param device_index the index of the joystick to query (the N'th joystick
* on the system
* \returns the USB product ID of the selected joystick. If called on an
* invalid index, this function returns zero
*/
extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProduct(int device_index);
/**
* Get the product version of a joystick, if available.
*
* This can be called before any joysticks are opened.
* If the product version isn't available this function returns 0.
*
* \param device_index the index of the joystick to query (the N'th joystick
* on the system
* \returns the product version of the selected joystick. If called on an
* invalid index, this function returns zero
*/
extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProductVersion(int device_index);
/**
* Get the type of a joystick, if available.
*
* This can be called before any joysticks are opened.
*
* \param device_index the index of the joystick to query (the N'th joystick
* on the system
* \returns the SDL_JoystickType of the selected joystick. If called on an
* invalid index, this function returns `SDL_JOYSTICK_TYPE_UNKNOWN`
*/
extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetDeviceType(int device_index);
/**
* Get the instance ID of a joystick.
*
* This can be called before any joysticks are opened.
* If the index is out of range, this function will return -1.
*
* \param device_index the index of the joystick to query (the N'th joystick
* on the system
* \returns the instance id of the selected joystick. If called on an invalid
* index, this function returns zero
*/
extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickGetDeviceInstanceID(int device_index);
/**
* Open a joystick for use.
* The index passed as an argument refers to the N'th joystick on the system.
* This index is not the value which will identify this joystick in future
* joystick events. The joystick's instance id (::SDL_JoystickID) will be used
* there instead.
*
* \return A joystick identifier, or NULL if an error occurred.
* The `device_index` argument refers to the N'th joystick presently
* recognized by SDL on the system. It is **NOT** the same as the instance ID
* used to identify the joystick in future events. See
* SDL_JoystickInstanceID() for more details about instance IDs.
*
* The joystick subsystem must be initialized before a joystick can be opened
* for use.
*
* \param device_index the index of the joystick to query
* \returns a joystick identifier or NULL if an error occurred; call
* SDL_GetError() for more information.
*
* \sa SDL_JoystickClose
* \sa SDL_JoystickInstanceID
*/
extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickOpen(int device_index);
/**
* Return the SDL_Joystick associated with an instance id.
* Get the SDL_Joystick associated with an instance id.
*
* \param joyid the instance id to get the SDL_Joystick for
* \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError()
* for more information.
*
* \since This function is available since SDL 2.0.4.
*/
extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickFromInstanceID(SDL_JoystickID instance_id);
/**
* Return the SDL_Joystick associated with a player index.
* Get the SDL_Joystick associated with a player index.
*
* \param player_index the player index to get the SDL_Joystick for
* \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError()
* for more information.
*/
extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickFromPlayerIndex(int player_index);
/**
* Attaches a new virtual joystick.
* Returns the joystick's device index, or -1 if an error occurred.
* Attach a new virtual joystick.
*
* \returns the joystick's device index, or -1 if an error occurred.
*/
extern DECLSPEC int SDLCALL SDL_JoystickAttachVirtual(SDL_JoystickType type,
int naxes,
@ -215,68 +303,144 @@ extern DECLSPEC int SDLCALL SDL_JoystickAttachVirtual(SDL_JoystickType type,
int nhats);
/**
* Detaches a virtual joystick
* Returns 0 on success, or -1 if an error occurred.
* Detach a virtual joystick.
*
* \param device_index a value previously returned from
* SDL_JoystickAttachVirtual()
* \returns 0 on success, or -1 if an error occurred.
*/
extern DECLSPEC int SDLCALL SDL_JoystickDetachVirtual(int device_index);
/**
* Indicates whether or not a virtual-joystick is at a given device index.
* Query whether or not the joystick at a given device index is virtual.
*
* \param device_index a joystick device index.
* \returns SDL_TRUE if the joystick is virtual, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_JoystickIsVirtual(int device_index);
/**
* Set values on an opened, virtual-joystick's controls.
* Set values on an opened, virtual-joystick's axis.
*
* Please note that values set here will not be applied until the next
* call to SDL_JoystickUpdate, which can either be called directly,
* or can be called indirectly through various other SDL APIS,
* or can be called indirectly through various other SDL APIs,
* including, but not limited to the following: SDL_PollEvent,
* SDL_PumpEvents, SDL_WaitEventTimeout, SDL_WaitEvent.
*
* Returns 0 on success, -1 on error.
* \param joystick the virtual joystick on which to set state.
* \param axis the specific axis on the virtual joystick to set.
* \param value the new value for the specified axis.
* \returns 0 on success, -1 on error.
*/
extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualAxis(SDL_Joystick *joystick, int axis, Sint16 value);
/**
* Set values on an opened, virtual-joystick's button.
*
* Please note that values set here will not be applied until the next
* call to SDL_JoystickUpdate, which can either be called directly,
* or can be called indirectly through various other SDL APIs,
* including, but not limited to the following: SDL_PollEvent,
* SDL_PumpEvents, SDL_WaitEventTimeout, SDL_WaitEvent.
*
* \param joystick the virtual joystick on which to set state.
* \param button the specific button on the virtual joystick to set.
* \param value the new value for the specified button.
* \returns 0 on success, -1 on error.
*/
extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualButton(SDL_Joystick *joystick, int button, Uint8 value);
/**
* Set values on an opened, virtual-joystick's hat.
*
* Please note that values set here will not be applied until the next
* call to SDL_JoystickUpdate, which can either be called directly,
* or can be called indirectly through various other SDL APIs,
* including, but not limited to the following: SDL_PollEvent,
* SDL_PumpEvents, SDL_WaitEventTimeout, SDL_WaitEvent.
*
* \param joystick the virtual joystick on which to set state.
* \param hat the specific hat on the virtual joystick to set.
* \param value the new value for the specified hat.
* \returns 0 on success, -1 on error.
*/
extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value);
/**
* Return the name for this currently opened joystick.
* If no name can be found, this function returns NULL.
* Get the implementation dependent name of a joystick.
*
* \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
* \returns the name of the selected joystick. If no name can be found, this
* function returns NULL; call SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_JoystickNameForIndex
* \sa SDL_JoystickOpen
*/
extern DECLSPEC const char *SDLCALL SDL_JoystickName(SDL_Joystick *joystick);
/**
* Get the player index of an opened joystick, or -1 if it's not available
* Get the player index of an opened joystick.
*
* For XInput controllers this returns the XInput user index.
* For XInput controllers this returns the XInput user index. Many joysticks
* will not be able to supply this information.
*
* \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
* \returns the player index, or -1 if it's not available.
*/
extern DECLSPEC int SDLCALL SDL_JoystickGetPlayerIndex(SDL_Joystick *joystick);
/**
* Set the player index of an opened joystick
* Set the player index of an opened joystick.
*
* \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
* \param player_index the player index to set.
*/
extern DECLSPEC void SDLCALL SDL_JoystickSetPlayerIndex(SDL_Joystick *joystick, int player_index);
/**
* Return the GUID for this opened joystick
* Get the implementation-dependent GUID for the joystick.
*
* This function requires an open joystick.
*
* \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
* \returns the GUID of the given joystick. If called on an invalid index,
* this function returns a zero GUID; call SDL_GetError() for more
* information.
*
* \sa SDL_JoystickGetDeviceGUID
* \sa SDL_JoystickGetGUIDString
*/
extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetGUID(SDL_Joystick *joystick);
/**
* Get the USB vendor ID of an opened joystick, if available.
*
* If the vendor ID isn't available this function returns 0.
*
* \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
* \returns the USB vendor ID of the selected joystick, or 0 if unavailable.
*/
extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetVendor(SDL_Joystick *joystick);
/**
* Get the USB product ID of an opened joystick, if available.
*
* If the product ID isn't available this function returns 0.
*
* \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
* \returns the USB product ID of the selected joystick, or 0 if unavailable.
*/
extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProduct(SDL_Joystick *joystick);
/**
* Get the product version of an opened joystick, if available.
* If the product version isn't available this function returns 0.
*
* \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
* \returns the product version of the selected joystick, or 0 if unavailable.
*/
extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProductVersion(SDL_Joystick *joystick);
@ -284,63 +448,136 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProductVersion(SDL_Joystick *joyst
* Get the serial number of an opened joystick, if available.
*
* Returns the serial number of the joystick, or NULL if it is not available.
*
* \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
* \returns the serial number of the selected joystick, or NULL if unavailable.
*/
extern DECLSPEC const char * SDLCALL SDL_JoystickGetSerial(SDL_Joystick *joystick);
/**
* Get the type of an opened joystick.
*
* \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
* \returns the SDL_JoystickType of the selected joystick.
*/
extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetType(SDL_Joystick *joystick);
/**
* Return a string representation for this guid. pszGUID must point to at least 33 bytes
* (32 for the string plus a NULL terminator).
* Get an ASCII string representation for a given SDL_JoystickGUID.
*
* You should supply at least 33 bytes for pszGUID.
*
* \param guid the SDL_JoystickGUID you wish to convert to string
* \param pszGUID buffer in which to write the ASCII string
* \param cbGUID the size of pszGUID
*
* \sa SDL_JoystickGetDeviceGUID
* \sa SDL_JoystickGetGUID
* \sa SDL_JoystickGetGUIDFromString
*/
extern DECLSPEC void SDLCALL SDL_JoystickGetGUIDString(SDL_JoystickGUID guid, char *pszGUID, int cbGUID);
/**
* Convert a string into a joystick guid
* Convert a GUID string into a SDL_JoystickGUID structure.
*
* Performs no error checking. If this function is given a string containing
* an invalid GUID, the function will silently succeed, but the GUID generated
* will not be useful.
*
* \param pchGUID string containing an ASCII representation of a GUID
* \returns a SDL_JoystickGUID structure.
*
* \sa SDL_JoystickGetGUIDString
*/
extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetGUIDFromString(const char *pchGUID);
/**
* Returns SDL_TRUE if the joystick has been opened and currently connected, or SDL_FALSE if it has not.
* Get the status of a specified joystick.
*
* \param joystick the joystick to query
* \returns SDL_TRUE if the joystick has been opened, SDL_FALSE if it has not;
* call SDL_GetError() for more information.
*
* \sa SDL_JoystickClose
* \sa SDL_JoystickOpen
*/
extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAttached(SDL_Joystick *joystick);
/**
* Get the instance ID of an opened joystick or -1 if the joystick is invalid.
* Get the instance ID of an opened joystick.
*
* \param joystick an SDL_Joystick structure containing joystick information
* \returns the instance ID of the specified joystick on success or a negative
* error code on failure; call SDL_GetError() for more information.
*
* \sa SDL_JoystickOpen
*/
extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickInstanceID(SDL_Joystick *joystick);
/**
* Get the number of general axis controls on a joystick.
*
* Often, the directional pad on a game controller will either look like 4
* separate buttons or a POV hat, and not axes, but all of this is up to the
* device and platform.
*
* \param joystick an SDL_Joystick structure containing joystick information
* \returns the number of axis controls/number of axes on success or a
* negative error code on failure; call SDL_GetError() for more
* information.
*
* \sa SDL_JoystickGetAxis
* \sa SDL_JoystickOpen
*/
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.
* Joystick trackballs have only relative motion events associated with them
* and their state cannot be polled.
*
* Most joysticks do not have trackballs.
*
* \param joystick an SDL_Joystick structure containing joystick information
* \returns the number of trackballs on success or a negative error code on
* failure; call SDL_GetError() for more information.
*
* \sa SDL_JoystickGetBall
*/
extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(SDL_Joystick *joystick);
/**
* Get the number of POV hats on a joystick.
*
* \param joystick an SDL_Joystick structure containing joystick information
* \returns the number of POV hats on success or a negative error code on
* failure; call SDL_GetError() for more information.
*
* \sa SDL_JoystickGetHat
* \sa SDL_JoystickOpen
*/
extern DECLSPEC int SDLCALL SDL_JoystickNumHats(SDL_Joystick *joystick);
/**
* Get the number of buttons on a joystick.
*
* \param joystick an SDL_Joystick structure containing joystick information
* \returns the number of buttons on success or a negative error code on
* failure; call SDL_GetError() for more information.
*
* \sa SDL_JoystickGetButton
* \sa SDL_JoystickOpen
*/
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.
* This is called automatically by the event loop if any joystick events are
* enabled.
*
* \sa SDL_JoystickEventState
*/
extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void);
@ -348,10 +585,22 @@ 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.
* yourself and manually check the state of the joystick when you want
* joystick information.
*
* The state can be one of ::SDL_QUERY, ::SDL_ENABLE or ::SDL_IGNORE.
* It is recommended that you leave joystick event handling enabled.
*
* **WARNING**: Calling this function may delete all events currently in SDL's
* event queue.
*
* \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`
* \returns 1 if enabled, 0 if disabled, or a negative error code on failure;
* call SDL_GetError() for more information.
*
* If `state` is `SDL_QUERY` then the current state is returned,
* otherwise the new processing state is returned.
*
* \sa SDL_GameControllerEventState
*/
extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state);
@ -360,9 +609,23 @@ 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.
* SDL makes no promises about what part of the joystick any given axis
* refers to. Your game should have some sort of configuration UI to let
* users specify what each axis should be bound to. Alternately, SDL's
* higher-level Game Controller API makes a great effort to apply order
* to this lower-level interface, so you know that a specific axis is the
* "left thumb stick," etc.
*
* The axis indices start at index 0.
* The value returned by SDL_JoystickGetAxis() is a signed integer (-32768 to
* 32767) representing the current position of the axis. It may be necessary
* to impose certain tolerances on these values to account for jitter.
*
* \param joystick an SDL_Joystick structure containing joystick information
* \param axis the axis to query; the axis indices start at index 0
* \returns a 16-bit signed integer representing the current position of the
* axis or 0 on failure; call SDL_GetError() for more information.
*
* \sa SDL_JoystickNumAxes
*/
extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick *joystick,
int axis);
@ -374,6 +637,9 @@ extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick *joystick,
*
* The axis indices start at index 0.
*
* \param joystick an SDL_Joystick structure containing joystick information
* \param axis the axis to query; the axis indices start at index 0
* \param state Upon return, the initial value is supplied here.
* \return SDL_TRUE if this axis has any initial value, or SDL_FALSE if not.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAxisInitialState(SDL_Joystick *joystick,
@ -397,18 +663,32 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAxisInitialState(SDL_Joystick *j
/**
* Get the current state of a POV hat on a joystick.
*
* The hat indices start at index 0.
* The returned value will be one of the following positions:
*
* \return The return value is one of the following positions:
* - ::SDL_HAT_CENTERED
* - ::SDL_HAT_UP
* - ::SDL_HAT_RIGHT
* - ::SDL_HAT_DOWN
* - ::SDL_HAT_LEFT
* - ::SDL_HAT_RIGHTUP
* - ::SDL_HAT_RIGHTDOWN
* - ::SDL_HAT_LEFTUP
* - ::SDL_HAT_LEFTDOWN
* - `SDL_HAT_CENTERED`
*
* - `SDL_HAT_UP`
*
* - `SDL_HAT_RIGHT`
*
* - `SDL_HAT_DOWN`
*
* - `SDL_HAT_LEFT`
*
* - `SDL_HAT_RIGHTUP`
*
* - `SDL_HAT_RIGHTDOWN`
*
* - `SDL_HAT_LEFTUP`
*
* - `SDL_HAT_LEFTDOWN`
*
* \param joystick an SDL_Joystick structure containing joystick information
* \param hat the hat index to get the state from; hat indices start at index
* 0
* \returns the current hat position.
*
* \sa SDL_JoystickNumHats
*/
extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick *joystick,
int hat);
@ -416,9 +696,20 @@ extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick *joystick,
/**
* Get the ball axis change since the last poll.
*
* \return 0, or -1 if you passed it invalid parameters.
* Trackballs can only return relative motion since the last call to
* SDL_JoystickGetBall(), these motion deltas are placed into `dx` and
* `dy`.
*
* The ball indices start at index 0.
* Most joysticks do not have trackballs.
*
* \param joystick the SDL_Joystick to query
* \param ball the ball index to query; ball indices start at index 0
* \param dx stores the difference in the x axis position since the last poll
* \param dy stores the difference in the y axis position since the last poll
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_JoystickNumBalls
*/
extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick *joystick,
int ball, int *dx, int *dy);
@ -426,65 +717,97 @@ extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick *joystick,
/**
* Get the current state of a button on a joystick.
*
* The button indices start at index 0.
* \param joystick an SDL_Joystick structure containing joystick information
* \param button the button index to get the state from; indices start at
* index 0
* \returns 1 if the specified button is pressed, 0 otherwise.
*
* \sa SDL_JoystickNumButtons
*/
extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick *joystick,
int button);
/**
* Start a rumble effect
* Each call to this function cancels any previous rumble effect, and calling it with 0 intensity stops any rumbling.
* Start a rumble effect.
*
* Each call to this function cancels any previous rumble effect, and calling
* it with 0 intensity stops any rumbling.
*
* \param joystick The joystick to vibrate
* \param low_frequency_rumble The intensity of the low frequency (left) rumble motor, from 0 to 0xFFFF
* \param high_frequency_rumble The intensity of the high frequency (right) rumble motor, from 0 to 0xFFFF
* \param low_frequency_rumble The intensity of the low frequency (left)
* rumble motor, from 0 to 0xFFFF
* \param high_frequency_rumble The intensity of the high frequency (right)
* rumble motor, from 0 to 0xFFFF
* \param duration_ms The duration of the rumble effect, in milliseconds
*
* \return 0, or -1 if rumble isn't supported on this joystick
* \returns 0, or -1 if rumble isn't supported on this joystick
*/
extern DECLSPEC int SDLCALL SDL_JoystickRumble(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms);
/**
* Start a rumble effect in the joystick's triggers
* Each call to this function cancels any previous trigger rumble effect, and calling it with 0 intensity stops any rumbling.
*
* Each call to this function cancels any previous trigger rumble effect,
* and calling it with 0 intensity stops any rumbling.
*
* Note that this function is for _trigger_ rumble; the first joystick to
* support this was the PlayStation 5's DualShock 5 controller. If you want
* the (more common) whole-controller rumble, use SDL_JoystickRumble() instead.
*
* \param joystick The joystick to vibrate
* \param left_rumble The intensity of the left trigger rumble motor, from 0 to 0xFFFF
* \param right_rumble The intensity of the right trigger rumble motor, from 0 to 0xFFFF
* \param left_rumble The intensity of the left trigger rumble motor, from 0
* to 0xFFFF
* \param right_rumble The intensity of the right trigger rumble motor, from 0
* to 0xFFFF
* \param duration_ms The duration of the rumble effect, in milliseconds
*
* \return 0, or -1 if trigger rumble isn't supported on this joystick
* \returns 0, or -1 if trigger rumble isn't supported on this joystick
*/
extern DECLSPEC int SDLCALL SDL_JoystickRumbleTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms);
/**
* Return whether a joystick has an LED
* Query whether a joystick has an LED.
*
* An example of a joystick LED is the light on the back of a PlayStation 4's
* DualShock 4 controller.
*
* \param joystick The joystick to query
*
* \return SDL_TRUE, or SDL_FALSE if this joystick does not have a modifiable LED
* \return SDL_TRUE if the joystick has a modifiable LED, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasLED(SDL_Joystick *joystick);
/**
* Update a joystick's LED color.
*
* An example of a joystick LED is the light on the back of a PlayStation 4's
* DualShock 4 controller.
*
* \param joystick The joystick to update
* \param red The intensity of the red LED
* \param green The intensity of the green LED
* \param blue The intensity of the blue LED
*
* \return 0, or -1 if this joystick does not have a modifiable LED
* \returns 0 on success, -1 if this joystick does not have a modifiable LED
*/
extern DECLSPEC int SDLCALL SDL_JoystickSetLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue);
/**
* Close a joystick previously opened with SDL_JoystickOpen().
*
* \param joystick The joystick device to close
*
* \sa SDL_JoystickOpen
*/
extern DECLSPEC void SDLCALL SDL_JoystickClose(SDL_Joystick *joystick);
/**
* Return the battery level of this joystick
* Get the battery level of a joystick as SDL_JoystickPowerLevel.
*
* \param joystick the SDL_Joystick to query
* \returns the current battery level as SDL_JoystickPowerLevel on success or
* `SDL_JOYSTICK_POWER_UNKNOWN` if it is unknown
*
* \since This function is available since SDL 2.0.4.
*/
extern DECLSPEC SDL_JoystickPowerLevel SDLCALL SDL_JoystickCurrentPowerLevel(SDL_Joystick *joystick);

201
include/SDL_keyboard.h
View File

@ -55,154 +55,231 @@ typedef struct SDL_Keysym
/* Function prototypes */
/**
* \brief Get the window which currently has keyboard focus.
* Query the window which currently has keyboard focus.
*
* \returns the window with keyboard focus.
*/
extern DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void);
/**
* \brief Get a snapshot of the current state of the keyboard.
* Get a snapshot of the current state of the keyboard.
*
* \param numkeys if non-NULL, receives the length of the returned array.
* The pointer returned is a pointer to an internal SDL array. It will be
* valid for the whole lifetime of the application and should not be freed
* by the caller.
*
* \return An array of key states. Indexes into this array are obtained by using ::SDL_Scancode values.
* A array element with a value of 1 means that the key is pressed and a value
* of 0 means that it is not. Indexes into this array are obtained by using
* SDL_Scancode values.
*
* \b Example:
* \code
* const Uint8 *state = SDL_GetKeyboardState(NULL);
* if ( state[SDL_SCANCODE_RETURN] ) {
* printf("<RETURN> is pressed.\n");
* }
* \endcode
* Use SDL_PumpEvents() to update the state array.
*
* This function gives you the current state after all events have been
* processed, so if a key or button has been pressed and released before you
* process events, then the pressed state will never show up in the
* SDL_GetKeyboardState() calls.
*
* Note: This function doesn't take into account whether shift has been
* pressed or not.
*
* \param numkeys if non-NULL, receives the length of the returned array
* \returns a pointer to an array of key states.
*
* \sa SDL_PumpEvents
*/
extern DECLSPEC const Uint8 *SDLCALL SDL_GetKeyboardState(int *numkeys);
/**
* \brief Get the current key modifier state for the keyboard.
* Get the current key modifier state for the keyboard.
*
* \returns an OR'd combination of the modifier keys for the keyboard. See
* SDL_Keymod for details.
*
* \sa SDL_GetKeyboardState
* \sa SDL_SetModState
*/
extern DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void);
/**
* \brief Set the current key modifier state for the keyboard.
* Set the current key modifier state for the keyboard.
*
* \note This does not change the keyboard state, only the key modifier flags.
* The inverse of SDL_GetModState(), SDL_SetModState() allows you to impose
* modifier key states on your application. Simply pass your desired modifier
* states into `modstate`. This value may be a bitwise, OR'd combination of
* SDL_Keymod values.
*
* This does not change the keyboard state, only the key modifier flags that
* SDL reports.
*
* \param modstate the desired SDL_Keymod for the keyboard
*
* \sa SDL_GetModState
*/
extern DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
/**
* \brief Get the key code corresponding to the given scancode according
* to the current keyboard layout.
* Get the key code corresponding to the given scancode
* according to the current keyboard layout.
*
* See ::SDL_Keycode for details.
* See SDL_Keycode for details.
*
* \sa SDL_GetKeyName()
* \param scancode the desired SDL_Scancode to query
* \returns the SDL_Keycode that corresponds to the given SDL_Scancode.
*
* \sa SDL_GetKeyName
* \sa SDL_GetScancodeFromKey
*/
extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode);
/**
* \brief Get the scancode corresponding to the given key code according to the
* current keyboard layout.
* Get the scancode corresponding to the given key code
* according to the current keyboard layout.
*
* See ::SDL_Scancode for details.
* See SDL_Scancode for details.
*
* \sa SDL_GetScancodeName()
* \param key the desired SDL_Keycode to query
* \returns the SDL_Scancode that corresponds to the given SDL_Keycode.
*
* \sa SDL_GetKeyFromScancode
* \sa SDL_GetScancodeName
*/
extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key);
/**
* \brief Get a human-readable name for a scancode.
* Get a human-readable name for a scancode.
*
* \return A pointer to the name for the scancode.
* If the scancode doesn't have a name, this function returns
* an empty string ("").
* See SDL_Scancode for details.
*
* \sa SDL_Scancode
* **Warning**: The returned name is by design not stable across platforms,
* e.g. the name for `SDL_SCANCODE_LGUI` is "Left GUI" under Linux but "Left
* Windows" under Microsoft Windows, and some scancodes like
* `SDL_SCANCODE_NONUSBACKSLASH` don't have any name at all. There are even
* scancodes that share names, e.g. `SDL_SCANCODE_RETURN` and
* `SDL_SCANCODE_RETURN2` (both called "Return"). This function is therefore
* unsuitable for creating a stable cross-platform two-way mapping between
* strings and scancodes.
*
* \param scancode the desired SDL_Scancode to query
* \returns a pointer to the name for the scancode. If the scancode doesn't
* have a name this function returns an empty string ("").
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_GetScancodeFromKey
* \sa SDL_GetScancodeFromName
*/
extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_Scancode scancode);
/**
* \brief Get a scancode from a human-readable name
* Get a scancode from a human-readable name.
*
* \return scancode, or SDL_SCANCODE_UNKNOWN if the name wasn't recognized
* \param name the human-readable scancode name
* \returns the SDL_Scancode, or `SDL_SCANCODE_UNKNOWN` if the name wasn't
* recognized; call SDL_GetError() for more information.
*
* \sa SDL_Scancode
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_GetKeyFromName
* \sa SDL_GetScancodeFromKey
* \sa SDL_GetScancodeName
*/
extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *name);
/**
* \brief Get a human-readable name for a key.
* Get a human-readable name for a key.
*
* \return A pointer to a UTF-8 string that stays valid at least until the next
* call to this function. If you need it around any longer, you must
* copy it. If the key doesn't have a name, this function returns an
* empty string ("").
* See SDL_Scancode and SDL_Keycode for details.
*
* \sa SDL_Keycode
* \param key the desired SDL_Keycode to query
* \returns a pointer to a UTF-8 string that stays valid at least until the
* next call to this function. If you need it around any longer, you
* must copy it. If the key doesn't have a name, this function
* returns an empty string ("").
*
* \sa SDL_GetKeyFromName
* \sa SDL_GetKeyFromScancode
* \sa SDL_GetScancodeFromKey
*/
extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDL_Keycode key);
/**
* \brief Get a key code from a human-readable name
* Get a key code from a human-readable name.
*
* \return key code, or SDLK_UNKNOWN if the name wasn't recognized
* \param name the human-readable key name
* \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call
* SDL_GetError() for more information.
*
* \sa SDL_Keycode
* \sa SDL_GetKeyFromScancode
* \sa SDL_GetKeyName
* \sa SDL_GetScancodeFromName
*/
extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name);
/**
* \brief Start accepting Unicode text input events.
* This function will show the on-screen keyboard if supported.
* Start accepting Unicode text input events.
*
* \sa SDL_StopTextInput()
* \sa SDL_SetTextInputRect()
* \sa SDL_HasScreenKeyboardSupport()
* This function will start accepting Unicode text input events in the focused
* SDL window, and start emitting SDL_TextInputEvent (SDL_TEXTINPUT) and
* SDL_TextEditingEvent (SDL_TEXTEDITING) events. Please use this function
* in pair with SDL_StopTextInput().
*
* On some platforms using this function activates the screen keyboard.
*
* \sa SDL_SetTextInputRect
* \sa SDL_StopTextInput
*/
extern DECLSPEC void SDLCALL SDL_StartTextInput(void);
/**
* \brief Return whether or not Unicode text input events are enabled.
* Check whether or not Unicode text input events are enabled.
*
* \sa SDL_StartTextInput()
* \sa SDL_StopTextInput()
* \returns SDL_TRUE if text input events are enabled else SDL_FALSE.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_StartTextInput
*/
extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputActive(void);
/**
* \brief Stop receiving any text input events.
* This function will hide the on-screen keyboard if supported.
* Stop receiving any text input events.
*
* \sa SDL_StartTextInput()
* \sa SDL_HasScreenKeyboardSupport()
* \sa SDL_StartTextInput
*/
extern DECLSPEC void SDLCALL SDL_StopTextInput(void);
/**
* \brief Set the rectangle used to type Unicode text inputs.
* This is used as a hint for IME and on-screen keyboard placement.
* Set the rectangle used to type Unicode text inputs.
*
* \sa SDL_StartTextInput()
* \param rect the SDL_Rect structure representing the rectangle to receive
* text (ignored if NULL)
*
* \sa SDL_StartTextInput
*/
extern DECLSPEC void SDLCALL SDL_SetTextInputRect(SDL_Rect *rect);
/**
* \brief Returns whether the platform has some screen keyboard support.
* Check whether the platform has screen keyboard support.
*
* \return SDL_TRUE if some keyboard support is available else SDL_FALSE.
* \returns SDL_TRUE if the platform has some screen keyboard support or
* SDL_FALSE if not.
*
* \note Not all screen keyboard functions are supported on all platforms.
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_IsScreenKeyboardShown()
* \sa SDL_StartTextInput
* \sa SDL_IsScreenKeyboardShown
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void);
/**
* \brief Returns whether the screen keyboard is shown for given window.
* Check whether the screen keyboard is shown for given window.
*
* \param window The window for which screen keyboard should be queried.
* \param window the window for which screen keyboard should be queried
* \returns SDL_TRUE if screen keyboard is shown or SDL_FALSE if not.
*
* \return SDL_TRUE if screen keyboard is shown else SDL_FALSE.
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_HasScreenKeyboardSupport()
* \sa SDL_HasScreenKeyboardSupport
*/
extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenKeyboardShown(SDL_Window *window);

40
include/SDL_loadso.h
View File

@ -51,22 +51,50 @@ extern "C" {
#endif
/**
* 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.
* Dynamically load a shared object.
*
* \param sofile a system-dependent name of the object file
* \returns an opaque pointer to the object handle or NULL if there was an
* error; call SDL_GetError() for more information.
*
* \sa SDL_LoadFunction
* \sa SDL_UnloadObject
*/
extern DECLSPEC void *SDLCALL SDL_LoadObject(const char *sofile);
/**
* 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().
* Look up the address of the named function in a shared object.
*
* This function pointer is no longer valid after calling SDL_UnloadObject().
*
* This function can only look up 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.
*
* If the requested function doesn't exist, NULL is returned.
*
* \param handle a valid shared object handle returned by SDL_LoadObject()
* \param name the name of the function to look up
* \returns a pointer to the function or NULL if there was an error; call
* SDL_GetError() for more information.
*
* \sa SDL_LoadObject
* \sa SDL_UnloadObject
*/
extern DECLSPEC void *SDLCALL SDL_LoadFunction(void *handle,
const char *name);
/**
* Unload a shared object from memory.
*
* \param handle a valid shared object handle returned by SDL_LoadObject()
*
* \sa SDL_LoadFunction
* \sa SDL_LoadObject
*/
extern DECLSPEC void SDLCALL SDL_UnloadObject(void *handle);

200
include/SDL_log.h
View File

@ -112,90 +112,254 @@ typedef enum
/**
* \brief Set the priority of all log categories
* Set the priority of all log categories.
*
* \param priority the SDL_LogPriority to assign
*
* \sa SDL_LogSetPriority
*/
extern DECLSPEC void SDLCALL SDL_LogSetAllPriority(SDL_LogPriority priority);
/**
* \brief Set the priority of a particular log category
* Set the priority of a particular log category.
*
* \param category the category to assign a priority to
* \param priority the SDL_LogPriority to assign
*
* \sa SDL_LogGetPriority
* \sa SDL_LogSetAllPriority
*/
extern DECLSPEC void SDLCALL SDL_LogSetPriority(int category,
SDL_LogPriority priority);
/**
* \brief Get the priority of a particular log category
* Get the priority of a particular log category.
*
* \param category the category to query
* \returns the SDL_LogPriority for the requested category
*
* \sa SDL_LogSetPriority
*/
extern DECLSPEC SDL_LogPriority SDLCALL SDL_LogGetPriority(int category);
/**
* \brief Reset all priorities to default.
* Reset all priorities to default.
*
* \note This is called in SDL_Quit().
* This is called by SDL_Quit().
*
* \sa SDL_LogSetAllPriority
* \sa SDL_LogSetPriority
*/
extern DECLSPEC void SDLCALL SDL_LogResetPriorities(void);
/**
* \brief Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO
* Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO.
*
= * \param fmt a printf() style message format string
* \param ... additional parameters matching % tokens in the `fmt` string,
* if any
*
* \sa SDL_LogCritical
* \sa SDL_LogDebug
* \sa SDL_LogError
* \sa SDL_LogInfo
* \sa SDL_LogMessage
* \sa SDL_LogMessageV
* \sa SDL_LogVerbose
* \sa SDL_LogWarn
*/
extern DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
/**
* \brief Log a message with SDL_LOG_PRIORITY_VERBOSE
* Log a message with SDL_LOG_PRIORITY_VERBOSE.
*
* \param category the category of the message
* \param fmt a printf() style message format string
* \param ... additional parameters matching % tokens in the **fmt** string,
* if any
*
* \sa SDL_Log
* \sa SDL_LogCritical
* \sa SDL_LogDebug
* \sa SDL_LogError
* \sa SDL_LogInfo
* \sa SDL_LogMessage
* \sa SDL_LogMessageV
* \sa SDL_LogWarn
*/
extern DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
/**
* \brief Log a message with SDL_LOG_PRIORITY_DEBUG
* Log a message with SDL_LOG_PRIORITY_DEBUG.
*
* \param category the category of the message
* \param fmt a printf() style message format string
* \param ... additional parameters matching % tokens in the **fmt** string,
* if any
*
* \sa SDL_Log
* \sa SDL_LogCritical
* \sa SDL_LogError
* \sa SDL_LogInfo
* \sa SDL_LogMessage
* \sa SDL_LogMessageV
* \sa SDL_LogVerbose
* \sa SDL_LogWarn
*/
extern DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
/**
* \brief Log a message with SDL_LOG_PRIORITY_INFO
* Log a message with SDL_LOG_PRIORITY_INFO.
*
* \param category the category of the message
* \param fmt a printf() style message format string
* \param ... additional parameters matching % tokens in the **fmt** string,
* if any
*
* \sa SDL_Log
* \sa SDL_LogCritical
* \sa SDL_LogDebug
* \sa SDL_LogError
* \sa SDL_LogMessage
* \sa SDL_LogMessageV
* \sa SDL_LogVerbose
* \sa SDL_LogWarn
*/
extern DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
/**
* \brief Log a message with SDL_LOG_PRIORITY_WARN
* Log a message with SDL_LOG_PRIORITY_WARN.
*
* \param category the category of the message
* \param fmt a printf() style message format string
* \param ... additional parameters matching % tokens in the **fmt** string,
* if any
*
* \sa SDL_Log
* \sa SDL_LogCritical
* \sa SDL_LogDebug
* \sa SDL_LogError
* \sa SDL_LogInfo
* \sa SDL_LogMessage
* \sa SDL_LogMessageV
* \sa SDL_LogVerbose
*/
extern DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
/**
* \brief Log a message with SDL_LOG_PRIORITY_ERROR
* Log a message with SDL_LOG_PRIORITY_ERROR.
*
* \param category the category of the message
* \param fmt a printf() style message format string
* \param ... additional parameters matching % tokens in the **fmt** string,
* if any
*
* \sa SDL_Log
* \sa SDL_LogCritical
* \sa SDL_LogDebug
* \sa SDL_LogInfo
* \sa SDL_LogMessage
* \sa SDL_LogMessageV
* \sa SDL_LogVerbose
* \sa SDL_LogWarn
*/
extern DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
/**
* \brief Log a message with SDL_LOG_PRIORITY_CRITICAL
* Log a message with SDL_LOG_PRIORITY_CRITICAL.
*
* \param category the category of the message
* \param fmt a printf() style message format string
* \param ... additional parameters matching % tokens in the **fmt** string,
* if any
*
* \sa SDL_Log
* \sa SDL_LogDebug
* \sa SDL_LogError
* \sa SDL_LogInfo
* \sa SDL_LogMessage
* \sa SDL_LogMessageV
* \sa SDL_LogVerbose
* \sa SDL_LogWarn
*/
extern DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
/**
* \brief Log a message with the specified category and priority.
* Log a message with the specified category and priority.
*
* \param category the category of the message
* \param priority the priority of the message
* \param fmt a printf() style message format string
* \param ... additional parameters matching % tokens in the **fmt** string,
* if any
*
* \sa SDL_Log
* \sa SDL_LogCritical
* \sa SDL_LogDebug
* \sa SDL_LogError
* \sa SDL_LogInfo
* \sa SDL_LogMessageV
* \sa SDL_LogVerbose
* \sa SDL_LogWarn
*/
extern DECLSPEC void SDLCALL SDL_LogMessage(int category,
SDL_LogPriority priority,
SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3);
/**
* \brief Log a message with the specified category and priority.
* Log a message with the specified category and priority.
*
* \param category the category of the message
* \param priority the priority of the message
* \param fmt a printf() style message format string
* \param ap a variable argument list
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_Log
* \sa SDL_LogCritical
* \sa SDL_LogDebug
* \sa SDL_LogError
* \sa SDL_LogInfo
* \sa SDL_LogMessage
* \sa SDL_LogVerbose
* \sa SDL_LogWarn
*/
extern DECLSPEC void SDLCALL SDL_LogMessageV(int category,
SDL_LogPriority priority,
const char *fmt, va_list ap);
/**
* \brief The prototype for the log output function
* The prototype for the log output callback function.
*
* This function is called by SDL when there is new text to be logged.
*
* \param userdata what was passed as `userdata` to SDL_LogSetOutputFunction()
* \param category the category of the message
* \param priority the priority of the message
* \param message the message being output
*/
typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message);
/**
* \brief Get the current log output function.
* Get the current log output function.
*
* \param callback an SDL_LogOutputFunction filled in with the current log
* callback
* \param userdata a pointer filled in with the pointer that is passed to
* `callback`
*
* \sa SDL_LogSetOutputFunction
*/
extern DECLSPEC void SDLCALL SDL_LogGetOutputFunction(SDL_LogOutputFunction *callback, void **userdata);
/**
* \brief This function allows you to replace the default log output
* function with one of your own.
* Replace the default log output function with one of your own.
*
* \param callback an SDL_LogOutputFunction to call instead of the default
* \param userdata a pointer that is passed to `callback`
*
* \sa SDL_LogGetOutputFunction
*/
extern DECLSPEC void SDLCALL SDL_LogSetOutputFunction(SDL_LogOutputFunction callback, void *userdata);

27
include/SDL_main.h
View File

@ -122,11 +122,14 @@ extern SDLMAIN_DECLSPEC int SDL_main(int argc, char *argv[]);
/**
* This is called by the real SDL main function to let the rest of the
* library know that initialization was done properly.
* Circumvent failure of SDL_Init() when not using SDL_main() as an entry point.
*
* Calling this yourself without knowing what you're doing can cause
* crashes and hard to diagnose problems with your application.
* This function is defined in SDL_main.h, along with the preprocessor rule to
* redefine main() as SDL_main(). Thus to ensure that your main() function
* will not be changed it is necessary to define SDL_MAIN_HANDLED before
* including SDL.h.
*
* \sa SDL_Init
*/
extern DECLSPEC void SDLCALL SDL_SetMainReady(void);
@ -144,12 +147,14 @@ extern DECLSPEC void SDLCALL SDL_UnregisterApp(void);
#ifdef __WINRT__
/**
* \brief Initializes and launches an SDL/WinRT application.
* Initialize and launch an SDL/WinRT application.
*
* \param mainFunction The SDL app's C-style main().
* \param reserved Reserved for future use; should be NULL
* \return 0 on success, -1 on failure. On failure, use SDL_GetError to retrieve more
* information on the failure.
* \param mainFunction the SDL app's C-style main(), an SDL_main_func
* \param reserved reserved for future use; should be NULL
* \returns 0 on success or -1 on failure; call SDL_GetError() to retrieve
* more information on the failure.
*
* \since This function is available since SDL 2.0.3.
*/
extern DECLSPEC int SDLCALL SDL_WinRTRunApp(SDL_main_func mainFunction, void * reserved);
@ -158,11 +163,11 @@ extern DECLSPEC int SDLCALL SDL_WinRTRunApp(SDL_main_func mainFunction, void * r
#if defined(__IPHONEOS__)
/**
* \brief Initializes and launches an SDL application.
* Initializes and launches an SDL application.
*
* \param argc The argc parameter from the application's main() function
* \param argv The argv parameter from the application's main() function
* \param mainFunction The SDL app's C-style main().
* \param mainFunction The SDL app's C-style main(), an SDL_main_func
* \return the return value from mainFunction
*/
extern DECLSPEC int SDLCALL SDL_UIKitRunApp(int argc, char *argv[], SDL_main_func mainFunction);

87
include/SDL_messagebox.h
View File

@ -32,7 +32,7 @@ extern "C" {
#endif
/**
* \brief SDL_MessageBox flags. If supported will display warning icon, etc.
* SDL_MessageBox flags. If supported will display warning icon, etc.
*/
typedef enum
{
@ -44,7 +44,7 @@ typedef enum
} SDL_MessageBoxFlags;
/**
* \brief Flags for SDL_MessageBoxButtonData.
* Flags for SDL_MessageBoxButtonData.
*/
typedef enum
{
@ -53,7 +53,7 @@ typedef enum
} SDL_MessageBoxButtonFlags;
/**
* \brief Individual button data.
* Individual button data.
*/
typedef struct
{
@ -63,7 +63,7 @@ typedef struct
} SDL_MessageBoxButtonData;
/**
* \brief RGB value used in a message box color scheme
* RGB value used in a message box color scheme
*/
typedef struct
{
@ -81,7 +81,7 @@ typedef enum
} SDL_MessageBoxColorType;
/**
* \brief A set of colors to use for message box dialogs
* A set of colors to use for message box dialogs
*/
typedef struct
{
@ -89,7 +89,7 @@ typedef struct
} SDL_MessageBoxColorScheme;
/**
* \brief MessageBox structure containing title, text, window, etc.
* MessageBox structure containing title, text, window, etc.
*/
typedef struct
{
@ -105,30 +105,77 @@ typedef struct
} SDL_MessageBoxData;
/**
* \brief Create a modal message box.
* Create a modal message box.
*
* \param messageboxdata The SDL_MessageBoxData structure with title, text, etc.
* \param buttonid The pointer to which user id of hit button should be copied.
* If your needs aren't complex, it might be easier to use
* SDL_ShowSimpleMessageBox.
*
* \return -1 on error, otherwise 0 and buttonid contains user id of button
* hit or -1 if dialog was closed.
*
* \note This function should be called on the thread that created the parent
* This function should be called on the thread that created the parent
* window, or on the main thread if the messagebox has no parent. It will
* block execution of that thread until the user clicks a button or
* closes the messagebox.
* block execution of that thread until the user clicks a button or closes the
* messagebox.
*
* This function may be called at any time, even before SDL_Init(). This makes
* it useful for reporting errors like a failure to create a renderer or
* OpenGL context.
*
* On X11, SDL rolls its own dialog box with X11 primitives instead of a
* formal toolkit like GTK+ or Qt.
*
* Note that if SDL_Init() would fail because there isn't any available video
* target, this function is likely to fail for the same reasons. If this is a
* concern, check the return value from this function and fall back to writing
* to stderr if you can.
*
* \param messageboxdata the SDL_MessageBoxData structure with title, text and
* other options
* \param buttonid the pointer to which user id of hit button should be copied
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_ShowSimpleMessageBox
*/
extern DECLSPEC int SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid);
/**
* \brief Create a simple modal message box
* Display a simple modal message box.
*
* \param flags ::SDL_MessageBoxFlags
* If your needs aren't complex, this function is preferred over
* SDL_ShowMessageBox.
*
* `flags` may be any of the following:
*
* - `SDL_MESSAGEBOX_ERROR`: error dialog
*
* - `SDL_MESSAGEBOX_WARNING`: warning dialog
*
* - `SDL_MESSAGEBOX_INFORMATION`: informational dialog
*
* This function should be called on the thread that created the parent
* window, or on the main thread if the messagebox has no parent. It will
* block execution of that thread until the user clicks a button or closes the
* messagebox.
*
* This function may be called at any time, even before SDL_Init(). This makes
* it useful for reporting errors like a failure to create a renderer or
* OpenGL context.
*
* On X11, SDL rolls its own dialog box with X11 primitives instead of a
* formal toolkit like GTK+ or Qt.
*
* Note that if SDL_Init() would fail because there isn't any available video
* target, this function is likely to fail for the same reasons. If this is a
* concern, check the return value from this function and fall back to writing
* to stderr if you can.
*
* \param flags an SDL_MessageBoxFlags value
* \param title UTF-8 title text
* \param message UTF-8 message text
* \param window The parent window, or NULL for no parent
*
* \return 0 on success, -1 on error
* \param window the parent window, or NULL for no parent
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_ShowMessageBox
*/

20
include/SDL_misc.h
View File

@ -38,13 +38,13 @@ extern "C" {
#endif
/**
* \brief Open an URL / URI in the browser or other
* Open a URL/URI in the browser or other appropriate external application.
*
* Open a URL in a separate, system-provided application. How this works will
* vary wildly depending on the platform. This will likely launch what
* makes sense to handle a specific URL's protocol (a web browser for http://,
* etc), but it might also be able to launch file managers for directories
* and other things.
* vary wildly depending on the platform. This will likely launch what makes
* sense to handle a specific URL's protocol (a web browser for `http://`,
* etc), but it might also be able to launch file managers for directories and
* other things.
*
* What happens when you open a URL varies wildly as well: your game window
* may lose focus (and may or may not lose focus if your game was fullscreen
@ -54,13 +54,17 @@ extern "C" {
*
* If this is unimplemented (or simply unavailable) for a platform, this will
* fail with an error. A successful result does not mean the URL loaded, just
* that we launched something to handle it (or at least believe we did).
* that we launched _something_ to handle it (or at least believe we did).
*
* All this to say: this function can be useful, but you should definitely
* test it on every platform you target.
*
* \param url A valid URL to open.
* \return 0 on success, or -1 on error.
* \param url A valid URL/URI to open. Use `file:///full/path/to/file` for
* local files, if supported.
* \returns 0 on success, or -1 on error; call SDL_GetError() for more
* information.
*
* \since This function is available in SDL 2.0.14 and newer
*/
extern DECLSPEC int SDLCALL SDL_OpenURL(const char *url);

310
include/SDL_mouse.h
View File

@ -72,150 +72,220 @@ typedef enum
/* Function prototypes */
/**
* \brief Get the window which currently has mouse focus.
* Get the window which currently has mouse focus.
*
* \returns the window with mouse focus.
*/
extern DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void);
/**
* \brief Retrieve the current state of the mouse.
* 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
* mouse cursor position relative to the focus window for the currently
* selected mouse. You can pass NULL for either x or y.
* The current button state is returned as a button bitmask, which can be
* tested using the `SDL_BUTTON(X)` macros (where `X` is generally 1 for the
* left, 2 for middle, 3 for the right button), and `x` and `y` are set to the
* mouse cursor position relative to the focus window. You can pass NULL for
* either `x` or `y`.
*
* \param x the x coordinate of the mouse cursor position relative to the
* focus window
* \param y the y coordinate of the mouse cursor position relative to the
* focus window
* \returns a 32-bit button bitmask of the current button state.
*
* \sa SDL_GetGlobalMouseState
* \sa SDL_GetRelativeMouseState
* \sa SDL_PumpEvents
*/
extern DECLSPEC Uint32 SDLCALL SDL_GetMouseState(int *x, int *y);
/**
* \brief Get the current state of the mouse, in relation to the desktop
* Get the current state of the mouse in relation to the desktop.
*
* This works just like SDL_GetMouseState(), but the coordinates will be
* reported relative to the top-left of the desktop. This can be useful if
* you need to track the mouse outside of a specific window and
* SDL_CaptureMouse() doesn't fit your needs. For example, it could be
* useful if you need to track the mouse while dragging a window, where
* coordinates relative to a window might not be in sync at all times.
* This works similarly to SDL_GetMouseState(), but the coordinates will be
* reported relative to the top-left of the desktop. This can be useful if you
* need to track the mouse outside of a specific window and SDL_CaptureMouse()
* doesn't fit your needs. For example, it could be useful if you need to
* track the mouse while dragging a window, where coordinates relative to a
* window might not be in sync at all times.
*
* \note SDL_GetMouseState() returns the mouse position as SDL understands
* it from the last pump of the event queue. This function, however,
* queries the OS for the current mouse position, and as such, might
* be a slightly less efficient function. Unless you know what you're
* doing and have a good reason to use this function, you probably want
* SDL_GetMouseState() instead.
* Note: SDL_GetMouseState() returns the mouse position as SDL understands it
* from the last pump of the event queue. This function, however, queries
* the OS for the current mouse position, and as such, might be a slightly
* less efficient function. Unless you know what you're doing and have a good
* reason to use this function, you probably want SDL_GetMouseState() instead.
*
* \param x Returns the current X coord, relative to the desktop. Can be NULL.
* \param y Returns the current Y coord, relative to the desktop. Can be NULL.
* \return The current button state as a bitmask, which can be tested using the SDL_BUTTON(X) macros.
* \param x filled in with the current X coord relative to the desktop; can be
* NULL
* \param y filled in with the current Y coord relative to the desktop; can be
* NULL
* \returns the current button state as a bitmask which can be tested using
* the SDL_BUTTON(X) macros.
*
* \sa SDL_GetMouseState
* \since This function is available since SDL 2.0.4.
*
* \sa SDL_CaptureMouse
*/
extern DECLSPEC Uint32 SDLCALL SDL_GetGlobalMouseState(int *x, int *y);
/**
* \brief Retrieve the relative state of the mouse.
* Retrieve the relative 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
* mouse deltas since the last call to SDL_GetRelativeMouseState().
* The current button state is returned as a button bitmask, which can be
* tested using the `SDL_BUTTON(X)` macros (where `X` is generally 1 for the
* left, 2 for middle, 3 for the right button), and `x` and `y` are set to the
* mouse deltas since the last call to SDL_GetRelativeMouseState() or since
* event initialization. You can pass NULL for either `x` or `y`.
*
* \param x a pointer filled with the last recorded x coordinate of the mouse
* \param y a pointer filled with the last recorded y coordinate of the mouse
* \returns a 32-bit button bitmask of the relative button state.
*
* \sa SDL_GetMouseState
*/
extern DECLSPEC Uint32 SDLCALL SDL_GetRelativeMouseState(int *x, int *y);
/**
* \brief Moves the mouse to the given position within the window.
* Move the mouse cursor to the given position within the window.
*
* \param window The window to move the mouse into, or NULL for the current mouse focus
* \param x The x coordinate within the window
* \param y The y coordinate within the window
* This function generates a mouse motion event.
*
* \note This function generates a mouse motion event
* \param window the window to move the mouse into, or NULL for the current
* mouse focus
* \param x the x coordinate within the window
* \param y the y coordinate within the window
*
* \sa SDL_WarpMouseGlobal
*/
extern DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * window,
int x, int y);
/**
* \brief Moves the mouse to the given position in global screen space.
* Move the mouse to the given position in global screen space.
*
* \param x The x coordinate
* \param y The y coordinate
* \return 0 on success, -1 on error (usually: unsupported by a platform).
* This function generates a mouse motion event.
*
* \note This function generates a mouse motion event
* A failure of this function usually means that it is unsupported by a
* platform.
*
* \param x the x coordinate
* \param y the y coordinate
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.4.
*
* \sa SDL_WarpMouseInWindow
*/
extern DECLSPEC int SDLCALL SDL_WarpMouseGlobal(int x, int y);
/**
* \brief Set relative mouse mode.
* Set relative mouse mode.
*
* \param enabled Whether or not to enable relative mode
* While the mouse is in relative mode, the cursor is hidden, and the driver
* will try to report continuous motion in the current window. Only relative
* motion events will be delivered, the mouse position will not change.
*
* \return 0 on success, or -1 if relative mode is not supported.
* This function will flush any pending mouse motion.
*
* While the mouse is in relative mode, the cursor is hidden, and the
* driver will try to report continuous motion in the current window.
* Only relative motion events will be delivered, the mouse position
* will not change.
* \param enabled SDL_TRUE to enable relative mode, SDL_FALSE to disable.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \note This function will flush any pending mouse motion.
* If relative mode is not supported, this returns -1.
*
* \sa SDL_GetRelativeMouseMode()
* \sa SDL_GetRelativeMouseMode
*/
extern DECLSPEC int SDLCALL SDL_SetRelativeMouseMode(SDL_bool enabled);
/**
* \brief Capture the mouse, to track input outside an SDL window.
* Capture the mouse and to track input outside an SDL window.
*
* \param enabled Whether or not to enable capturing
*
* Capturing enables your app to obtain mouse events globally, instead of
* just within your window. Not all video targets support this function.
* When capturing is enabled, the current window will get all mouse events,
* but unlike relative mode, no change is made to the cursor and it is
* not restrained to your window.
* Capturing enables your app to obtain mouse events globally, instead of just
* within your window. Not all video targets support this function. When
* capturing is enabled, the current window will get all mouse events, but
* unlike relative mode, no change is made to the cursor and it is not
* restrained to your window.
*
* This function may also deny mouse input to other windows--both those in
* your application and others on the system--so you should use this
* function sparingly, and in small bursts. For example, you might want to
* track the mouse while the user is dragging something, until the user
* releases a mouse button. It is not recommended that you capture the mouse
* for long periods of time, such as the entire time your app is running.
* your application and others on the system--so you should use this function
* sparingly, and in small bursts. For example, you might want to track the
* mouse while the user is dragging something, until the user releases a mouse
* button. It is not recommended that you capture the mouse for long periods
* of time, such as the entire time your app is running. For that, you should
* probably use SDL_SetRelativeMouseMode() or SDL_SetWindowGrab(), depending
* on your goals.
*
* While captured, mouse events still report coordinates relative to the
* current (foreground) window, but those coordinates may be outside the
* bounds of the window (including negative values). Capturing is only
* allowed for the foreground window. If the window loses focus while
* capturing, the capture will be disabled automatically.
* bounds of the window (including negative values). Capturing is only allowed
* for the foreground window. If the window loses focus while capturing, the
* capture will be disabled automatically.
*
* While capturing is enabled, the current window will have the
* SDL_WINDOW_MOUSE_CAPTURE flag set.
* `SDL_WINDOW_MOUSE_CAPTURE` flag set.
*
* \return 0 on success, or -1 if not supported.
* \param enabled SDL_TRUE to enable capturing, SDL_FALSE to disable.
* \returns 0 on success or -1 if not supported; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 2.0.4.
*
* \sa SDL_GetGlobalMouseState
*/
extern DECLSPEC int SDLCALL SDL_CaptureMouse(SDL_bool enabled);
/**
* \brief Query whether relative mouse mode is enabled.
* Query whether relative mouse mode is enabled.
*
* \sa SDL_SetRelativeMouseMode()
* \returns SDL_TRUE if relative mode is enabled or SDL_FALSE otherwise.
*
* \sa SDL_SetRelativeMouseMode
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(void);
/**
* \brief Create a cursor, using the specified bitmap data and
* Create a cursor using the specified bitmap data and
* mask (in MSB format).
*
* The cursor width must be a multiple of 8 bits.
* `mask` has to be in MSB (Most Significant Bit) format.
*
* The cursor width (`w`) must be a multiple of 8 bits.
*
* The cursor is created in black and white according to the following:
* <table>
* <tr><td> data </td><td> mask </td><td> resulting pixel on screen </td></tr>
* <tr><td> 0 </td><td> 1 </td><td> White </td></tr>
* <tr><td> 1 </td><td> 1 </td><td> Black </td></tr>
* <tr><td> 0 </td><td> 0 </td><td> Transparent </td></tr>
* <tr><td> 1 </td><td> 0 </td><td> Inverted color if possible, black
* if not. </td></tr>
* </table>
*
* \sa SDL_FreeCursor()
* - data=0, mask=1: white
*
* - data=1, mask=1: black
*
* - data=0, mask=1: transparent
*
* - data=1, mask=0: inverted color if possible, black if not.
*
* Cursors created with this function must be freed with SDL_FreeCursor().
*
* If you want to have a color cursor, or create your cursor from an
* SDL_Surface, you should use SDL_CreateColorCursor(). Alternately, you can
* hide the cursor and draw your own as part of your game's rendering, but it
* will be bound to the framerate.
*
* Also, since SDL 2.0.0, SDL_CreateSystemCursor() is available, which
* provides twelve readily available system cursors to pick from.
*
* \param data the color value for each pixel of the cursor
* \param mask the mask value for each pixel of the cursor
* \param w the width of the cursor
* \param h the height of the cursor
* \param hot_x the X-axis location of the upper left corner of the cursor
* relative to the actual mouse position
* \param hot_y the Y-axis location of the upper left corner of the cursor
* relative to the actual mouse position
* \returns a new cursor with the specified parameters on success or NULL on
* failure; call SDL_GetError() for more information.
*
* \sa SDL_FreeCursor
* \sa SDL_SetCursor
* \sa SDL_ShowCursor
*/
extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data,
const Uint8 * mask,
@ -223,57 +293,112 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data,
int hot_y);
/**
* \brief Create a color cursor.
* Create a color cursor.
*
* \sa SDL_FreeCursor()
* \param surface an SDL_Surface structure representing the cursor image
* \param hot_x the x position of the cursor hot spot
* \param hot_y the y position of the cursor hot spot
* \returns the new cursor on success or NULL on failure; call SDL_GetError()
* for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_CreateCursor
* \sa SDL_FreeCursor
*/
extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateColorCursor(SDL_Surface *surface,
int hot_x,
int hot_y);
/**
* \brief Create a system cursor.
* Create a system cursor.
*
* \sa SDL_FreeCursor()
* \param id an SDL_SystemCursor enum value
* \returns a cursor on success or NULL on failure; call SDL_GetError() for
* more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_FreeCursor
*/
extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor id);
/**
* \brief Set the active cursor.
* Set the active cursor.
*
* This function sets the currently active cursor to the specified one. If the
* cursor is currently visible, the change will be immediately represented on
* the display. SDL_SetCursor(NULL) can be used to force cursor redraw, if
* this is desired for any reason.
*
* \param cursor a cursor to make active
*
* \sa SDL_CreateCursor
* \sa SDL_GetCursor
* \sa SDL_ShowCursor
*/
extern DECLSPEC void SDLCALL SDL_SetCursor(SDL_Cursor * cursor);
/**
* \brief Return the active cursor.
* Get the active cursor.
*
* This function returns a pointer to the current cursor which is owned by the
* library. It is not necessary to free the cursor with SDL_FreeCursor().
*
* \returns the active cursor or NULL if there is no mouse.
*
* \sa SDL_SetCursor
*/
extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetCursor(void);
/**
* \brief Return the default cursor.
* Get the default cursor.
*
* \returns the default cursor on success or NULL on failure.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_CreateSystemCursor
*/
extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetDefaultCursor(void);
/**
* \brief Frees a cursor created with SDL_CreateCursor() or similar functions.
* Free a previously-created cursor.
*
* \sa SDL_CreateCursor()
* \sa SDL_CreateColorCursor()
* \sa SDL_CreateSystemCursor()
* Use this function to free cursor resources created with SDL_CreateCursor(),
* SDL_CreateColorCursor() or SDL_CreateSystemCursor().
*
* \param cursor the cursor to free
*
* \sa SDL_CreateColorCursor
* \sa SDL_CreateCursor
* \sa SDL_CreateSystemCursor
*/
extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor * cursor);
/**
* \brief Toggle whether or not the cursor is shown.
* Toggle whether or not the cursor is shown.
*
* \param toggle 1 to show the cursor, 0 to hide it, -1 to query the current
* state.
* The cursor starts off displayed but can be turned off. Passing `SDL_ENABLE`
* displays the cursor and passing `SDL_DISABLE` hides it.
*
* \return 1 if the cursor is shown, or 0 if the cursor is hidden.
* The current state of the mouse cursor can be queried by passing `SDL_QUERY`;
* either `SDL_DISABLE` or `SDL_ENABLE` will be returned.
*
* \param toggle `SDL_ENABLE` to show the cursor, `SDL_DISABLE` to hide it,
* `SDL_QUERY` to query the current state without changing it.
* \returns `SDL_ENABLE` if the cursor is shown, or `SDL_DISABLE` if the
* cursor is hidden, or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_CreateCursor
* \sa SDL_SetCursor
*/
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
@ -290,7 +415,6 @@ extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
#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
}

301
include/SDL_mutex.h
View File

@ -59,38 +59,95 @@ struct SDL_mutex;
typedef struct SDL_mutex SDL_mutex;
/**
* Create a mutex, initialized unlocked.
* Create a new mutex.
*
* All newly-created mutexes begin in the _unlocked_ state.
*
* Calls to SDL_LockMutex() will not return while the mutex is locked by
* another thread. See SDL_TryLockMutex() to attempt to lock without blocking.
*
* SDL mutexes are reentrant.
*
* \returns the initialized and unlocked mutex or NULL on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_DestroyMutex
* \sa SDL_LockMutex
* \sa SDL_TryLockMutex
* \sa SDL_UnlockMutex
*/
extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void);
/**
* Lock the mutex.
*
* This will block until the mutex is available, which is to say it is in the
* unlocked state and the OS has chosen the caller as the next thread to lock
* it. Of all threads waiting to lock the mutex, only one may do so at a time.
*
* It is legal for the owning thread to lock an already-locked mutex. It must
* unlock it the same number of times before it is actually made available
* for other threads in the system (this is known as a "recursive mutex").
*
* \param mutex the mutex to lock
* \return 0, or -1 on error.
*/
#define SDL_mutexP(m) SDL_LockMutex(m)
extern DECLSPEC int SDLCALL SDL_LockMutex(SDL_mutex * mutex);
#define SDL_mutexP(m) SDL_LockMutex(m)
/**
* Try to lock the mutex
* Try to lock a mutex without blocking.
*
* \return 0, SDL_MUTEX_TIMEDOUT, or -1 on error
* This works just like SDL_LockMutex(), but if the mutex is not available,
* this function returns `SDL_MUTEX_TIMEOUT` immediately.
*
* This technique is useful if you need exclusive access to a resource but
* don't want to wait for it, and will return to it to try again later.
*
* \param mutex the mutex to try to lock
* \returns return 0, `SDL_MUTEX_TIMEDOUT`, or -1 on error; call
* SDL_GetError() for more information.
*
* \sa SDL_CreateMutex
* \sa SDL_DestroyMutex
* \sa SDL_LockMutex
* \sa SDL_UnlockMutex
*/
extern DECLSPEC int SDLCALL SDL_TryLockMutex(SDL_mutex * mutex);
/**
* Unlock the mutex.
*
* \return 0, or -1 on error.
* It is legal for the owning thread to lock an already-locked mutex. It must
* unlock it the same number of times before it is actually made available
* for other threads in the system (this is known as a "recursive mutex").
*
* \warning It is an error to unlock a mutex that has not been locked by
* the current thread, and doing so results in undefined behavior.
* It is an error to unlock a mutex that has not been locked by the current
* thread, and doing so results in undefined behavior.
*
* It is also an error to unlock a mutex that isn't locked at all.
*
* \param mutex the mutex to unlock.
* \returns 0, or -1 on error.
*/
#define SDL_mutexV(m) SDL_UnlockMutex(m)
extern DECLSPEC int SDLCALL SDL_UnlockMutex(SDL_mutex * mutex);
#define SDL_mutexV(m) SDL_UnlockMutex(m)
/**
* Destroy a mutex.
* Destroy a mutex created with SDL_CreateMutex().
*
* This function must be called on any mutex that is no longer needed. Failure
* to destroy a mutex will result in a system memory or resource leak. While
* it is safe to destroy a mutex that is _unlocked_, it is not safe to attempt
* to destroy a locked mutex, and may result in undefined behavior depending
* on the platform.
*
* \param mutex the mutex to destroy
*
* \sa SDL_CreateMutex
* \sa SDL_LockMutex
* \sa SDL_TryLockMutex
* \sa SDL_UnlockMutex
*/
extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex * mutex);
@ -107,50 +164,138 @@ struct SDL_semaphore;
typedef struct SDL_semaphore SDL_sem;
/**
* Create a semaphore, initialized with value, returns NULL on failure.
* Create a semaphore.
*
* This function creates a new semaphore and initializes it with the value
* `initial_value`. Each wait operation on the semaphore will atomically
* decrement the semaphore value and potentially block if the semaphore value
* is 0. Each post operation will atomically increment the semaphore value and
* wake waiting threads and allow them to retry the wait operation.
*
* \param initial_value the starting value of the semaphore
* \returns a new semaphore or NULL on failure; call SDL_GetError() for more
* information.
*
* \sa SDL_DestroySemaphore
* \sa SDL_SemPost
* \sa SDL_SemTryWait
* \sa SDL_SemValue
* \sa SDL_SemWait
* \sa SDL_SemWaitTimeout
*/
extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
/**
* Destroy a semaphore.
*
* It is not safe to destroy a semaphore if there are threads currently
* waiting on it.
*
* \param sem the semaphore to destroy
*
* \sa SDL_CreateSemaphore
* \sa SDL_SemPost
* \sa SDL_SemTryWait
* \sa SDL_SemValue
* \sa SDL_SemWait
* \sa SDL_SemWaitTimeout
*/
extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem);
/**
* This function suspends the calling thread until the semaphore pointed
* to by \c sem has a positive count. It then atomically decreases the
* semaphore count.
* Wait until a semaphore has a positive value and then decrements it.
*
* This function suspends the calling thread until either the semaphore
* pointed to by `sem` has a positive value or the call is interrupted by a
* signal or error. If the call is successful it will atomically decrement the
* semaphore value.
*
* This function is the equivalent of calling SDL_SemWaitTimeout() with a time
* length of `SDL_MUTEX_MAXWAIT`.
*
* \param sem the semaphore wait on
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_CreateSemaphore
* \sa SDL_DestroySemaphore
* \sa SDL_SemPost
* \sa SDL_SemTryWait
* \sa SDL_SemValue
* \sa SDL_SemWait
* \sa SDL_SemWaitTimeout
*/
extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem);
/**
* Non-blocking variant of SDL_SemWait().
* See if a semaphore has a positive value and decrement it if it does.
*
* \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait would
* block, and -1 on error.
* This function checks to see if the semaphore pointed to by `sem` has a
* positive value and atomically decrements the semaphore value if it does. If
* the semaphore doesn't have a positive value, the function immediately
* returns SDL_MUTEX_TIMEDOUT.
*
* \param sem the semaphore to wait on
* \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait would
* block, or a negative error code on failure; call SDL_GetError()
* for more information.
*
* \sa SDL_CreateSemaphore
* \sa SDL_DestroySemaphore
* \sa SDL_SemPost
* \sa SDL_SemValue
* \sa SDL_SemWait
* \sa SDL_SemWaitTimeout
*/
extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem);
/**
* Variant of SDL_SemWait() with a timeout in milliseconds.
* Wait until a semaphore has a positive value and then
* decrements it.
*
* \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait does not
* succeed in the allotted time, and -1 on error.
* This function suspends the calling thread until either the semaphore
* pointed to by `sem` has a positive value, the call is interrupted by a
* signal or error, or the specified time has elapsed. If the call is
* successful it will atomically decrement the semaphore value.
*
* \warning On some platforms this function is implemented by looping with a
* delay of 1 ms, and so should be avoided if possible.
* \param sem the semaphore to wait on
* \param ms the length of the timeout, in milliseconds
* \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait does not
* succeed in the allotted time, or a negative error code on failure;
* call SDL_GetError() for more information.
*
* \sa SDL_CreateSemaphore
* \sa SDL_DestroySemaphore
* \sa SDL_SemPost
* \sa SDL_SemTryWait
* \sa SDL_SemValue
* \sa SDL_SemWait
*/
extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem * sem, Uint32 ms);
/**
* Atomically increases the semaphore's count (not blocking).
* Atomically increment a semaphore's value and wake waiting threads.
*
* \return 0, or -1 on error.
* \param sem the semaphore to increment
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_CreateSemaphore
* \sa SDL_DestroySemaphore
* \sa SDL_SemTryWait
* \sa SDL_SemValue
* \sa SDL_SemWait
* \sa SDL_SemWaitTimeout
*/
extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem);
/**
* Returns the current count of the semaphore.
* Get the current value of a semaphore.
*
* \param sem the semaphore to query
* \returns the current value of the semaphore.
*
* \sa SDL_CreateSemaphore
*/
extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem * sem);
@ -169,70 +314,110 @@ typedef struct SDL_cond SDL_cond;
/**
* Create a condition variable.
*
* Typical use of condition variables:
* \returns a new condition variable or NULL on failure; call SDL_GetError()
* for more information.
*
* Thread A:
* SDL_LockMutex(lock);
* while ( ! condition ) {
* SDL_CondWait(cond, lock);
* }
* SDL_UnlockMutex(lock);
*
* Thread B:
* SDL_LockMutex(lock);
* ...
* condition = true;
* ...
* SDL_CondSignal(cond);
* SDL_UnlockMutex(lock);
*
* There is some discussion whether to signal the condition variable
* with the mutex locked or not. There is some potential performance
* benefit to unlocking first on some platforms, but there are some
* potential race conditions depending on how your code is structured.
*
* In general it's safer to signal the condition variable while the
* mutex is locked.
* \sa SDL_CondBroadcast
* \sa SDL_CondSignal
* \sa SDL_CondWait
* \sa SDL_CondWaitTimeout
* \sa SDL_DestroyCond
*/
extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void);
/**
* Destroy a condition variable.
*
* \param cond the condition variable to destroy
*
* \sa SDL_CondBroadcast
* \sa SDL_CondSignal
* \sa SDL_CondWait
* \sa SDL_CondWaitTimeout
* \sa SDL_CreateCond
*/
extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * cond);
/**
* Restart one of the threads that are waiting on the condition variable.
*
* \return 0 or -1 on error.
* \param cond the condition variable to signal
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_CondBroadcast
* \sa SDL_CondWait
* \sa SDL_CondWaitTimeout
* \sa SDL_CreateCond
* \sa SDL_DestroyCond
*/
extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * cond);
/**
* Restart all threads that are waiting on the condition variable.
*
* \return 0 or -1 on error.
* \param cond the condition variable to signal
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_CondSignal
* \sa SDL_CondWait
* \sa SDL_CondWaitTimeout
* \sa SDL_CreateCond
* \sa SDL_DestroyCond
*/
extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond);
/**
* Wait on the condition variable, unlocking the provided mutex.
* Wait until a condition variable is signaled.
*
* \warning The mutex must be locked before entering this function!
* This function unlocks the specified `mutex` and waits for another thread
* to call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable
* `cond`. Once the condition variable is signaled, the mutex is re-locked
* and the function returns.
*
* The mutex is re-locked once the condition variable is signaled.
* The mutex must be locked before calling this function.
*
* \return 0 when it is signaled, or -1 on error.
* This function is the equivalent of calling SDL_CondWaitTimeout() with a
* time length of `SDL_MUTEX_MAXWAIT`.
*
* \param cond the condition variable to wait on
* \param mutex the mutex used to coordinate thread access
* \returns 0 when it is signaled or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_CondBroadcast
* \sa SDL_CondSignal
* \sa SDL_CondWaitTimeout
* \sa SDL_CreateCond
* \sa SDL_DestroyCond
*/
extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mutex);
/**
* Waits for at most \c 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.
* Wait until a condition variable is signaled or a certain time has passed.
*
* \warning On some platforms this function is implemented by looping with a
* delay of 1 ms, and so should be avoided if possible.
* This function unlocks the specified `mutex` and waits for another thread
* to call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable
* `cond`, or for the specified time to elapse. Once the condition variable
* is signaled or the time elapsed, the mutex is re-locked and the function
* returns.
*
* The mutex must be locked before calling this function.
*
* \param cond the condition variable to wait on
* \param mutex the mutex used to coordinate thread access
* \param ms the maximum time to wait, in milliseconds, or `SDL_MUTEX_MAXWAIT`
* to wait indefinitely
* \returns 0 if the condition variable is signaled, `SDL_MUTEX_TIMEDOUT` if
* the condition is not signaled in the allotted time, or a negative
* error code on failure; call SDL_GetError() for more information.
*
* \sa SDL_CondBroadcast
* \sa SDL_CondSignal
* \sa SDL_CondWait
* \sa SDL_CreateCond
* \sa SDL_DestroyCond
*/
extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond * cond,
SDL_mutex * mutex, Uint32 ms);

192
include/SDL_pixels.h
View File

@ -345,16 +345,29 @@ typedef struct SDL_PixelFormat
} SDL_PixelFormat;
/**
* \brief Get the human readable name of a pixel format
* Get the human readable name of a pixel format.
*
* \param format the pixel format to query
* \returns the human readable name of the specified pixel format or
* `SDL_PIXELFORMAT_UNKNOWN` if the format isn't recognized.
*
* \since This function is available since SDL 2.0.0.
*/
extern DECLSPEC const char* SDLCALL SDL_GetPixelFormatName(Uint32 format);
/**
* \brief Convert one of the enumerated pixel formats to a bpp and RGBA masks.
* Convert one of the enumerated pixel formats to a bpp value and RGBA masks.
*
* \return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible.
* \param format one of the SDL_PixelFormatEnum values
* \param bpp a bits per pixel value; usually 15, 16, or 32
* \param Rmask a pointer filled in with the red mask for the format
* \param Gmask a pointer filled in with the green mask for the format
* \param Bmask a pointer filled in with the blue mask for the format
* \param Amask a pointer filled in with the alpha mask for the format
* \returns SDL_TRUE on success or SDL_FALSE if the conversion wasn't
* possible; call SDL_GetError() for more information.
*
* \sa SDL_MasksToPixelFormatEnum()
* \sa SDL_MasksToPixelFormatEnum
*/
extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format,
int *bpp,
@ -364,12 +377,19 @@ extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format,
Uint32 * Amask);
/**
* \brief Convert a bpp and RGBA masks to an enumerated pixel format.
* Convert a bpp value and RGBA masks to an enumerated pixel format.
*
* \return The pixel format, or ::SDL_PIXELFORMAT_UNKNOWN if the conversion
* wasn't possible.
* This will return `SDL_PIXELFORMAT_UNKNOWN` if the conversion wasn't
* possible.
*
* \sa SDL_PixelFormatEnumToMasks()
* \param bpp a bits per pixel value; usually 15, 16, or 32
* \param Rmask the red mask for the format
* \param Gmask the green mask for the format
* \param Bmask the blue mask for the format
* \param Amask the alpha mask for the format
* \returns one of the SDL_PixelFormatEnum values
*
* \sa SDL_PixelFormatEnumToMasks
*/
extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
Uint32 Rmask,
@ -378,65 +398,142 @@ extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
Uint32 Amask);
/**
* \brief Create an SDL_PixelFormat structure from a pixel format enum.
* Create an SDL_PixelFormat structure corresponding to a pixel format.
*
* Returned structure may come from a shared global cache (i.e. not newly
* allocated), and hence should not be modified, especially the palette. Weird
* errors such as `Blit combination not supported` may occur.
*
* \param pixel_format one of the SDL_PixelFormatEnum values
* \returns the new SDL_PixelFormat structure or NULL on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_FreeFormat
*/
extern DECLSPEC SDL_PixelFormat * SDLCALL SDL_AllocFormat(Uint32 pixel_format);
/**
* \brief Free an SDL_PixelFormat structure.
* Free an SDL_PixelFormat structure allocated by SDL_AllocFormat().
*
* \param format the SDL_PixelFormat structure to free
*
* \sa SDL_AllocFormat
*/
extern DECLSPEC void SDLCALL SDL_FreeFormat(SDL_PixelFormat *format);
/**
* \brief Create a palette structure with the specified number of color
* entries.
* Create a palette structure with the specified number of color entries.
*
* \return A new palette, or NULL if there wasn't enough memory.
* The palette entries are initialized to white.
*
* \note The palette entries are initialized to white.
* \param ncolors represents the number of color entries in the color palette
* \returns a new SDL_Palette structure on success or NULL on failure (e.g. if
* there wasn't enough memory); call SDL_GetError() for more
* information.
*
* \sa SDL_FreePalette()
* \sa SDL_FreePalette
*/
extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors);
/**
* \brief Set the palette for a pixel format structure.
* Set the palette for a pixel format structure.
*
* \param format the SDL_PixelFormat structure that will use the palette
* \param palette the SDL_Palette structure that will be used
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_AllocPalette
* \sa SDL_FreePalette
*/
extern DECLSPEC int SDLCALL SDL_SetPixelFormatPalette(SDL_PixelFormat * format,
SDL_Palette *palette);
/**
* \brief Set a range of colors in a palette.
* Set a range of colors in a palette.
*
* \param palette The palette to modify.
* \param colors An array of colors to copy into the palette.
* \param firstcolor The index of the first palette entry to modify.
* \param ncolors The number of entries to modify.
* \param palette the SDL_Palette structure to modify
* \param colors an array of SDL_Color structures to copy into the palette
* \param firstcolor the index of the first palette entry to modify
* \param ncolors the number of entries to modify
* \returns 0 on success or a negative error code if not all of the colors
* could be set; call SDL_GetError() for more information.
*
* \return 0 on success, or -1 if not all of the colors could be set.
* \sa SDL_AllocPalette
* \sa SDL_CreateRGBSurface
*/
extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette,
const SDL_Color * colors,
int firstcolor, int ncolors);
/**
* \brief Free a palette created with SDL_AllocPalette().
* Free a palette created with SDL_AllocPalette().
*
* \sa SDL_AllocPalette()
* \param palette the SDL_Palette structure to be freed
*
* \sa SDL_AllocPalette
*/
extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette);
/**
* \brief Maps an RGB triple to an opaque pixel value for a given pixel format.
* Map an RGB triple to an opaque pixel value for a given pixel format.
*
* This function maps the RGB color value to the specified pixel format and
* returns the pixel value best approximating the given RGB color value for
* the given pixel format.
*
* If the format has a palette (8-bit) the index of the closest matching color
* in the palette will be returned.
*
* If the specified pixel format has an alpha component it will be returned as
* all 1 bits (fully opaque).
*
* If the pixel format bpp (color depth) is less than 32-bpp then the unused
* upper bits of the return value can safely be ignored (e.g., with a 16-bpp
* format the return value can be assigned to a Uint16, and similarly a Uint8
* for an 8-bpp format).
*
* \param format an SDL_PixelFormat structure describing the pixel format
* \param r the red component of the pixel in the range 0-255
* \param g the green component of the pixel in the range 0-255
* \param b the blue component of the pixel in the range 0-255
* \returns a pixel value
*
* \sa SDL_GetRGB
* \sa SDL_GetRGBA
* \sa SDL_MapRGBA
*/
extern DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format,
Uint8 r, Uint8 g, Uint8 b);
/**
* \brief Maps an RGBA quadruple to a pixel value for a given pixel format.
* Map an RGBA quadruple to a pixel value for a given pixel format.
*
* This function maps the RGBA color value to the specified pixel format and
* returns the pixel value best approximating the given RGBA color value for
* the given pixel format.
*
* If the specified pixel format has no alpha component the alpha value will
* be ignored (as it will be in formats with a palette).
*
* If the format has a palette (8-bit) the index of the closest matching color
* in the palette will be returned.
*
* If the pixel format bpp (color depth) is less than 32-bpp then the unused
* upper bits of the return value can safely be ignored (e.g., with a 16-bpp
* format the return value can be assigned to a Uint16, and similarly a Uint8
* for an 8-bpp format).
*
* \param format an SDL_PixelFormat structure describing the format of the
* pixel
* \param r the red component of the pixel in the range 0-255
* \param g the green component of the pixel in the range 0-255
* \param b the blue component of the pixel in the range 0-255
* \param a the alpha component of the pixel in the range 0-255
* \returns a pixel value
*
* \sa SDL_GetRGB
* \sa SDL_GetRGBA
* \sa SDL_MapRGB
*/
extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format,
@ -444,18 +541,50 @@ extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format,
Uint8 a);
/**
* \brief Get the RGB components from a pixel of the specified format.
* Get RGB values from a pixel in the specified format.
*
* This function uses the entire 8-bit [0..255] range when converting color
* components from pixel formats with less than 8-bits per RGB component
* (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff,
* 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
*
* \param pixel a pixel value
* \param format an SDL_PixelFormat structure describing the format of the
* pixel
* \param r a pointer filled in with the red component
* \param g a pointer filled in with the green component
* \param b a pointer filled in with the blue component
*
* \sa SDL_GetRGBA
* \sa SDL_MapRGB
* \sa SDL_MapRGBA
*/
extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
const SDL_PixelFormat * format,
Uint8 * r, Uint8 * g, Uint8 * b);
/**
* \brief Get the RGBA components from a pixel of the specified format.
* Get RGBA values from a pixel in the specified format.
*
* This function uses the entire 8-bit [0..255] range when converting color
* components from pixel formats with less than 8-bits per RGB component
* (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff,
* 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
*
* If the surface has no alpha component, the alpha will be returned as 0xff
* (100% opaque).
*
* \param pixel a pixel value
* \param format an SDL_PixelFormat structure describing the format of the
* pixel
* \param r a pointer filled in with the red component
* \param g a pointer filled in with the green component
* \param b a pointer filled in with the blue component
* \param a a pointer filled in with the alpha component
*
* \sa SDL_GetRGB
* \sa SDL_MapRGB
* \sa SDL_MapRGBA
*/
extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
const SDL_PixelFormat * format,
@ -463,7 +592,12 @@ extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
Uint8 * a);
/**
* \brief Calculate a 256 entry gamma ramp for a gamma value.
* Calculate a 256 entry gamma ramp for a gamma value.
*
* \param gamma a gamma value where 0.0 is black and 1.0 is identity
* \param ramp an array of 256 values filled in with the gamma ramp
*
* \sa SDL_SetWindowGammaRamp
*/
extern DECLSPEC void SDLCALL SDL_CalculateGammaRamp(float gamma, Uint16 * ramp);

17
include/SDL_platform.h
View File

@ -186,7 +186,22 @@ extern "C" {
#endif
/**
* \brief Gets the name of the platform.
* Get the name of the platform.
*
* Here are the names returned for some (but not all) supported platforms:
*
* - "Windows"
*
* - "Mac OS X"
*
* - "Linux"
*
* - "iOS"
*
* - "Android"
*
* \returns the name of the platform. If the correct platform name is not
* available, returns a string beginning with the text "Unknown".
*/
extern DECLSPEC const char * SDLCALL SDL_GetPlatform (void);

29
include/SDL_power.h
View File

@ -37,7 +37,7 @@ extern "C" {
#endif
/**
* \brief The basic state for the system's power supply.
* The basic state for the system's power supply.
*/
typedef enum
{
@ -50,17 +50,28 @@ typedef enum
/**
* \brief Get the current power supply details.
* Get the current power supply details.
*
* \param secs Seconds of battery life left. You can pass a NULL here if
* you don't care. Will return -1 if we can't determine a
* value, or we're not running on a battery.
* You should never take a battery status as absolute truth. Batteries
* (especially failing batteries) are delicate hardware, and the values
* reported here are best estimates based on what that hardware reports. It's
* not uncommon for older batteries to lose stored power much faster than it
* reports, or completely drain when reporting it has 20 percent left, etc.
*
* \param pct Percentage of battery life left, between 0 and 100. You can
* pass a NULL here if you don't care. Will return -1 if we
* can't determine a value, or we're not running on a battery.
* Battery status can change at any time; if you are concerned with power
* state, you should call this function frequently, and perhaps ignore changes
* until they seem to be stable for a few seconds.
*
* \return The state of the battery (if any).
* It's possible a platform can only report battery percentage or time left
* but not both.
*
* \param secs seconds of battery life left, you can pass a NULL here if you
* don't care, will return -1 if we can't determine a value, or
* we're not running on a battery
* \param pct percentage of battery life left, between 0 and 100, you can pass
* a NULL here if you don't care, will return -1 if we can't
* determine a value, or we're not running on a battery
* \returns an SDL_PowerState enum representing the current battery state.
*/
extern DECLSPEC SDL_PowerState SDLCALL SDL_GetPowerInfo(int *secs, int *pct);

76
include/SDL_rect.h
View File

@ -40,7 +40,7 @@ extern "C" {
#endif
/**
* \brief The structure that defines a point (integer)
* The structure that defines a point (integer)
*
* \sa SDL_EnclosePoints
* \sa SDL_PointInRect
@ -52,7 +52,7 @@ typedef struct SDL_Point
} SDL_Point;
/**
* \brief The structure that defines a point (floating point)
* The structure that defines a point (floating point)
*
* \sa SDL_EnclosePoints
* \sa SDL_PointInRect
@ -65,7 +65,7 @@ typedef struct SDL_FPoint
/**
* \brief A rectangle, with the origin at the upper left (integer).
* A rectangle, with the origin at the upper left (integer).
*
* \sa SDL_RectEmpty
* \sa SDL_RectEquals
@ -82,7 +82,7 @@ typedef struct SDL_Rect
/**
* \brief A rectangle, with the origin at the upper left (floating point).
* A rectangle, with the origin at the upper left (floating point).
*/
typedef struct SDL_FRect
{
@ -94,7 +94,7 @@ typedef struct SDL_FRect
/**
* \brief Returns true if point resides inside a rectangle.
* Returns true if point resides inside a rectangle.
*/
SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r)
{
@ -103,7 +103,7 @@ SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r)
}
/**
* \brief Returns true if the rectangle has no area.
* Returns true if the rectangle has no area.
*/
SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r)
{
@ -111,7 +111,7 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r)
}
/**
* \brief Returns true if the two rectangles are equal.
* Returns true if the two rectangles are equal.
*/
SDL_FORCE_INLINE SDL_bool SDL_RectEquals(const SDL_Rect *a, const SDL_Rect *b)
{
@ -120,33 +120,66 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEquals(const SDL_Rect *a, const SDL_Rect *b)
}
/**
* \brief Determine whether two rectangles intersect.
* Determine whether two rectangles intersect.
*
* \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
* If either pointer is NULL the function will return SDL_FALSE.
*
* \param A an SDL_Rect structure representing the first rectangle
* \param B an SDL_Rect structure representing the second rectangle
* \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_IntersectRect
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasIntersection(const SDL_Rect * A,
const SDL_Rect * B);
/**
* \brief Calculate the intersection of two rectangles.
* Calculate the intersection of two rectangles.
*
* \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
* If `result` is NULL then this function will return SDL_FALSE.
*
* \param A an SDL_Rect structure representing the first rectangle
* \param B an SDL_Rect structure representing the second rectangle
* \param result an SDL_Rect structure filled in with the intersection of
* rectangles `A` and `B`
* \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_HasIntersection
*/
extern DECLSPEC SDL_bool SDLCALL SDL_IntersectRect(const SDL_Rect * A,
const SDL_Rect * B,
SDL_Rect * result);
/**
* \brief Calculate the union of two rectangles.
* Calculate the union of two rectangles.
*
* \param A an SDL_Rect structure representing the first rectangle
* \param B an SDL_Rect structure representing the second rectangle
* \param result an SDL_Rect structure filled in with the union of rectangles
* `A` and `B`
*/
extern DECLSPEC void SDLCALL SDL_UnionRect(const SDL_Rect * A,
const SDL_Rect * B,
SDL_Rect * result);
/**
* \brief Calculate a minimal rectangle enclosing a set of points
* Calculate a minimal rectangle enclosing a set of points.
*
* \return SDL_TRUE if any points were within the clipping rect
* If `clip` is not NULL then only points inside of the clipping rectangle
* are considered.
*
* \param points an array of SDL_Point structures representing points to be
* enclosed
* \param count the number of structures in the `points` array
* \param clip an SDL_Rect used for clipping or NULL to enclose all points
* \param result an SDL_Rect structure filled in with the minimal enclosing
* rectangle
* \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the
* points were outside of the clipping rectangle.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_EnclosePoints(const SDL_Point * points,
int count,
@ -154,9 +187,20 @@ extern DECLSPEC SDL_bool SDLCALL SDL_EnclosePoints(const SDL_Point * points,
SDL_Rect * result);
/**
* \brief Calculate the intersection of a rectangle and line segment.
* Calculate the intersection of a rectangle and line segment.
*
* \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
* This function is used to clip a line segment to a rectangle. A line segment
* contained entirely within the rectangle or that does not intersect will
* remain unchanged. A line segment that crosses the rectangle at either or
* both ends will be clipped to the boundary of the rectangle and the new
* coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary.
*
* \param rect an SDL_Rect structure representing the rectangle to intersect
* \param X1 a pointer to the starting X-coordinate of the line
* \param Y1 a pointer to the starting Y-coordinate of the line
* \param X2 a pointer to the ending X-coordinate of the line
* \param Y2 a pointer to the ending Y-coordinate of the line
* \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_IntersectRectAndLine(const SDL_Rect *
rect, int *X1,

1299
include/SDL_render.h
View File

File diff suppressed because it is too large Load Diff

173
include/SDL_rwops.h
View File

@ -182,77 +182,194 @@ extern DECLSPEC void SDLCALL SDL_FreeRW(SDL_RWops * area);
#define RW_SEEK_END 2 /**< Seek relative to the end of data */
/**
* Return the size of the file in this rwops, or -1 if unknown
* Use this macro to get the size of the data stream in an SDL_RWops.
*
* \param context the SDL_RWops to get the size of the data stream from
* \returns the size of the data stream in the SDL_RWops on success, -1 if
* unknown or a negative error code on failure; call SDL_GetError()
* for more information.
*
* \since This function is available since SDL 2.0.0.
*/
extern DECLSPEC Sint64 SDLCALL SDL_RWsize(SDL_RWops *context);
/**
* Seek to \c offset relative to \c whence, one of stdio's whence values:
* RW_SEEK_SET, RW_SEEK_CUR, RW_SEEK_END
* Seek within an SDL_RWops data stream.
*
* \return the final offset in the data stream, or -1 on error.
* This function seeks to byte `offset`, relative to `whence`.
*
* `whence` may be any of the following values:
*
* - `RW_SEEK_SET`: seek from the beginning of data
*
* - `RW_SEEK_CUR`: seek relative to current read point
*
* - `RW_SEEK_END`: seek relative to the end of data
*
* If this stream can not seek, it will return -1.
*
* SDL_RWseek() is actually a wrapper function that calls the SDL_RWops's
* `seek` method appropriately, to simplify application development.
*
* \param context a pointer to an SDL_RWops structure
* \param offset an offset in bytes, relative to **whence** location; can be
* negative
* \param whence any of `RW_SEEK_SET`, `RW_SEEK_CUR`, `RW_SEEK_END`
* \returns the final offset in the data stream after the seek or -1 on error.
*
* \sa SDL_RWclose
* \sa SDL_RWFromConstMem
* \sa SDL_RWFromFile
* \sa SDL_RWFromFP
* \sa SDL_RWFromMem
* \sa SDL_RWread
* \sa SDL_RWtell
* \sa SDL_RWwrite
*/
extern DECLSPEC Sint64 SDLCALL SDL_RWseek(SDL_RWops *context,
Sint64 offset, int whence);
/**
* Return the current offset in the data stream, or -1 on error.
* Determine the current read/write offset in an SDL_RWops data stream.
*
* SDL_RWtell is actually a wrapper function that calls the SDL_RWops's
* `seek` method, with an offset of 0 bytes from `RW_SEEK_CUR`, to simplify
* application development.
*
* \param context a SDL_RWops data stream object from which to get the current
* offset
* \returns the current offset in the stream, or -1 if the information can not
* be determined.
*
* \sa SDL_RWclose
* \sa SDL_RWFromConstMem
* \sa SDL_RWFromFile
* \sa SDL_RWFromFP
* \sa SDL_RWFromMem
* \sa SDL_RWread
* \sa SDL_RWseek
* \sa SDL_RWwrite
*/
extern DECLSPEC Sint64 SDLCALL SDL_RWtell(SDL_RWops *context);
/**
* Read up to \c maxnum objects each of size \c size from the data
* stream to the area pointed at by \c ptr.
* Read from a data source.
*
* \return the number of objects read, or 0 at error or end of file.
* This function reads up to `maxnum` objects each of size `size` from the
* data source to the area pointed at by `ptr`. This function may read less
* objects than requested. It will return zero when there has been an error or
* the data stream is completely read.
*
* SDL_RWread() is actually a function wrapper that calls the SDL_RWops's
* `read` method appropriately, to simplify application development.
*
* \param context a pointer to an SDL_RWops structure
* \param ptr a pointer to a buffer to read data into
* \param size the size of each object to read, in bytes
* \param maxnum the maximum number of objects to be read
* \returns the number of objects read, or 0 at error or end of file; call
* SDL_GetError() for more information.
*
* \sa SDL_RWclose
* \sa SDL_RWFromConstMem
* \sa SDL_RWFromFile
* \sa SDL_RWFromFP
* \sa SDL_RWFromMem
* \sa SDL_RWseek
* \sa SDL_RWwrite
*/
extern DECLSPEC size_t SDLCALL SDL_RWread(SDL_RWops *context,
void *ptr, size_t size, size_t maxnum);
void *ptr, size_t size,
size_t maxnum);
/**
* Write exactly \c num objects each of size \c size from the area
* pointed at by \c ptr to data stream.
* Write to an SDL_RWops data stream.
*
* \return the number of objects written, or 0 at error or end of file.
* This function writes exactly `num` objects each of size `size` from the
* area pointed at by `ptr` to the stream. If this fails for any reason,
* it'll return less than `num` to demonstrate how far the write progressed.
* On success, it returns `num`.
*
* SDL_RWwrite is actually a function wrapper that calls the SDL_RWops's
* `write` method appropriately, to simplify application development.
*
* \param context a pointer to an SDL_RWops structure
* \param ptr a pointer to a buffer containing data to write
* \param size the size of an object to write, in bytes
* \param num the number of objects to write
* \returns the number of objects written, which will be less than **num** on
* error; call SDL_GetError() for more information.
*
* \sa SDL_RWclose
* \sa SDL_RWFromConstMem
* \sa SDL_RWFromFile
* \sa SDL_RWFromFP
* \sa SDL_RWFromMem
* \sa SDL_RWread
* \sa SDL_RWseek
*/
extern DECLSPEC size_t SDLCALL SDL_RWwrite(SDL_RWops *context,
const void *ptr, size_t size, size_t num);
const void *ptr, size_t size,
size_t num);
/**
* Close and free an allocated SDL_RWops structure.
*
* \return 0 if successful or -1 on write error when flushing data.
* SDL_RWclose() closes and cleans up the SDL_RWops stream. It releases any
* resources used by the stream and frees the SDL_RWops itself with
* SDL_FreeRW(). This returns 0 on success, or -1 if the stream failed to
* flush to its output (e.g. to disk).
*
* Note that if this fails to flush the stream to disk, this function reports
* an error, but the SDL_RWops is still invalid once this function returns.
*
* SDL_RWclose() is actually a macro that calls the SDL_RWops's `close`
* method appropriately, to simplify application development.
*
* \param context SDL_RWops structure to close
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_RWFromConstMem
* \sa SDL_RWFromFile
* \sa SDL_RWFromFP
* \sa SDL_RWFromMem
* \sa SDL_RWread
* \sa SDL_RWseek
* \sa SDL_RWwrite
*/
extern DECLSPEC int SDLCALL SDL_RWclose(SDL_RWops *context);
/**
* Load all the data from an SDL data stream.
*
* The data is allocated with a zero byte at the end (null terminated)
*
* If \c datasize is not NULL, it is filled with the size of the data read.
*
* If \c freesrc is non-zero, the stream will be closed after being read.
* The data is allocated with a zero byte at the end (null terminated) for
* convenience. This extra byte is not included in the value reported via
* `datasize`.
*
* The data should be freed with SDL_free().
*
* \return the data, or NULL if there was an error.
* \param src the SDL_RWops to read all available data from
* \param datasize if not NULL, will store the number of bytes read
* \param freesrc if non-zero, calls SDL_RWclose() on `src` before returning
* \returns the data, or NULL if there was an error.
*/
extern DECLSPEC void *SDLCALL SDL_LoadFile_RW(SDL_RWops * src, size_t *datasize,
extern DECLSPEC void *SDLCALL SDL_LoadFile_RW(SDL_RWops *src,
size_t *datasize,
int freesrc);
/**
* Load an entire file.
* Load all the data from a file path.
*
* The data is allocated with a zero byte at the end (null terminated)
*
* If \c datasize is not NULL, it is filled with the size of the data read.
*
* If \c freesrc is non-zero, the stream will be closed after being read.
* The data is allocated with a zero byte at the end (null terminated) for
* convenience. This extra byte is not included in the value reported via
* `datasize`.
*
* The data should be freed with SDL_free().
*
* \return the data, or NULL if there was an error.
* \param file the path to read all available data from
* \param datasize if not NULL, will store the number of bytes read
* \returns the data, or NULL if there was an error.
*/
extern DECLSPEC void *SDLCALL SDL_LoadFile(const char *file, size_t *datasize);

86
include/SDL_sensor.h
View File

@ -138,91 +138,92 @@ extern DECLSPEC void SDLCALL SDL_LockSensors(void);
extern DECLSPEC void SDLCALL SDL_UnlockSensors(void);
/**
* \brief Count the number of sensors attached to the system right now
* Count the number of sensors attached to the system right now.
*
* \returns The number of sensors detected.
*/
extern DECLSPEC int SDLCALL SDL_NumSensors(void);
/**
* \brief Get the implementation dependent name of a sensor.
* Get the implementation dependent name of a sensor.
*
* This can be called before any sensors are opened.
*
* \return The sensor name, or NULL if device_index is out of range.
* \param device_index The sensor to obtain name from
* \returns The sensor name, or NULL if `device_index` is out of range.
*/
extern DECLSPEC const char *SDLCALL SDL_SensorGetDeviceName(int device_index);
/**
* \brief Get the type of a sensor.
* Get the type of a sensor.
*
* This can be called before any sensors are opened.
*
* \return The sensor type, or SDL_SENSOR_INVALID if device_index is out of range.
* \param device_index The sensor to get the type from
* \returns The SDL_SensorType, or `SDL_SENSOR_INVALID` if `device_index` is
* out of range.
*/
extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetDeviceType(int device_index);
/**
* \brief Get the platform dependent type of a sensor.
* Get the platform dependent type of a sensor.
*
* This can be called before any sensors are opened.
*
* \return The sensor platform dependent type, or -1 if device_index is out of range.
* \param device_index The sensor to check
* \returns The sensor platform dependent type, or -1 if `device_index` is out
* of range.
*/
extern DECLSPEC int SDLCALL SDL_SensorGetDeviceNonPortableType(int device_index);
/**
* \brief Get the instance ID of a sensor.
* Get the instance ID of a sensor.
*
* This can be called before any sensors are opened.
*
* \return The sensor instance ID, or -1 if device_index is out of range.
* \param device_index The sensor to get instance id from
* \returns The sensor instance ID, or -1 if `device_index` is out of range.
*/
extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetDeviceInstanceID(int device_index);
/**
* \brief Open a sensor for use.
* Open a sensor for use.
*
* The index passed as an argument refers to the N'th sensor on the system.
*
* \return A sensor identifier, or NULL if an error occurred.
* \param device_index The sensor to open
* \returns An SDL_Sensor sensor object, or NULL if an error occurred.
*/
extern DECLSPEC SDL_Sensor *SDLCALL SDL_SensorOpen(int device_index);
/**
* Return the SDL_Sensor associated with an instance id.
*
* \param instance_id The sensor from instance id
* \returns An SDL_Sensor object.
*/
extern DECLSPEC SDL_Sensor *SDLCALL SDL_SensorFromInstanceID(SDL_SensorID instance_id);
/**
* \brief Get the implementation dependent name of a sensor.
* Get the implementation dependent name of a sensor
*
* \return The sensor name, or NULL if the sensor is NULL.
* \param sensor The SDL_Sensor object
* \returns The sensor name, or NULL if `sensor` is NULL.
*/
extern DECLSPEC const char *SDLCALL SDL_SensorGetName(SDL_Sensor *sensor);
/**
* \brief Get the type of a sensor.
* Get the type of a sensor.
*
* This can be called before any sensors are opened.
*
* \return The sensor type, or SDL_SENSOR_INVALID if the sensor is NULL.
* \param sensor The SDL_Sensor object to inspect
* \returns The SDL_SensorType type, or `SDL_SENSOR_INVALID` if `sensor` is
* NULL.
*/
extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetType(SDL_Sensor *sensor);
/**
* \brief Get the platform dependent type of a sensor.
* Get the platform dependent type of a sensor.
*
* This can be called before any sensors are opened.
*
* \return The sensor platform dependent type, or -1 if the sensor is NULL.
* \param sensor The SDL_Sensor object to inspect
* \returns The sensor platform dependent type, or -1 if `sensor` is NULL.
*/
extern DECLSPEC int SDLCALL SDL_SensorGetNonPortableType(SDL_Sensor *sensor);
/**
* \brief Get the instance ID of a sensor.
* Get the instance ID of a sensor.
*
* This can be called before any sensors are opened.
*
* \return The sensor instance ID, or -1 if the sensor is NULL.
* \param sensor The SDL_Sensor object to inspect
* \returns The sensor instance ID, or -1 if `sensor` is NULL.
*/
extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetInstanceID(SDL_Sensor *sensor);
@ -231,25 +232,28 @@ extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetInstanceID(SDL_Sensor *sensor)
*
* The number of values and interpretation of the data is sensor dependent.
*
* \param sensor The sensor to query
* \param sensor The SDL_Sensor object to query
* \param data A pointer filled with the current sensor state
* \param num_values The number of values to write to data
*
* \return 0 or -1 if an error occurred.
* \returns 0 or -1 if an error occurred.
*/
extern DECLSPEC int SDLCALL SDL_SensorGetData(SDL_Sensor * sensor, float *data, int num_values);
/**
* Close a sensor previously opened with SDL_SensorOpen()
* Close a sensor previously opened with SDL_SensorOpen().
*
* \param sensor The SDL_Sensor object to close
*/
extern DECLSPEC void SDLCALL SDL_SensorClose(SDL_Sensor * sensor);
/**
* Update the current state of the open sensors.
*
* This is called automatically by the event loop if sensor events are enabled.
* This is called automatically by the event loop if sensor events are
* enabled.
*
* This needs to be called from the thread that initialized the sensor subsystem.
* This needs to be called from the thread that initialized the sensor
* subsystem.
*/
extern DECLSPEC void SDLCALL SDL_SensorUpdate(void);

585
include/SDL_surface.h
View File

@ -112,31 +112,101 @@ typedef enum
} SDL_YUV_CONVERSION_MODE;
/**
* Allocate and free an RGB surface.
* Allocate a new RGB surface.
*
* 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
* flags '[RGB]mask'.
* If `depth` is 4 or 8 bits, an empty palette is allocated for the surface.
* If `depth` is greater than 8 bits, the pixel format is set using the
* [RGBA]mask parameters.
*
* If the function runs out of memory, it will return NULL.
* The [RGBA]mask parameters are the bitmasks used to extract that color from
* a pixel. For instance, `Rmask` being 0xFF000000 means the red data is
* stored in the most significant byte. Using zeros for the RGB masks sets a
* default value, based on the depth. For example:
*
* \param flags The \c flags are obsolete and should be set to 0.
* \param width The width in pixels of the surface to create.
* \param height The height in pixels of the surface to create.
* \param depth The depth in bits of the surface to create.
* \param Rmask The red mask of the surface to create.
* \param Gmask The green mask of the surface to create.
* \param Bmask The blue mask of the surface to create.
* \param Amask The alpha mask of the surface to create.
* ```c++
* SDL_CreateRGBSurface(0,w,h,32,0,0,0,0);
* ```
*
* However, using zero for the Amask results in an Amask of 0.
*
* By default surfaces with an alpha mask are set up for blending as with:
*
* ```c++
* SDL_SetSurfaceBlendMode(surface, SDL_BLENDMODE_BLEND)
* ```
*
* You can change this by calling SDL_SetSurfaceBlendMode() and selecting a
* different `blendMode`.
*
* \param flags the flags are unused and should be set to 0
* \param width the width of the surface
* \param height the height of the surface
* \param depth the depth of the surface in bits
* \param Rmask the red mask for the pixels
* \param Gmask the green mask for the pixels
* \param Bmask the blue mask for the pixels
* \param Amask the alpha mask for the pixels
* \returns the new SDL_Surface structure that is created or NULL if it fails;
* call SDL_GetError() for more information.
*
* \sa SDL_CreateRGBSurfaceFrom
* \sa SDL_CreateRGBSurfaceWithFormat
* \sa SDL_FreeSurface
*/
extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface
(Uint32 flags, int width, int height, int depth,
Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
/* !!! FIXME for 2.1: why does this ask for depth? Format provides that. */
/**
* Allocate a new RGB surface with a specific pixel format.
*
* This function operates mostly like SDL_CreateRGBSurface(), except instead
* of providing pixel color masks, you provide it with a predefined format
* from SDL_PixelFormatEnum.
*
* \param flags the flags are unused and should be set to 0
* \param width the width of the surface
* \param height the height of the surface
* \param depth the depth of the surface in bits
* \param format the SDL_PixelFormatEnum for the new surface's pixel format.
* \returns the new SDL_Surface structure that is created or NULL if it fails;
* call SDL_GetError() for more information.
*
* \sa SDL_CreateRGBSurface
* \sa SDL_CreateRGBSurfaceFrom
* \sa SDL_FreeSurface
*/
extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceWithFormat
(Uint32 flags, int width, int height, int depth, Uint32 format);
/**
* Allocate a new RGB surface with existing pixel data.
*
* This function operates mostly like SDL_CreateRGBSurface(), except it does
* not allocate memory for the pixel data, instead the caller provides an
* existing buffer of data for the surface to use.
*
* No copy is made of the pixel data. Pixel data is not managed
* automatically; you must free the surface before you free the pixel data.
*
* \param pixels a pointer to existing pixel data
* \param width the width of the surface
* \param height the height of the surface
* \param depth the depth of the surface in bits
* \param pitch the pitch of the surface in bytes
* \param Rmask the red mask for the pixels
* \param Gmask the green mask for the pixels
* \param Bmask the blue mask for the pixels
* \param Amask the alpha mask for the pixels
* \returns the new SDL_Surface structure that is created or NULL if it fails;
* call SDL_GetError() for more information.
*
* \sa SDL_CreateRGBSurface
* \sa SDL_CreateRGBSurfaceWithFormat
* \sa SDL_FreeSurface
*/
extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
int width,
int height,
@ -146,51 +216,105 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
Uint32 Gmask,
Uint32 Bmask,
Uint32 Amask);
/* !!! FIXME for 2.1: why does this ask for depth? Format provides that. */
/**
* Allocate a new RGB surface with with a specific pixel format and existing
* pixel data.
*
* This function operates mostly like SDL_CreateRGBSurfaceFrom(), except
* instead of providing pixel color masks, you provide it with a predefined
* format from SDL_PixelFormatEnum.
*
* No copy is made of the pixel data. Pixel data is not managed
* automatically; you must free the surface before you free the pixel data.
*
* \param pixels a pointer to existing pixel data
* \param width the width of the surface
* \param height the height of the surface
* \param depth the depth of the surface in bits
* \param pitch the pitch of the surface in bytes
* \param format the SDL_PixelFormatEnum for the new surface's pixel format.
* \returns the new SDL_Surface structure that is created or NULL if it fails;
* call SDL_GetError() for more information.
*
* \sa SDL_CreateRGBSurfaceFrom
* \sa SDL_CreateRGBSurfaceWithFormat
* \sa SDL_FreeSurface
*/
extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceWithFormatFrom
(void *pixels, int width, int height, int depth, int pitch, Uint32 format);
/**
* Free an RGB surface.
*
* It is safe to pass NULL to this function.
*
* \param surface the SDL_Surface to free.
*
* \sa SDL_CreateRGBSurface
* \sa SDL_CreateRGBSurfaceFrom
* \sa SDL_LoadBMP
* \sa SDL_LoadBMP_RW
*/
extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface);
/**
* \brief Set the palette used by a surface.
* Set the palette used by a surface.
*
* \return 0, or -1 if the surface format doesn't use a palette.
* A single palette can be shared with many surfaces.
*
* \note A single palette can be shared with many surfaces.
* \param surface the SDL_Surface structure to update
* \param palette the SDL_Palette structure to use
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*/
extern DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface * surface,
SDL_Palette * palette);
/**
* \brief Sets up a surface for directly accessing the pixels.
* Set up a surface for directly accessing the pixels.
*
* Between calls to SDL_LockSurface() / SDL_UnlockSurface(), you can write
* to and read from \c surface->pixels, using the pixel format stored in
* \c surface->format. Once you are done accessing the surface, you should
* use SDL_UnlockSurface() to release it.
* Between calls to SDL_LockSurface() / SDL_UnlockSurface(), you can write to
* and read from `surface->pixels`, using the pixel format stored in
* `surface->format`. Once you are done accessing the surface, you should use
* SDL_UnlockSurface() to release it.
*
* Not all surfaces require locking. If SDL_MUSTLOCK(surface) evaluates
* to 0, then you can read and write to the surface at any time, and the
* pixel format of the surface will not change.
* Not all surfaces require locking. If `SDL_MUSTLOCK(surface)` evaluates to
* 0, then you can read and write to the surface at any time, and the pixel
* format of the surface will not change.
*
* No operating system or library calls should be made between lock/unlock
* pairs, as critical system locks may be held during this time.
* \param surface the SDL_Surface structure to be locked
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked.
*
* \sa SDL_UnlockSurface()
* \sa SDL_MUSTLOCK
* \sa SDL_UnlockSurface
*/
extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface);
/** \sa SDL_LockSurface() */
/**
* Release a surface after directly accessing the pixels.
*
* \param surface the SDL_Surface structure to be unlocked
*
* \sa SDL_LockSurface()
*/
extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface);
/**
* Load a surface from a seekable SDL data stream (memory or file).
*
* If \c freesrc is non-zero, the stream will be closed after being read.
* Load a BMP image from a seekable SDL data stream.
*
* The new surface should be freed with SDL_FreeSurface().
*
* \return the new surface, or NULL if there was an error.
* \param src the data stream for the surface
* \param freesrc non-zero to close the stream after being read
* \returns a pointer to a new SDL_Surface structure or NULL if there was an
* error; call SDL_GetError() for more information.
*
* \sa SDL_FreeSurface
* \sa SDL_LoadBMP
* \sa SDL_SaveBMP_RW
*/
extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src,
int freesrc);
@ -203,7 +327,7 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src,
#define SDL_LoadBMP(file) SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
/**
* Save a surface to a seekable SDL data stream (memory or file).
* Save a surface to a seekable SDL data stream in BMP format.
*
* Surfaces with a 24-bit, 32-bit and paletted 8-bit format get saved in the
* BMP directly. Other RGB formats with 8-bit or higher get converted to a
@ -211,9 +335,14 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src,
* surface before they are saved. YUV and paletted 1-bit and 4-bit formats are
* not supported.
*
* If \c freedst is non-zero, the stream will be closed after being written.
* \param surface the SDL_Surface structure containing the image to be saved
* \param dst a data stream to save to
* \param freedst non-zero to close the stream after being written
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \return 0 if successful or -1 if there was an error.
* \sa SDL_LoadBMP_RW
* \sa SDL_SaveBMP
*/
extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
(SDL_Surface * surface, SDL_RWops * dst, int freedst);
@ -227,190 +356,300 @@ extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
/**
* \brief Sets the RLE acceleration hint for a surface.
* Set the RLE acceleration hint for a surface.
*
* \return 0 on success, or -1 if the surface is not valid
* If RLE is enabled, color key and alpha blending blits are much faster, but
* the surface must be locked before directly accessing the pixels.
*
* \note If RLE is enabled, colorkey and alpha blending blits are much faster,
* but the surface must be locked before directly accessing the pixels.
* \param surface the SDL_Surface structure to optimize
* \param flag 0 to disable, non-zero to enable RLE acceleration
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_BlitSurface
* \sa SDL_LockSurface
* \sa SDL_UnlockSurface
*/
extern DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface * surface,
int flag);
/**
* \brief Returns whether the surface is RLE enabled
* Returns whether the surface is RLE enabled
*
* \return SDL_TRUE if the surface is RLE enabled, or SDL_FALSE if the surface is NULL or not RLE enabled
* It is safe to pass a NULL `surface` here; it will return SDL_FALSE.
*
* \param surface the SDL_Surface structure to query
* \returns SDL_TRUE if the surface is RLE enabled, SDL_FALSE otherwise.
*
* \sa SDL_SetSurfaceRLE
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasSurfaceRLE(SDL_Surface * surface);
/**
* \brief Sets the color key (transparent pixel) in a blittable surface.
* Set the color key (transparent pixel) in a surface.
*
* \param surface The surface to update
* \param flag Non-zero to enable colorkey and 0 to disable colorkey
* \param key The transparent pixel in the native surface format
* The color key defines a pixel value that will be treated as transparent in
* a blit. It is a pixel of the format used by the surface, as generated by
* SDL_MapRGB().
*
* \return 0 on success, or -1 if the surface is not valid
* RLE acceleration can substantially speed up blitting of images with large
* horizontal runs of transparent pixels. See SDL_SetSurfaceRLE() for details.
*
* You can pass SDL_RLEACCEL to enable RLE accelerated blits.
* \param surface the SDL_Surface structure to update
* \param flag SDL_TRUE to enable color key, SDL_FALSE to disable color key
* \param key the transparent pixel
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_BlitSurface
* \sa SDL_GetColorKey
*/
extern DECLSPEC int SDLCALL SDL_SetColorKey(SDL_Surface * surface,
int flag, Uint32 key);
/**
* \brief Returns whether the surface has a color key
* Returns whether the surface has a color key
*
* \return SDL_TRUE if the surface has a color key, or SDL_FALSE if the surface is NULL or has no color key
* It is safe to pass a NULL `surface` here; it will return SDL_FALSE.
*
* \param surface the SDL_Surface structure to query
* \return SDL_TRUE if the surface has a color key, SDL_FALSE otherwise.
*
* \sa SDL_SetColorKey
* \sa SDL_GetColorKey
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasColorKey(SDL_Surface * surface);
/**
* \brief Gets the color key (transparent pixel) in a blittable surface.
* Get the color key (transparent pixel) for a surface.
*
* \param surface The surface to update
* \param key A pointer filled in with the transparent pixel in the native
* surface format
* The color key is a pixel of the format used by the surface, as generated by
* SDL_MapRGB().
*
* \return 0 on success, or -1 if the surface is not valid or colorkey is not
* enabled.
* If the surface doesn't have color key enabled this function returns -1.
*
* \param surface the SDL_Surface structure to query
* \param key a pointer filled in with the transparent pixel
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_BlitSurface
* \sa SDL_SetColorKey
*/
extern DECLSPEC int SDLCALL SDL_GetColorKey(SDL_Surface * surface,
Uint32 * key);
/**
* \brief Set an additional color value used in blit operations.
* Set an additional color value multiplied into blit operations.
*
* \param surface The surface to update.
* \param r The red color value multiplied into blit operations.
* \param g The green color value multiplied into blit operations.
* \param b The blue color value multiplied into blit operations.
* When this surface is blitted, during the blit operation each source color
* channel is modulated by the appropriate color value according to the
* following formula:
*
* \return 0 on success, or -1 if the surface is not valid.
* `srcC = srcC * (color / 255)`
*
* \sa SDL_GetSurfaceColorMod()
* \param surface the SDL_Surface structure to update
* \param r the red color value multiplied into blit operations
* \param g the green color value multiplied into blit operations
* \param b the blue color value multiplied into blit operations
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_GetSurfaceColorMod
* \sa SDL_SetSurfaceAlphaMod
*/
extern DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface * surface,
Uint8 r, Uint8 g, Uint8 b);
/**
* \brief Get the additional color value used in blit operations.
* Get the additional color value multiplied into blit operations.
*
* \param surface The surface to query.
* \param r A pointer filled in with the current red color value.
* \param g A pointer filled in with the current green color value.
* \param b A pointer filled in with the current blue color value.
* \param surface the SDL_Surface structure to query
* \param r a pointer filled in with the current red color value
* \param g a pointer filled in with the current green color value
* \param b a pointer filled in with the current blue color value
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \return 0 on success, or -1 if the surface is not valid.
*
* \sa SDL_SetSurfaceColorMod()
* \sa SDL_GetSurfaceAlphaMod
* \sa SDL_SetSurfaceColorMod
*/
extern DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface * surface,
Uint8 * r, Uint8 * g,
Uint8 * b);
/**
* \brief Set an additional alpha value used in blit operations.
* Set an additional alpha value used in blit operations.
*
* \param surface The surface to update.
* \param alpha The alpha value multiplied into blit operations.
* When this surface is blitted, during the blit operation the source alpha
* value is modulated by this alpha value according to the following formula:
*
* \return 0 on success, or -1 if the surface is not valid.
* `srcA = srcA * (alpha / 255)`
*
* \sa SDL_GetSurfaceAlphaMod()
* \param surface the SDL_Surface structure to update
* \param alpha the alpha value multiplied into blit operations
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_GetSurfaceAlphaMod
* \sa SDL_SetSurfaceColorMod
*/
extern DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface * surface,
Uint8 alpha);
/**
* \brief Get the additional alpha value used in blit operations.
* Get the additional alpha value used in blit operations.
*
* \param surface The surface to query.
* \param alpha A pointer filled in with the current alpha value.
* \param surface the SDL_Surface structure to query
* \param alpha a pointer filled in with the current alpha value
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \return 0 on success, or -1 if the surface is not valid.
*
* \sa SDL_SetSurfaceAlphaMod()
* \sa SDL_GetSurfaceColorMod
* \sa SDL_SetSurfaceAlphaMod
*/
extern DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface * surface,
Uint8 * alpha);
/**
* \brief Set the blend mode used for blit operations.
* Set the blend mode used for blit operations.
*
* \param surface The surface to update.
* \param blendMode ::SDL_BlendMode to use for blit blending.
* To copy a surface to another surface (or texture) without blending with the
* existing data, the blendmode of the SOURCE surface should be set to
* `SDL_BLENDMODE_NONE`.
*
* \return 0 on success, or -1 if the parameters are not valid.
* \param surface the SDL_Surface structure to update
* \param blendMode the SDL_BlendMode to use for blit blending
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_GetSurfaceBlendMode()
* \sa SDL_GetSurfaceBlendMode
*/
extern DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface * surface,
SDL_BlendMode blendMode);
/**
* \brief Get the blend mode used for blit operations.
* Get the blend mode used for blit operations.
*
* \param surface The surface to query.
* \param blendMode A pointer filled in with the current blend mode.
* \param surface the SDL_Surface structure to query
* \param blendMode a pointer filled in with the current SDL_BlendMode
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \return 0 on success, or -1 if the surface is not valid.
*
* \sa SDL_SetSurfaceBlendMode()
* \sa SDL_SetSurfaceBlendMode
*/
extern DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface * surface,
SDL_BlendMode *blendMode);
/**
* Sets the clipping rectangle for the destination surface in a blit.
* Set the clipping rectangle for a surface.
*
* If the clip rectangle is NULL, clipping will be disabled.
* When `surface` is the destination of a blit, only the area within the
* clip rectangle is drawn into.
*
* If the clip rectangle doesn't intersect the surface, the function will
* return SDL_FALSE and blits will be completely clipped. Otherwise the
* function returns SDL_TRUE and blits to the surface will be clipped to
* the intersection of the surface area and the clipping rectangle.
* Note that blits are automatically clipped to the edges of the source and
* destination surfaces.
*
* Note that blits are automatically clipped to the edges of the source
* and destination surfaces.
* \param surface the SDL_Surface structure to be clipped
* \param rect the SDL_Rect structure representing the clipping rectangle, or
* NULL to disable clipping
* \returns SDL_TRUE if the rectangle intersects the surface, otherwise
* SDL_FALSE and blits will be completely clipped.
*
* \sa SDL_BlitSurface
* \sa SDL_GetClipRect
*/
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.
* Get the clipping rectangle for a surface.
*
* \c rect must be a pointer to a valid rectangle which will be filled
* with the correct values.
* When `surface` is the destination of a blit, only the area within the
* clip rectangle is drawn into.
*
* \param surface the SDL_Surface structure representing the surface to be
* clipped
* \param rect an SDL_Rect structure filled in with the clipping rectangle for
* the surface
*
* \sa SDL_BlitSurface
* \sa SDL_SetClipRect
*/
extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface * surface,
SDL_Rect * rect);
/*
* Creates a new surface identical to the existing surface
* Creates a new surface identical to the existing surface.
*
* The returned surface should be freed with SDL_FreeSurface().
*
* \param surface the surface to duplicate.
* \returns a copy of the surface, or NULL on failure; call SDL_GetError() for
* more information.
*/
extern DECLSPEC SDL_Surface *SDLCALL SDL_DuplicateSurface(SDL_Surface * surface);
/**
* 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.
* Copy an existing surface to a new surface of the specified format.
*
* The \c flags parameter is passed to SDL_CreateRGBSurface() and has those
* semantics. You can also pass ::SDL_RLEACCEL in the flags parameter and
* SDL will try to RLE accelerate colorkey and alpha blits in the resulting
* surface.
* This function is used to optimize images for faster *repeat* blitting. This
* is accomplished by converting the original and storing the result as a new
* surface. The new, optimized surface can then be used as the source for
* future blits, making them faster.
*
* \param src the existing SDL_Surface structure to convert
* \param fmt the SDL_PixelFormat structure that the new surface is optimized
* for
* \param flags the flags are unused and should be set to 0; this is a
* leftover from SDL 1.2's API
* \returns the new SDL_Surface structure that is created or NULL if it fails;
* call SDL_GetError() for more information.
*
* \sa SDL_AllocFormat
* \sa SDL_ConvertSurfaceFormat
* \sa SDL_CreateRGBSurface
*/
extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface
(SDL_Surface * src, const SDL_PixelFormat * fmt, Uint32 flags);
/**
* Copy an existing surface to a new surface of the specified format enum.
*
* This function operates just like SDL_ConvertSurface(), but accepts an
* SDL_PixelFormatEnum value instead of an SDL_PixelFormat structure. As
* such, it might be easier to call but it doesn't have access to palette
* information for the destination surface, in case that would be important.
*
* \param src the existing SDL_Surface structure to convert
* \param pixel_format the SDL_PixelFormatEnum that the new surface is
* optimized for
* \param flags the flags are unused and should be set to 0; this is a
* leftover from SDL 1.2's API
* \returns the new SDL_Surface structure that is created or NULL if it fails;
* call SDL_GetError() for more information.
*
* \sa SDL_AllocFormat
* \sa SDL_ConvertSurfaceFormat
* \sa SDL_CreateRGBSurface
*/
extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurfaceFormat
(SDL_Surface * src, Uint32 pixel_format, Uint32 flags);
/**
* \brief Copy a block of pixels of one format to another format
* Copy a block of pixels of one format to another format.
*
* \return 0 on success, or -1 if there was an error
* \param width the width of the block to copy, in pixels
* \param height the height of the block to copy, in pixels
* \param src_format an SDL_PixelFormatEnum value of the `src` pixels format
* \param src a pointer to the source pixels
* \param src_pitch the pitch of the block to copy, in bytes
* \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format
* \param dst a pointer to be filled in with new pixel data
* \param dst_pitch the pitch of the destination pixels, in bytes
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*/
extern DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height,
Uint32 src_format,
@ -419,20 +658,54 @@ extern DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height,
void * dst, int dst_pitch);
/**
* Performs a fast fill of the given rectangle with \c color.
* Perform a fast fill of a rectangle with a specific color.
*
* If \c rect is NULL, the whole surface will be filled with \c color.
* `color` should be a pixel of the format used by the surface, and can be
* generated by SDL_MapRGB() or SDL_MapRGBA(). If the color value contains an
* alpha component then the destination is simply filled with that alpha
* information, no blending takes place.
*
* The color should be a pixel of the format used by the surface, and
* can be generated by the SDL_MapRGB() function.
* If there is a clip rectangle set on the destination (set via
* SDL_SetClipRect()), then this function will fill based on the intersection
* of the clip rectangle and `rect`.
*
* \return 0 on success, or -1 on error.
* \param dst the SDL_Surface structure that is the drawing target
* \param rect the SDL_Rect structure representing the rectangle to fill, or
* NULL to fill the entire surface
* \param color the color to fill with
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_FillRects
*/
extern DECLSPEC int SDLCALL SDL_FillRect
(SDL_Surface * dst, const SDL_Rect * rect, Uint32 color);
/**
* Perform a fast fill of a set of rectangles with a specific color.
*
* `color` should be a pixel of the format used by the surface, and can be
* generated by SDL_MapRGB() or SDL_MapRGBA(). If the color value contains an
* alpha component then the destination is simply filled with that alpha
* information, no blending takes place.
*
* If there is a clip rectangle set on the destination (set via
* SDL_SetClipRect()), then this function will fill based on the intersection
* of the clip rectangle and `rect`.
*
* \param dst the SDL_Surface structure that is the drawing target
* \param rects an array of SDL_Rects representing the rectangles to fill.
* \param count the number of rectangles in the array
* \param color the color to fill with
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_FillRect
*/
extern DECLSPEC int SDLCALL SDL_FillRects
(SDL_Surface * dst, const SDL_Rect * rects, int count, Uint32 color);
/* !!! FIXME: merge this documentation with the wiki */
/**
* Performs a fast blit from the source surface to the destination surface.
*
@ -493,26 +766,49 @@ extern DECLSPEC int SDLCALL SDL_FillRects
#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()
* Perform a fast blit from the source surface to the destination surface.
*
* SDL_UpperBlit() has been replaced by SDL_BlitSurface(), which is merely
* a macro for this function with a less confusing name.
*
* \sa SDL_BlitSurface
*/
extern DECLSPEC int SDLCALL SDL_UpperBlit
(SDL_Surface * src, const SDL_Rect * srcrect,
SDL_Surface * dst, SDL_Rect * dstrect);
/**
* Perform low-level surface blitting only.
*
* This is a semi-private blit function and it performs low-level surface
* blitting only.
* blitting, assuming the input rectangles have already been clipped.
*
* Unless you know what you're doing, you should be using SDL_BlitSurface()
* instead.
*
* \param src the SDL_Surface structure to be copied from
* \param srcrect the SDL_Rect structure representing the rectangle to be
* copied, or NULL to copy the entire surface
* \param dst the SDL_Surface structure that is the blit target
* \param dstrect the SDL_Rect structure representing the rectangle that is
* copied into
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_BlitSurface
*/
extern DECLSPEC int SDLCALL SDL_LowerBlit
(SDL_Surface * src, SDL_Rect * srcrect,
SDL_Surface * dst, SDL_Rect * dstrect);
/**
* \brief Perform a fast, low quality, stretch blit between two surfaces of the
* same pixel format.
/**
* Perform a fast, low quality, stretch blit between two surfaces of the
* same format.
*
* \note This function uses a static buffer, and is not thread-safe.
* **Warning**: This function uses a static buffer, and is not thread-safe.
*
* Please use SDL_BlitScaled() instead.
*/
extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src,
const SDL_Rect * srcrect,
@ -520,9 +816,7 @@ extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src,
const SDL_Rect * dstrect);
/**
* \brief Perform a bilinear scaling between two surfaces of the
* same pixel format, 32BPP.
*
* Perform bilinear scaling between two surfaces of the same format, 32BPP.
*/
extern DECLSPEC int SDLCALL SDL_SoftStretchLinear(SDL_Surface * src,
const SDL_Rect * srcrect,
@ -533,33 +827,50 @@ extern DECLSPEC int SDLCALL SDL_SoftStretchLinear(SDL_Surface * src,
#define SDL_BlitScaled SDL_UpperBlitScaled
/**
* This is the public scaled blit function, SDL_BlitScaled(), and it performs
* rectangle validation and clipping before passing it to SDL_LowerBlitScaled()
* Perform a scaled surface copy to a destination surface.
*
* SDL_UpperBlitScaled() has been replaced by SDL_BlitScaled(), which is
* merely a macro for this function with a less confusing name.
*
* \sa SDL_BlitScaled
*/
extern DECLSPEC int SDLCALL SDL_UpperBlitScaled
(SDL_Surface * src, const SDL_Rect * srcrect,
SDL_Surface * dst, SDL_Rect * dstrect);
/**
* This is a semi-private blit function and it performs low-level surface
* scaled blitting only.
* Perform low-level surface scaled blitting only.
*
* This is a semi-private function and it performs low-level surface blitting,
* assuming the input rectangles have already been clipped.
*
* \param src the SDL_Surface structure to be copied from
* \param srcrect the SDL_Rect structure representing the rectangle to be
* copied
* \param dst the SDL_Surface structure that is the blit target
* \param dstrect the SDL_Rect structure representing the rectangle that is
* copied into
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \sa SDL_BlitScaled
*/
extern DECLSPEC int SDLCALL SDL_LowerBlitScaled
(SDL_Surface * src, SDL_Rect * srcrect,
SDL_Surface * dst, SDL_Rect * dstrect);
/**
* \brief Set the YUV conversion mode
* Set the YUV conversion mode
*/
extern DECLSPEC void SDLCALL SDL_SetYUVConversionMode(SDL_YUV_CONVERSION_MODE mode);
/**
* \brief Get the YUV conversion mode
* Get the YUV conversion mode
*/
extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionMode(void);
/**
* \brief Get the YUV conversion mode, returning the correct mode for the resolution when the current conversion mode is SDL_YUV_CONVERSION_AUTOMATIC
* Get the YUV conversion mode, returning the correct mode for the resolution when the current conversion mode is SDL_YUV_CONVERSION_AUTOMATIC
*/
extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionModeForResolution(int width, int height);

376
include/SDL_system.h
View File

@ -43,41 +43,78 @@ extern "C" {
/* Platform specific functions for Windows */
#ifdef __WIN32__
/**
\brief Set a function that is called for every windows message, before TranslateMessage()
*/
typedef void (SDLCALL * SDL_WindowsMessageHook)(void *userdata, void *hWnd, unsigned int message, Uint64 wParam, Sint64 lParam);
/**
* Set a callback for every Windows message, run before TranslateMessage().
*
* \param callback The SDL_WindowsMessageHook function to call.
* \param userdata a pointer to pass to every iteration of `callback`
*/
extern DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata);
/**
\brief Returns the D3D9 adapter index that matches the specified display index.
This adapter index can be passed to IDirect3D9::CreateDevice and controls
on which monitor a full screen application will appear.
*/
* Get the D3D9 adapter index that matches the specified display index.
*
* The returned adapter index can be passed to `IDirect3D9::CreateDevice` and
* controls on which monitor a full screen application will appear.
*
* \param displayIndex the display index for which to get the D3D9 adapter
* index
* \returns the D3D9 adapter index on success or a negative error code on
* failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.1.
*/
extern DECLSPEC int SDLCALL SDL_Direct3D9GetAdapterIndex( int displayIndex );
typedef struct IDirect3DDevice9 IDirect3DDevice9;
/**
\brief Returns the D3D9 device associated with a renderer, or NULL if it's not a D3D9 renderer.
Once you are done using the device, you should release it to avoid a resource leak.
/**
* Get the D3D9 device associated with a renderer.
*
* Once you are done using the device, you should release it to avoid a
* resource leak.
*
* \param renderer the renderer from which to get the associated D3D device
* \returns the D3D9 device associated with given renderer or NULL if it is
* not a D3D9 renderer; call SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.1.
*/
extern DECLSPEC IDirect3DDevice9* SDLCALL SDL_RenderGetD3D9Device(SDL_Renderer * renderer);
typedef struct ID3D11Device ID3D11Device;
/**
\brief Returns the D3D11 device associated with a renderer, or NULL if it's not a D3D11 renderer.
Once you are done using the device, you should release it to avoid a resource leak.
/**
* Get the D3D11 device associated with a renderer.
*
* Once you are done using the device, you should release it to avoid a
* resource leak.
*
* \param renderer the renderer from which to get the associated D3D11 device
* \returns the D3D11 device associated with given renderer or NULL if it is
* not a D3D11 renderer; call SDL_GetError() for more information.
*/
extern DECLSPEC ID3D11Device* SDLCALL SDL_RenderGetD3D11Device(SDL_Renderer * renderer);
/**
\brief Returns the DXGI Adapter and Output indices for the specified display index.
These can be passed to EnumAdapters and EnumOutputs respectively to get the objects
required to create a DX10 or DX11 device and swap chain.
* Get the DXGI Adapter and Output indices for the specified display index.
*
* The DXGI Adapter and Output indices can be passed to `EnumAdapters` and
* `EnumOutputs` respectively to get the objects required to create a DX10 or
* DX11 device and swap chain.
*
* Before SDL 2.0.4 this function did not return a value. Since SDL 2.0.4 it
* returns an SDL_bool.
*
* \param displayIndex the display index for which to get both indices
* \param adapterIndex a pointer to be filled in with the adapter index
* \param outputIndex a pointer to be filled in with the output index
* \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
* for more information.
*
* \since This function is available since SDL 2.0.2.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_DXGIGetOutputInfo( int displayIndex, int *adapterIndex, int *outputIndex );
@ -88,9 +125,13 @@ extern DECLSPEC SDL_bool SDLCALL SDL_DXGIGetOutputInfo( int displayIndex, int *a
#ifdef __LINUX__
/**
\brief Sets the UNIX nice value for a thread, using setpriority() if possible, and RealtimeKit if available.
\return 0 on success, or -1 on error.
* Sets the UNIX nice value for a thread.
*
* This uses setpriority() if possible, and RealtimeKit if available.
*
* \param threadID the Unix thread ID to change priority of.
* \param priority The new, Unix-specific, priority value.
* \returns 0 on success, or -1 on error.
*/
extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriority(Sint64 threadID, int priority);
@ -112,66 +153,118 @@ extern DECLSPEC void SDLCALL SDL_iPhoneSetEventPump(SDL_bool enabled);
#ifdef __ANDROID__
/**
\brief Get the JNI environment for the current thread
This returns JNIEnv*, but the prototype is void* so we don't need jni.h
* Get the Android Java Native Interface Environment of the current thread.
*
* This is the JNIEnv one needs to access the Java virtual machine from native
* code, and is needed for many Android APIs to be usable from C.
*
* The prototype of the function in SDL's code actually declare a void* return
* type, even if the implementation returns a pointer to a JNIEnv. The
* rationale being that the SDL headers can avoid including jni.h.
*
* \returns a pointer to Java native interface object (JNIEnv) to which the
* current thread is attached, or 0 on error.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_AndroidGetActivity
*/
extern DECLSPEC void * SDLCALL SDL_AndroidGetJNIEnv(void);
/**
\brief Get the SDL Activity object for the application
This returns jobject, but the prototype is void* so we don't need jni.h
The jobject returned by SDL_AndroidGetActivity is a local reference.
It is the caller's responsibility to properly release it
(using env->Push/PopLocalFrame or manually with env->DeleteLocalRef)
* Retrieve the Java instance of the Android activity class.
*
* The prototype of the function in SDL's code actually declares a void*
* return type, even if the implementation returns a jobject. The rationale
* being that the SDL headers can avoid including jni.h.
*
* The jobject returned by the function is a local reference and must
* be released by the caller. See the PushLocalFrame() and PopLocalFrame() or
* DeleteLocalRef() functions of the Java native interface:
*
* https://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/functions.html
*
* \returns the jobject representing the instance of the Activity class of the
* Android application, or NULL on error.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_AndroidGetJNIEnv
*/
extern DECLSPEC void * SDLCALL SDL_AndroidGetActivity(void);
/**
\brief Return API level of the current device
API level 30: Android 11
API level 29: Android 10
API level 28: Android 9
API level 27: Android 8.1
API level 26: Android 8.0
API level 25: Android 7.1
API level 24: Android 7.0
API level 23: Android 6.0
API level 22: Android 5.1
API level 21: Android 5.0
API level 20: Android 4.4W
API level 19: Android 4.4
API level 18: Android 4.3
API level 17: Android 4.2
API level 16: Android 4.1
API level 15: Android 4.0.3
API level 14: Android 4.0
API level 13: Android 3.2
API level 12: Android 3.1
API level 11: Android 3.0
API level 10: Android 2.3.3
* Query Android API level of the current device.
*
* - API level 30: Android 11
*
* - API level 29: Android 10
*
* - API level 28: Android 9
*
* - API level 27: Android 8.1
*
* - API level 26: Android 8.0
*
* - API level 25: Android 7.1
*
* - API level 24: Android 7.0
*
* - API level 23: Android 6.0
*
* - API level 22: Android 5.1
*
* - API level 21: Android 5.0
*
* - API level 20: Android 4.4W
*
* - API level 19: Android 4.4
*
* - API level 18: Android 4.3
*
* - API level 17: Android 4.2
*
* - API level 16: Android 4.1
*
* - API level 15: Android 4.0.3
*
* - API level 14: Android 4.0
*
* - API level 13: Android 3.2
*
* - API level 12: Android 3.1
*
* - API level 11: Android 3.0
*
* - API level 10: Android 2.3.3
*
* \returns Android API level.
*/
extern DECLSPEC int SDLCALL SDL_GetAndroidSDKVersion(void);
/**
\brief Return true if the application is running on Android TV
* Query if the application is running on Android TV.
*
* \returns SDL_TRUE if this is Android TV, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_IsAndroidTV(void);
/**
\brief Return true if the application is running on a Chromebook
* Query if the application is running on a Chromebook.
*
* \returns SDL_TRUE if this is a Chromebook, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_IsChromebook(void);
/**
\brief Return true is the application is running on a Samsung DeX docking station
* Query if the application is running on a Samsung DeX docking station.
*
* \returns SDL_TRUE if this is a DeX docking station, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_IsDeXMode(void);
/**
\brief Trigger the Android system back button behavior.
* Trigger the Android system back button behavior.
*/
extern DECLSPEC void SDLCALL SDL_AndroidBackButton(void);
@ -183,54 +276,91 @@ extern DECLSPEC void SDLCALL SDL_AndroidBackButton(void);
#define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02
/**
\brief Get the path used for internal storage for this application.
This path is unique to your application and cannot be written to
by other applications.
* Get the path used for internal storage for this application.
*
* This path is unique to your application and cannot be written to by other
* applications.
*
* Your internal storage path is typically:
* `/data/data/your.app.package/files`.
*
* \returns the path used for internal storage or NULL on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_AndroidGetExternalStorageState
*/
extern DECLSPEC const char * SDLCALL SDL_AndroidGetInternalStoragePath(void);
/**
\brief Get the current state of external storage, a bitmask of these values:
SDL_ANDROID_EXTERNAL_STORAGE_READ
SDL_ANDROID_EXTERNAL_STORAGE_WRITE
If external storage is currently unavailable, this will return 0.
*/
* Get the current state of external storage.
*
* The current state of external storage, a bitmask of these values:
* `SDL_ANDROID_EXTERNAL_STORAGE_READ`, `SDL_ANDROID_EXTERNAL_STORAGE_WRITE`.
*
* If external storage is currently unavailable, this will return 0.
*
* \returns the current state of external storage on success or 0 on failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_AndroidGetExternalStoragePath
*/
extern DECLSPEC int SDLCALL SDL_AndroidGetExternalStorageState(void);
/**
\brief Get the path used for external storage for this application.
This path is unique to your application, but is public and can be
written to by other applications.
* Get the path used for external storage for this application.
*
* This path is unique to your application, but is public and can be written
* to by other applications.
*
* Your external storage path is typically:
* `/storage/sdcard0/Android/data/your.app.package/files`.
*
* \returns the path used for external storage for this application on success
* or NULL on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_AndroidGetExternalStorageState
*/
extern DECLSPEC const char * SDLCALL SDL_AndroidGetExternalStoragePath(void);
/**
\brief Request permissions at runtime.
This blocks the calling thread until the permission is granted or
denied. Returns SDL_TRUE if the permission was granted.
* Request permissions at runtime.
*
* This blocks the calling thread until the permission is granted or
* denied.
*
* \param permission The permission to request.
* \returns SDL_TRUE if the permission was granted, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_AndroidRequestPermission(const char *permission);
/**
\brief Shows android toast notification
\note Shows toast in UI thread [https://developer.android.com/guide/topics/ui/notifiers/toasts]
\param message : text message to be shown
duration : 0 - short [https://developer.android.com/reference/android/widget/Toast#LENGTH_SHORT],
1 - long [https://developer.android.com/reference/android/widget/Toast#LENGTH_LONG]
gravity : the location at which the notification should appear on the screen.
It's an optional parameter. Set -1 if you don't want specify any gravity or
choose some value from https://developer.android.com/reference/android/view/Gravity
xOffset : set this parameter only when gravity >=0
yOffset : set this parameter only when gravity >=0
\return 0 if success, -1 if any error occurs.
*/
extern DECLSPEC int SDLCALL SDL_AndroidShowToast(const char* message, int duration, int gravity, int xOffset, int yOffset);
* Shows an Android toast notification.
*
* Toasts are a sort of lightweight notification that are unique to Android.
*
* https://developer.android.com/guide/topics/ui/notifiers/toasts
*
* Shows toast in UI thread.
*
* For the `gravity` parameter, choose a value from here, or -1 if you don't
* have a preference:
*
* https://developer.android.com/reference/android/view/Gravity
*
* \param message text message to be shown
* \param duration 0=short, 1=long
* \param gravity where the notification should appear on the screen.
* \param xoffset set this parameter only when gravity >=0
* \param yoffset set this parameter only when gravity >=0
* \returns 0 if success, -1 if any error occurs.
*/
extern DECLSPEC int SDLCALL SDL_AndroidShowToast(const char* message, int duration, int gravity, int xoffset, int yoffset);
#endif /* __ANDROID__ */
@ -281,50 +411,66 @@ typedef enum
/**
* \brief Retrieves a WinRT defined path on the local file system
* Retrieve a WinRT defined path on the local file system.
*
* \note Documentation on most app-specific path types on WinRT
* can be found on MSDN, at the URL:
* http://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
* Not all paths are available on all versions of Windows. This is especially
* true on Windows Phone. Check the documentation for the given SDL_WinRT_Path
* for more information on which path types are supported where.
*
* \param pathType The type of path to retrieve.
* \return A UCS-2 string (16-bit, wide-char) containing the path, or NULL
* if the path is not available for any reason. Not all paths are
* available on all versions of Windows. This is especially true on
* Windows Phone. Check the documentation for the given
* SDL_WinRT_Path for more information on which path types are
* supported where.
* Documentation on most app-specific path types on WinRT can be found on
* MSDN, at the URL:
*
* https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
*
* \param pathType the type of path to retrieve, one of SDL_WinRT_Path
* \returns a UCS-2 string (16-bit, wide-char) containing the path, or NULL if
* the path is not available for any reason; call SDL_GetError() for
* more information.
*
* \since This function is available since SDL 2.0.3.
*
* \sa SDL_WinRTGetFSPathUTF8
*/
extern DECLSPEC const wchar_t * SDLCALL SDL_WinRTGetFSPathUNICODE(SDL_WinRT_Path pathType);
/**
* \brief Retrieves a WinRT defined path on the local file system
* Retrieve a WinRT defined path on the local file system.
*
* \note Documentation on most app-specific path types on WinRT
* can be found on MSDN, at the URL:
* http://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
* Not all paths are available on all versions of Windows. This is especially
* true on Windows Phone. Check the documentation for the given SDL_WinRT_Path
* for more information on which path types are supported where.
*
* \param pathType The type of path to retrieve.
* \return A UTF-8 string (8-bit, multi-byte) containing the path, or NULL
* if the path is not available for any reason. Not all paths are
* available on all versions of Windows. This is especially true on
* Windows Phone. Check the documentation for the given
* SDL_WinRT_Path for more information on which path types are
* supported where.
* Documentation on most app-specific path types on WinRT can be found on
* MSDN, at the URL:
*
* https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
*
* \param pathType the type of path to retrieve, one of SDL_WinRT_Path
* \returns a UTF-8 string (8-bit, multi-byte) containing the path, or NULL if
* the path is not available for any reason; call SDL_GetError() for
* more information.
*
* \since This function is available since SDL 2.0.3.
*
* \sa SDL_WinRTGetFSPathUNICODE
*/
extern DECLSPEC const char * SDLCALL SDL_WinRTGetFSPathUTF8(SDL_WinRT_Path pathType);
/**
* \brief Detects the device family of WinRT plattform on runtime
* Detects the device family of WinRT plattform at runtime.
*
* \return Device family
* \returns A value from the SDL_WinRT_DeviceFamily enum.
*/
extern DECLSPEC SDL_WinRT_DeviceFamily SDLCALL SDL_WinRTGetDeviceFamily();
#endif /* __WINRT__ */
/**
\brief Return true if the current device is a tablet.
* Query if the current device is a tablet.
*
* If SDL can't determine this, it will return SDL_FALSE.
*
* \returns SDL_TRUE if the device is a tablet, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_IsTablet(void);

26
include/SDL_syswm.h
View File

@ -344,23 +344,23 @@ struct SDL_SysWMinfo
typedef struct SDL_SysWMinfo SDL_SysWMinfo;
/* Function prototypes */
/**
* \brief This function allows access to driver-dependent window information.
* Get driver-specific information about a window.
*
* \param window The window about which information is being requested
* \param info This structure must be initialized with the SDL version, and is
* then filled in with information about the given window.
* You must include SDL_syswm.h for the declaration of SDL_SysWMinfo.
*
* \return SDL_TRUE if the function is implemented and the version member of
* the \c info struct is valid, SDL_FALSE otherwise.
* The caller must initialize the `info` structure's version by using
* `SDL_VERSION(&info.version)`, and then this function will fill in the
* rest of the structure with information about the given window.
*
* You typically use this function like this:
* \code
* SDL_SysWMinfo info;
* SDL_VERSION(&info.version);
* if ( SDL_GetWindowWMInfo(window, &info) ) { ... }
* \endcode
* \param window the window about which information is being requested
* \param info an SDL_SysWMinfo structure filled in with window information
* \returns SDL_TRUE if the function is implemented and the `version` member
* of the `info` struct is valid, or SDL_FALSE if the information
* could not be retrieved; call SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowWMInfo(SDL_Window * window,
SDL_SysWMinfo * info);

227
include/SDL_thread.h
View File

@ -70,10 +70,13 @@ typedef enum {
/**
* The function passed to SDL_CreateThread().
* It is passed a void* user context parameter and returns an int.
*
* \param data what was passed as `data` to SDL_CreateThread()
* \returns a value that can be reported through SDL_WaitThread().
*/
typedef int (SDLCALL * SDL_ThreadFunction) (void *data);
#if defined(__WIN32__)
/**
* \file SDL_thread.h
@ -183,39 +186,68 @@ SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn, const char *name, const siz
#else
/**
* Create a thread with a default stack size.
* Create a new thread with a default stack size.
*
* This is equivalent to calling:
*
* ```c
* SDL_CreateThreadWithStackSize(fn, name, 0, data);
* ```
*
* \param fn the SDL_ThreadFunction function to call in the new thread
* \param name the name of the thread
* \param data a pointer that is passed to `fn`
* \returns an opaque pointer to the new thread object on success, NULL if the
* new thread could not be created; call SDL_GetError() for more
* information.
*
* \sa SDL_CreateThreadWithStackSize
* \sa SDL_WaitThread
*/
extern DECLSPEC SDL_Thread *SDLCALL
SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data);
/**
* Create a thread.
* Create a new thread with a specific stack size.
*
* SDL makes an attempt to report `name` to the system, so that debuggers
* can display it. Not all platforms support this.
*
* Thread naming is a little complicated: Most systems have very small
* limits for the string length (Haiku has 32 bytes, Linux currently has 16,
* Visual C++ 6.0 has nine!), and possibly other arbitrary rules. You'll
* Visual C++ 6.0 has _nine_!), and possibly other arbitrary rules. You'll
* have to see what happens with your system's debugger. The name should be
* UTF-8 (but using the naming limits of C identifiers is a better bet).
* There are no requirements for thread naming conventions, so long as the
* string is null-terminated UTF-8, but these guidelines are helpful in
* choosing a name:
*
* http://stackoverflow.com/questions/149932/naming-conventions-for-threads
* https://stackoverflow.com/questions/149932/naming-conventions-for-threads
*
* If a system imposes requirements, SDL will try to munge the string for
* it (truncate, etc), but the original string contents will be available
* from SDL_GetThreadName().
*
* The size (in bytes) of the new stack can be specified. Zero means "use
* the system default" which might be wildly different between platforms
* (x86 Linux generally defaults to eight megabytes, an embedded device
* might be a few kilobytes instead).
* the system default" which might be wildly different between platforms.
* x86 Linux generally defaults to eight megabytes, an embedded device
* might be a few kilobytes instead. You generally need to specify a stack
* that is a multiple of the system's page size (in many cases, this is 4
* kilobytes, but check your system documentation).
*
* In SDL 2.1, stacksize will be folded into the original SDL_CreateThread
* In SDL 2.1, stack size will be folded into the original SDL_CreateThread
* function, but for backwards compatibility, this is currently a separate
* function.
*
* \param fn the SDL_ThreadFunction function to call in the new thread
* \param name the name of the thread
* \param stacksize the size, in bytes, to allocate for the new thread stack.
* \param data a pointer that is passed to `fn`
* \returns an opaque pointer to the new thread object on success, NULL if the
* new thread could not be created; call SDL_GetError() for more
* information.
*
* \sa SDL_WaitThread
*/
extern DECLSPEC SDL_Thread *SDLCALL
SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn, const char *name, const size_t stacksize, void *data);
@ -223,134 +255,183 @@ SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn, const char *name, const siz
#endif
/**
* Get the thread name, as it was specified in SDL_CreateThread().
* This function returns a pointer to a UTF-8 string that names the
* specified thread, or NULL if it doesn't have a name. This is internal
* memory, not to be free()'d by the caller, and remains valid until the
* specified thread is cleaned up by SDL_WaitThread().
* Get the thread name as it was specified in SDL_CreateThread().
*
* This is internal memory, not to be freed by the caller, and remains valid
* until the specified thread is cleaned up by SDL_WaitThread().
*
* \param thread the thread to query
* \returns a pointer to a UTF-8 string that names the specified thread, or
* NULL if it doesn't have a name.
*
* \sa SDL_CreateThread
*/
extern DECLSPEC const char *SDLCALL SDL_GetThreadName(SDL_Thread *thread);
/**
* Get the thread identifier for the current thread.
*
* This thread identifier is as reported by the underlying operating system.
* If SDL is running on a platform that does not support threads the return
* value will always be zero.
*
* This function also returns a valid thread ID when called from the main
* thread.
*
* \returns the ID of the current thread.
*
* \sa SDL_GetThreadID
*/
extern DECLSPEC SDL_threadID SDLCALL SDL_ThreadID(void);
/**
* Get the thread identifier for the specified thread.
*
* Equivalent to SDL_ThreadID() if the specified thread is NULL.
* This thread identifier is as reported by the underlying operating system.
* If SDL is running on a platform that does not support threads the return
* value will always be zero.
*
* \param thread the thread to query
* \returns the ID of the specified thread, or the ID of the current thread if
* `thread` is NULL.
*
* \sa SDL_ThreadID
*/
extern DECLSPEC SDL_threadID SDLCALL SDL_GetThreadID(SDL_Thread * thread);
/**
* Set the priority for the current thread
* Set the priority for the current thread.
*
* Note that some platforms will not let you alter the priority (or at least,
* promote the thread to a higher priority) at all, and some require you
* to be an administrator account. Be prepared for this to fail.
*
* \param priority the SDL_ThreadPriority to set
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*/
extern DECLSPEC int SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority priority);
/**
* Wait for a thread to finish. Threads that haven't been detached will
* remain (as a "zombie") until this function cleans them up. Not doing so
* is a resource leak.
* Wait for a thread to finish.
*
* Threads that haven't been detached will remain (as a "zombie") until this
* function cleans them up. Not doing so is a resource leak.
*
* Once a thread has been cleaned up through this function, the SDL_Thread
* that references it becomes invalid and should not be referenced again.
* As such, only one thread may call SDL_WaitThread() on another.
* that references it becomes invalid and should not be referenced again. As
* such, only one thread may call SDL_WaitThread() on another.
*
* The return code for the thread function is placed in the area
* pointed to by \c status, if \c status is not NULL.
* The return code for the thread function is placed in the area pointed to by
* `status`, if `status` is not NULL.
*
* You may not wait on a thread that has been used in a call to
* SDL_DetachThread(). Use either that function or this one, but not
* both, or behavior is undefined.
* SDL_DetachThread(). Use either that function or this one, but not both, or
* behavior is undefined.
*
* It is safe to pass NULL to this function; it is a no-op.
* It is safe to pass a NULL thread to this function; it is a no-op.
*
* Note that the thread pointer is freed by this function and is not valid
* afterward.
*
* \param thread the SDL_Thread pointer that was returned from the
* SDL_CreateThread() call that started this thread
* \param status pointer to an integer that will receive the value returned
* from the thread function by its 'return', or NULL to not
* receive such value back.
*
* \sa SDL_CreateThread
* \sa SDL_DetachThread
*/
extern DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread * thread, int *status);
/**
* Let a thread clean up on exit without intervention.
*
* A thread may be "detached" to signify that it should not remain until
* another thread has called SDL_WaitThread() on it. Detaching a thread
* is useful for long-running threads that nothing needs to synchronize
* with or further manage. When a detached thread is done, it simply
* goes away.
* another thread has called SDL_WaitThread() on it. Detaching a thread is
* useful for long-running threads that nothing needs to synchronize with or
* further manage. When a detached thread is done, it simply goes away.
*
* There is no way to recover the return code of a detached thread. If you
* need this, don't detach the thread and instead use SDL_WaitThread().
*
* Once a thread is detached, you should usually assume the SDL_Thread isn't
* safe to reference again, as it will become invalid immediately upon
* the detached thread's exit, instead of remaining until someone has called
* safe to reference again, as it will become invalid immediately upon the
* detached thread's exit, instead of remaining until someone has called
* SDL_WaitThread() to finally clean it up. As such, don't detach the same
* thread more than once.
*
* If a thread has already exited when passed to SDL_DetachThread(), it will
* stop waiting for a call to SDL_WaitThread() and clean up immediately.
* It is not safe to detach a thread that might be used with SDL_WaitThread().
* stop waiting for a call to SDL_WaitThread() and clean up immediately. It is
* not safe to detach a thread that might be used with SDL_WaitThread().
*
* You may not call SDL_WaitThread() on a thread that has been detached.
* Use either that function or this one, but not both, or behavior is
* undefined.
* You may not call SDL_WaitThread() on a thread that has been detached. Use
* either that function or this one, but not both, or behavior is undefined.
*
* It is safe to pass NULL to this function; it is a no-op.
*
* \param thread the SDL_Thread pointer that was returned from the
* SDL_CreateThread() call that started this thread
*
* \since This function is available since SDL 2.0.2.
*
* \sa SDL_CreateThread
* \sa SDL_WaitThread
*/
extern DECLSPEC void SDLCALL SDL_DetachThread(SDL_Thread * thread);
/**
* \brief Create an identifier that is globally visible to all threads but refers to data that is thread-specific.
* Create a piece of thread-local storage.
*
* \return The newly created thread local storage identifier, or 0 on error
* This creates an identifier that is globally visible to all
* threads but refers to data that is thread-specific.
*
* \code
* static SDL_SpinLock tls_lock;
* static SDL_TLSID thread_local_storage;
* \returns the newly created thread local storage identifier or 0 on error.
*
* void SetMyThreadData(void *value)
* {
* if (!thread_local_storage) {
* SDL_AtomicLock(&tls_lock);
* if (!thread_local_storage) {
* thread_local_storage = SDL_TLSCreate();
* }
* SDL_AtomicUnlock(&tls_lock);
* }
* SDL_TLSSet(thread_local_storage, value, 0);
* }
* \since This function is available since SDL 2.0.0.
*
* void *GetMyThreadData(void)
* {
* return SDL_TLSGet(thread_local_storage);
* }
* \endcode
*
* \sa SDL_TLSGet()
* \sa SDL_TLSSet()
* \sa SDL_TLSGet
* \sa SDL_TLSSet
*/
extern DECLSPEC SDL_TLSID SDLCALL SDL_TLSCreate(void);
/**
* \brief Get the value associated with a thread local storage ID for the current thread.
* Get the current thread's value associated with a thread local storage ID.
*
* \param id The thread local storage ID
* \param id the thread local storage ID
* \returns the value associated with the ID for the current thread or NULL if
* no value has been set; call SDL_GetError() for more information.
*
* \return The value associated with the ID for the current thread, or NULL if no value has been set.
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_TLSCreate()
* \sa SDL_TLSSet()
* \sa SDL_TLSCreate
* \sa SDL_TLSSet
*/
extern DECLSPEC void * SDLCALL SDL_TLSGet(SDL_TLSID id);
/**
* \brief Set the value associated with a thread local storage ID for the current thread.
* Set the current thread's value associated with a thread local storage ID.
*
* \param id The thread local storage ID
* \param value The value to associate with the ID for the current thread
* \param destructor A function called when the thread exits, to free the value.
* The function prototype for `destructor` is:
*
* \return 0 on success, -1 on error
* ```c
* void destructor(void *value)
* ```
*
* \sa SDL_TLSCreate()
* \sa SDL_TLSGet()
* where its parameter `value` is what was passed as `value` to SDL_TLSSet().
*
* \param id the thread local storage ID
* \param value the value to associate with the ID for the current thread
* \param destructor a function called when the thread exits, to free the
* value
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_TLSCreate
* \sa SDL_TLSGet
*/
extern DECLSPEC int SDLCALL SDL_TLSSet(SDL_TLSID id, const void *value, void (SDLCALL *destructor)(void*));

83
include/SDL_timer.h
View File

@ -38,35 +38,65 @@ extern "C" {
#endif
/**
* \brief Get the number of milliseconds since the SDL library initialization.
* Get the number of milliseconds since SDL library initialization.
*
* \note This value wraps if the program runs for more than ~49 days.
* This value wraps if the program runs for more than ~49 days.
*
* \returns an unsigned 32-bit value representing the number of milliseconds
* since the SDL library initialized.
*
* \sa SDL_TICKS_PASSED
*/
extern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void);
/**
* \brief Compare SDL ticks values, and return true if A has passed B
* Compare SDL ticks values, and return true if `A` has passed `B`.
*
* e.g. if you want to wait 100 ms, you could do this:
* For example, if you want to wait 100 ms, you could do this:
*
* ```c++
* Uint32 timeout = SDL_GetTicks() + 100;
* while (!SDL_TICKS_PASSED(SDL_GetTicks(), timeout)) {
* ... do work until timeout has elapsed
* // ... do work until timeout has elapsed
* }
* ```
*/
#define SDL_TICKS_PASSED(A, B) ((Sint32)((B) - (A)) <= 0)
/**
* \brief Get the current value of the high resolution counter
* Get the current value of the high resolution counter.
*
* This function is typically used for profiling.
*
* The counter values are only meaningful relative to each other. Differences
* between values can be converted to times by using
* SDL_GetPerformanceFrequency().
*
* \returns the current counter value.
*
* \sa SDL_GetPerformanceFrequency
*/
extern DECLSPEC Uint64 SDLCALL SDL_GetPerformanceCounter(void);
/**
* \brief Get the count per second of the high resolution counter
* Get the count per second of the high resolution counter.
*
* \returns a platform-specific count per second.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_GetPerformanceCounter
*/
extern DECLSPEC Uint64 SDLCALL SDL_GetPerformanceFrequency(void);
/**
* \brief Wait a specified number of milliseconds before returning.
* Wait a specified number of milliseconds before returning.
*
* This function waits a specified number of milliseconds before returning. It
* waits at least the specified time, but possibly longer due to OS
* scheduling.
*
* \param ms the number of milliseconds to delay
*/
extern DECLSPEC void SDLCALL SDL_Delay(Uint32 ms);
@ -86,20 +116,47 @@ typedef Uint32 (SDLCALL * SDL_TimerCallback) (Uint32 interval, void *param);
typedef int SDL_TimerID;
/**
* \brief Add a new timer to the pool of timers already running.
* Call a callback function at a future time.
*
* \return A timer ID, or 0 when an error occurs.
* If you use this function, you must pass `SDL_INIT_TIMER` to SDL_Init().
*
* The callback function is passed the current timer interval and the user
* supplied parameter from the SDL_AddTimer() call and should return the next
* timer interval. If the value returned from the callback is 0, the timer is
* canceled.
*
* The callback is run on a separate thread.
*
* Timers take into account the amount of time it took to execute the
* callback. For example, if the callback took 250 ms to execute and returned
* 1000 (ms), the timer would only wait another 750 ms before its next
* iteration.
*
* Timing may be inexact due to OS scheduling. Be sure to note the current
* time with SDL_GetTicks() or SDL_GetPerformanceCounter() in case your
* callback needs to adjust for variances.
*
* \param interval the timer delay, in milliseconds, passed to `callback`
* \param callback the SDL_TimerCallback function to call when the specified
* `interval` elapses
* \param param a pointer that is passed to `callback`
* \returns a timer ID or 0 if an error occurs; call SDL_GetError() for more
* information.
*
* \sa SDL_RemoveTimer
*/
extern DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval,
SDL_TimerCallback callback,
void *param);
/**
* \brief Remove a timer knowing its ID.
* Remove a timer created with SDL_AddTimer().
*
* \return A boolean value indicating success or failure.
* \param id the ID of the timer to remove
* \returns SDL_TRUE if the timer is removed or SDL_FALSE if the timer wasn't
* found.
*
* \warning It is not safe to remove a timer multiple times.
* \sa SDL_AddTimer
*/
extern DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID id);

50
include/SDL_touch.h
View File

@ -64,30 +64,66 @@ typedef struct SDL_Finger
#define SDL_MOUSE_TOUCHID ((Sint64)-1)
/* Function prototypes */
/**
* \brief Get the number of registered touch devices.
* Get the number of registered touch devices.
*
* On some platforms SDL first sees the touch device if it was actually used.
* Therefore SDL_GetNumTouchDevices() may return 0 although devices are
* available. After using all devices at least once the number will be
* correct.
*
* This was fixed for Android in SDL 2.0.1.
*
* \returns the number of registered touch devices.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_GetTouchDevice
*/
extern DECLSPEC int SDLCALL SDL_GetNumTouchDevices(void);
/**
* \brief Get the touch ID with the given index, or 0 if the index is invalid.
* Get the touch ID with the given index.
*
* \param index the touch device index
* \returns the touch ID with the given index on success or 0 if the index is
* invalid; call SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_GetNumTouchDevices
*/
extern DECLSPEC SDL_TouchID SDLCALL SDL_GetTouchDevice(int index);
/**
* \brief Get the type of the given touch device.
* Get the type of the given touch device.
*/
extern DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_TouchID touchID);
/**
* \brief Get the number of active fingers for a given touch device.
* Get the number of active fingers for a given touch device.
*
* \param touchID the ID of a touch device
* \returns the number of active fingers for a given touch device on success
* or 0 on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_GetTouchFinger
*/
extern DECLSPEC int SDLCALL SDL_GetNumTouchFingers(SDL_TouchID touchID);
/**
* \brief Get the finger object of the given touch, with the given index.
* Get the finger object for specified touch device ID and finger index.
*
* The returned resource is owned by SDL and should not be deallocated.
*
* \param touchID the ID of the requested touch device
* \param index the index of the requested finger
* \returns a pointer to the SDL_Finger object or NULL if no object at the
* given ID and index could be found.
*
* \sa SDL_RecordGesture
*/
extern DECLSPEC SDL_Finger * SDLCALL SDL_GetTouchFinger(SDL_TouchID touchID, int index);

54
include/SDL_version.h
View File

@ -37,7 +37,7 @@ extern "C" {
#endif
/**
* \brief Information the version of SDL in use.
* Information about the version of SDL in use.
*
* Represents the library's version as three levels: major revision
* (increments with massive changes, additions, and enhancements),
@ -62,7 +62,7 @@ typedef struct SDL_version
#define SDL_PATCHLEVEL 15
/**
* \brief Macro to determine SDL version program was compiled against.
* Macro to determine SDL version program was compiled against.
*
* This macro fills in a SDL_version structure with the version of the
* library you compiled against. This is determined by what header the
@ -107,42 +107,50 @@ typedef struct SDL_version
(SDL_COMPILEDVERSION >= SDL_VERSIONNUM(X, Y, Z))
/**
* \brief Get the version of SDL that is linked against your program.
* Get the version of SDL that is linked against your program.
*
* If you are linking to SDL dynamically, then it is possible that the
* current version will be different than the version you compiled against.
* This function returns the current version, while SDL_VERSION() is a
* macro that tells you what version you compiled with.
*
* \code
* SDL_version compiled;
* SDL_version linked;
*
* SDL_VERSION(&compiled);
* SDL_GetVersion(&linked);
* printf("We compiled against SDL version %d.%d.%d ...\n",
* compiled.major, compiled.minor, compiled.patch);
* printf("But we linked against SDL version %d.%d.%d.\n",
* linked.major, linked.minor, linked.patch);
* \endcode
* If you are linking to SDL dynamically, then it is possible that the current
* version will be different than the version you compiled against. This
* function returns the current version, while SDL_VERSION() is a macro that
* tells you what version you compiled with.
*
* This function may be called safely at any time, even before SDL_Init().
*
* \sa SDL_VERSION
* \param ver the SDL_version structure that contains the version information
*
* \sa SDL_GetRevision
*/
extern DECLSPEC void SDLCALL SDL_GetVersion(SDL_version * ver);
/**
* \brief Get the code revision of SDL that is linked against your program.
* Get the code revision of SDL that is linked against your program.
*
* Returns an arbitrary string (a hash value) uniquely identifying the
* This value is the revision of the code you are linked with and may be
* different from the code you are compiling with, which is found in the
* constant SDL_REVISION.
*
* The revision is arbitrary string (a hash value) uniquely identifying the
* exact revision of the SDL library in use, and is only useful in comparing
* against other revisions. It is NOT an incrementing number.
*
* If SDL wasn't built from a git repository with the appropriate tools, this
* will return an empty string.
*
* Prior to SDL 2.0.16, before development moved to GitHub, this returned a
* hash for a Mercurial repository.
*
* You shouldn't use this function for anything but logging it for debugging
* purposes. The string is not intended to be reliable in any way.
*
* \returns an arbitrary string, uniquely identifying the exact revision of
* the SDL library in use.
*
* \sa SDL_GetVersion
*/
extern DECLSPEC const char *SDLCALL SDL_GetRevision(void);
/**
* \brief Obsolete function, do not use.
* Obsolete function, do not use.
*
* When SDL was hosted in a Mercurial repository, and was built carefully,
* this would return the revision number that the build was created from.

1421
include/SDL_video.h
View File

File diff suppressed because it is too large Load Diff

231
include/SDL_vulkan.h
View File

@ -66,201 +66,140 @@ typedef VkSurfaceKHR SDL_vulkanSurface; /* for compatibility with Tizen */
/* @{ */
/**
* \brief Dynamically load a Vulkan loader library.
*
* \param [in] path The platform dependent Vulkan loader library name, or
* \c NULL.
*
* \return \c 0 on success, or \c -1 if the library couldn't be loaded.
*
* If \a path is NULL SDL will use the value of the environment variable
* \c SDL_VULKAN_LIBRARY, if set, otherwise it loads the default Vulkan
* loader library.
* Dynamically load the Vulkan loader library.
*
* This should be called after initializing the video driver, but before
* creating any Vulkan windows. If no Vulkan loader library is loaded, the
* default library will be loaded upon creation of the first Vulkan window.
*
* \note It is fairly common for Vulkan applications to link with \a libvulkan
* instead of explicitly loading it at run time. This will work with
* SDL provided the application links to a dynamic library and both it
* and SDL use the same search path.
* It is fairly common for Vulkan applications to link with libvulkan instead
* of explicitly loading it at run time. This will work with SDL provided the
* application links to a dynamic library and both it and SDL use the same
* search path.
*
* \note If you specify a non-NULL \c path, an application should retrieve all
* of the Vulkan functions it uses from the dynamic library using
* \c SDL_Vulkan_GetVkGetInstanceProcAddr() unless you can guarantee
* \c path points to the same vulkan loader library the application
* linked to.
* If you specify a non-NULL `path`, an application should retrieve
* all of the Vulkan functions it uses from the dynamic library using
* SDL_Vulkan_GetVkGetInstanceProcAddr unless you can guarantee `path`
* points to the same vulkan loader library the application linked to.
*
* \note On Apple devices, if \a path is NULL, SDL will attempt to find
* the vkGetInstanceProcAddr address within all the mach-o images of
* the current process. This is because it is fairly common for Vulkan
* applications to link with libvulkan (and historically MoltenVK was
* provided as a static library). If it is not found then, on macOS, SDL
* will attempt to load \c vulkan.framework/vulkan, \c libvulkan.1.dylib,
* followed by \c libvulkan.dylib, in that order.
* On iOS SDL will attempt to load \c libvulkan.dylib only. Applications
* using a dynamic framework or .dylib must ensure it is included in its
* application bundle.
* On Apple devices, if `path` is NULL, SDL will attempt to find the
* `vkGetInstanceProcAddr` address within all the Mach-O images of the
* current process. This is because it is fairly common for Vulkan
* applications to link with libvulkan (and historically MoltenVK was provided
* as a static library). If it is not found, on macOS, SDL will attempt
* to load `vulkan.framework/vulkan`, `libvulkan.1.dylib`,
* `MoltenVK.framework/MoltenVK`, and `libMoltenVK.dylib`, in that
* order. On iOS, SDL will attempt to load `libMoltenVK.dylib`.
* Applications using a dynamic framework or .dylib must ensure it is included
* in its application bundle.
*
* \note On non-Apple devices, application linking with a static libvulkan is
* not supported. Either do not link to the Vulkan loader or link to a
* dynamic library version.
* On non-Apple devices, application linking with a static libvulkan is not
* supported. Either do not link to the Vulkan loader or link to a dynamic
* library version.
*
* \note This function will fail if there are no working Vulkan drivers
* installed.
* \param path The platform dependent Vulkan loader library name or NULL
* \returns 0 on success or -1 if the library couldn't be loaded; call
* SDL_GetError() for more information.
*
* \sa SDL_Vulkan_GetVkGetInstanceProcAddr()
* \sa SDL_Vulkan_UnloadLibrary()
* \since This function is available in SDL 2.0.8
*
* \sa SDL_Vulkan_GetVkInstanceProcAddr
* \sa SDL_Vulkan_UnloadLibrary
*/
extern DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path);
/**
* \brief Get the address of the \c vkGetInstanceProcAddr function.
* Get the address of the `vkGetInstanceProcAddr` function.
*
* \note This should be called after either calling SDL_Vulkan_LoadLibrary
* or creating an SDL_Window with the SDL_WINDOW_VULKAN flag.
* This should be called after either calling SDL_Vulkan_LoadLibrary()
* or creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag.
*
* \returns The function pointer for `vkGetInstanceProcAddr` or NULL on error.
*/
extern DECLSPEC void *SDLCALL SDL_Vulkan_GetVkGetInstanceProcAddr(void);
/**
* \brief Unload the Vulkan loader library previously loaded by
* \c SDL_Vulkan_LoadLibrary().
* Unload the Vulkan library previously loaded by SDL_Vulkan_LoadLibrary()
*
* \sa SDL_Vulkan_LoadLibrary()
* \since This function is available in SDL 2.0.8
*
* \sa SDL_Vulkan_LoadLibrary
*/
extern DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void);
/**
* \brief Get the names of the Vulkan instance extensions needed to create
* a surface with \c SDL_Vulkan_CreateSurface().
* Get the names of the Vulkan instance extensions needed
* to create a surface with SDL_Vulkan_CreateSurface.
*
* \param [in] \c NULL or window Window for which the required Vulkan instance
* extensions should be retrieved
* \param [in,out] pCount pointer to an \c unsigned related to the number of
* required Vulkan instance extensions
* \param [out] pNames \c NULL or a pointer to an array to be filled with the
* required Vulkan instance extensions
* If `pNames` is NULL, then the number of required Vulkan instance
* extensions is returned in `pCount`. Otherwise, `pCount` must point
* to a variable set to the number of elements in the `pNames` array, and
* on return the variable is overwritten with the number of names actually
* written to `pNames`. If `pCount` is less than the number of
* required extensions, at most `pCount` structures will be written. If
* `pCount` is smaller than the number of required extensions,
* SDL_FALSE will be returned instead of SDL_TRUE, to indicate
* that not all the required extensions were returned.
*
* \return \c SDL_TRUE on success, \c SDL_FALSE on error.
* The `window` parameter is currently needed to be valid as of
* SDL 2.0.8, however, this parameter will likely be removed in future
* releases
*
* If \a pNames is \c NULL, then the number of required Vulkan instance
* extensions is returned in pCount. Otherwise, \a pCount must point to a
* variable set to the number of elements in the \a pNames array, and on
* return the variable is overwritten with the number of names actually
* written to \a pNames. If \a pCount is less than the number of required
* extensions, at most \a pCount structures will be written. If \a pCount
* is smaller than the number of required extensions, \c SDL_FALSE will be
* returned instead of \c SDL_TRUE, to indicate that not all the required
* extensions were returned.
* \param window A window for which the required Vulkan instance extensions
* should be retrieved (will be deprecated in a future release)
* \param pCount A pointer to an unsigned int corresponding to the
* number of extensions to be returned
* \param names NULL or a pointer to an array to be filled with required
* Vulkan instance extensions
* \returns SDL_TRUE on success, SDL_FALSE on error.
*
* \note If \c window is not NULL, it will be checked against its creation
* flags to ensure that the Vulkan flag is present. This parameter
* will be removed in a future major release.
* \since This function is available in SDL 2.0.8
*
* \note The returned list of extensions will contain \c VK_KHR_surface
* and zero or more platform specific extensions
*
* \note The extension names queried here must be enabled when calling
* VkCreateInstance, otherwise surface creation will fail.
*
* \note \c window should have been created with the \c SDL_WINDOW_VULKAN flag
* or be \c NULL
*
* \code
* unsigned int count;
* // get count of required extensions
* if(!SDL_Vulkan_GetInstanceExtensions(NULL, &count, NULL))
* handle_error();
*
* static const char *const additionalExtensions[] =
* {
* VK_EXT_DEBUG_REPORT_EXTENSION_NAME, // example additional extension
* };
* size_t additionalExtensionsCount = sizeof(additionalExtensions) / sizeof(additionalExtensions[0]);
* size_t extensionCount = count + additionalExtensionsCount;
* const char **names = malloc(sizeof(const char *) * extensionCount);
* if(!names)
* handle_error();
*
* // get names of required extensions
* if(!SDL_Vulkan_GetInstanceExtensions(NULL, &count, names))
* handle_error();
*
* // copy additional extensions after required extensions
* for(size_t i = 0; i < additionalExtensionsCount; i++)
* names[i + count] = additionalExtensions[i];
*
* VkInstanceCreateInfo instanceCreateInfo = {};
* instanceCreateInfo.enabledExtensionCount = extensionCount;
* instanceCreateInfo.ppEnabledExtensionNames = names;
* // fill in rest of instanceCreateInfo
*
* VkInstance instance;
* // create the Vulkan instance
* VkResult result = vkCreateInstance(&instanceCreateInfo, NULL, &instance);
* free(names);
* \endcode
*
* \sa SDL_Vulkan_CreateSurface()
* \sa SDL_Vulkan_CreateSurface
*/
extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_GetInstanceExtensions(SDL_Window *window,
unsigned int *pCount,
const char **pNames);
/**
* \brief Create a Vulkan rendering surface for a window.
* Create a Vulkan rendering surface for a window.
*
* \param [in] window SDL_Window to which to attach the rendering surface.
* \param [in] instance handle to the Vulkan instance to use.
* \param [out] surface pointer to a VkSurfaceKHR handle to receive the
* handle of the newly created surface.
* The `window` must have been created with the `SDL_WINDOW_VULKAN` flag and
* `instance` must have been created with extensions returned by
* SDL_Vulkan_GetInstanceExtensions() enabled.
*
* \return \c SDL_TRUE on success, \c SDL_FALSE on error.
* \param window The window to which to attach the Vulkan surface
* \param instance The Vulkan instance handle
* \param surface A pointer to a VkSurfaceKHR handle to output the newly
* created surface
* \returns SDL_TRUE on success, SDL_FALSE on error.
*
* \code
* VkInstance instance;
* SDL_Window *window;
* \since This function is available in SDL 2.0.8
*
* // create instance and window
*
* // create the Vulkan surface
* VkSurfaceKHR surface;
* if(!SDL_Vulkan_CreateSurface(window, instance, &surface))
* handle_error();
* \endcode
*
* \note \a window should have been created with the \c SDL_WINDOW_VULKAN flag.
*
* \note \a instance should have been created with the extensions returned
* by \c SDL_Vulkan_CreateSurface() enabled.
*
* \sa SDL_Vulkan_GetInstanceExtensions()
* \sa SDL_Vulkan_GetInstanceExtensions
* \sa SDL_Vulkan_GetDrawableSize
*/
extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window,
VkInstance instance,
VkSurfaceKHR* surface);
/**
* \brief Get the size of a window's underlying drawable in pixels (for use
* with setting viewport, scissor & etc).
*
* \param window SDL_Window from which the drawable size should be queried
* \param w Pointer to variable for storing the width in pixels,
* may be NULL
* \param h Pointer to variable for storing the height in pixels,
* may be NULL
* Get the size of the window's underlying drawable dimensions in pixels.
*
* This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI
* drawable, i.e. the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a
* platform with high-DPI support (Apple calls this "Retina"), and not disabled
* by the \c SDL_HINT_VIDEO_HIGHDPI_DISABLED hint.
* drawable, i.e. the window was created with `SDL_WINDOW_ALLOW_HIGHDPI`
* on a platform with high-DPI support (Apple calls this "Retina"), and not
* disabled by the `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint.
*
* \note On macOS high-DPI support must be enabled for an application by
* setting NSHighResolutionCapable to true in its Info.plist.
* \param window an SDL_Window for which the size is to be queried
* \param w Pointer to the variable to write the width to or NULL
* \param h Pointer to the variable to write the height to or NULL
*
* \sa SDL_GetWindowSize()
* \sa SDL_CreateWindow()
* \since This function is available in SDL 2.0.8
*
* \sa SDL_GetWindowSize
* \sa SDL_CreateWindow
* \sa SDL_Vulkan_CreateSurface
*/
extern DECLSPEC void SDLCALL SDL_Vulkan_GetDrawableSize(SDL_Window * window,
int *w, int *h);