From 3f40396d33df64326756648c3b8e1e6c922efe5a Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" Date: Sun, 21 Mar 2021 14:18:39 -0400 Subject: [PATCH] First shot at merging the wiki documentation into the headers. --- include/SDL.h | 110 ++- include/SDL_assert.h | 127 +-- include/SDL_atomic.h | 134 ++- include/SDL_audio.h | 816 +++++++++++++------ include/SDL_blendmode.h | 109 ++- include/SDL_clipboard.h | 30 +- include/SDL_cpuinfo.h | 329 ++++++-- include/SDL_error.h | 76 +- include/SDL_events.h | 415 ++++++++-- include/SDL_filesystem.h | 120 +-- include/SDL_gamecontroller.h | 546 ++++++++++--- include/SDL_gesture.h | 40 +- include/SDL_haptic.h | 490 ++++++----- include/SDL_hints.h | 86 +- include/SDL_joystick.h | 565 ++++++++++--- include/SDL_keyboard.h | 201 +++-- include/SDL_loadso.h | 42 +- include/SDL_log.h | 200 ++++- include/SDL_main.h | 33 +- include/SDL_messagebox.h | 91 ++- include/SDL_misc.h | 32 +- include/SDL_mouse.h | 328 +++++--- include/SDL_mutex.h | 317 ++++++-- include/SDL_pixels.h | 200 ++++- include/SDL_platform.h | 17 +- include/SDL_power.h | 29 +- include/SDL_rect.h | 96 ++- include/SDL_render.h | 1437 ++++++++++++++++++++------------ include/SDL_rwops.h | 183 ++++- include/SDL_sensor.h | 94 ++- include/SDL_surface.h | 605 ++++++++++---- include/SDL_system.h | 376 ++++++--- include/SDL_syswm.h | 26 +- include/SDL_thread.h | 283 ++++--- include/SDL_timer.h | 99 ++- include/SDL_touch.h | 50 +- include/SDL_version.h | 100 +-- include/SDL_video.h | 1493 +++++++++++++++++++++++----------- include/SDL_vulkan.h | 235 ++---- 39 files changed, 7487 insertions(+), 3073 deletions(-) diff --git a/include/SDL.h b/include/SDL.h index 02203f29a..a69541679 100644 --- a/include/SDL.h +++ b/include/SDL.h @@ -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); diff --git a/include/SDL_assert.h b/include/SDL_assert.h index b1355b31b..6a5bc0006 100644 --- a/include/SDL_assert.h +++ b/include/SDL_assert.h @@ -193,88 +193,119 @@ 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. * - * 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. + * The function prototype for `handler` is: * - * Setting the callback to NULL restores SDL's original internal handler. + * ```c + * SDL_AssertState YourAssertionHandler(const SDL_AssertData* data, void* userdata) + * ``` * - * This callback is NOT reset to SDL's internal handler upon SDL_Quit()! + * where `YourAssertionHandler` is the name of your function and its + * parameters are: * - * Return SDL_AssertState value of how to handle the assertion failure. + * - `data`: a pointer to the SDL_AssertData structure corresponding to the + * current assertion + * - `userdata`: what was passed as `userdata` to SDL_SetAssertionHandler() * - * \param handler Callback function, called when an assertion fails. - * \param userdata A pointer passed to the callback as-is. + * 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. + * + * This callback is NOT reset to SDL's internal handler upon SDL_Quit()! + * + * \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` + * + * \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. + * 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. * - * \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(). + * 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(). * - * \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: + * The proper way to examine this data looks something like this: * - * - * const SDL_AssertData *item = SDL_GetAssertionReport(); - * while (item) { - * printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\\n", - * item->condition, item->function, item->filename, - * item->linenum, item->trigger_count, - * item->always_ignore ? "yes" : "no"); - * item = item->next; - * } - * + * ```c + * const SDL_AssertData *item = SDL_GetAssertionReport(); + * while (item) { + * printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\\n", + * item->condition, item->function, item->filename, + * item->linenum, item->trigger_count, + * item->always_ignore ? "yes" : "no"); + * item = item->next; + * } + * ``` * - * \return List of all assertions. - * \sa SDL_ResetAssertionReport + * \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. + * + * \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 + * \sa SDL_GetAssertionReport */ extern DECLSPEC void SDLCALL SDL_ResetAssertionReport(void); diff --git a/include/SDL_atomic.h b/include/SDL_atomic.h index 5f62bd736..df2974bbb 100644 --- a/include/SDL_atomic.h +++ b/include/SDL_atomic.h @@ -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); diff --git a/include/SDL_audio.h b/include/SDL_audio.h index 46fefe2e2..99d8a2b8b 100644 --- a/include/SDL_audio.h +++ b/include/SDL_audio.h @@ -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. * - * 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 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 - * hardware. + * Get the human-readable name of a specific audio device. * - * 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. + * 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 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 - * hardware. + * Get the preferred audio format of a specific audio device. * - * The 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. + * 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. * - * \return 0 on success, nonzero on error + * `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. + * + * \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 - * 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. + * 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. * - * \return 0 on error, a valid device ID that is >= 2 on success. + * 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. * - * SDL_OpenAudio(), unlike this function, always acts on device ID 1. + * 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. + * + * When filling in the desired audio spec structure: + * + * - `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 - * to be valid pointers. The entire data portion of the file is then loaded - * into memory and decoded if necessary. + * 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 - * freed before the function returns. + * 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 - * 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. + * 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 + * `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. + * It's necessary to use SDL_FreeWAV() to free the audio data returned in + * `audio_buf` when it is no longer used. * - * Because of the underspecification of the Waveform 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 - * loading process. + * 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 + * 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. + * 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 `src` being NULL), an appropriate error message will be set. * - * It is required that the data source supports seeking. + * It is required that the data source supports seeking. * - * Example: - * \code - * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...); - * \endcode + * Example: + * ```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 - * \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. + * 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 + * \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 - * to the desired format. + * Convert audio data to a desired audio 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. + * 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. * - * \return 0 on success or -1 if \c cvt->buf is NULL. + * 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 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. + * + * 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, @@ -687,161 +963,163 @@ extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst, Uint32 len, int volume); /** - * Queue more audio on non-callback devices. + * 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. + * 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. * - * 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. + * 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. * - * 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. + * 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. * - * You should not call SDL_LockAudio() on the device before queueing; SDL - * handles locking internally for this function. + * 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. * - * \sa SDL_GetQueuedAudioSize - * \sa SDL_ClearQueuedAudio + * \since This function is available since SDL 2.0.4. + * + * \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. + * 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. + * 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 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 - * handles locking internally for this function. + * 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. * - * \sa SDL_GetQueuedAudioSize - * \sa SDL_ClearQueuedAudio + * \since This function is available since SDL 2.0.5. + * + * \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. + * 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: + * 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. * - * 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 should not call SDL_LockAudio() on the device before querying; SDL + * handles locking internally for this function. * - * 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. + * \param dev the device ID of which we will query queued audio size + * \returns the number of bytes (not samples!) of queued audio. * - * You should not call SDL_LockAudio() on the device before querying; SDL - * handles locking internally for this function. + * \since This function is available since SDL 2.0.4. * - * \param dev The device ID of which we will query queued audio size. - * \return Number of bytes (not samples!) of queued audio. - * - * \sa SDL_QueueAudio - * \sa SDL_ClearQueuedAudio + * \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!). + * Immediately after this call, SDL_GetQueuedAudioSize() will return 0. For + * 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. + * 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. + * 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 * - * \sa SDL_QueueAudio - * \sa SDL_GetQueuedAudioSize + * \since This function is available since SDL 2.0.4. + * + * \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); diff --git a/include/SDL_blendmode.h b/include/SDL_blendmode.h index 4c45cad66..919588a70 100644 --- a/include/SDL_blendmode.h +++ b/include/SDL_blendmode.h @@ -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, diff --git a/include/SDL_clipboard.h b/include/SDL_clipboard.h index 1455348fd..79e4dcc33 100644 --- a/include/SDL_clipboard.h +++ b/include/SDL_clipboard.h @@ -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); diff --git a/include/SDL_cpuinfo.h b/include/SDL_cpuinfo.h index d3984be34..d5273113c 100644 --- a/include/SDL_cpuinfo.h +++ b/include/SDL_cpuinfo.h @@ -117,136 +117,340 @@ 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. - * For example, if the machine supports SSE only, it will return 16, but if - * it supports AVX-512F, it'll return 64 (etc). This only reports values for - * instruction sets SDL knows about, so if your SDL build doesn't have - * 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. + * aligned to be compatible with SIMD instructions on the current machine. + * For example, if the machine supports SSE only, it will return 16, but if + * it supports AVX-512F, it'll return 64 (etc). This only reports values for + * instruction sets SDL knows about, so if your SDL build doesn't have + * 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 - * the system's supported vector instructions. + * instructions. Specifically, it will be properly aligned and padded for + * the system's supported vector instructions. * * The memory returned will be padded such that it is safe to read or write - * an incomplete vector at the end of the memory block. This can be useful - * so you don't have to drop back to a scalar fallback at the end of your - * SIMD processing loop to deal with the final elements without overflowing - * the allocated buffer. + * an incomplete vector at the end of the memory block. This can be useful + * so you don't have to drop back to a scalar fallback at the end of your + * SIMD processing loop to deal with the final elements without overflowing + * the allocated buffer. * * You must free this memory with SDL_FreeSIMD(), not free() or SDL_free() - * or delete[], etc. + * or delete[], etc. * * Note that SDL will only deal with SIMD instruction sets it is aware of; - * for example, SDL 2.0.8 knows that SSE wants 16-byte vectors - * (SDL_HasSSE()), and AVX2 wants 32 bytes (SDL_HasAVX2()), but doesn't - * know that AVX-512 wants 64. To be clear: if you can't decide to use an - * instruction set with an SDL_Has*() function, don't use that instruction - * set with memory allocated through here. + * for example, SDL 2.0.8 knows that SSE wants 16-byte vectors + * (SDL_HasSSE()), and AVX2 wants 32 bytes (SDL_HasAVX2()), but doesn't + * know that AVX-512 wants 64. To be clear: if you can't decide to use an + * instruction set with an SDL_Has*() function, don't use that instruction + * 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 - * allocated block might be larger due to padding, etc. - * \return Pointer to newly-allocated block, NULL if out of memory. + * \param len The length, in bytes, of the block to allocate. The actual + * allocated block might be larger due to padding, etc. + * \returns Pointer to newly-allocated block, NULL if out of memory. * * \sa SDL_SIMDAlignment * \sa SDL_SIMDRealloc @@ -255,20 +459,20 @@ 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, - * SDL_malloc, memalign, new[], etc. + * SDL_SIMDAlloc(). It can't be used on pointers from malloc, realloc, + * SDL_malloc, memalign, new[], etc. * - * \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. - * \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. + * \param mem The pointer obtained from SDL_SIMDAlloc. This function also + * accepts NULL, at which point this function is the same as + * 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. + * \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 } diff --git a/include/SDL_error.h b/include/SDL_error.h index 144a17070..bb200c5fb 100644 --- a/include/SDL_error.h +++ b/include/SDL_error.h @@ -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. - * - * This returns a pointer to a static buffer for convenience and should not - * be called by multiple threads simultaneously. + * It is possible for multiple errors to occur before calling SDL_GetError(). + * Only the last error is returned. * - * \return a pointer to the last error message that was set + * 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. + * + * 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. - * - * \param errstr A buffer to fill with the last error message that was set + * 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 + * \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); diff --git a/include/SDL_events.h b/include/SDL_events.h index c775b1047..a2f3e3c8e 100644 --- a/include/SDL_events.h +++ b/include/SDL_events.h @@ -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 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. * - * This function is thread-safe. + * 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 - * 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. + * 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 - * are posted to the internal event queue. + * 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. + * 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); diff --git a/include/SDL_filesystem.h b/include/SDL_filesystem.h index c3b6602b8..55c93eee9 100644 --- a/include/SDL_filesystem.h +++ b/include/SDL_filesystem.h @@ -38,88 +38,102 @@ 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 - * application. This directory is unique per user, per application. + * files (preferences and save games, etc) that are specific to your + * application. This directory is unique per user, per application. * * This function will decide the appropriate location in the native filesystem, - * create the directory if necessary, and return a string of the absolute - * path to the directory in UTF-8 encoding. + * create the directory if necessary, and return a string of the absolute + * 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. - * - 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. + * - Try to use the same org string (_including case-sensitivity_) for all + * your applications that use this function. * - * This returns an absolute path in UTF-8 encoding, and is guaranteed to - * end with a path separator ('\\' on Windows, '/' most other places). + * - Always use a unique app string for each one, and make sure it never + * changes for an app once you've decided on it. * - * 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. + * - Unicode characters are legal, as long as it's UTF-8 encoded, but... * - * 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). + * - ...only use letters, numbers, and spaces. Avoid punctuation like "Game + * Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient. * - * Some platforms can't determine the pref path, and on other - * platforms, this might be meaningless. In such cases, this function will - * return NULL. + * The returned path is guaranteed to end with a path separator ('\' on + * Windows, '/' on most other platforms). * - * \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). + * The pointer returned is owned by the caller. Please call SDL_free() on + * the pointer when done with it. + * + * \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.). + * + * \since This function is available since SDL 2.0.1. * * \sa SDL_GetBasePath */ diff --git a/include/SDL_gamecontroller.h b/include/SDL_gamecontroller.h index aa4b47983..5b6461ed2 100644 --- a/include/SDL_gamecontroller.h +++ b/include/SDL_gamecontroller.h @@ -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. - * - * \return number of mappings added, -1 on error + * You can call this function several times, if needed, to load different + * database files. + * + * 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,161 +161,338 @@ 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. + * 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. + * 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. + * Get the mapping of a game controller. * - * \return the mapping string. Must be freed with SDL_free(). Returns NULL if no mapping is available + * 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 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. + * Open a game controller for use. * - * \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. + * 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. + * 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. + * 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); /** - * Get the serial number of an opened controller, if available. + * Get the serial number of an opened controller, if available. * - * Returns the serial number of the controller, or NULL if it is not 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. + * 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,35 +519,81 @@ 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); /** - * Get the current state of an axis control on a game controller. + * 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 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,150 +629,207 @@ 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); /** - * Get the current state of a button on a game controller. + * 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); /** - * Get the number of touchpads on a game controller. + * Get the number of touchpads on a game controller. */ extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpads(SDL_GameController *gamecontroller); /** - * Get the number of supported simultaneous fingers on a touchpad on a game controller. + * Get the number of supported simultaneous fingers on a touchpad on a game controller. */ extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpadFingers(SDL_GameController *gamecontroller, int touchpad); /** - * Get the current state of a finger on a touchpad on a game controller. + * Get the current state of a finger on a touchpad on a game controller. */ extern DECLSPEC int SDLCALL SDL_GameControllerGetTouchpadFinger(SDL_GameController *gamecontroller, int touchpad, int finger, Uint8 *state, float *x, float *y, float *pressure); /** - * Return whether a game controller has a particular sensor. + * Return whether a game controller has a particular sensor. * - * \param gamecontroller The controller to query - * \param type The type of sensor to query + * \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 + * \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 + * \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); /** - * Get the current state of a game controller sensor. + * Get the current state of a game controller sensor. * - * The number of values and interpretation of the data is sensor dependent. - * See SDL_sensor.h for the details for each type of sensor. + * The number of values and interpretation of the data is sensor dependent. + * See SDL_sensor.h for the details for each type of sensor. * - * \param gamecontroller The controller to query - * \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. + * \param gamecontroller The controller to query + * \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. * - * \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 duration_ms The duration of the rumble effect, in milliseconds + * Each call to this function cancels any previous rumble effect, and calling + * it with 0 intensity stops any rumbling. * - * \return 0, or -1 if rumble isn't supported on this controller + * \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 duration_ms The duration of the rumble effect, in milliseconds + * \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. * - * \param gamecontroller The controller 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 duration_ms The duration of the rumble effect, in milliseconds + * Each call to this function cancels any previous trigger rumble effect, and + * calling it with 0 intensity stops any rumbling. * - * \return 0, or -1 if rumble isn't supported on this controller + * 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 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 + * + * \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 + * \param gamecontroller The controller to query + * \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 + * \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 + * \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 } diff --git a/include/SDL_gesture.h b/include/SDL_gesture.h index a7382bc68..530b3d577 100644 --- a/include/SDL_gesture.h +++ b/include/SDL_gesture.h @@ -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 } diff --git a/include/SDL_haptic.h b/include/SDL_haptic.h index 29f45066a..424cbd111 100644 --- a/include/SDL_haptic.h +++ b/include/SDL_haptic.h @@ -821,418 +821,492 @@ 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. * - * \sa SDL_NumHaptics + * \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. + * 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(). + * 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(). * - * \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. * - * \sa SDL_HapticIndex - * \sa SDL_HapticOpenFromMouse - * \sa SDL_HapticOpenFromJoystick - * \sa SDL_HapticClose - * \sa SDL_HapticSetGain - * \sa SDL_HapticSetAutocenter - * \sa SDL_HapticPause - * \sa SDL_HapticStopAll + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticClose + * \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. * - * \sa SDL_HapticOpen - * \sa SDL_HapticIndex + * \since This function is available since SDL 2.0.0. + * + * \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. * - * \sa SDL_HapticOpen - * \sa SDL_HapticOpened + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticOpen + * \sa SDL_HapticOpened */ 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. * - * \sa SDL_HapticOpenFromMouse + * \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. * - * \sa SDL_MouseIsHaptic - * \sa SDL_HapticOpen + * \since This function is available since SDL 2.0.0. + * + * \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. * - * \sa SDL_HapticOpenFromJoystick + * \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. + * 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 - * 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. + * 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. * - * \sa SDL_HapticOpen - * \sa SDL_HapticClose + * \since This function is available since SDL 2.0.0. + * + * \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(). + * 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. * - * \sa SDL_HapticNumEffectsPlaying - * \sa SDL_HapticQuery + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticNumEffectsPlaying + * \sa SDL_HapticQuery */ 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. + * This is not supported on all platforms, but will always return a value. * - * \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. * - * \sa SDL_HapticNumEffects - * \sa SDL_HapticQuery + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticNumEffects + * \sa SDL_HapticQuery */ 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_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. * - * \sa SDL_HapticQuery - * \sa SDL_HapticNewEffect + * \since This function is available since SDL 2.0.0. + * + * \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_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 - * running SDL_HapticUpdateEffect(). + * Can be used dynamically, although behavior when dynamically changing + * 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. * - * \sa SDL_HapticNewEffect - * \sa SDL_HapticRunEffect - * \sa SDL_HapticDestroyEffect + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticDestroyEffect + * \sa SDL_HapticNewEffect + * \sa SDL_HapticRunEffect */ 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. * - * \sa SDL_HapticStopEffect - * \sa SDL_HapticDestroyEffect - * \sa SDL_HapticGetEffectStatus + * \since This function is available since SDL 2.0.0. + * + * \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_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. + * 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 * - * \sa SDL_HapticNewEffect + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticNewEffect */ 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. * - * \sa SDL_HapticRunEffect - * \sa SDL_HapticStopEffect + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticRunEffect + * \sa SDL_HapticStopEffect */ 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 - * maximum. + * 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 + * 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. * - * \sa SDL_HapticQuery + * \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. + * 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 + * \sa SDL_HapticQuery */ 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 - * SDL_HapticUnpause() to resume playback. + * 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 + * \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(). + * 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 + * \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 - * \sa SDL_HapticRumbleStop + * \sa SDL_HapticRumbleInit + * \sa SDL_HapticRumblePlay + * \sa SDL_HapticRumbleStop */ 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. * - * \sa SDL_HapticOpen - * \sa SDL_HapticRumbleSupported - * \sa SDL_HapticRumblePlay - * \sa SDL_HapticRumbleStop + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_HapticOpen + * \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_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_HapticRumbleInit + * \sa SDL_HapticRumblePlay + * \sa SDL_HapticRumbleSupported */ extern DECLSPEC int SDLCALL SDL_HapticRumbleStop(SDL_Haptic * haptic); diff --git a/include/SDL_hints.h b/include/SDL_hints.h index 097e78699..90e45de98 100644 --- a/include/SDL_hints.h +++ b/include/SDL_hints.h @@ -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); diff --git a/include/SDL_joystick.h b/include/SDL_joystick.h index 259204002..cfdbcd8db 100644 --- a/include/SDL_joystick.h +++ b/include/SDL_joystick.h @@ -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. + * Get the implementation dependent name of a joystick. + * + * 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 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. + * 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. + * 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. + * 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. + * 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. + * 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. + * Open a joystick for use. * - * \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,166 +303,344 @@ 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. + * 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. + * 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. + * 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); /** - * Get the serial number of an opened joystick, if available. + * Get the serial number of an opened joystick, if available. * - * Returns the serial number of the joystick, or NULL if it is not 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. + * 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. + * 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. + * 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. + * 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. + * 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. + * 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); /** - * Enable/disable joystick event polling. + * 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. + * If joystick events are disabled, you must call SDL_JoystickUpdate() + * 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); #define SDL_JOYSTICK_AXIS_MAX 32767 #define SDL_JOYSTICK_AXIS_MIN -32768 /** - * Get the current state of an axis control on a joystick. + * 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); /** - * Get the initial state of an axis control on a joystick. + * Get the initial state of an axis control on a joystick. * - * The state is a value ranging from -32768 to 32767. + * The state is a value ranging from -32768 to 32767. * - * The axis indices start at index 0. + * The axis indices start at index 0. * - * \return SDL_TRUE if this axis has any initial value, or SDL_FALSE if not. + * \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, int axis, Sint16 *state); @@ -395,96 +661,153 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAxisInitialState(SDL_Joystick *j /* @} */ /** - * Get the current state of a POV hat on a joystick. + * 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); /** - * Get the ball axis change since the last poll. + * 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); /** - * Get the current state of a button on a 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. * - * \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 duration_ms The duration of the rumble effect, in milliseconds + * Each call to this function cancels any previous rumble effect, and calling + * it with 0 intensity stops any rumbling. * - * \return 0, or -1 if rumble isn't supported on this joystick + * \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 duration_ms The duration of the rumble effect, in milliseconds + * + * \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. + * Start a rumble effect in the joystick's triggers * - * \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 duration_ms The duration of the rumble effect, in milliseconds + * Each call to this function cancels any previous trigger rumble effect, + * and calling it with 0 intensity stops any rumbling. * - * \return 0, or -1 if trigger rumble isn't supported on this joystick + * 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 duration_ms The duration of the rumble effect, in milliseconds + * + * \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. * - * \param joystick The joystick to query + * An example of a joystick LED is the light on the back of a PlayStation 4's + * DualShock 4 controller. * - * \return SDL_TRUE, or SDL_FALSE if this joystick does not have a modifiable LED + * \param joystick The joystick to query + * \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. + * Update a joystick's LED color. * - * \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 + * An example of a joystick LED is the light on the back of a PlayStation 4's + * DualShock 4 controller. * - * \return 0, or -1 if this joystick does not have a modifiable LED + * \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 + * + * \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(). + * 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); diff --git a/include/SDL_keyboard.h b/include/SDL_keyboard.h index 9eaeb2838..3b14acbf2 100644 --- a/include/SDL_keyboard.h +++ b/include/SDL_keyboard.h @@ -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(" 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); diff --git a/include/SDL_loadso.h b/include/SDL_loadso.h index 80379bccb..e6a33a0a2 100644 --- a/include/SDL_loadso.h +++ b/include/SDL_loadso.h @@ -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. + * 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); diff --git a/include/SDL_log.h b/include/SDL_log.h index f038e20cc..19b437af6 100644 --- a/include/SDL_log.h +++ b/include/SDL_log.h @@ -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); diff --git a/include/SDL_main.h b/include/SDL_main.h index 2d7c90733..020945181 100644 --- a/include/SDL_main.h +++ b/include/SDL_main.h @@ -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,12 +163,12 @@ 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(). - * \return the return value from mainFunction + * \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(), an SDL_main_func + * \return the return value from mainFunction */ extern DECLSPEC int SDLCALL SDL_UIKitRunApp(int argc, char *argv[], SDL_main_func mainFunction); diff --git a/include/SDL_messagebox.h b/include/SDL_messagebox.h index 8caecc5b1..02f546902 100644 --- a/include/SDL_messagebox.h +++ b/include/SDL_messagebox.h @@ -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,32 +105,79 @@ 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. + * 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. * - * \note 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 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 - * \param title UTF-8 title text - * \param message UTF-8 message text - * \param window The parent window, or NULL for no parent + * If your needs aren't complex, this function is preferred over + * SDL_ShowMessageBox. * - * \return 0 on success, -1 on error + * `flags` may be any of the following: * - * \sa SDL_ShowMessageBox + * - `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 + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_ShowMessageBox */ extern DECLSPEC int SDLCALL SDL_ShowSimpleMessageBox(Uint32 flags, const char *title, const char *message, SDL_Window *window); diff --git a/include/SDL_misc.h b/include/SDL_misc.h index 5eac321bf..7cd4d5788 100644 --- a/include/SDL_misc.h +++ b/include/SDL_misc.h @@ -38,29 +38,33 @@ 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 - * or grabbing input at the time). On mobile devices, your app will likely - * move to the background or your process might be paused. Any given platform - * may or may not handle a given URL. + * may lose focus (and may or may not lose focus if your game was fullscreen + * or grabbing input at the time). On mobile devices, your app will likely + * move to the background or your process might be paused. Any given platform + * may or may not handle a given URL. * * 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). + * 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). * * All this to say: this function can be useful, but you should definitely - * test it on every platform you target. + * 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); diff --git a/include/SDL_mouse.h b/include/SDL_mouse.h index 32303076c..3bfc4d195 100644 --- a/include/SDL_mouse.h +++ b/include/SDL_mouse.h @@ -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. For that, you should + * probably use SDL_SetRelativeMouseMode() or SDL_SetWindowGrab(), depending + * on your goals. * - * 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. + * 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. * - * 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. + * While capturing is enabled, the current window will have the + * `SDL_WINDOW_MOUSE_CAPTURE` flag set. * - * While capturing is enabled, the current window will have the - * SDL_WINDOW_MOUSE_CAPTURE flag set. + * \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. * - * \return 0 on success, or -1 if not supported. + * \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 - * mask (in MSB format). + * 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 is created in black and white according to the following: - * - * - * - * - * - * - *
data mask resulting pixel on screen
0 1 White
1 1 Black
0 0 Transparent
1 0 Inverted color if possible, black - * if not.
+ * The cursor width (`w`) must be a multiple of 8 bits. * - * \sa SDL_FreeCursor() + * The cursor is created in black and white according to the following: + * + * - 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,60 +293,115 @@ 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 + * Used as a mask when testing buttons in buttonstate. + * + * - Button 1: Left mouse button + * - Button 2: Middle mouse button + * - Button 3: Right mouse button */ #define SDL_BUTTON(X) (1 << ((X)-1)) #define SDL_BUTTON_LEFT 1 @@ -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 } diff --git a/include/SDL_mutex.h b/include/SDL_mutex.h index f49b6477d..3b2bf1941 100644 --- a/include/SDL_mutex.h +++ b/include/SDL_mutex.h @@ -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. + * Lock the mutex. * - * \return 0, or -1 on error. + * 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. + * 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. + * 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); @@ -167,72 +312,112 @@ struct SDL_cond; typedef struct SDL_cond SDL_cond; /** - * Create a condition variable. + * 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. + * 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. + * 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. + * 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); diff --git a/include/SDL_pixels.h b/include/SDL_pixels.h index e1aedf2ab..a6d464c71 100644 --- a/include/SDL_pixels.h +++ b/include/SDL_pixels.h @@ -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,84 +398,193 @@ 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. * - * \sa SDL_MapRGBA + * 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. * - * \sa SDL_MapRGB + * 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, Uint8 r, Uint8 g, Uint8 b, Uint8 a); /** - * \brief Get the RGB components from a pixel of the specified format. + * Get RGB values from a pixel in the specified format. * - * \sa SDL_GetRGBA + * 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. * - * \sa SDL_GetRGB + * 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); diff --git a/include/SDL_platform.h b/include/SDL_platform.h index 428e42712..ea3aadd6a 100644 --- a/include/SDL_platform.h +++ b/include/SDL_platform.h @@ -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); diff --git a/include/SDL_power.h b/include/SDL_power.h index cc6160ed1..872be1840 100644 --- a/include/SDL_power.h +++ b/include/SDL_power.h @@ -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); diff --git a/include/SDL_rect.h b/include/SDL_rect.h index b1897e525..ae47298d2 100644 --- a/include/SDL_rect.h +++ b/include/SDL_rect.h @@ -40,10 +40,10 @@ extern "C" { #endif /** - * \brief The structure that defines a point (integer) + * The structure that defines a point (integer) * - * \sa SDL_EnclosePoints - * \sa SDL_PointInRect + * \sa SDL_EnclosePoints + * \sa SDL_PointInRect */ typedef struct SDL_Point { @@ -52,10 +52,10 @@ 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 + * \sa SDL_EnclosePoints + * \sa SDL_PointInRect */ typedef struct SDL_FPoint { @@ -65,14 +65,14 @@ 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 - * \sa SDL_HasIntersection - * \sa SDL_IntersectRect - * \sa SDL_UnionRect - * \sa SDL_EnclosePoints + * \sa SDL_RectEmpty + * \sa SDL_RectEquals + * \sa SDL_HasIntersection + * \sa SDL_IntersectRect + * \sa SDL_UnionRect + * \sa SDL_EnclosePoints */ typedef struct SDL_Rect { @@ -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, diff --git a/include/SDL_render.h b/include/SDL_render.h index 980109afb..21ce63a83 100644 --- a/include/SDL_render.h +++ b/include/SDL_render.h @@ -59,7 +59,7 @@ extern "C" { #endif /** - * \brief Flags used when creating a rendering context + * Flags used when creating a rendering context */ typedef enum { @@ -73,7 +73,7 @@ typedef enum } SDL_RendererFlags; /** - * \brief Information on the capabilities of a render driver or context. + * Information on the capabilities of a render driver or context. */ typedef struct SDL_RendererInfo { @@ -86,7 +86,7 @@ typedef struct SDL_RendererInfo } SDL_RendererInfo; /** - * \brief The scaling mode for a texture. + * The scaling mode for a texture. */ typedef enum { @@ -96,7 +96,7 @@ typedef enum } SDL_ScaleMode; /** - * \brief The access pattern allowed for a texture. + * The access pattern allowed for a texture. */ typedef enum { @@ -106,7 +106,7 @@ typedef enum } SDL_TextureAccess; /** - * \brief The texture channel modulation used in SDL_RenderCopy(). + * The texture channel modulation used in SDL_RenderCopy(). */ typedef enum { @@ -116,7 +116,7 @@ typedef enum } SDL_TextureModulate; /** - * \brief Flip constants for SDL_RenderCopyEx + * Flip constants for SDL_RenderCopyEx */ typedef enum { @@ -126,13 +126,13 @@ typedef enum } SDL_RendererFlip; /** - * \brief A structure representing rendering state + * A structure representing rendering state */ struct SDL_Renderer; typedef struct SDL_Renderer SDL_Renderer; /** - * \brief An efficient driver-specific representation of pixel data + * An efficient driver-specific representation of pixel data */ struct SDL_Texture; typedef struct SDL_Texture SDL_Texture; @@ -141,43 +141,53 @@ typedef struct SDL_Texture SDL_Texture; /* Function prototypes */ /** - * \brief Get the number of 2D rendering drivers available for the current - * display. + * Get the number of 2D rendering drivers available for the current display. * - * A render driver is a set of code that handles rendering and texture - * management on a particular display. Normally there is only one, but - * some drivers may have several available with different capabilities. + * A render driver is a set of code that handles rendering and texture + * management on a particular display. Normally there is only one, but some + * drivers may have several available with different capabilities. * - * \sa SDL_GetRenderDriverInfo() - * \sa SDL_CreateRenderer() + * There may be none if SDL was compiled without render support. + * + * \returns a number >= 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_CreateRenderer + * \sa SDL_GetRenderDriverInfo */ extern DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void); /** - * \brief Get information about a specific 2D rendering driver for the current - * display. + * Get info about a specific 2D rendering driver for the current display. * - * \param index The index of the driver to query information about. - * \param info A pointer to an SDL_RendererInfo struct to be filled with - * information on the rendering driver. + * \param index the index of the driver to query information about + * \param info an SDL_RendererInfo structure to be filled with information on + * the rendering driver + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. * - * \return 0 on success, -1 if the index was out of range. - * - * \sa SDL_CreateRenderer() + * \sa SDL_CreateRenderer + * \sa SDL_GetNumRenderDrivers */ extern DECLSPEC int SDLCALL SDL_GetRenderDriverInfo(int index, SDL_RendererInfo * info); /** - * \brief Create a window and default renderer + * Create a window and default renderer. * - * \param width The width of the window - * \param height The height of the window - * \param window_flags The flags used to create the window - * \param window A pointer filled with the window, or NULL on error - * \param renderer A pointer filled with the renderer, or NULL on error + * \param width the width of the window + * \param height the height of the window + * \param window_flags the flags used to create the window (see + * SDL_CreateWindow()) + * \param window a pointer filled with the window, or NULL on error + * \param renderer a pointer filled with the renderer, or NULL on error + * \returns 0 on success, or -1 on error; call SDL_GetError() for more + * information. * - * \return 0 on success, or -1 on error + * \sa SDL_CreateRenderer + * \sa SDL_CreateWindow */ extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer( int width, int height, Uint32 window_flags, @@ -185,69 +195,106 @@ extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer( /** - * \brief Create a 2D rendering context for a window. + * Create a 2D rendering context for a window. * - * \param window The window where rendering is displayed. - * \param index The index of the rendering driver to initialize, or -1 to - * initialize the first one supporting the requested flags. - * \param flags ::SDL_RendererFlags. + * \param window the window where rendering is displayed + * \param index the index of the rendering driver to initialize, or -1 to + * initialize the first one supporting the requested flags + * \param flags 0, or one or more SDL_RendererFlags OR'd together + * \returns a valid rendering context or NULL if there was an error; call + * SDL_GetError() for more information. * - * \return A valid rendering context or NULL if there was an error. - * - * \sa SDL_CreateSoftwareRenderer() - * \sa SDL_GetRendererInfo() - * \sa SDL_DestroyRenderer() + * \sa SDL_CreateSoftwareRenderer + * \sa SDL_DestroyRenderer + * \sa SDL_GetNumRenderDrivers + * \sa SDL_GetRendererInfo */ extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window * window, int index, Uint32 flags); /** - * \brief Create a 2D software rendering context for a surface. + * Create a 2D software rendering context for a surface. * - * \param surface The surface where rendering is done. + * Two other API which can be used to create SDL_Renderer: + * SDL_CreateRenderer() and SDL_CreateWindowAndRenderer(). These can _also_ + * create a software renderer, but they are intended to be used with an + * SDL_Window as the final destination and not an SDL_Surface. * - * \return A valid rendering context or NULL if there was an error. + * \param surface the SDL_Surface structure representing the surface where + * rendering is done + * \returns a valid rendering context or NULL if there was an error; call + * SDL_GetError() for more information. * - * \sa SDL_CreateRenderer() - * \sa SDL_DestroyRenderer() + * \sa SDL_CreateRenderer + * \sa SDL_CreateWindowRenderer + * \sa SDL_DestroyRenderer */ extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateSoftwareRenderer(SDL_Surface * surface); /** - * \brief Get the renderer associated with a window. + * Get the renderer associated with a window. + * + * \param window the window to query + * \returns the rendering context on success or NULL on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_CreateRenderer */ extern DECLSPEC SDL_Renderer * SDLCALL SDL_GetRenderer(SDL_Window * window); /** - * \brief Get information about a rendering context. + * Get information about a rendering context. + * + * \param renderer the rendering context + * \param info an SDL_RendererInfo structure filled with information about the + * current renderer + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_CreateRenderer */ extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_Renderer * renderer, SDL_RendererInfo * info); /** - * \brief Get the output size in pixels of a rendering context. + * Get the output size in pixels of a rendering context. + * + * Due to high-dpi displays, you might end up with a rendering context that + * has more pixels than the window that contains it, so use this instead of + * SDL_GetWindowSize() to decide how much drawing area you have. + * + * \param renderer the rendering context + * \param w an int filled with the width + * \param h an int filled with the height + * \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_GetRenderer */ extern DECLSPEC int SDLCALL SDL_GetRendererOutputSize(SDL_Renderer * renderer, int *w, int *h); /** - * \brief Create a texture for a rendering context. + * Create a texture for a rendering context. * - * \param renderer The renderer. - * \param format The format of the texture. - * \param access One of the enumerated values in ::SDL_TextureAccess. - * \param w The width of the texture in pixels. - * \param h The height of the texture in pixels. + * You can set the texture scaling method by setting + * `SDL_HINT_RENDER_SCALE_QUALITY` before creating the texture. * - * \return The created texture is returned, or NULL if no rendering context was - * active, the format was unsupported, or the width or height were out - * of range. + * \param renderer the rendering context + * \param format one of the enumerated values in SDL_PixelFormatEnum + * \param access one of the enumerated values in SDL_TextureAccess + * \param w the width of the texture in pixels + * \param h the height of the texture in pixels + * \returns a pointer to the created texture or NULL if no rendering context + * was active, the format was unsupported, or the width or height + * were out of range; call SDL_GetError() for more information. * - * \note The contents of the texture are not defined at creation. - * - * \sa SDL_QueryTexture() - * \sa SDL_UpdateTexture() - * \sa SDL_DestroyTexture() + * \sa SDL_CreateTextureFromSurface + * \sa SDL_DestroyTexture + * \sa SDL_QueryTexture + * \sa SDL_UpdateTexture */ extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTexture(SDL_Renderer * renderer, Uint32 format, @@ -255,194 +302,243 @@ extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTexture(SDL_Renderer * renderer, int h); /** - * \brief Create a texture from an existing surface. + * Create a texture from an existing surface. * - * \param renderer The renderer. - * \param surface The surface containing pixel data used to fill the texture. + * The surface is not modified or freed by this function. * - * \return The created texture is returned, or NULL on error. + * The SDL_TextureAccess hint for the created texture is + * `SDL_TEXTUREACCESS_STATIC`. * - * \note The surface is not modified or freed by this function. + * The pixel format of the created texture may be different from the pixel + * format of the surface. Use SDL_QueryTexture() to query the pixel format of + * the texture. * - * \sa SDL_QueryTexture() - * \sa SDL_DestroyTexture() + * \param renderer the rendering context + * \param surface the SDL_Surface structure containing pixel data used to fill + * the texture + * \returns the created texture or NULL on failure; call SDL_GetError() for + * more information. + * + * \sa SDL_CreateTexture + * \sa SDL_DestroyTexture + * \sa SDL_QueryTexture */ extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer * renderer, SDL_Surface * surface); /** - * \brief Query the attributes of a texture + * Query the attributes of a texture. * - * \param texture A texture to be queried. - * \param format A pointer filled in with the raw format of the texture. The - * actual format may differ, but pixel transfers will use this - * format. - * \param access A pointer filled in with the actual access to the texture. - * \param w A pointer filled in with the width of the texture in pixels. - * \param h A pointer filled in with the height of the texture in pixels. + * \param texture the texture to query + * \param format a pointer filled in with the raw format of the texture; the + * actual format may differ, but pixel transfers will use this + * format (one of the SDL_PixelFormatEnum values) + * \param access a pointer filled in with the actual access to the texture + * (one of the SDL_TextureAccess values) + * \param w a pointer filled in with the width of the texture in pixels + * \param h a pointer filled in with the height of the texture in pixels + * \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 texture is not valid. + * \sa SDL_CreateTexture */ extern DECLSPEC int SDLCALL SDL_QueryTexture(SDL_Texture * texture, Uint32 * format, int *access, int *w, int *h); /** - * \brief Set an additional color value used in render copy operations. + * Set an additional color value multiplied into render copy operations. * - * \param texture The texture to update. - * \param r The red color value multiplied into copy operations. - * \param g The green color value multiplied into copy operations. - * \param b The blue color value multiplied into copy operations. + * When this texture is rendered, during the copy 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 texture is not valid or color modulation - * is not supported. + * `srcC = srcC * (color / 255)` * - * \sa SDL_GetTextureColorMod() + * Color modulation is not always supported by the renderer; it will return -1 + * if color modulation is not supported. + * + * \param texture the texture to update + * \param r the red color value multiplied into copy operations + * \param g the green color value multiplied into copy operations + * \param b the blue color value multiplied into copy operations + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_GetTextureColorMod + * \sa SDL_SetTextureAlphaMod */ extern DECLSPEC int SDLCALL SDL_SetTextureColorMod(SDL_Texture * texture, Uint8 r, Uint8 g, Uint8 b); /** - * \brief Get the additional color value used in render copy operations. + * Get the additional color value multiplied into render copy operations. * - * \param texture The texture 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 texture the texture 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 texture is not valid. - * - * \sa SDL_SetTextureColorMod() + * \sa SDL_GetTextureAlphaMod + * \sa SDL_SetTextureColorMod */ extern DECLSPEC int SDLCALL SDL_GetTextureColorMod(SDL_Texture * texture, Uint8 * r, Uint8 * g, Uint8 * b); /** - * \brief Set an additional alpha value used in render copy operations. + * Set an additional alpha value multiplied into render copy operations. * - * \param texture The texture to update. - * \param alpha The alpha value multiplied into copy operations. + * When this texture is rendered, during the copy operation the source alpha + * value is modulated by this alpha value according to the following formula: * - * \return 0 on success, or -1 if the texture is not valid or alpha modulation - * is not supported. + * `srcA = srcA * (alpha / 255)` * - * \sa SDL_GetTextureAlphaMod() + * Alpha modulation is not always supported by the renderer; it will return -1 + * if alpha modulation is not supported. + * + * \param texture the texture to update + * \param alpha the source alpha value multiplied into copy operations + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_GetTextureAlphaMod + * \sa SDL_SetTextureColorMod */ extern DECLSPEC int SDLCALL SDL_SetTextureAlphaMod(SDL_Texture * texture, Uint8 alpha); /** - * \brief Get the additional alpha value used in render copy operations. + * Get the additional alpha value multiplied into render + * copy operations. * - * \param texture The texture to query. - * \param alpha A pointer filled in with the current alpha value. + * \param texture the texture 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 texture is not valid. - * - * \sa SDL_SetTextureAlphaMod() + * \sa SDL_GetTextureColorMod + * \sa SDL_SetTextureAlphaMod */ extern DECLSPEC int SDLCALL SDL_GetTextureAlphaMod(SDL_Texture * texture, Uint8 * alpha); /** - * \brief Set the blend mode used for texture copy operations. + * Set the blend mode for a texture, used by + * SDL_RenderCopy(). * - * \param texture The texture to update. - * \param blendMode ::SDL_BlendMode to use for texture blending. + * If the blend mode is not supported, the closest supported mode is chosen + * and this function returns -1. * - * \return 0 on success, or -1 if the texture is not valid or the blend mode is - * not supported. + * \param texture the texture to update + * \param blendMode the SDL_BlendMode to use for texture blending + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. * - * \note If the blend mode is not supported, the closest supported mode is - * chosen. - * - * \sa SDL_GetTextureBlendMode() + * \sa SDL_GetTextureBlendMode + * \sa SDL_RenderCopy */ extern DECLSPEC int SDLCALL SDL_SetTextureBlendMode(SDL_Texture * texture, SDL_BlendMode blendMode); /** - * \brief Get the blend mode used for texture copy operations. + * Get the blend mode used for texture copy operations. * - * \param texture The texture to query. - * \param blendMode A pointer filled in with the current blend mode. + * \param texture the texture 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 texture is not valid. - * - * \sa SDL_SetTextureBlendMode() + * \sa SDL_SetTextureBlendMode */ extern DECLSPEC int SDLCALL SDL_GetTextureBlendMode(SDL_Texture * texture, SDL_BlendMode *blendMode); /** - * \brief Set the scale mode used for texture scale operations. + * Set the scale mode used for texture scale operations. * - * \param texture The texture to update. - * \param scaleMode ::SDL_ScaleMode to use for texture scaling. + * If the scale mode is not supported, the closest supported mode is chosen. * - * \return 0 on success, or -1 if the texture is not valid. + * \param texture The texture to update. + * \param scaleMode the SDL_ScaleMode to use for texture scaling. + * \returns 0 on success, or -1 if the texture is not valid. * - * \note If the scale mode is not supported, the closest supported mode is - * chosen. - * - * \sa SDL_GetTextureScaleMode() + * \sa SDL_GetTextureScaleMode() */ extern DECLSPEC int SDLCALL SDL_SetTextureScaleMode(SDL_Texture * texture, SDL_ScaleMode scaleMode); /** - * \brief Get the scale mode used for texture scale operations. + * Get the scale mode used for texture scale operations. * - * \param texture The texture to query. - * \param scaleMode A pointer filled in with the current scale mode. + * \param texture the texture to query. + * \param scaleMode a pointer filled in with the current scale mode. + * \return 0 on success, or -1 if the texture is not valid. * - * \return 0 on success, or -1 if the texture is not valid. - * - * \sa SDL_SetTextureScaleMode() + * \sa SDL_SetTextureScaleMode() */ extern DECLSPEC int SDLCALL SDL_GetTextureScaleMode(SDL_Texture * texture, SDL_ScaleMode *scaleMode); /** - * \brief Update the given texture rectangle with new pixel data. + * Update the given texture rectangle with new pixel data. * - * \param texture The texture to update - * \param rect A pointer to the rectangle of pixels to update, or NULL to - * update the entire texture. - * \param pixels The raw pixel data in the format of the texture. - * \param pitch The number of bytes in a row of pixel data, including padding between lines. + * The pixel data must be in the pixel format of the texture. Use + * SDL_QueryTexture() to query the pixel format of the texture. * - * The pixel data must be in the format of the texture. The pixel format can be - * queried with SDL_QueryTexture. + * This is a fairly slow function, intended for use with static textures that + * do not change often. * - * \return 0 on success, or -1 if the texture is not valid. + * If the texture is intended to be updated often, it is preferred to create + * the texture as streaming and use the locking functions referenced below. + * While this function will work with streaming textures, for optimization + * reasons you may not get the pixels back if you lock the texture afterward. * - * \note This is a fairly slow function. + * \param texture the texture to update + * \param rect an SDL_Rect structure representing the area to update, or NULL + * to update the entire texture + * \param pixels the raw pixel data in the format of the texture + * \param pitch the number of bytes in a row of pixel data, including padding + * between lines + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_CreateTexture + * \sa SDL_LockTexture + * \sa SDL_UnlockTexture */ extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_Texture * texture, const SDL_Rect * rect, const void *pixels, int pitch); /** - * \brief Update a rectangle within a planar YV12 or IYUV texture with new pixel data. + * Update a rectangle within a planar YV12 or IYUV + * texture with new pixel data. * - * \param texture The texture to update - * \param rect A pointer to the rectangle of pixels to update, or NULL to - * update the entire texture. - * \param Yplane The raw pixel data for the Y plane. - * \param Ypitch The number of bytes between rows of pixel data for the Y plane. - * \param Uplane The raw pixel data for the U plane. - * \param Upitch The number of bytes between rows of pixel data for the U plane. - * \param Vplane The raw pixel data for the V plane. - * \param Vpitch The number of bytes between rows of pixel data for the V plane. + * You can use SDL_UpdateTexture() as long as your pixel data is a contiguous + * block of Y and U/V planes in the proper order, but this function is + * available if your pixel data is not contiguous. * - * \return 0 on success, or -1 if the texture is not valid. + * \param texture the texture to update + * \param rect a pointer to the rectangle of pixels to update, or NULL to + * update the entire texture + * \param Yplane the raw pixel data for the Y plane + * \param Ypitch the number of bytes between rows of pixel data for the Y + * plane + * \param Uplane the raw pixel data for the U plane + * \param Upitch the number of bytes between rows of pixel data for the U + * plane + * \param Vplane the raw pixel data for the V plane + * \param Vpitch the number of bytes between rows of pixel data for the V + * plane + * \returns 0 on success or -1 if the texture is not valid; call + * SDL_GetError() for more information. * - * \note You can use SDL_UpdateTexture() as long as your pixel data is - * a contiguous block of Y and U/V planes in the proper order, but - * this function is available if your pixel data is not contiguous. + * \since This function is available since SDL 2.0.1. + * + * \sa SDL_UpdateTexture */ extern DECLSPEC int SDLCALL SDL_UpdateYUVTexture(SDL_Texture * texture, const SDL_Rect * rect, @@ -451,21 +547,20 @@ extern DECLSPEC int SDLCALL SDL_UpdateYUVTexture(SDL_Texture * texture, const Uint8 *Vplane, int Vpitch); /** - * \brief Update a rectangle within a planar NV12 or NV21 texture with new pixel data. + * Update a rectangle within a planar NV12 or NV21 texture with new pixels. * - * \param texture The texture to update - * \param rect A pointer to the rectangle of pixels to update, or NULL to - * update the entire texture. - * \param Yplane The raw pixel data for the Y plane. - * \param Ypitch The number of bytes between rows of pixel data for the Y plane. - * \param UVplane The raw pixel data for the UV plane. - * \param UVpitch The number of bytes between rows of pixel data for the UV plane. + * You can use SDL_UpdateTexture() as long as your pixel data is a contiguous + * block of NV12/21 planes in the proper order, but this function is available + * if your pixel data is not contiguous. * - * \return 0 on success, or -1 if the texture is not valid. - * - * \note You can use SDL_UpdateTexture() as long as your pixel data is - * a contiguous block of NV12/21 planes in the proper order, but - * this function is available if your pixel data is not contiguous. + * \param texture the texture to update + * \param rect a pointer to the rectangle of pixels to update, or NULL to + * update the entire texture. + * \param Yplane the raw pixel data for the Y plane. + * \param Ypitch the number of bytes between rows of pixel data for the Y plane. + * \param UVplane the raw pixel data for the UV plane. + * \param UVpitch the number of bytes between rows of pixel data for the UV plane. + * \return 0 on success, or -1 if the texture is not valid. */ extern DECLSPEC int SDLCALL SDL_UpdateNVTexture(SDL_Texture * texture, const SDL_Rect * rect, @@ -473,421 +568,662 @@ extern DECLSPEC int SDLCALL SDL_UpdateNVTexture(SDL_Texture * texture, const Uint8 *UVplane, int UVpitch); /** - * \brief Lock a portion of the texture for write-only pixel access. + * Lock a portion of the texture for **write-only** pixel access. * - * \param texture The texture to lock for access, which was created with - * ::SDL_TEXTUREACCESS_STREAMING. - * \param rect A pointer to the rectangle to lock for access. If the rect - * is NULL, the entire texture will be locked. - * \param pixels This is filled in with a pointer to the locked pixels, - * appropriately offset by the locked area. - * \param pitch This is filled in with the pitch of the locked pixels. + * As an optimization, the pixels made available for editing don't necessarily + * contain the old texture data. This is a write-only operation, and if you + * need to keep a copy of the texture data you should do that at the + * application level. * - * \return 0 on success, or -1 if the texture is not valid or was not created with ::SDL_TEXTUREACCESS_STREAMING. + * You must use SDL_UnlockTexture() to unlock the pixels and apply any + * changes. * - * \sa SDL_UnlockTexture() + * \param texture the texture to lock for access, which was created with + * `SDL_TEXTUREACCESS_STREAMING` + * \param rect an SDL_Rect structure representing the area to lock for access; + * NULL to lock the entire texture + * \param pixels this is filled in with a pointer to the locked pixels, + * appropriately offset by the locked area + * \param pitch this is filled in with the pitch of the locked pixels; the + * pitch is the length of one row in bytes + * \returns 0 on success or a negative error code if the texture is not valid + * or was not created with `SDL_TEXTUREACCESS_STREAMING`; call + * SDL_GetError() for more information. + * + * \sa SDL_UnlockTexture */ extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_Texture * texture, const SDL_Rect * rect, void **pixels, int *pitch); /** - * \brief Lock a portion of the texture for write-only pixel access. - * Expose it as a SDL surface. + * Lock a portion of the texture for **write-only** pixel access, and expose + * it as a SDL surface. * - * \param texture The texture to lock for access, which was created with - * ::SDL_TEXTUREACCESS_STREAMING. - * \param rect A pointer to the rectangle to lock for access. If the rect - * is NULL, the entire texture will be locked. - * \param surface This is filled in with a SDL surface representing the locked area - * Surface is freed internally after calling SDL_UnlockTexture or SDL_DestroyTexture. + * Besides providing an SDL_Surface instead of raw pixel data, this function + * operates like SDL_LockTexture. * - * \return 0 on success, or -1 if the texture is not valid or was not created with ::SDL_TEXTUREACCESS_STREAMING. + * As an optimization, the pixels made available for editing don't necessarily + * contain the old texture data. This is a write-only operation, and if you + * need to keep a copy of the texture data you should do that at the + * application level. * - * \sa SDL_UnlockTexture() + * You must use SDL_UnlockTexture() to unlock the pixels and apply any + * changes. + * + * The returned surface is freed internally after calling SDL_UnlockTexture() + * or SDL_DestroyTexture(). The caller should not free it. + * + * \param texture the texture to lock for access, which was created with + * `SDL_TEXTUREACCESS_STREAMING` + * \param rect a pointer to the rectangle to lock for access. If the rect is + * NULL, the entire texture will be locked + * \param surface this is filled in with an SDL surface representing the + * locked area + * \returns 0 on success, or -1 if the texture is not valid or was not created + * with `SDL_TEXTUREACCESS_STREAMING` + * + * \sa SDL_LockTexture() + * \sa SDL_UnlockTexture() */ extern DECLSPEC int SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture, const SDL_Rect *rect, SDL_Surface **surface); /** - * \brief Unlock a texture, uploading the changes to video memory, if needed. - * If SDL_LockTextureToSurface() was called for locking, the SDL surface is freed. + * Unlock a texture, uploading the changes to video memory, if needed. * - * \sa SDL_LockTexture() - * \sa SDL_LockTextureToSurface() + * **Warning**: Please note that SDL_LockTexture() is intended to be + * write-only; it will notguarantee the previous contents of the texture will + * be provided. You must fully initialize any area of a texture that you lock + * before unlocking it, as the pixels might otherwise be uninitialized memory. + * + * Which is to say: locking and immediately unlocking a texture can result + * in corrupted textures, depending on the renderer in use. + * + * \param texture a texture locked by SDL_LockTexture() + * + * \sa SDL_LockTexture */ extern DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_Texture * texture); /** - * \brief Determines whether a window supports the use of render targets + * Determine whether a renderer supports the use of render targets. * - * \param renderer The renderer that will be checked + * \param renderer the renderer that will be checked + * \returns SDL_TRUE if supported or SDL_FALSE if not. * - * \return SDL_TRUE if supported, SDL_FALSE if not. + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_SetRenderTarget */ extern DECLSPEC SDL_bool SDLCALL SDL_RenderTargetSupported(SDL_Renderer *renderer); /** - * \brief Set a texture as the current rendering target. + * Set a texture as the current rendering target. * - * \param renderer The renderer. - * \param texture The targeted texture, which must be created with the SDL_TEXTUREACCESS_TARGET flag, or NULL for the default render target + * Before using this function, you should check the + * `SDL_RENDERER_TARGETTEXTURE` bit in the flags of SDL_RendererInfo to see + * if render targets are supported. * - * \return 0 on success, or -1 on error + * The default render target is the window for which the renderer was created. + * To stop rendering to a texture and render to the window again, call this + * function with a NULL `texture`. * - * \sa SDL_GetRenderTarget() + * \param renderer the rendering context + * \param texture the targeted texture, which must be created with the + * `SDL_TEXTUREACCESS_TARGET` flag, or NULL + * to render to the window instead of a texture. + * \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_GetRenderTarget */ extern DECLSPEC int SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, SDL_Texture *texture); /** - * \brief Get the current render target or NULL for the default render target. + * Get the current render target. * - * \return The current render target + * The default render target is the window for which the renderer was created, + * and is reported a NULL here. * - * \sa SDL_SetRenderTarget() + * \param renderer the rendering context + * \returns the current render target or NULL for the default render target. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_SetRenderTarget */ extern DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *renderer); /** - * \brief Set device independent resolution for rendering + * Set a device independent resolution for rendering. * - * \param renderer The renderer for which resolution should be set. - * \param w The width of the logical resolution - * \param h The height of the logical resolution + * This function uses the viewport and scaling functionality to allow a fixed + * logical resolution for rendering, regardless of the actual output + * resolution. If the actual output resolution doesn't have the same aspect + * ratio the output rendering will be centered within the output display. * - * This function uses the viewport and scaling functionality to allow a fixed logical - * resolution for rendering, regardless of the actual output resolution. If the actual - * output resolution doesn't have the same aspect ratio the output rendering will be - * centered within the output display. + * If the output display is a window, mouse and touch events in the window + * will be filtered and scaled so they seem to arrive within the logical + * resolution. * - * If the output display is a window, mouse events in the window will be filtered - * and scaled so they seem to arrive within the logical resolution. + * If this function results in scaling or subpixel drawing by the rendering + * backend, it will be handled using the appropriate quality hints. * - * \note If this function results in scaling or subpixel drawing by the - * rendering backend, it will be handled using the appropriate - * quality hints. + * \param renderer the renderer for which resolution should be set + * \param w the width of the logical resolution + * \param h the height of the logical resolution + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. * - * \sa SDL_RenderGetLogicalSize() - * \sa SDL_RenderSetScale() - * \sa SDL_RenderSetViewport() + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_RenderGetLogicalSize */ extern DECLSPEC int SDLCALL SDL_RenderSetLogicalSize(SDL_Renderer * renderer, int w, int h); /** - * \brief Get device independent resolution for rendering + * Get device independent resolution for rendering. * - * \param renderer The renderer from which resolution should be queried. - * \param w A pointer filled with the width of the logical resolution - * \param h A pointer filled with the height of the logical resolution + * This may return 0 for `w` and `h` if the SDL_Renderer has never had its + * logical size set by SDL_RenderSetLogicalSize() and never had a render + * target set. * - * \sa SDL_RenderSetLogicalSize() + * \param renderer a rendering context + * \param w an int to be filled with the width + * \param h an int to be filled with the height + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_RenderSetLogicalSize */ extern DECLSPEC void SDLCALL SDL_RenderGetLogicalSize(SDL_Renderer * renderer, int *w, int *h); /** - * \brief Set whether to force integer scales for resolution-independent rendering + * Set whether to force integer scales for resolution-independent rendering. * - * \param renderer The renderer for which integer scaling should be set. - * \param enable Enable or disable integer scaling + * This function restricts the logical viewport to integer values - that is, + * when a resolution is between two multiples of a logical size, the viewport + * size is rounded down to the lower multiple. * - * This function restricts the logical viewport to integer values - that is, when - * a resolution is between two multiples of a logical size, the viewport size is - * rounded down to the lower multiple. + * \param renderer the renderer for which integer scaling should be set + * \param enable enable or disable the integer scaling for rendering + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. * - * \sa SDL_RenderSetLogicalSize() + * \since This function is available since SDL 2.0.5. + * + * \sa SDL_RenderGetIntegerScale + * \sa SDL_RenderSetLogicalSize */ extern DECLSPEC int SDLCALL SDL_RenderSetIntegerScale(SDL_Renderer * renderer, SDL_bool enable); /** - * \brief Get whether integer scales are forced for resolution-independent rendering + * Get whether integer scales are forced for resolution-independent rendering. * - * \param renderer The renderer from which integer scaling should be queried. + * \param renderer the renderer from which integer scaling should be queried + * \returns SDL_TRUE if integer scales are forced or SDL_FALSE if not and on + * failure; call SDL_GetError() for more information. * - * \sa SDL_RenderSetIntegerScale() + * \since This function is available since SDL 2.0.5. + * + * \sa SDL_RenderSetIntegerScale */ extern DECLSPEC SDL_bool SDLCALL SDL_RenderGetIntegerScale(SDL_Renderer * renderer); /** - * \brief Set the drawing area for rendering on the current target. + * Set the drawing area for rendering on the current target. * - * \param renderer The renderer for which the drawing area should be set. - * \param rect The rectangle representing the drawing area, or NULL to set the viewport to the entire target. + * When the window is resized, the viewport is reset to fill the entire + * new window size. * - * The x,y of the viewport rect represents the origin for rendering. + * \param renderer the rendering context + * \param rect the SDL_Rect structure representing the drawing area, or NULL + * to set the viewport to the entire target + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. * - * \return 0 on success, or -1 on error - * - * \note If the window associated with the renderer is resized, the viewport is automatically reset. - * - * \sa SDL_RenderGetViewport() - * \sa SDL_RenderSetLogicalSize() + * \sa SDL_RenderGetViewport */ extern DECLSPEC int SDLCALL SDL_RenderSetViewport(SDL_Renderer * renderer, const SDL_Rect * rect); /** - * \brief Get the drawing area for the current target. + * Get the drawing area for the current target. * - * \sa SDL_RenderSetViewport() + * \param renderer the rendering context + * \param rect an SDL_Rect structure filled in with the current drawing area + * + * \sa SDL_RenderSetViewport */ extern DECLSPEC void SDLCALL SDL_RenderGetViewport(SDL_Renderer * renderer, SDL_Rect * rect); /** - * \brief Set the clip rectangle for the current target. + * Set the clip rectangle for rendering on the specified target. * - * \param renderer The renderer for which clip rectangle should be set. - * \param rect A pointer to the rectangle to set as the clip rectangle, - * relative to the viewport, or NULL to disable clipping. + * \param renderer the rendering context for which clip rectangle should be + * set + * \param rect an SDL_Rect structure representing the clip area, relative to + * the viewport, or NULL to disable clipping + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. * - * \return 0 on success, or -1 on error - * - * \sa SDL_RenderGetClipRect() + * \sa SDL_RenderGetClipRect + * \sa SDL_RenderIsClipEnabled */ extern DECLSPEC int SDLCALL SDL_RenderSetClipRect(SDL_Renderer * renderer, const SDL_Rect * rect); /** - * \brief Get the clip rectangle for the current target. + * Get the clip rectangle for the current target. * - * \param renderer The renderer from which clip rectangle should be queried. - * \param rect A pointer filled in with the current clip rectangle, or - * an empty rectangle if clipping is disabled. + * \param renderer the rendering context from which clip rectangle should be + * queried + * \param rect an SDL_Rect structure filled in with the current clipping area + * or an empty rectangle if clipping is disabled * - * \sa SDL_RenderSetClipRect() + * \sa SDL_RenderIsClipEnabled + * \sa SDL_RenderSetClipRect */ extern DECLSPEC void SDLCALL SDL_RenderGetClipRect(SDL_Renderer * renderer, SDL_Rect * rect); /** - * \brief Get whether clipping is enabled on the given renderer. + * Get whether clipping is enabled on the given renderer. * - * \param renderer The renderer from which clip state should be queried. + * \param renderer the renderer from which clip state should be queried + * \returns SDL_TRUE if clipping is enabled or SDL_FALSE if not; call + * SDL_GetError() for more information. * - * \sa SDL_RenderGetClipRect() + * \since This function is available since SDL 2.0.4. + * + * \sa SDL_RenderGetClipRect + * \sa SDL_RenderSetClipRect */ extern DECLSPEC SDL_bool SDLCALL SDL_RenderIsClipEnabled(SDL_Renderer * renderer); /** - * \brief Set the drawing scale for rendering on the current target. + * Set the drawing scale for rendering on the current target. * - * \param renderer The renderer for which the drawing scale should be set. - * \param scaleX The horizontal scaling factor - * \param scaleY The vertical scaling factor + * The drawing coordinates are scaled by the x/y scaling factors before they + * are used by the renderer. This allows resolution independent drawing with a + * single coordinate system. * - * The drawing coordinates are scaled by the x/y scaling factors - * before they are used by the renderer. This allows resolution - * independent drawing with a single coordinate system. + * If this results in scaling or subpixel drawing by the rendering backend, it + * will be handled using the appropriate quality hints. For best results use + * integer scaling factors. * - * \note If this results in scaling or subpixel drawing by the - * rendering backend, it will be handled using the appropriate - * quality hints. For best results use integer scaling factors. + * \param renderer a rendering context + * \param scaleX the horizontal scaling factor + * \param scaleY the vertical scaling factor + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. * - * \sa SDL_RenderGetScale() - * \sa SDL_RenderSetLogicalSize() + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_RenderGetScale + * \sa SDL_RenderSetLogicalSize */ extern DECLSPEC int SDLCALL SDL_RenderSetScale(SDL_Renderer * renderer, float scaleX, float scaleY); /** - * \brief Get the drawing scale for the current target. + * Get the drawing scale for the current target. * - * \param renderer The renderer from which drawing scale should be queried. - * \param scaleX A pointer filled in with the horizontal scaling factor - * \param scaleY A pointer filled in with the vertical scaling factor + * \param renderer the renderer from which drawing scale should be queried + * \param scaleX a pointer filled in with the horizontal scaling factor + * \param scaleY a pointer filled in with the vertical scaling factor * - * \sa SDL_RenderSetScale() + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_RenderSetScale */ extern DECLSPEC void SDLCALL SDL_RenderGetScale(SDL_Renderer * renderer, float *scaleX, float *scaleY); /** - * \brief Set the color used for drawing operations (Rect, Line and Clear). + * Set the color used for drawing operations (Rect, Line and Clear). * - * \param renderer The renderer for which drawing color should be set. - * \param r The red value used to draw on the rendering target. - * \param g The green value used to draw on the rendering target. - * \param b The blue value used to draw on the rendering target. - * \param a The alpha value used to draw on the rendering target, usually - * ::SDL_ALPHA_OPAQUE (255). + * Set the color for drawing or filling rectangles, lines, and points, + * and for SDL_RenderClear(). * - * \return 0 on success, or -1 on error + * \param renderer the rendering context + * \param r the red value used to draw on the rendering target + * \param g the green value used to draw on the rendering target + * \param b the blue value used to draw on the rendering target + * \param a the alpha value used to draw on the rendering target; usually + * `SDL_ALPHA_OPAQUE` (255). Use SDL_SetRenderDrawBlendMode to + * specify how the alpha channel is used + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_GetRenderDrawColor + * \sa SDL_RenderClear + * \sa SDL_RenderDrawLine + * \sa SDL_RenderDrawLines + * \sa SDL_RenderDrawPoint + * \sa SDL_RenderDrawPoints + * \sa SDL_RenderDrawRect + * \sa SDL_RenderDrawRects + * \sa SDL_RenderFillRect + * \sa SDL_RenderFillRects */ extern DECLSPEC int SDLCALL SDL_SetRenderDrawColor(SDL_Renderer * renderer, Uint8 r, Uint8 g, Uint8 b, Uint8 a); /** - * \brief Get the color used for drawing operations (Rect, Line and Clear). + * Get the color used for drawing operations (Rect, Line and Clear). * - * \param renderer The renderer from which drawing color should be queried. - * \param r A pointer to the red value used to draw on the rendering target. - * \param g A pointer to the green value used to draw on the rendering target. - * \param b A pointer to the blue value used to draw on the rendering target. - * \param a A pointer to the alpha value used to draw on the rendering target, - * usually ::SDL_ALPHA_OPAQUE (255). + * \param renderer the rendering context + * \param r a pointer filled in with the red value used to draw on the + * rendering target + * \param g a pointer filled in with the green value used to draw on the + * rendering target + * \param b a pointer filled in with the blue value used to draw on the + * rendering target + * \param a a pointer filled in with the alpha value used to draw on the + * rendering target; usually `SDL_ALPHA_OPAQUE` (255) + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. * - * \return 0 on success, or -1 on error + * \sa SDL_SetRenderDrawColor */ extern DECLSPEC int SDLCALL SDL_GetRenderDrawColor(SDL_Renderer * renderer, Uint8 * r, Uint8 * g, Uint8 * b, Uint8 * a); /** - * \brief Set the blend mode used for drawing operations (Fill and Line). + * Set the blend mode used for drawing operations (Fill and Line). * - * \param renderer The renderer for which blend mode should be set. - * \param blendMode ::SDL_BlendMode to use for blending. + * If the blend mode is not supported, the closest supported mode is chosen. * - * \return 0 on success, or -1 on error + * \param renderer the rendering context + * \param blendMode the SDL_BlendMode to use for blending + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. * - * \note If the blend mode is not supported, the closest supported mode is - * chosen. - * - * \sa SDL_GetRenderDrawBlendMode() + * \sa SDL_GetRenderDrawBlendMode + * \sa SDL_RenderDrawLine + * \sa SDL_RenderDrawLines + * \sa SDL_RenderDrawPoint + * \sa SDL_RenderDrawPoints + * \sa SDL_RenderDrawRect + * \sa SDL_RenderDrawRects + * \sa SDL_RenderFillRect + * \sa SDL_RenderFillRects */ extern DECLSPEC int SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer * renderer, SDL_BlendMode blendMode); /** - * \brief Get the blend mode used for drawing operations. + * Get the blend mode used for drawing operations. * - * \param renderer The renderer from which blend mode should be queried. - * \param blendMode A pointer filled in with the current blend mode. + * \param renderer the rendering context + * \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 on error - * - * \sa SDL_SetRenderDrawBlendMode() + * \sa SDL_SetRenderDrawBlendMode */ extern DECLSPEC int SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer * renderer, SDL_BlendMode *blendMode); /** - * \brief Clear the current rendering target with the drawing color + * Clear the current rendering target with the drawing color. * - * This function clears the entire rendering target, ignoring the viewport and - * the clip rectangle. + * This function clears the entire rendering target, ignoring the viewport and + * the clip rectangle. * - * \return 0 on success, or -1 on error + * \param renderer the rendering context + * \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_SetRenderDrawColor */ extern DECLSPEC int SDLCALL SDL_RenderClear(SDL_Renderer * renderer); /** - * \brief Draw a point on the current rendering target. + * Draw a point on the current rendering target. * - * \param renderer The renderer which should draw a point. - * \param x The x coordinate of the point. - * \param y The y coordinate of the point. + * SDL_RenderDrawPoint() draws a single point. If you want to draw multiple, + * use SDL_RenderDrawPoints() instead. * - * \return 0 on success, or -1 on error + * \param renderer the rendering context + * \param x the x coordinate of the point + * \param y the y coordinate of the point + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_RenderDrawLine + * \sa SDL_RenderDrawLines + * \sa SDL_RenderDrawPoints + * \sa SDL_RenderDrawRect + * \sa SDL_RenderDrawRects + * \sa SDL_RenderFillRect + * \sa SDL_RenderFillRects + * \sa SDL_RenderPresent + * \sa SDL_SetRenderDrawBlendMode + * \sa SDL_SetRenderDrawColor */ extern DECLSPEC int SDLCALL SDL_RenderDrawPoint(SDL_Renderer * renderer, int x, int y); /** - * \brief Draw multiple points on the current rendering target. + * Draw multiple points on the current rendering target. * - * \param renderer The renderer which should draw multiple points. - * \param points The points to draw - * \param count The number of points to draw + * \param renderer the rendering context + * \param points an array of SDL_Point structures that represent the points to + * draw + * \param count the number of points to draw + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. * - * \return 0 on success, or -1 on error + * \sa SDL_RenderDrawLine + * \sa SDL_RenderDrawLines + * \sa SDL_RenderDrawPoint + * \sa SDL_RenderDrawRect + * \sa SDL_RenderDrawRects + * \sa SDL_RenderFillRect + * \sa SDL_RenderFillRects + * \sa SDL_RenderPresent + * \sa SDL_SetRenderDrawBlendMode + * \sa SDL_SetRenderDrawColor */ extern DECLSPEC int SDLCALL SDL_RenderDrawPoints(SDL_Renderer * renderer, const SDL_Point * points, int count); /** - * \brief Draw a line on the current rendering target. + * Draw a line on the current rendering target. * - * \param renderer The renderer which should draw a line. - * \param x1 The x coordinate of the start point. - * \param y1 The y coordinate of the start point. - * \param x2 The x coordinate of the end point. - * \param y2 The y coordinate of the end point. + * SDL_RenderDrawLine() draws the line to include both end points. If you want + * to draw multiple, connecting lines use SDL_RenderDrawLines() instead. * - * \return 0 on success, or -1 on error + * \param renderer the rendering context + * \param x1 the x coordinate of the start point + * \param y1 the y coordinate of the start point + * \param x2 the x coordinate of the end point + * \param y2 the y coordinate of the end point + * \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_RenderDrawLines + * \sa SDL_RenderDrawPoint + * \sa SDL_RenderDrawPoints + * \sa SDL_RenderDrawRect + * \sa SDL_RenderDrawRects + * \sa SDL_RenderFillRect + * \sa SDL_RenderFillRects + * \sa SDL_RenderPresent + * \sa SDL_SetRenderDrawBlendMode + * \sa SDL_SetRenderDrawColor */ extern DECLSPEC int SDLCALL SDL_RenderDrawLine(SDL_Renderer * renderer, int x1, int y1, int x2, int y2); /** - * \brief Draw a series of connected lines on the current rendering target. + * Draw a series of connected lines on the current rendering target. * - * \param renderer The renderer which should draw multiple lines. - * \param points The points along the lines - * \param count The number of points, drawing count-1 lines + * \param renderer the rendering context + * \param points an array of SDL_Point structures representing points along + * the lines + * \param count the number of points, drawing count-1 lines + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. * - * \return 0 on success, or -1 on error + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_RenderDrawLine + * \sa SDL_RenderDrawPoint + * \sa SDL_RenderDrawPoints + * \sa SDL_RenderDrawRect + * \sa SDL_RenderDrawRects + * \sa SDL_RenderFillRect + * \sa SDL_RenderFillRects + * \sa SDL_RenderPresent + * \sa SDL_SetRenderDrawBlendMode + * \sa SDL_SetRenderDrawColor */ extern DECLSPEC int SDLCALL SDL_RenderDrawLines(SDL_Renderer * renderer, const SDL_Point * points, int count); /** - * \brief Draw a rectangle on the current rendering target. + * Draw a rectangle on the current rendering target. * - * \param renderer The renderer which should draw a rectangle. - * \param rect A pointer to the destination rectangle, or NULL to outline the entire rendering target. + * \param renderer the rendering context + * \param rect an SDL_Rect structure representing the rectangle to draw, or + * NULL to outline the entire rendering target + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. * - * \return 0 on success, or -1 on error + * \sa SDL_RenderDrawLine + * \sa SDL_RenderDrawLines + * \sa SDL_RenderDrawPoint + * \sa SDL_RenderDrawPoints + * \sa SDL_RenderDrawRects + * \sa SDL_RenderFillRect + * \sa SDL_RenderFillRects + * \sa SDL_RenderPresent + * \sa SDL_SetRenderDrawBlendMode + * \sa SDL_SetRenderDrawColor */ extern DECLSPEC int SDLCALL SDL_RenderDrawRect(SDL_Renderer * renderer, const SDL_Rect * rect); /** - * \brief Draw some number of rectangles on the current rendering target. + * Draw some number of rectangles on the current rendering target. * - * \param renderer The renderer which should draw multiple rectangles. - * \param rects A pointer to an array of destination rectangles. - * \param count The number of rectangles. + * \param renderer the rendering context + * \param rects an array of SDL_Rect structures representing the rectangles to + * be drawn + * \param count the number of rectangles + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. * - * \return 0 on success, or -1 on error + * \sa SDL_RenderDrawLine + * \sa SDL_RenderDrawLines + * \sa SDL_RenderDrawPoint + * \sa SDL_RenderDrawPoints + * \sa SDL_RenderDrawRect + * \sa SDL_RenderFillRect + * \sa SDL_RenderFillRects + * \sa SDL_RenderPresent + * \sa SDL_SetRenderDrawBlendMode + * \sa SDL_SetRenderDrawColor */ extern DECLSPEC int SDLCALL SDL_RenderDrawRects(SDL_Renderer * renderer, const SDL_Rect * rects, int count); /** - * \brief Fill a rectangle on the current rendering target with the drawing color. + * Fill a rectangle on the current rendering target with the drawing color. * - * \param renderer The renderer which should fill a rectangle. - * \param rect A pointer to the destination rectangle, or NULL for the entire - * rendering target. + * The current drawing color is set by SDL_SetRenderDrawColor(), and the + * color's alpha value is ignored unless blending is enabled with the + * appropriate call to SDL_SetRenderDrawBlendMode(). * - * \return 0 on success, or -1 on error + * \param renderer the rendering context + * \param rect the SDL_Rect structure representing the rectangle to fill, or + * NULL for the entire rendering target + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_RenderDrawLine + * \sa SDL_RenderDrawLines + * \sa SDL_RenderDrawPoint + * \sa SDL_RenderDrawPoints + * \sa SDL_RenderDrawRect + * \sa SDL_RenderDrawRects + * \sa SDL_RenderFillRects + * \sa SDL_RenderPresent + * \sa SDL_SetRenderDrawBlendMode + * \sa SDL_SetRenderDrawColor */ extern DECLSPEC int SDLCALL SDL_RenderFillRect(SDL_Renderer * renderer, const SDL_Rect * rect); /** - * \brief Fill some number of rectangles on the current rendering target with the drawing color. + * Fill some number of rectangles on the current rendering target with the + * drawing color. * - * \param renderer The renderer which should fill multiple rectangles. - * \param rects A pointer to an array of destination rectangles. - * \param count The number of rectangles. + * \param renderer the rendering context + * \param rects an array of SDL_Rect structures representing the rectangles to + * be filled + * \param count the number of rectangles + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. * - * \return 0 on success, or -1 on error + * \sa SDL_RenderDrawLine + * \sa SDL_RenderDrawLines + * \sa SDL_RenderDrawPoint + * \sa SDL_RenderDrawPoints + * \sa SDL_RenderDrawRect + * \sa SDL_RenderDrawRects + * \sa SDL_RenderFillRect + * \sa SDL_RenderPresent */ extern DECLSPEC int SDLCALL SDL_RenderFillRects(SDL_Renderer * renderer, const SDL_Rect * rects, int count); /** - * \brief Copy a portion of the texture to the current rendering target. + * Copy a portion of the texture to the current rendering target. * - * \param renderer The renderer which should copy parts of a texture. - * \param texture The source texture. - * \param srcrect A pointer to the source rectangle, or NULL for the entire - * texture. - * \param dstrect A pointer to the destination rectangle, or NULL for the - * entire rendering target. + * The texture is blended with the destination based on its blend mode set + * with SDL_SetTextureBlendMode(). * - * \return 0 on success, or -1 on error + * The texture color is affected based on its color modulation set by + * SDL_SetTextureColorMod(). + * + * The texture alpha is affected based on its alpha modulation set by + * SDL_SetTextureAlphaMod(). + * + * \param renderer the rendering context + * \param texture the source texture + * \param srcrect the source SDL_Rect structure or NULL for the entire texture + * \param dstrect the destination SDL_Rect structure or NULL for the entire + * rendering target; the texture will be stretched to fill the + * given rectangle + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_RenderCopyEx + * \sa SDL_SetTextureAlphaMod + * \sa SDL_SetTextureBlendMode + * \sa SDL_SetTextureColorMod */ extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_Renderer * renderer, SDL_Texture * texture, @@ -895,19 +1231,41 @@ extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_Renderer * renderer, const SDL_Rect * dstrect); /** - * \brief Copy a portion of the source texture to the current rendering target, rotating it by angle around the given center + * Copy a portion of the texture to the current rendering, with optional + * rotation and flipping. * - * \param renderer The renderer which should copy parts of a texture. - * \param texture The source texture. - * \param srcrect A pointer to the source rectangle, or NULL for the entire - * texture. - * \param dstrect A pointer to the destination rectangle, or NULL for the - * entire rendering target. - * \param angle An angle in degrees that indicates the rotation that will be applied to dstrect, rotating it in a clockwise direction - * \param center A pointer to a point indicating the point around which dstrect will be rotated (if NULL, rotation will be done around dstrect.w/2, dstrect.h/2). - * \param flip An SDL_RendererFlip value stating which flipping actions should be performed on the texture + * Copy a portion of the texture to the current rendering + * target, optionally rotating it by angle around the given center and also + * flipping it top-bottom and/or left-right. * - * \return 0 on success, or -1 on error + * The texture is blended with the destination based on its blend mode set + * with SDL_SetTextureBlendMode(). + * + * The texture color is affected based on its color modulation set by + * SDL_SetTextureColorMod(). + * + * The texture alpha is affected based on its alpha modulation set by + * SDL_SetTextureAlphaMod(). + * + * \param renderer the rendering context + * \param texture the source texture + * \param srcrect the source SDL_Rect structure or NULL for the entire texture + * \param dstrect the destination SDL_Rect structure or NULL for the entire + * rendering target + * \param angle an angle in degrees that indicates the rotation that will be + * applied to dstrect, rotating it in a clockwise direction + * \param center a pointer to a point indicating the point around which + * dstrect will be rotated (if NULL, rotation will be done + * around `dstrect.w / 2`, `dstrect.h / 2`) + * \param flip a SDL_RendererFlip value stating which flipping actions should + * be performed on the texture + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_RenderCopy + * \sa SDL_SetTextureAlphaMod + * \sa SDL_SetTextureBlendMode + * \sa SDL_SetTextureColorMod */ extern DECLSPEC int SDLCALL SDL_RenderCopyEx(SDL_Renderer * renderer, SDL_Texture * texture, @@ -919,117 +1277,113 @@ extern DECLSPEC int SDLCALL SDL_RenderCopyEx(SDL_Renderer * renderer, /** - * \brief Draw a point on the current rendering target. + * Draw a point on the current rendering target at subpixel precision. * - * \param renderer The renderer which should draw a point. - * \param x The x coordinate of the point. - * \param y The y coordinate of the point. - * - * \return 0 on success, or -1 on error + * \param renderer The renderer which should draw a point. + * \param x The x coordinate of the point. + * \param y The y coordinate of the point. + * \return 0 on success, or -1 on error */ extern DECLSPEC int SDLCALL SDL_RenderDrawPointF(SDL_Renderer * renderer, float x, float y); /** - * \brief Draw multiple points on the current rendering target. + * Draw multiple points on the current rendering target at subpixel precision. * - * \param renderer The renderer which should draw multiple points. - * \param points The points to draw - * \param count The number of points to draw - * - * \return 0 on success, or -1 on error + * \param renderer The renderer which should draw multiple points. + * \param points The points to draw + * \param count The number of points to draw + * \return 0 on success, or -1 on error */ extern DECLSPEC int SDLCALL SDL_RenderDrawPointsF(SDL_Renderer * renderer, const SDL_FPoint * points, int count); /** - * \brief Draw a line on the current rendering target. + * Draw a line on the current rendering target at subpixel precision. * - * \param renderer The renderer which should draw a line. - * \param x1 The x coordinate of the start point. - * \param y1 The y coordinate of the start point. - * \param x2 The x coordinate of the end point. - * \param y2 The y coordinate of the end point. - * - * \return 0 on success, or -1 on error + * \param renderer The renderer which should draw a line. + * \param x1 The x coordinate of the start point. + * \param y1 The y coordinate of the start point. + * \param x2 The x coordinate of the end point. + * \param y2 The y coordinate of the end point. + * \return 0 on success, or -1 on error */ extern DECLSPEC int SDLCALL SDL_RenderDrawLineF(SDL_Renderer * renderer, float x1, float y1, float x2, float y2); /** - * \brief Draw a series of connected lines on the current rendering target. + * Draw a series of connected lines on the current rendering target at + * subpixel precision. * - * \param renderer The renderer which should draw multiple lines. - * \param points The points along the lines - * \param count The number of points, drawing count-1 lines - * - * \return 0 on success, or -1 on error + * \param renderer The renderer which should draw multiple lines. + * \param points The points along the lines + * \param count The number of points, drawing count-1 lines + * \return 0 on success, or -1 on error */ extern DECLSPEC int SDLCALL SDL_RenderDrawLinesF(SDL_Renderer * renderer, - const SDL_FPoint * points, - int count); + const SDL_FPoint * points, + int count); /** - * \brief Draw a rectangle on the current rendering target. + * Draw a rectangle on the current rendering target at subpixel precision. * - * \param renderer The renderer which should draw a rectangle. - * \param rect A pointer to the destination rectangle, or NULL to outline the entire rendering target. - * - * \return 0 on success, or -1 on error + * \param renderer The renderer which should draw a rectangle. + * \param rect A pointer to the destination rectangle, or NULL to outline the entire rendering target. + * \return 0 on success, or -1 on error */ extern DECLSPEC int SDLCALL SDL_RenderDrawRectF(SDL_Renderer * renderer, - const SDL_FRect * rect); + const SDL_FRect * rect); /** - * \brief Draw some number of rectangles on the current rendering target. + * Draw some number of rectangles on the current rendering target at subpixel + * precision. * - * \param renderer The renderer which should draw multiple rectangles. - * \param rects A pointer to an array of destination rectangles. - * \param count The number of rectangles. - * - * \return 0 on success, or -1 on error + * \param renderer The renderer which should draw multiple rectangles. + * \param rects A pointer to an array of destination rectangles. + * \param count The number of rectangles. + * \return 0 on success, or -1 on error */ extern DECLSPEC int SDLCALL SDL_RenderDrawRectsF(SDL_Renderer * renderer, const SDL_FRect * rects, int count); /** - * \brief Fill a rectangle on the current rendering target with the drawing color. + * Fill a rectangle on the current rendering target with the drawing color + * at subpixel precision. * - * \param renderer The renderer which should fill a rectangle. - * \param rect A pointer to the destination rectangle, or NULL for the entire - * rendering target. - * - * \return 0 on success, or -1 on error + * \param renderer The renderer which should fill a rectangle. + * \param rect A pointer to the destination rectangle, or NULL for the entire + * rendering target. + * \return 0 on success, or -1 on error */ extern DECLSPEC int SDLCALL SDL_RenderFillRectF(SDL_Renderer * renderer, const SDL_FRect * rect); /** - * \brief Fill some number of rectangles on the current rendering target with the drawing color. + * Fill some number of rectangles on the current rendering target with the + * drawing color at subpixel precision. * - * \param renderer The renderer which should fill multiple rectangles. - * \param rects A pointer to an array of destination rectangles. - * \param count The number of rectangles. - * - * \return 0 on success, or -1 on error + * \param renderer The renderer which should fill multiple rectangles. + * \param rects A pointer to an array of destination rectangles. + * \param count The number of rectangles. + * \return 0 on success, or -1 on error */ extern DECLSPEC int SDLCALL SDL_RenderFillRectsF(SDL_Renderer * renderer, const SDL_FRect * rects, int count); /** - * \brief Copy a portion of the texture to the current rendering target. + * Copy a portion of the texture to the current rendering target at subpixel + * precision. * - * \param renderer The renderer which should copy parts of a texture. - * \param texture The source texture. - * \param srcrect A pointer to the source rectangle, or NULL for the entire - * texture. - * \param dstrect A pointer to the destination rectangle, or NULL for the - * entire rendering target. - * - * \return 0 on success, or -1 on error + * \param renderer The renderer which should copy parts of a texture. + * \param texture The source texture. + * \param srcrect A pointer to the source rectangle, or NULL for the entire + * texture. + * \param dstrect A pointer to the destination rectangle, or NULL for the + * entire rendering target. + * \return 0 on success, or -1 on error */ extern DECLSPEC int SDLCALL SDL_RenderCopyF(SDL_Renderer * renderer, SDL_Texture * texture, @@ -1037,19 +1391,20 @@ extern DECLSPEC int SDLCALL SDL_RenderCopyF(SDL_Renderer * renderer, const SDL_FRect * dstrect); /** - * \brief Copy a portion of the source texture to the current rendering target, rotating it by angle around the given center + * Copy a portion of the source texture to the current rendering target, + * with rotation and flipping, at subpixel precision. * - * \param renderer The renderer which should copy parts of a texture. - * \param texture The source texture. - * \param srcrect A pointer to the source rectangle, or NULL for the entire - * texture. - * \param dstrect A pointer to the destination rectangle, or NULL for the - * entire rendering target. - * \param angle An angle in degrees that indicates the rotation that will be applied to dstrect, rotating it in a clockwise direction - * \param center A pointer to a point indicating the point around which dstrect will be rotated (if NULL, rotation will be done around dstrect.w/2, dstrect.h/2). - * \param flip An SDL_RendererFlip value stating which flipping actions should be performed on the texture + * \param renderer The renderer which should copy parts of a texture. + * \param texture The source texture. + * \param srcrect A pointer to the source rectangle, or NULL for the entire + * texture. + * \param dstrect A pointer to the destination rectangle, or NULL for the + * entire rendering target. + * \param angle An angle in degrees that indicates the rotation that will be applied to dstrect, rotating it in a clockwise direction + * \param center A pointer to a point indicating the point around which dstrect will be rotated (if NULL, rotation will be done around dstrect.w/2, dstrect.h/2). + * \param flip An SDL_RendererFlip value stating which flipping actions should be performed on the texture * - * \return 0 on success, or -1 on error + * \return 0 on success, or -1 on error */ extern DECLSPEC int SDLCALL SDL_RenderCopyExF(SDL_Renderer * renderer, SDL_Texture * texture, @@ -1060,19 +1415,27 @@ extern DECLSPEC int SDLCALL SDL_RenderCopyExF(SDL_Renderer * renderer, const SDL_RendererFlip flip); /** - * \brief Read pixels from the current rendering target. + * Read pixels from the current rendering target to an array of pixels. * - * \param renderer The renderer from which pixels should be read. - * \param rect A pointer to the rectangle to read, or NULL for the entire - * render target. - * \param format The desired format of the pixel data, or 0 to use the format - * of the rendering target - * \param pixels A pointer to be filled in with the pixel data - * \param pitch The pitch of the pixels parameter. + * **WARNING**: This is a very slow operation, and should not be used + * frequently. * - * \return 0 on success, or -1 if pixel reading is not supported. + * `pitch` specifies the number of bytes between rows in the destination + * `pixels data. This allows you to write to a subrectangle or have padded + * rows in the destination. Generally, `pitch` should equal the number of + * pixels per row in the `pixels` data times the number of bytes per pixel, + * but it might contain additional padding (for example, 24bit RGB Windows + * Bitmap data pads all rows to multiples of 4 bytes). * - * \warning This is a very slow operation, and should not be used frequently. + * \param renderer the rendering context + * \param rect an SDL_Rect structure representing the area to read, or NULL + * for the entire render target + * \param format an SDL_PixelFormatEnum value of the desired format of the + * pixel data, or 0 to use the format of the rendering target + * \param pixels a pointer to the pixel data to copy into + * \param pitch the pitch of the `pixels` parameter + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. */ extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Renderer * renderer, const SDL_Rect * rect, @@ -1080,90 +1443,168 @@ extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Renderer * renderer, void *pixels, int pitch); /** - * \brief Update the screen with rendering performed. + * Update the screen with any rendering performed since + * the previous call. + * + * SDL's rendering functions operate on a backbuffer; that is, calling a + * rendering function such as SDL_RenderDrawLine() does not directly put a + * line on the screen, but rather updates the backbuffer. As such, you compose + * your entire scene and *present* the composed backbuffer to the screen as a + * complete picture. + * + * Therefore, when using SDL's rendering API, one does all drawing intended + * for the frame, and then calls this function once per frame to present the + * final drawing to the user. + * + * The backbuffer should be considered invalidated after each present; do not + * assume that previous contents will exist between frames. You are strongly + * encouraged to call SDL_RenderClear() to initialize the backbuffer before + * starting each new frame's drawing, even if you plan to overwrite every + * pixel. + * + * \param renderer the rendering context + * + * \sa SDL_RenderClear + * \sa SDL_RenderDrawLine + * \sa SDL_RenderDrawLines + * \sa SDL_RenderDrawPoint + * \sa SDL_RenderDrawPoints + * \sa SDL_RenderDrawRect + * \sa SDL_RenderDrawRects + * \sa SDL_RenderFillRect + * \sa SDL_RenderFillRects + * \sa SDL_SetRenderDrawBlendMode + * \sa SDL_SetRenderDrawColor */ extern DECLSPEC void SDLCALL SDL_RenderPresent(SDL_Renderer * renderer); /** - * \brief Destroy the specified texture. + * Destroy the specified texture. * - * \sa SDL_CreateTexture() - * \sa SDL_CreateTextureFromSurface() + * Passing NULL or an otherwise invalid texture will set the SDL error message + * to "Invalid texture". + * + * \param texture the texture to destroy + * + * \sa SDL_CreateTexture + * \sa SDL_CreateTextureFromSurface */ extern DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_Texture * texture); /** - * \brief Destroy the rendering context for a window and free associated - * textures. + * Destroy the rendering context for a window and free associated textures. * - * \sa SDL_CreateRenderer() + * \param renderer the rendering context + * + * \sa SDL_CreateRenderer */ extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer * renderer); /** - * \brief Force the rendering context to flush any pending commands to the - * underlying rendering API. + * Force the rendering context to flush any pending commands to the underlying + * rendering API. * - * You do not need to (and in fact, shouldn't) call this function unless - * you are planning to call into OpenGL/Direct3D/Metal/whatever directly - * in addition to using an SDL_Renderer. + * You do not need to (and in fact, shouldn't) call this function unless + * you are planning to call into OpenGL/Direct3D/Metal/whatever directly + * in addition to using an SDL_Renderer. * - * This is for a very-specific case: if you are using SDL's render API, - * you asked for a specific renderer backend (OpenGL, Direct3D, etc), - * you set SDL_HINT_RENDER_BATCHING to "1", and you plan to make - * OpenGL/D3D/whatever calls in addition to SDL render API calls. If all of - * this applies, you should call SDL_RenderFlush() between calls to SDL's - * render API and the low-level API you're using in cooperation. + * This is for a very-specific case: if you are using SDL's render API, you + * asked for a specific renderer backend (OpenGL, Direct3D, etc), you set + * SDL_HINT_RENDER_BATCHING to "1", and you plan to make OpenGL/D3D/whatever + * calls in addition to SDL render API calls. If all of this applies, you + * should call SDL_RenderFlush() between calls to SDL's render API and the + * low-level API you're using in cooperation. * - * In all other cases, you can ignore this function. This is only here to - * get maximum performance out of a specific situation. In all other cases, - * SDL will do the right thing, perhaps at a performance loss. + * In all other cases, you can ignore this function. This is only here to get + * maximum performance out of a specific situation. In all other cases, SDL + * will do the right thing, perhaps at a performance loss. * - * This function is first available in SDL 2.0.10, and is not needed in - * 2.0.9 and earlier, as earlier versions did not queue rendering commands - * at all, instead flushing them to the OS immediately. + * This function is first available in SDL 2.0.10, and is not needed in + * 2.0.9 and earlier, as earlier versions did not queue rendering commands + * at all, instead flushing them to the OS immediately. + * + * \param renderer the rendering context + * \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.10. */ extern DECLSPEC int SDLCALL SDL_RenderFlush(SDL_Renderer * renderer); /** - * \brief Bind the texture to the current OpenGL/ES/ES2 context for use with - * OpenGL instructions. + * Bind an OpenGL/ES/ES2 texture to the current context. * - * \param texture The SDL texture to bind - * \param texw A pointer to a float that will be filled with the texture width - * \param texh A pointer to a float that will be filled with the texture height + * This is for use with OpenGL instructions when rendering OpenGL primitives + * directly. * - * \return 0 on success, or -1 if the operation is not supported + * If not NULL, `texw` and `texh` will be filled with the width and height + * values suitable for the provided texture. In most cases, both will be 1.0, + * however, on systems that support the GL_ARB_texture_rectangle extension, + * these values will actually be the pixel width and height used to create the + * texture, so this factor needs to be taken into account when providing + * texture coordinates to OpenGL. + * + * You need a renderer to create an SDL_Texture, therefore you can only use + * this function with an implicit OpenGL context from SDL_CreateRenderer(), + * not with your own OpenGL context. If you need control over your OpenGL + * context, you need to write your own texture-loading methods. + * + * Also note that SDL may upload RGB textures as BGR (or vice-versa), and + * re-order the color channels in the shaders phase, so the uploaded texture + * may have swapped color channels. + * + * \param texture the texture to bind to the current OpenGL/ES/ES2 context + * \param texw a pointer to a float value which will be filled with the + * texture width or NULL if you don't need that value + * \param texh a pointer to a float value which will be filled with the + * texture height or NULL if you don't need that value + * \returns 0 on success, or -1 if the operation is not supported; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GL_MakeCurrent + * \sa SDL_GL_UnbindTexture */ extern DECLSPEC int SDLCALL SDL_GL_BindTexture(SDL_Texture *texture, float *texw, float *texh); /** - * \brief Unbind a texture from the current OpenGL/ES/ES2 context. + * Unbind an OpenGL/ES/ES2 texture from the current context. * - * \param texture The SDL texture to unbind + * See SDL_GL_BindTexture() for examples on how to use these functions * - * \return 0 on success, or -1 if the operation is not supported + * \param texture the texture to unbind from the current OpenGL/ES/ES2 context + * \returns 0 on success, or -1 if the operation is not supported + * + * \sa SDL_GL_BindTexture + * \sa SDL_GL_MakeCurrent */ extern DECLSPEC int SDLCALL SDL_GL_UnbindTexture(SDL_Texture *texture); /** - * \brief Get the CAMetalLayer associated with the given Metal renderer + * Get the CAMetalLayer associated with the given Metal renderer. * - * \param renderer The renderer to query + * This function returns `void *`, so SDL doesn't have to include Metal's + * headers, but it can be safely cast to a `CAMetalLayer *`. * - * \return CAMetalLayer* on success, or NULL if the renderer isn't a Metal renderer + * \param renderer The renderer to query + * \returns CAMetalLayer* on success, or NULL if the renderer isn't a Metal + * renderer * - * \sa SDL_RenderGetMetalCommandEncoder() + * \sa SDL_RenderGetMetalCommandEncoder() */ extern DECLSPEC void *SDLCALL SDL_RenderGetMetalLayer(SDL_Renderer * renderer); /** - * \brief Get the Metal command encoder for the current frame + * Get the Metal command encoder for the current frame * - * \param renderer The renderer to query + * This function returns `void *`, so SDL doesn't have to include Metal's + * headers, but it can be safely cast to an `id`. * - * \return id on success, or NULL if the renderer isn't a Metal renderer + * \param renderer The renderer to query + * \returns `id` on success, or NULL if the renderer + * isn't a Metal renderer. * * \sa SDL_RenderGetMetalLayer() */ diff --git a/include/SDL_rwops.h b/include/SDL_rwops.h index e73080749..88003e403 100644 --- a/include/SDL_rwops.h +++ b/include/SDL_rwops.h @@ -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. + * 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. + * Load all the data from an SDL data stream. * - * The data is allocated with a zero byte at the end (null terminated) + * 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`. * - * If \c datasize is not NULL, it is filled with the size of the data read. + * The data should be freed with SDL_free(). * - * If \c freesrc is non-zero, the stream will be closed after being read. - * - * 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, - int freesrc); +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) + * 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`. * - * If \c datasize is not NULL, it is filled with the size of the data read. + * The data should be freed with SDL_free(). * - * If \c freesrc is non-zero, the stream will be closed after being read. - * - * 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); diff --git a/include/SDL_sensor.h b/include/SDL_sensor.h index b89e68767..6b2a330c8 100644 --- a/include/SDL_sensor.h +++ b/include/SDL_sensor.h @@ -138,118 +138,122 @@ 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); /** - * Get the current state of an opened sensor. + * Get the current state of an opened sensor. * * The number of values and interpretation of the data is sensor dependent. * - * \param sensor The 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. + * \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 + * \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. + * 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); diff --git a/include/SDL_surface.h b/include/SDL_surface.h index d9b119583..2051aba57 100644 --- a/include/SDL_surface.h +++ b/include/SDL_surface.h @@ -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,74 +216,133 @@ 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). + * Load a BMP image from a seekable SDL data stream. * - * If \c freesrc is non-zero, the stream will be closed after being read. + * The new surface should be freed with SDL_FreeSurface(). * - * The new surface should be freed with SDL_FreeSurface(). + * \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. * - * \return the new surface, or NULL if there was an error. + * \sa SDL_FreeSurface + * \sa SDL_LoadBMP + * \sa SDL_SaveBMP_RW */ extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src, int freesrc); /** - * Load a surface from a file. + * Load a surface from a file. * - * Convenience macro. + * Convenience macro. */ #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 - * 24-bit surface or, if they have an alpha mask or a colorkey, to a 32-bit - * surface before they are saved. YUV and paletted 1-bit and 4-bit formats are - * not supported. + * 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 + * 24-bit surface or, if they have an alpha mask or a colorkey, to a 32-bit + * 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,36 +766,57 @@ 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); /** - * This is a semi-private blit function and it performs low-level surface - * blitting only. + * Perform low-level surface blitting only. + * + * This is a semi-private blit function and it performs low-level surface + * 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. - * - * \note This function uses a static buffer, and is not thread-safe. - */ + + /** + * Perform a fast, low quality, stretch blit between two surfaces of the + * same format. + * + * **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, SDL_Surface * dst, 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); diff --git a/include/SDL_system.h b/include/SDL_system.h index e62c9e5ee..753272e5d 100644 --- a/include/SDL_system.h +++ b/include/SDL_system.h @@ -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); diff --git a/include/SDL_syswm.h b/include/SDL_syswm.h index 1d1584945..12e86a17c 100644 --- a/include/SDL_syswm.h +++ b/include/SDL_syswm.h @@ -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); diff --git a/include/SDL_thread.h b/include/SDL_thread.h index 4b71083f6..49168c52f 100644 --- a/include/SDL_thread.h +++ b/include/SDL_thread.h @@ -69,11 +69,14 @@ typedef enum { } SDL_ThreadPriority; /** - * The function passed to SDL_CreateThread(). - * It is passed a void* user context parameter and returns an int. + * The function passed to SDL_CreateThread(). + * + * \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: - * SDL_CreateThreadWithStackSize(fn, name, 0, data); + * 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. * - * 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 - * 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: + * SDL makes an attempt to report `name` to the system, so that debuggers + * can display it. Not all platforms support this. * - * http://stackoverflow.com/questions/149932/naming-conventions-for-threads + * 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 + * 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: * - * 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(). + * https://stackoverflow.com/questions/149932/naming-conventions-for-threads * - * 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). + * 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(). * - * In SDL 2.1, stacksize will be folded into the original SDL_CreateThread - * function. + * 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. 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, 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. + * 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. + * 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. * - * 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. + * Threads that haven't been detached will remain (as a "zombie") until this + * function cleans them up. Not doing so is a resource leak. * - * The return code for the thread function is placed in the area - * pointed to by \c status, if \c status is not NULL. + * 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. * - * 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. + * The return code for the thread function is placed in the area pointed to by + * `status`, if `status` is not NULL. * - * It is safe to pass NULL to this function; it is a no-op. + * 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. + * + * 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); /** - * 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. + * Let a thread clean up on exit without intervention. * - * 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(). + * 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. * - * 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 - * SDL_WaitThread() to finally clean it up. As such, don't detach the same - * thread more than once. + * 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(). * - * 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(). + * 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 + * SDL_WaitThread() to finally clean it up. As such, don't detach the same + * thread more than once. * - * 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. + * 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(). * - * It is safe to pass NULL to this function; it is a no-op. + * 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; - * - * 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); - * } - * - * void *GetMyThreadData(void) - * { - * return SDL_TLSGet(thread_local_storage); - * } - * \endcode + * \returns the newly created thread local storage identifier or 0 on error. * - * \sa SDL_TLSGet() - * \sa SDL_TLSSet() + * \since This function is available since SDL 2.0.0. + * + * \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*)); diff --git a/include/SDL_timer.h b/include/SDL_timer.h index 66ab2d9e9..04696dc88 100644 --- a/include/SDL_timer.h +++ b/include/SDL_timer.h @@ -38,45 +38,75 @@ 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: - * Uint32 timeout = SDL_GetTicks() + 100; - * while (!SDL_TICKS_PASSED(SDL_GetTicks(), timeout)) { - * ... do work until timeout has elapsed - * } + * 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 + * } + * ``` */ #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); /** - * Function prototype for the timer callback function. + * Function prototype for the timer callback function. * - * The callback function is passed the current timer interval and returns - * the next timer interval. If the returned value is the same as the one - * passed in, the periodic alarm continues, otherwise a new alarm is - * scheduled. If the callback returns 0, the periodic alarm is cancelled. + * The callback function is passed the current timer interval and returns + * the next timer interval. If the returned value is the same as the one + * passed in, the periodic alarm continues, otherwise a new alarm is + * scheduled. If the callback returns 0, the periodic alarm is cancelled. */ typedef Uint32 (SDLCALL * SDL_TimerCallback) (Uint32 interval, void *param); @@ -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); diff --git a/include/SDL_touch.h b/include/SDL_touch.h index 323cd225f..f370a6730 100644 --- a/include/SDL_touch.h +++ b/include/SDL_touch.h @@ -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); diff --git a/include/SDL_version.h b/include/SDL_version.h index a78ac72e4..362a0c567 100644 --- a/include/SDL_version.h +++ b/include/SDL_version.h @@ -37,16 +37,16 @@ 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), - * minor revision (increments with backwards-compatible changes to the - * major revision), and patchlevel (increments with fixes to the minor - * revision). + * Represents the library's version as three levels: major revision + * (increments with massive changes, additions, and enhancements), + * minor revision (increments with backwards-compatible changes to the + * major revision), and patchlevel (increments with fixes to the minor + * revision). * - * \sa SDL_VERSION - * \sa SDL_GetVersion + * \sa SDL_VERSION + * \sa SDL_GetVersion */ typedef struct SDL_version { @@ -62,19 +62,19 @@ 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 - * compiler uses. Note that if you dynamically linked the library, you might - * have a slightly newer or older version at runtime. That version can be - * determined with SDL_GetVersion(), which, unlike SDL_VERSION(), - * is not a macro. + * This macro fills in a SDL_version structure with the version of the + * library you compiled against. This is determined by what header the + * compiler uses. Note that if you dynamically linked the library, you might + * have a slightly newer or older version at runtime. That version can be + * determined with SDL_GetVersion(), which, unlike SDL_VERSION(), + * is not a macro. * - * \param x A pointer to a SDL_version struct to initialize. + * \param x A pointer to a SDL_version struct to initialize. * - * \sa SDL_version - * \sa SDL_GetVersion + * \sa SDL_version + * \sa SDL_GetVersion */ #define SDL_VERSION(x) \ { \ @@ -107,48 +107,56 @@ 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. + * 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; + * This function may be called safely at any time, even before SDL_Init(). * - * 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 + * \param ver the SDL_version structure that contains the version information * - * This function may be called safely at any time, even before SDL_Init(). - * - * \sa SDL_VERSION + * \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 - * exact revision of the SDL library in use, and is only useful in comparing - * against other revisions. It is NOT an incrementing number. + * 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. - * This number was not reliable for several reasons, but more importantly, - * SDL is now hosted in a git repository, which does not offer numbers at - * all, only hashes. This function only ever returns zero now. Don't use it. + * When SDL was hosted in a Mercurial repository, and was built carefully, + * this would return the revision number that the build was created from. + * This number was not reliable for several reasons, but more importantly, + * SDL is now hosted in a git repository, which does not offer numbers at + * all, only hashes. This function only ever returns zero now. Don't use it. */ extern SDL_DEPRECATED DECLSPEC int SDLCALL SDL_GetRevisionNumber(void); diff --git a/include/SDL_video.h b/include/SDL_video.h index 0860ea04b..b9e3782ac 100644 --- a/include/SDL_video.h +++ b/include/SDL_video.h @@ -265,798 +265,1137 @@ typedef enum /* Function prototypes */ /** - * \brief Get the number of video drivers compiled into SDL + * Get the number of video drivers compiled into SDL. * - * \sa SDL_GetVideoDriver() + * \returns a number >= 1 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_GetVideoDriver */ extern DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void); /** - * \brief Get the name of a built in video driver. + * Get the name of a built in video driver. * - * \note The video drivers are presented in the order in which they are - * normally checked during initialization. + * The video drivers are presented in the order in which they are normally + * checked during initialization. * - * \sa SDL_GetNumVideoDrivers() + * \param index the index of a video driver + * \returns the name of the video driver with the given **index**. + * + * \sa SDL_GetNumVideoDrivers */ extern DECLSPEC const char *SDLCALL SDL_GetVideoDriver(int index); /** - * \brief Initialize the video subsystem, optionally specifying a video driver. + * Initialize the video subsystem, optionally specifying a video driver. * - * \param driver_name Initialize a specific driver by name, or NULL for the - * default video driver. + * This function initializes the video subsystem, setting up a connection to + * the window manager, etc, and determines the available display modes and + * pixel formats, but does not initialize a window or graphics mode. * - * \return 0 on success, -1 on error + * If you use this function and you haven't used the SDL_INIT_VIDEO flag with + * either SDL_Init() or SDL_InitSubSystem(), you should call SDL_VideoQuit() + * before calling SDL_Quit(). * - * This function initializes the video subsystem; setting up a connection - * to the window manager, etc, and determines the available display modes - * and pixel formats, but does not initialize a window or graphics mode. + * It is safe to call this function multiple times. SDL_VideoInit() will call + * SDL_VideoQuit() itself if the video subsystem has already been initialized. * - * \sa SDL_VideoQuit() + * You can use SDL_GetNumVideoDrivers() and SDL_GetVideoDriver() to find a + * specific `driver_name`. + * + * \param driver_name the name of a video driver to initialize, or NULL for + * the default driver + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_GetNumVideoDrivers + * \sa SDL_GetVideoDriver + * \sa SDL_InitSubSystem + * \sa SDL_VideoQuit */ extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name); /** - * \brief Shuts down the video subsystem. + * Shut down the video subsystem, if initialized with SDL_VideoInit(). * - * This function closes all windows, and restores the original video mode. + * This function closes all windows, and restores the original video mode. * - * \sa SDL_VideoInit() + * \sa SDL_VideoInit */ extern DECLSPEC void SDLCALL SDL_VideoQuit(void); /** - * \brief Returns the name of the currently initialized video driver. + * Get the name of the currently initialized video driver. * - * \return The name of the current video driver or NULL if no driver - * has been initialized + * \returns the name of the current video driver or NULL if no driver has been + * initialized. * - * \sa SDL_GetNumVideoDrivers() - * \sa SDL_GetVideoDriver() + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetNumVideoDrivers + * \sa SDL_GetVideoDriver */ extern DECLSPEC const char *SDLCALL SDL_GetCurrentVideoDriver(void); /** - * \brief Returns the number of available video displays. + * Get the number of available video displays. * - * \sa SDL_GetDisplayBounds() + * \returns a number >= 1 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_GetDisplayBounds */ extern DECLSPEC int SDLCALL SDL_GetNumVideoDisplays(void); /** - * \brief Get the name of a display in UTF-8 encoding + * Get the name of a display in UTF-8 encoding. * - * \return The name of a display, or NULL for an invalid display index. + * \param displayIndex the index of display from which the name should be + * queried + * \returns the name of a display or NULL for an invalid display index or + * failure; call SDL_GetError() for more information. * - * \sa SDL_GetNumVideoDisplays() + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetNumVideoDisplays */ extern DECLSPEC const char * SDLCALL SDL_GetDisplayName(int displayIndex); /** - * \brief Get the desktop area represented by a display, with the primary - * display located at 0,0 + * Get the desktop area represented by a display. * - * \return 0 on success, or -1 if the index is out of range. + * The primary display (`displayIndex` zero) is always located at 0,0. * - * \sa SDL_GetNumVideoDisplays() + * \param displayIndex the index of the display to query + * \param rect the SDL_Rect structure filled in with the display bounds + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_GetNumVideoDisplays */ extern DECLSPEC int SDLCALL SDL_GetDisplayBounds(int displayIndex, SDL_Rect * rect); /** - * \brief Get the usable desktop area represented by a display, with the - * primary display located at 0,0 + * Get the usable desktop area represented by a display. * - * This is the same area as SDL_GetDisplayBounds() reports, but with portions - * reserved by the system removed. For example, on Mac OS X, this subtracts - * the area occupied by the menu bar and dock. + * The primary display (`displayIndex` zero) is always located at 0,0. * - * Setting a window to be fullscreen generally bypasses these unusable areas, - * so these are good guidelines for the maximum space available to a - * non-fullscreen window. + * This is the same area as SDL_GetDisplayBounds() reports, but with portions + * reserved by the system removed. For example, on Apple's macOS, this + * subtracts the area occupied by the menu bar and dock. * - * \return 0 on success, or -1 if the index is out of range. + * Setting a window to be fullscreen generally bypasses these unusable areas, + * so these are good guidelines for the maximum space available to a + * non-fullscreen window. * - * \sa SDL_GetDisplayBounds() - * \sa SDL_GetNumVideoDisplays() + * The parameter `rect` is ignored if it is NULL. + * + * This function also returns -1 if the parameter `displayIndex` is out of + * range. + * + * \param displayIndex the index of the display to query the usable bounds + * from + * \param rect the SDL_Rect structure filled in with the display bounds + * \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.5. + * + * \sa SDL_GetDisplayBounds + * \sa SDL_GetNumVideoDisplays */ extern DECLSPEC int SDLCALL SDL_GetDisplayUsableBounds(int displayIndex, SDL_Rect * rect); /** - * \brief Get the dots/pixels-per-inch for a display + * Get the dots/pixels-per-inch for a display. * - * \note Diagonal, horizontal and vertical DPI can all be optionally - * returned if the parameter is non-NULL. + * Diagonal, horizontal and vertical DPI can all be optionally returned if the + * appropriate parameter is non-NULL. * - * \return 0 on success, or -1 if no DPI information is available or the index is out of range. + * A failure of this function usually means that either no DPI information is + * available or the `displayIndex` is out of range. * - * \sa SDL_GetNumVideoDisplays() + * \param displayIndex the index of the display from which DPI information + * should be queried + * \param ddpi a pointer filled in with the diagonal DPI of the display; may + * be NULL + * \param hdpi a pointer filled in with the horizontal DPI of the display; may + * be NULL + * \param vdpi a pointer filled in with the vertical DPI of the display; may + * be NULL + * \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_GetNumVideoDisplays */ extern DECLSPEC int SDLCALL SDL_GetDisplayDPI(int displayIndex, float * ddpi, float * hdpi, float * vdpi); /** - * \brief Get the orientation of a display + * Get the orientation of a display. * - * \return The orientation of the display, or SDL_ORIENTATION_UNKNOWN if it isn't available. + * \params displayIndex the index of the display to query + * \returns The SDL_DisplayOrientation enum value of the display, or + * `SDL_ORIENTATION_UNKNOWN` if it isn't available. * - * \sa SDL_GetNumVideoDisplays() + * \sa SDL_GetNumVideoDisplays() */ extern DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetDisplayOrientation(int displayIndex); /** - * \brief Returns the number of available display modes. + * Get the number of available display modes. * - * \sa SDL_GetDisplayMode() + * The `displayIndex` needs to be in the range from 0 to + * SDL_GetNumVideoDisplays() - 1. + * + * \param displayIndex the index of the display to query + * \returns a number >= 1 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_GetDisplayMode + * \sa SDL_GetNumVideoDisplays */ extern DECLSPEC int SDLCALL SDL_GetNumDisplayModes(int displayIndex); /** - * \brief Fill in information about a specific display mode. + * Get information about a specific display mode. * - * \note The display modes are sorted in this priority: - * \li bits per pixel -> more colors to fewer colors - * \li width -> largest to smallest - * \li height -> largest to smallest - * \li refresh rate -> highest to lowest + * The display modes are sorted in this priority: * - * \sa SDL_GetNumDisplayModes() + * - width -> largest to smallest + * + * - height -> largest to smallest + * + * - bits per pixel -> more colors to fewer colors + * + * - packed pixel layout -> largest to smallest + * + * - refresh rate -> highest to lowest + * + * \param displayIndex the index of the display to query + * \param modeIndex the index of the display mode to query + * \param mode an SDL_DisplayMode structure filled in with the mode at + * `modeIndex` + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_GetNumDisplayModes */ extern DECLSPEC int SDLCALL SDL_GetDisplayMode(int displayIndex, int modeIndex, SDL_DisplayMode * mode); /** - * \brief Fill in information about the desktop display mode. + * Get information about the desktop's display mode. + * + * There's a difference between this function and SDL_GetCurrentDisplayMode() + * when SDL runs fullscreen and has changed the resolution. In that case this + * function will return the previous native display mode, and not the current + * display mode. + * + * \param displayIndex the index of the display to query + * \param mode an SDL_DisplayMode structure filled in with the current display + * mode + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_GetCurrentDisplayMode + * \sa SDL_GetDisplayMode + * \sa SDL_SetWindowDisplayMode */ extern DECLSPEC int SDLCALL SDL_GetDesktopDisplayMode(int displayIndex, SDL_DisplayMode * mode); /** - * \brief Fill in information about the current display mode. + * Get information about the current display mode. + * + * There's a difference between this function and SDL_GetDesktopDisplayMode() + * when SDL runs fullscreen and has changed the resolution. In that case this + * function will return the current display mode, and not the previous native + * display mode. + * + * \param displayIndex the index of the display to query + * \param mode an SDL_DisplayMode structure filled in with the current display + * mode + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_GetDesktopDisplayMode + * \sa SDL_GetDisplayMode + * \sa SDL_GetNumVideoDisplays + * \sa SDL_SetWindowDisplayMode */ extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(int displayIndex, SDL_DisplayMode * mode); /** - * \brief Get the closest match to the requested display mode. + * Get the closest match to the requested display mode. * - * \param displayIndex The index of display from which mode should be queried. - * \param mode The desired display mode - * \param closest A pointer to a display mode to be filled in with the closest - * match of the available display modes. + * The available display modes are scanned and `closest` is filled in with + * the closest mode matching the requested mode and returned. The mode format + * and refresh rate default to the desktop mode if they are set to 0. The + * modes are scanned with size being first priority, format being second + * priority, and finally checking the refresh rate. If all the available modes + * are too small, then NULL is returned. * - * \return The passed in value \c closest, or NULL if no matching video mode - * was available. + * \param displayIndex the index of the display to query + * \param mode an SDL_DisplayMode structure containing the desired display + * mode + * \param closest an SDL_DisplayMode structure filled in with the closest + * match of the available display modes + * \returns the passed in value `closest` or NULL if no matching video mode + * was available; call SDL_GetError() for more information. * - * The available display modes are scanned, and \c closest is filled in with the - * closest mode matching the requested mode and returned. The mode format and - * refresh_rate default to the desktop mode if they are 0. The modes are - * scanned with size being first priority, format being second priority, and - * finally checking the refresh_rate. If all the available modes are too - * small, then NULL is returned. - * - * \sa SDL_GetNumDisplayModes() - * \sa SDL_GetDisplayMode() + * \sa SDL_GetDisplayMode + * \sa SDL_GetNumDisplayModes */ extern DECLSPEC SDL_DisplayMode * SDLCALL SDL_GetClosestDisplayMode(int displayIndex, const SDL_DisplayMode * mode, SDL_DisplayMode * closest); /** - * \brief Get the display index associated with a window. + * Get the index of the display associated with a window. * - * \return the display index of the display containing the center of the - * window, or -1 on error. + * \param window the window to query + * \returns the index of the display containing the center of the window on + * success or a negative error code on failure; call SDL_GetError() + * for more information. + * + * \sa SDL_GetDisplayBounds + * \sa SDL_GetNumVideoDisplays */ extern DECLSPEC int SDLCALL SDL_GetWindowDisplayIndex(SDL_Window * window); /** - * \brief Set the display mode used when a fullscreen window is visible. + * Set the display mode to use when a window is visible at fullscreen. * - * By default the window's dimensions and the desktop format and refresh rate - * are used. + * This only affects the display mode used when the window is fullscreen. To + * change the window size when the window is not fullscreen, use + * SDL_SetWindowSize(). * - * \param window The window for which the display mode should be set. - * \param mode The mode to use, or NULL for the default mode. + * \param window the window to affect + * \param mode the SDL_DisplayMode structure representing the mode to use, or + * NULL to use the window's dimensions and the desktop's format + * and refresh rate + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. * - * \return 0 on success, or -1 if setting the display mode failed. - * - * \sa SDL_GetWindowDisplayMode() - * \sa SDL_SetWindowFullscreen() + * \sa SDL_GetWindowDisplayMode + * \sa SDL_SetWindowFullscreen */ extern DECLSPEC int SDLCALL SDL_SetWindowDisplayMode(SDL_Window * window, - const SDL_DisplayMode - * mode); + const SDL_DisplayMode * mode); /** - * \brief Fill in information about the display mode used when a fullscreen - * window is visible. + * Query the display mode to use when a window is visible at fullscreen. * - * \sa SDL_SetWindowDisplayMode() - * \sa SDL_SetWindowFullscreen() + * \param window the window to query + * \param mode an SDL_DisplayMode structure filled in with the fullscreen + * display mode + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_SetWindowDisplayMode + * \sa SDL_SetWindowFullscreen */ extern DECLSPEC int SDLCALL SDL_GetWindowDisplayMode(SDL_Window * window, SDL_DisplayMode * mode); /** - * \brief Get the pixel format associated with the window. + * Get the pixel format associated with the window. + * + * \param window the window to query + * \returns the pixel format of the window on success or + * SDL_PIXELFORMAT_UNKNOWN on failure; call SDL_GetError() for more + * information. */ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window * window); /** - * \brief Create a window with the specified position, dimensions, and flags. + * Create a window with the specified position, dimensions, and flags. * - * \param title The title of the window, in UTF-8 encoding. - * \param x The x position of the window, ::SDL_WINDOWPOS_CENTERED, or - * ::SDL_WINDOWPOS_UNDEFINED. - * \param y The y position of the window, ::SDL_WINDOWPOS_CENTERED, or - * ::SDL_WINDOWPOS_UNDEFINED. - * \param w The width of the window, in screen coordinates. - * \param h The height of the window, in screen coordinates. - * \param flags The flags for the window, a mask of any of the following: - * ::SDL_WINDOW_FULLSCREEN, ::SDL_WINDOW_OPENGL, - * ::SDL_WINDOW_HIDDEN, ::SDL_WINDOW_BORDERLESS, - * ::SDL_WINDOW_RESIZABLE, ::SDL_WINDOW_MAXIMIZED, - * ::SDL_WINDOW_MINIMIZED, ::SDL_WINDOW_MOUSE_GRABBED, - * ::SDL_WINDOW_ALLOW_HIGHDPI, ::SDL_WINDOW_KEYBOARD_GRABBED, - * ::SDL_WINDOW_VULKAN, ::SDL_WINDOW_METAL. + * `flags` may be any of the following OR'd together: * - * \return The created window, or NULL if window creation failed. + * - `SDL_WINDOW_FULLSCREEN`: fullscreen window * - * If the window is created with the SDL_WINDOW_ALLOW_HIGHDPI flag, its size - * in pixels may differ from its size in screen coordinates on platforms with - * high-DPI support (e.g. iOS and Mac OS X). Use SDL_GetWindowSize() to query - * the client area's size in screen coordinates, and SDL_GL_GetDrawableSize(), - * SDL_Vulkan_GetDrawableSize(), or SDL_GetRendererOutputSize() to query the - * drawable size in pixels. + * - `SDL_WINDOW_FULLSCREEN_DESKTOP: fullscreen window at desktop resolution * - * If the window is created with any of the SDL_WINDOW_OPENGL or - * SDL_WINDOW_VULKAN flags, then the corresponding LoadLibrary function - * (SDL_GL_LoadLibrary or SDL_Vulkan_LoadLibrary) is called and the - * corresponding UnloadLibrary function is called by SDL_DestroyWindow(). + * - `SDL_WINDOW_OPENGL`: window usable with an OpenGL context * - * If SDL_WINDOW_VULKAN is specified and there isn't a working Vulkan driver, - * SDL_CreateWindow() will fail because SDL_Vulkan_LoadLibrary() will fail. + * - `SDL_WINDOW_VULKAN`: window usable with a Vulkan instance * - * If SDL_WINDOW_METAL is specified on an OS that does not support Metal, - * SDL_CreateWindow() will fail. + * - `SDL_WINDOW_METAL`: window usable with a Metal instance * - * \note On non-Apple devices, SDL requires you to either not link to the - * Vulkan loader or link to a dynamic library version. This limitation - * may be removed in a future version of SDL. + * - `SDL_WINDOW_HIDDEN`: window is not visible * - * \sa SDL_DestroyWindow() - * \sa SDL_GL_LoadLibrary() - * \sa SDL_Vulkan_LoadLibrary() + * - `SDL_WINDOW_BORDERLESS`: no window decoration + * + * - `SDL_WINDOW_RESIZABLE`: window can be resized + * + * - `SDL_WINDOW_MINIMIZED`: window is minimized + * + * - `SDL_WINDOW_MAXIMIZED`: window is maximized + * + * - `SDL_WINDOW_INPUT_GRABBED`: window has grabbed input focus + * + * - `SDL_WINDOW_ALLOW_HIGHDPI`: window should be created in high-DPI mode if + * supported (>= SDL 2.0.1) + * + * `SDL_WINDOW_SHOWN` is ignored by SDL_CreateWindow(). The SDL_Window is + * implicitly shown if SDL_WINDOW_HIDDEN is not set. `SDL_WINDOW_SHOWN` may be + * queried later using SDL_GetWindowFlags(). + * + * On Apple's macOS, you **must** set the NSHighResolutionCapable Info.plist + * property to YES, otherwise you will not receive a High-DPI OpenGL canvas. + * + * If the window is created with the `SDL_WINDOW_ALLOW_HIGHDPI` flag, its size + * in pixels may differ from its size in screen coordinates on platforms with + * high-DPI support (e.g. iOS and macOS). Use SDL_GetWindowSize() to query + * the client area's size in screen coordinates, and SDL_GL_GetDrawableSize() + * or SDL_GetRendererOutputSize() to query the drawable size in pixels. + * + * If the window is set fullscreen, the width and height parameters `w` and + * `h` will not be used. However, invalid size parameters (e.g. too large) + * may still fail. Window size is actually limited to 16384 x 16384 for all + * platforms at window creation. + * + * If the window is created with any of the SDL_WINDOW_OPENGL or + * SDL_WINDOW_VULKAN flags, then the corresponding LoadLibrary function + * (SDL_GL_LoadLibrary or SDL_Vulkan_LoadLibrary) is called and the + * corresponding UnloadLibrary function is called by SDL_DestroyWindow(). + * + * If SDL_WINDOW_VULKAN is specified and there isn't a working Vulkan driver, + * SDL_CreateWindow() will fail because SDL_Vulkan_LoadLibrary() will fail. + * + * If SDL_WINDOW_METAL is specified on an OS that does not support Metal, + * SDL_CreateWindow() will fail. + * + * On non-Apple devices, SDL requires you to either not link to the Vulkan + * loader or link to a dynamic library version. This limitation may be removed + * in a future version of SDL. + * + * \param title the title of the window, in UTF-8 encoding + * \param x the x position of the window, `SDL_WINDOWPOS_CENTERED`, or + * `SDL_WINDOWPOS_UNDEFINED` + * \param y the y position of the window, `SDL_WINDOWPOS_CENTERED`, or + * `SDL_WINDOWPOS_UNDEFINED` + * \param w the width of the window, in screen coordinates + * \param h the height of the window, in screen coordinates + * \param flags 0, or one or more SDL_WindowFlags OR'd together + * \returns the window that was created or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_CreateWindowFrom + * \sa SDL_DestroyWindow */ extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title, int x, int y, int w, int h, Uint32 flags); /** - * \brief Create an SDL window from an existing native window. + * Create an SDL window from an existing native window. * - * \param data A pointer to driver-dependent window creation data + * In some cases (e.g. OpenGL) and on some platforms (e.g. Microsoft Windows) + * the hint `SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT` needs to be configured + * before using SDL_CreateWindowFrom(). * - * \return The created window, or NULL if window creation failed. + * \param data a pointer to driver-dependent window creation data, typically + * your native window cast to a void* + * \returns the window that was created or NULL on failure; call + * SDL_GetError() for more information. * - * \sa SDL_DestroyWindow() + * \sa SDL_CreateWindow + * \sa SDL_DestroyWindow */ extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindowFrom(const void *data); /** - * \brief Get the numeric ID of a window, for logging purposes. + * Get the numeric ID of a window. + * + * The numeric ID is what SDL_WindowEvent references, and is necessary to map + * these events to specific SDL_Window objects. + * + * \param window the window to query + * \returns the ID of the window on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetWindowFromID */ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowID(SDL_Window * window); /** - * \brief Get a window from a stored ID, or NULL if it doesn't exist. + * Get a window from a stored ID. + * + * The numeric ID is what SDL_WindowEvent references, and is necessary to map + * these events to specific SDL_Window objects. + * + * \param id the ID of the window + * \returns the window associated with `id` or NULL if it doesn't exist; + * call SDL_GetError() for more information. + * + * \sa SDL_GetWindowID */ extern DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromID(Uint32 id); /** - * \brief Get the window flags. + * Get the window flags. + * + * \param window the window to query + * \returns a mask of the SDL_WindowFlags associated with `window` + * + * \sa SDL_CreateWindow + * \sa SDL_HideWindow + * \sa SDL_MaximizeWindow + * \sa SDL_MinimizeWindow + * \sa SDL_SetWindowFullscreen + * \sa SDL_SetWindowGrab + * \sa SDL_ShowWindow */ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowFlags(SDL_Window * window); /** - * \brief Set the title of a window, in UTF-8 format. + * Set the title of a window. * - * \sa SDL_GetWindowTitle() + * This string is expected to be in UTF-8 encoding. + * + * \param window the window to change + * \param title the desired window title in UTF-8 format + * + * \sa SDL_GetWindowTitle */ extern DECLSPEC void SDLCALL SDL_SetWindowTitle(SDL_Window * window, const char *title); /** - * \brief Get the title of a window, in UTF-8 format. + * Get the title of a window. * - * \sa SDL_SetWindowTitle() + * \param window the window to query + * \returns the title of the window in UTF-8 format or "" if there is no + * title. + * + * \sa SDL_SetWindowTitle */ extern DECLSPEC const char *SDLCALL SDL_GetWindowTitle(SDL_Window * window); /** - * \brief Set the icon for a window. + * Set the icon for a window. * - * \param window The window for which the icon should be set. - * \param icon The icon for the window. + * \param window the window to change + * \param icon an SDL_Surface structure containing the icon for the window */ extern DECLSPEC void SDLCALL SDL_SetWindowIcon(SDL_Window * window, SDL_Surface * icon); /** - * \brief Associate an arbitrary named pointer with a window. + * Associate an arbitrary named pointer with a window. * - * \param window The window to associate with the pointer. - * \param name The name of the pointer. - * \param userdata The associated pointer. + * `name` is case-sensitive. * - * \return The previous value associated with 'name' + * \param window the window to associate with the pointer + * \param name the name of the pointer + * \param userdata the associated pointer + * \returns the previous value associated with `name`. * - * \note The name is case-sensitive. - * - * \sa SDL_GetWindowData() + * \sa SDL_GetWindowData */ extern DECLSPEC void* SDLCALL SDL_SetWindowData(SDL_Window * window, const char *name, void *userdata); /** - * \brief Retrieve the data pointer associated with a window. + * Retrieve the data pointer associated with a window. * - * \param window The window to query. - * \param name The name of the pointer. + * \param window the window to query + * \param name the name of the pointer + * \returns the value associated with `name`. * - * \return The value associated with 'name' - * - * \sa SDL_SetWindowData() + * \sa SDL_SetWindowData */ extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_Window * window, const char *name); /** - * \brief Set the position of a window. + * Set the position of a window. * - * \param window The window to reposition. - * \param x The x coordinate of the window in screen coordinates, or - * ::SDL_WINDOWPOS_CENTERED or ::SDL_WINDOWPOS_UNDEFINED. - * \param y The y coordinate of the window in screen coordinates, or - * ::SDL_WINDOWPOS_CENTERED or ::SDL_WINDOWPOS_UNDEFINED. + * The window coordinate origin is the upper left of the display. * - * \note The window coordinate origin is the upper left of the display. + * \param window the window to reposition + * \param x the x coordinate of the window in screen coordinates, or + * `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED` + * \param y the y coordinate of the window in screen coordinates, or + * `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED` * - * \sa SDL_GetWindowPosition() + * \sa SDL_GetWindowPosition */ extern DECLSPEC void SDLCALL SDL_SetWindowPosition(SDL_Window * window, int x, int y); /** - * \brief Get the position of a window. + * Get the position of a window. * - * \param window The window to query. - * \param x Pointer to variable for storing the x position, in screen - * coordinates. May be NULL. - * \param y Pointer to variable for storing the y position, in screen - * coordinates. May be NULL. + * If you do not need the value for one of the positions a NULL may be passed + * in the `x` or `y` parameter. * - * \sa SDL_SetWindowPosition() + * \param window the window to query + * \param x a pointer filled in with the x position of the window, in screen + * coordinates, may be NULL + * \param y a pointer filled in with the y position of the window, in screen + * coordinates, may be NULL + * + * \sa SDL_SetWindowPosition */ extern DECLSPEC void SDLCALL SDL_GetWindowPosition(SDL_Window * window, int *x, int *y); /** - * \brief Set the size of a window's client area. + * Set the size of a window's client area. * - * \param window The window to resize. - * \param w The width of the window, in screen coordinates. Must be >0. - * \param h The height of the window, in screen coordinates. Must be >0. + * The window size in screen coordinates may differ from the size in pixels, + * if the window was created with `SDL_WINDOW_ALLOW_HIGHDPI` on a platform + * with high-dpi support (e.g. iOS or macOS). Use SDL_GL_GetDrawableSize() or + * SDL_GetRendererOutputSize() to get the real client area size in pixels. * - * \note Fullscreen windows automatically match the size of the display mode, - * and you should use SDL_SetWindowDisplayMode() to change their size. + * Fullscreen windows automatically match the size of the display mode, and + * you should use SDL_SetWindowDisplayMode() to change their size. * - * The window size in screen coordinates may differ from the size in pixels, if - * the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a platform with - * high-dpi support (e.g. iOS or OS X). Use SDL_GL_GetDrawableSize() or - * SDL_GetRendererOutputSize() to get the real client area size in pixels. + * \param window the window to change + * \param w the width of the window in pixels, in screen coordinates, must be + * > 0 + * \param h the height of the window in pixels, in screen coordinates, must be + * > 0 * - * \sa SDL_GetWindowSize() - * \sa SDL_SetWindowDisplayMode() + * \sa SDL_GetWindowSize + * \sa SDL_SetWindowDisplayMode */ extern DECLSPEC void SDLCALL SDL_SetWindowSize(SDL_Window * window, int w, int h); /** - * \brief Get the size of a window's client area. + * Get the size of a window's client area. * - * \param window The window to query. - * \param w Pointer to variable for storing the width, in screen - * coordinates. May be NULL. - * \param h Pointer to variable for storing the height, in screen - * coordinates. May be NULL. + * NULL can safely be passed as the `w` or `h` parameter if the width or + * height value is not desired. * - * The window size in screen coordinates may differ from the size in pixels, if - * the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a platform with - * high-dpi support (e.g. iOS or OS X). Use SDL_GL_GetDrawableSize() or - * SDL_GetRendererOutputSize() to get the real client area size in pixels. + * The window size in screen coordinates may differ from the size in pixels, + * if the window was created with `SDL_WINDOW_ALLOW_HIGHDPI` on a platform + * with high-dpi support (e.g. iOS or macOS). Use SDL_GL_GetDrawableSize(), + * SDL_Vulkan_GetDrawableSize(), or SDL_GetRendererOutputSize() to get the + * real client area size in pixels. * - * \sa SDL_SetWindowSize() + * \param window the window to query the width and height from + * \param w a pointer filled in with the width of the window, in screen + * coordinates, may be NULL + * \param h a pointer filled in with the height of the window, in screen + * coordinates, may be NULL + * + * \sa SDL_GL_GetDrawableSize + * \sa SDL_Vulkan_GetDrawableSize + * \sa SDL_SetWindowSize */ extern DECLSPEC void SDLCALL SDL_GetWindowSize(SDL_Window * window, int *w, int *h); /** - * \brief Get the size of a window's borders (decorations) around the client area. + * Get the size of a window's borders (decorations) around the client area. * - * \param window The window to query. - * \param top Pointer to variable for storing the size of the top border. NULL is permitted. - * \param left Pointer to variable for storing the size of the left border. NULL is permitted. - * \param bottom Pointer to variable for storing the size of the bottom border. NULL is permitted. - * \param right Pointer to variable for storing the size of the right border. NULL is permitted. + * Note: If this function fails (returns -1), the size values will be + * initialized to 0, 0, 0, 0 (if a non-NULL pointer is provided), as if the + * window in question was borderless. * - * \return 0 on success, or -1 if getting this information is not supported. + * This function also returns -1 if getting the information is not supported. * - * \note if this function fails (returns -1), the size values will be - * initialized to 0, 0, 0, 0 (if a non-NULL pointer is provided), as - * if the window in question was borderless. + * \param window the window to query the size values of the border + * (decorations) from + * \param top pointer to variable for storing the size of the top border; NULL + * is permitted + * \param left pointer to variable for storing the size of the left border; + * NULL is permitted + * \param bottom pointer to variable for storing the size of the bottom + * border; NULL is permitted + * \param right pointer to variable for storing the size of the right border; + * NULL is permitted + * \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.5. + * + * \sa SDL_GetWindowSize */ extern DECLSPEC int SDLCALL SDL_GetWindowBordersSize(SDL_Window * window, int *top, int *left, int *bottom, int *right); /** - * \brief Set the minimum size of a window's client area. + * Set the minimum size of a window's client area. * - * \param window The window to set a new minimum size. - * \param min_w The minimum width of the window, must be >0 - * \param min_h The minimum height of the window, must be >0 + * \param window the window to change + * \param min_w the minimum width of the window in pixels + * \param min_h the minimum height of the window in pixels * - * \note You can't change the minimum size of a fullscreen window, it - * automatically matches the size of the display mode. - * - * \sa SDL_GetWindowMinimumSize() - * \sa SDL_SetWindowMaximumSize() + * \sa SDL_GetWindowMinimumSize + * \sa SDL_SetWindowMaximumSize */ extern DECLSPEC void SDLCALL SDL_SetWindowMinimumSize(SDL_Window * window, int min_w, int min_h); /** - * \brief Get the minimum size of a window's client area. + * Get the minimum size of a window's client area. * - * \param window The window to query. - * \param w Pointer to variable for storing the minimum width, may be NULL - * \param h Pointer to variable for storing the minimum height, may be NULL + * \param window the window to query + * \param w a pointer filled in with the minimum width of the window, may be + * NULL + * \param h a pointer filled in with the minimum height of the window, may be + * NULL * - * \sa SDL_GetWindowMaximumSize() - * \sa SDL_SetWindowMinimumSize() + * \sa SDL_GetWindowMaximumSize + * \sa SDL_SetWindowMinimumSize */ extern DECLSPEC void SDLCALL SDL_GetWindowMinimumSize(SDL_Window * window, int *w, int *h); /** - * \brief Set the maximum size of a window's client area. + * Set the maximum size of a window's client area. * - * \param window The window to set a new maximum size. - * \param max_w The maximum width of the window, must be >0 - * \param max_h The maximum height of the window, must be >0 + * \param window the window to change + * \param max_w the maximum width of the window in pixels + * \param max_h the maximum height of the window in pixels * - * \note You can't change the maximum size of a fullscreen window, it - * automatically matches the size of the display mode. - * - * \sa SDL_GetWindowMaximumSize() - * \sa SDL_SetWindowMinimumSize() + * \sa SDL_GetWindowMaximumSize + * \sa SDL_SetWindowMinimumSize */ extern DECLSPEC void SDLCALL SDL_SetWindowMaximumSize(SDL_Window * window, int max_w, int max_h); /** - * \brief Get the maximum size of a window's client area. + * Get the maximum size of a window's client area. * - * \param window The window to query. - * \param w Pointer to variable for storing the maximum width, may be NULL - * \param h Pointer to variable for storing the maximum height, may be NULL + * \param window the window to query + * \param w a pointer filled in with the maximum width of the window, may be + * NULL + * \param h a pointer filled in with the maximum height of the window, may be + * NULL * - * \sa SDL_GetWindowMinimumSize() - * \sa SDL_SetWindowMaximumSize() + * \sa SDL_GetWindowMinimumSize + * \sa SDL_SetWindowMaximumSize */ extern DECLSPEC void SDLCALL SDL_GetWindowMaximumSize(SDL_Window * window, int *w, int *h); /** - * \brief Set the border state of a window. + * Set the border state of a window. * - * This will add or remove the window's SDL_WINDOW_BORDERLESS flag and - * add or remove the border from the actual window. This is a no-op if the - * window's border already matches the requested state. + * This will add or remove the window's `SDL_WINDOW_BORDERLESS` flag and add + * or remove the border from the actual window. This is a no-op if the + * window's border already matches the requested state. * - * \param window The window of which to change the border state. - * \param bordered SDL_FALSE to remove border, SDL_TRUE to add border. + * You can't change the border state of a fullscreen window. * - * \note You can't change the border state of a fullscreen window. + * \param window the window of which to change the border state + * \param bordered SDL_FALSE to remove border, SDL_TRUE to add border * - * \sa SDL_GetWindowFlags() + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetWindowFlags */ extern DECLSPEC void SDLCALL SDL_SetWindowBordered(SDL_Window * window, SDL_bool bordered); /** - * \brief Set the user-resizable state of a window. + * Set the user-resizable state of a window. * - * This will add or remove the window's SDL_WINDOW_RESIZABLE flag and - * allow/disallow user resizing of the window. This is a no-op if the - * window's resizable state already matches the requested state. + * This will add or remove the window's `SDL_WINDOW_RESIZABLE` flag and + * allow/disallow user resizing of the window. This is a no-op if the window's + * resizable state already matches the requested state. * - * \param window The window of which to change the resizable state. - * \param resizable SDL_TRUE to allow resizing, SDL_FALSE to disallow. + * You can't change the resizable state of a fullscreen window. * - * \note You can't change the resizable state of a fullscreen window. + * \param window the window of which to change the resizable state + * \param resizable SDL_TRUE to allow resizing, SDL_FALSE to disallow * - * \sa SDL_GetWindowFlags() + * \since This function is available since SDL 2.0.5. + * + * \sa SDL_GetWindowFlags */ extern DECLSPEC void SDLCALL SDL_SetWindowResizable(SDL_Window * window, SDL_bool resizable); /** - * \brief Show a window. + * Show a window. * - * \sa SDL_HideWindow() + * \param window the window to show + * + * \sa SDL_HideWindow + * \sa SDL_RaiseWindow */ extern DECLSPEC void SDLCALL SDL_ShowWindow(SDL_Window * window); /** - * \brief Hide a window. + * Hide a window. * - * \sa SDL_ShowWindow() + * \param window the window to hide + * + * \sa SDL_ShowWindow */ extern DECLSPEC void SDLCALL SDL_HideWindow(SDL_Window * window); /** - * \brief Raise a window above other windows and set the input focus. + * Raise a window above other windows and set the input focus. + * + * \param window the window to raise */ extern DECLSPEC void SDLCALL SDL_RaiseWindow(SDL_Window * window); /** - * \brief Make a window as large as possible. + * Make a window as large as possible. * - * \sa SDL_RestoreWindow() + * \param window the window to maximize + * + * \sa SDL_MinimizeWindow + * \sa SDL_RestoreWindow */ extern DECLSPEC void SDLCALL SDL_MaximizeWindow(SDL_Window * window); /** - * \brief Minimize a window to an iconic representation. + * Minimize a window to an iconic representation. * - * \sa SDL_RestoreWindow() + * \param window the window to minimize + * + * \sa SDL_MaximizeWindow + * \sa SDL_RestoreWindow */ extern DECLSPEC void SDLCALL SDL_MinimizeWindow(SDL_Window * window); /** - * \brief Restore the size and position of a minimized or maximized window. + * Restore the size and position of a minimized or maximized window. * - * \sa SDL_MaximizeWindow() - * \sa SDL_MinimizeWindow() + * *You can add useful comments here* + * + * \param window the window to restore + * + * \sa SDL_MaximizeWindow + * \sa SDL_MinimizeWindow */ extern DECLSPEC void SDLCALL SDL_RestoreWindow(SDL_Window * window); /** - * \brief Set a window's fullscreen state. + * Set a window's fullscreen state. * - * \return 0 on success, or -1 if setting the display mode failed. + * `flags` may be `SDL_WINDOW_FULLSCREEN`, for "real" fullscreen with a + * videomode change; `SDL_WINDOW_FULLSCREEN_DESKTOP` for "fake" fullscreen + * that takes the size of the desktop; and 0 for windowed mode. * - * \sa SDL_SetWindowDisplayMode() - * \sa SDL_GetWindowDisplayMode() + * \param window the window to change + * \param flags `SDL_WINDOW_FULLSCREEN`, `SDL_WINDOW_FULLSCREEN_DESKTOP` or 0 + * \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_GetWindowDisplayMode + * \sa SDL_SetWindowDisplayMode */ extern DECLSPEC int SDLCALL SDL_SetWindowFullscreen(SDL_Window * window, Uint32 flags); /** - * \brief Get the SDL surface associated with the window. + * Get the SDL surface associated with the window. * - * \return The window's framebuffer surface, or NULL on error. + * A new surface will be created with the optimal format for the window, if + * necessary. This surface will be freed when the window is destroyed. Do not + * free this surface. * - * A new surface will be created with the optimal format for the window, - * if necessary. This surface will be freed when the window is destroyed. + * This surface will be invalidated if the window is resized. After resizing a + * window this function must be called again to return a valid surface. * - * \note You may not combine this with 3D or the rendering API on this window. + * You may not combine this with 3D or the rendering API on this window. * - * \sa SDL_UpdateWindowSurface() - * \sa SDL_UpdateWindowSurfaceRects() + * This function is affected by `SDL_HINT_FRAMEBUFFER_ACCELERATION`. + * + * \param window the window to query + * \returns the surface associated with the window, or NULL on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_UpdateWindowSurface + * \sa SDL_UpdateWindowSurfaceRects */ extern DECLSPEC SDL_Surface * SDLCALL SDL_GetWindowSurface(SDL_Window * window); /** - * \brief Copy the window surface to the screen. + * Copy the window surface to the screen. * - * \return 0 on success, or -1 on error. + * This is the function you use to reflect any changes to the surface on the + * screen. * - * \sa SDL_GetWindowSurface() - * \sa SDL_UpdateWindowSurfaceRects() + * This function is equivalent to the SDL 1.2 API SDL_Flip(). + * + * \param window the window to update + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_GetWindowSurface + * \sa SDL_UpdateWindowSurfaceRects */ extern DECLSPEC int SDLCALL SDL_UpdateWindowSurface(SDL_Window * window); /** - * \brief Copy a number of rectangles on the window surface to the screen. + * Copy areas of the window surface to the screen. * - * \return 0 on success, or -1 on error. + * This is the function you use to reflect changes to portions of the surface + * on the screen. * - * \sa SDL_GetWindowSurface() - * \sa SDL_UpdateWindowSurface() + * This function is equivalent to the SDL 1.2 API SDL_UpdateRects(). + * + * \param window the window to update + * \param rects an array of SDL_Rect structures representing areas of the + * surface to copy + * \param numrects the number of rectangles + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_GetWindowSurface + * \sa SDL_UpdateWindowSurface */ extern DECLSPEC int SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window * window, const SDL_Rect * rects, int numrects); /** - * \brief Set a window's input grab mode. + * Set a window's input grab mode. * - * \param window The window for which the input grab mode should be set. - * \param grabbed This is SDL_TRUE to grab input, and SDL_FALSE to release input. + * When input is grabbed the mouse is confined to the window. * - * If the caller enables a grab while another window is currently grabbed, - * the other window loses its grab in favor of the caller's window. + * If the caller enables a grab while another window is currently grabbed, the + * other window loses its grab in favor of the caller's window. * - * If SDL_HINT_GRAB_KEYBOARD=1, this also grabs keyboard input. + * \param window the window for which the input grab mode should be set + * \param grabbed SDL_TRUE to grab input or SDL_FALSE to release input * - * \sa SDL_GetWindowGrab() - * \sa SDL_SetWindowKeyboardGrab() - * \sa SDL_SetWindowMouseGrab() + * \sa SDL_GetGrabbedWindow + * \sa SDL_GetWindowGrab */ extern DECLSPEC void SDLCALL SDL_SetWindowGrab(SDL_Window * window, SDL_bool grabbed); /** - * \brief Set a window's keyboard grab mode. + * Set a window's keyboard grab mode. * - * \param window The window for which the keyboard grab mode should be set. - * \param grabbed This is SDL_TRUE to grab keyboard, and SDL_FALSE to release keyboard grab. + * If the caller enables a grab while another window is currently grabbed, + * the other window loses its grab in favor of the caller's window. * - * If the caller enables a grab while another window is currently grabbed, - * the other window loses its grab in favor of the caller's window. + * \param window The window for which the keyboard grab mode should be set. + * \param grabbed This is SDL_TRUE to grab keyboard, and SDL_FALSE to release. * - * \sa SDL_GetWindowKeyboardGrab() - * \sa SDL_SetWindowMouseGrab() - * \sa SDL_SetWindowGrab() + * \sa SDL_GetWindowKeyboardGrab + * \sa SDL_SetWindowMouseGrab + * \sa SDL_SetWindowGrab */ extern DECLSPEC void SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window * window, SDL_bool grabbed); /** - * \brief Set a window's mouse grab mode. + * Set a window's mouse grab mode. * - * \param window The window for which the mouse grab mode should be set. - * \param grabbed This is SDL_TRUE to grab mouse, and SDL_FALSE to release mouse grab. + * \param window The window for which the mouse grab mode should be set. + * \param grabbed This is SDL_TRUE to grab mouse, and SDL_FALSE to release. * - * If the caller enables a grab while another window is currently grabbed, - * the other window loses its grab in favor of the caller's window. + * If the caller enables a grab while another window is currently grabbed, + * the other window loses its grab in favor of the caller's window. * - * \sa SDL_GetWindowMouseGrab() - * \sa SDL_SetWindowKeyboardGrab() - * \sa SDL_SetWindowGrab() + * \sa SDL_GetWindowMouseGrab + * \sa SDL_SetWindowKeyboardGrab + * \sa SDL_SetWindowGrab */ extern DECLSPEC void SDLCALL SDL_SetWindowMouseGrab(SDL_Window * window, SDL_bool grabbed); /** - * \brief Get a window's input grab mode. + * Get a window's input grab mode. * - * \return This returns SDL_TRUE if keyboard or mouse input is grabbed, and SDL_FALSE otherwise. + * \param window the window to query + * \returns SDL_TRUE if input is grabbed, SDL_FALSE otherwise. * - * \sa SDL_SetWindowGrab() - * \sa SDL_GetWindowMouseGrab() - * \sa SDL_GetWindowKeyboardGrab() + * \sa SDL_SetWindowGrab */ extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowGrab(SDL_Window * window); /** - * \brief Get a window's keyboard grab mode. + * Get a window's keyboard grab mode. * - * \return This returns SDL_TRUE if keyboard is grabbed, and SDL_FALSE otherwise. + * \param window the window to query + * \returns SDL_TRUE if keyboard is grabbed, and SDL_FALSE otherwise. * - * \sa SDL_SetWindowKeyboardGrab() - * \sa SDL_GetWindowGrab() + * \sa SDL_SetWindowKeyboardGrab + * \sa SDL_GetWindowGrab */ extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window * window); /** - * \brief Get a window's mouse grab mode. + * Get a window's mouse grab mode. * - * \return This returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise. + * \param window the window to query + * \returns This returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise. * - * \sa SDL_SetWindowKeyboardGrab() - * \sa SDL_GetWindowGrab() + * \sa SDL_SetWindowKeyboardGrab + * \sa SDL_GetWindowGrab */ extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowMouseGrab(SDL_Window * window); /** - * \brief Get the window that currently has an input grab enabled. + * Get the window that currently has an input grab enabled. * - * \return This returns the window if input is grabbed, and NULL otherwise. + * \returns the window if input is grabbed or NULL otherwise. * - * \sa SDL_SetWindowGrab() + * \since This function is available since SDL 2.0.4. + * + * \sa SDL_GetWindowGrab + * \sa SDL_SetWindowGrab */ extern DECLSPEC SDL_Window * SDLCALL SDL_GetGrabbedWindow(void); /** - * \brief Set the brightness (gamma correction) for a window. + * Set the brightness (gamma multiplier) for a given window's display. * - * \return 0 on success, or -1 if setting the brightness isn't supported. + * Despite the name and signature, this method sets the brightness of the + * entire display, not an individual window. A window is considered to be + * owned by the display that contains the window's center pixel. (The index of + * this display can be retrieved using SDL_GetWindowDisplayIndex().) The + * brightness set will not follow the window if it is moved to another + * display. * - * \sa SDL_GetWindowBrightness() - * \sa SDL_SetWindowGammaRamp() + * Many platforms will refuse to set the display brightness in modern times. + * You are better off using a shader to adjust gamma during rendering, or + * something similar. + * + * \param window the window used to select the display whose brightness will + * be changed + * \param brightness the brightness (gamma multiplier) value to set where 0.0 + * is completely dark and 1.0 is normal brightness + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_GetWindowBrightness + * \sa SDL_SetWindowGammaRamp */ extern DECLSPEC int SDLCALL SDL_SetWindowBrightness(SDL_Window * window, float brightness); /** - * \brief Get the brightness (gamma correction) for a window. + * Get the brightness (gamma multiplier) for a given window's display. * - * \return The last brightness value passed to SDL_SetWindowBrightness() + * Despite the name and signature, this method retrieves the brightness of the + * entire display, not an individual window. A window is considered to be + * owned by the display that contains the window's center pixel. (The index of + * this display can be retrieved using SDL_GetWindowDisplayIndex().) * - * \sa SDL_SetWindowBrightness() + * \param window the window used to select the display whose brightness will + * be queried + * \returns the brightness for the display where 0.0 is completely dark and + * 1.0 is normal brightness. + * + * \sa SDL_SetWindowBrightness */ extern DECLSPEC float SDLCALL SDL_GetWindowBrightness(SDL_Window * window); /** - * \brief Set the opacity for a window + * Set the opacity for a window. * - * \param window The window which will be made transparent or opaque - * \param opacity Opacity (0.0f - transparent, 1.0f - opaque) This will be - * clamped internally between 0.0f and 1.0f. + * The parameter `opacity` will be clamped internally between 0.0f + * (transparent) and 1.0f (opaque). * - * \return 0 on success, or -1 if setting the opacity isn't supported. + * This function also returns -1 if setting the opacity isn't supported. * - * \sa SDL_GetWindowOpacity() + * \param window the window which will be made transparent or opaque + * \param opacity the opacity value (0.0f - transparent, 1.0f - opaque) + * \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.5. + * + * \sa SDL_GetWindowOpacity */ extern DECLSPEC int SDLCALL SDL_SetWindowOpacity(SDL_Window * window, float opacity); /** - * \brief Get the opacity of a window. + * Get the opacity of a window. * - * If transparency isn't supported on this platform, opacity will be reported - * as 1.0f without error. + * If transparency isn't supported on this platform, opacity will be reported + * as 1.0f without error. * - * \param window The window in question. - * \param out_opacity Opacity (0.0f - transparent, 1.0f - opaque) + * The parameter `opacity` is ignored if it is NULL. * - * \return 0 on success, or -1 on error (invalid window, etc). + * This function also returns -1 if an invalid window was provided. * - * \sa SDL_SetWindowOpacity() + * \param window the window to get the current opacity value from + * \param opacity the float filled in (0.0f - transparent, 1.0f - opaque) + * \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.5. + * + * \sa SDL_SetWindowOpacity */ extern DECLSPEC int SDLCALL SDL_GetWindowOpacity(SDL_Window * window, float * out_opacity); /** - * \brief Sets the window as a modal for another window (TODO: reconsider this function and/or its name) + * Set the window as a modal for another window. * - * \param modal_window The window that should be modal - * \param parent_window The parent window + * \param modal_window the window that should be set modal + * \param parent_window the parent window for the modal window + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. * - * \return 0 on success, or -1 otherwise. + * \since This function is available since SDL 2.0.5. */ extern DECLSPEC int SDLCALL SDL_SetWindowModalFor(SDL_Window * modal_window, SDL_Window * parent_window); /** - * \brief Explicitly sets input focus to the window. + * Explicitly set input focus to the window. * - * You almost certainly want SDL_RaiseWindow() instead of this function. Use - * this with caution, as you might give focus to a window that's completely - * obscured by other windows. + * You almost certainly want SDL_RaiseWindow() instead of this function. Use + * this with caution, as you might give focus to a window that is completely + * obscured by other windows. * - * \param window The window that should get the input focus + * \param window the window that should get the input focus + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. * - * \return 0 on success, or -1 otherwise. - * \sa SDL_RaiseWindow() + * \since This function is available since SDL 2.0.5. + * + * \sa SDL_RaiseWindow */ extern DECLSPEC int SDLCALL SDL_SetWindowInputFocus(SDL_Window * window); /** - * \brief Set the gamma ramp for a window. + * Set the gamma ramp for the display that owns a given window. * - * \param window The window for which the gamma ramp should be set. - * \param red The translation table for the red channel, or NULL. - * \param green The translation table for the green channel, or NULL. - * \param blue The translation table for the blue channel, or NULL. + * Set the gamma translation table for the red, green, and blue channels of + * the video hardware. Each table is an array of 256 16-bit quantities, + * representing a mapping between the input and output for that channel. The + * input is the index into the array, and the output is the 16-bit gamma value + * at that index, scaled to the output color precision. Despite the name and + * signature, this method sets the gamma ramp of the entire display, not an + * individual window. A window is considered to be owned by the display that + * contains the window's center pixel. (The index of this display can be + * retrieved using SDL_GetWindowDisplayIndex().) The gamma ramp set will not + * follow the window if it is moved to another display. * - * \return 0 on success, or -1 if gamma ramps are unsupported. + * \param window the window used to select the display whose gamma ramp will + * be changed + * \param red a 256 element array of 16-bit quantities representing the + * translation table for the red channel, or NULL + * \param green a 256 element array of 16-bit quantities representing the + * translation table for the green channel, or NULL + * \param blue a 256 element array of 16-bit quantities representing the + * translation table for the blue channel, or NULL + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. * - * Set the gamma translation table for the red, green, and blue channels - * of the video hardware. Each table is an array of 256 16-bit quantities, - * representing a mapping between the input and output for that channel. - * The input is the index into the array, and the output is the 16-bit - * gamma value at that index, scaled to the output color precision. - * - * \sa SDL_GetWindowGammaRamp() + * \sa SDL_GetWindowGammaRamp */ extern DECLSPEC int SDLCALL SDL_SetWindowGammaRamp(SDL_Window * window, const Uint16 * red, @@ -1064,19 +1403,25 @@ extern DECLSPEC int SDLCALL SDL_SetWindowGammaRamp(SDL_Window * window, const Uint16 * blue); /** - * \brief Get the gamma ramp for a window. + * Get the gamma ramp for a given window's display. * - * \param window The window from which the gamma ramp should be queried. - * \param red A pointer to a 256 element array of 16-bit quantities to hold - * the translation table for the red channel, or NULL. - * \param green A pointer to a 256 element array of 16-bit quantities to hold - * the translation table for the green channel, or NULL. - * \param blue A pointer to a 256 element array of 16-bit quantities to hold - * the translation table for the blue channel, or NULL. + * Despite the name and signature, this method retrieves the gamma ramp of the + * entire display, not an individual window. A window is considered to be + * owned by the display that contains the window's center pixel. (The index of + * this display can be retrieved using SDL_GetWindowDisplayIndex().) * - * \return 0 on success, or -1 if gamma ramps are unsupported. + * \param window the window used to select the display whose gamma ramp will + * be queried + * \param red a 256 element array of 16-bit quantities filled in with the + * translation table for the red channel, or NULL + * \param green a 256 element array of 16-bit quantities filled in with the + * translation table for the green channel, or NULL + * \param blue a 256 element array of 16-bit quantities filled in with the + * translation table for the blue channel, or NULL + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. * - * \sa SDL_SetWindowGammaRamp() + * \sa SDL_SetWindowGammaRamp */ extern DECLSPEC int SDLCALL SDL_GetWindowGammaRamp(SDL_Window * window, Uint16 * red, @@ -1084,9 +1429,9 @@ extern DECLSPEC int SDLCALL SDL_GetWindowGammaRamp(SDL_Window * window, Uint16 * blue); /** - * \brief Possible return values from the SDL_HitTest callback. + * Possible return values from the SDL_HitTest callback. * - * \sa SDL_HitTest + * \sa SDL_HitTest */ typedef enum { @@ -1103,82 +1448,115 @@ typedef enum } SDL_HitTestResult; /** - * \brief Callback used for hit-testing. + * Callback used for hit-testing. * - * \sa SDL_SetWindowHitTest + * \param win the SDL_Window where hit-testing was set on + * \param area an SDL_Point which should be hit-tested + * \param data what was passed as `callback_data` to SDL_SetWindowHitTest() + * \return an SDL_HitTestResult value. + * + * \sa SDL_SetWindowHitTest */ typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win, const SDL_Point *area, void *data); /** - * \brief Provide a callback that decides if a window region has special properties. + * Provide a callback that decides if a window region has special properties. * - * Normally windows are dragged and resized by decorations provided by the - * system window manager (a title bar, borders, etc), but for some apps, it - * makes sense to drag them from somewhere else inside the window itself; for - * example, one might have a borderless window that wants to be draggable - * from any part, or simulate its own title bar, etc. + * Normally windows are dragged and resized by decorations provided by the + * system window manager (a title bar, borders, etc), but for some apps, it + * makes sense to drag them from somewhere else inside the window itself; for + * example, one might have a borderless window that wants to be draggable from + * any part, or simulate its own title bar, etc. * - * This function lets the app provide a callback that designates pieces of - * a given window as special. This callback is run during event processing - * if we need to tell the OS to treat a region of the window specially; the - * use of this callback is known as "hit testing." + * This function lets the app provide a callback that designates pieces of a + * given window as special. This callback is run during event processing if we + * need to tell the OS to treat a region of the window specially; the use of + * this callback is known as "hit testing." * - * Mouse input may not be delivered to your application if it is within - * a special area; the OS will often apply that input to moving the window or - * resizing the window and not deliver it to the application. + * Mouse input may not be delivered to your application if it is within a + * special area; the OS will often apply that input to moving the window or + * resizing the window and not deliver it to the application. * - * Specifying NULL for a callback disables hit-testing. Hit-testing is - * disabled by default. + * Specifying NULL for a callback disables hit-testing. Hit-testing is + * disabled by default. * - * Platforms that don't support this functionality will return -1 - * unconditionally, even if you're attempting to disable hit-testing. + * Platforms that don't support this functionality will return -1 + * unconditionally, even if you're attempting to disable hit-testing. * - * Your callback may fire at any time, and its firing does not indicate any - * specific behavior (for example, on Windows, this certainly might fire - * when the OS is deciding whether to drag your window, but it fires for lots - * of other reasons, too, some unrelated to anything you probably care about - * _and when the mouse isn't actually at the location it is testing_). - * Since this can fire at any time, you should try to keep your callback - * efficient, devoid of allocations, etc. + * Your callback may fire at any time, and its firing does not indicate any + * specific behavior (for example, on Windows, this certainly might fire when + * the OS is deciding whether to drag your window, but it fires for lots of + * other reasons, too, some unrelated to anything you probably care about _and + * when the mouse isn't actually at the location it is testing_). Since this + * can fire at any time, you should try to keep your callback efficient, + * devoid of allocations, etc. * - * \param window The window to set hit-testing on. - * \param callback The callback to call when doing a hit-test. - * \param callback_data An app-defined void pointer passed to the callback. - * \return 0 on success, -1 on error (including unsupported). + * \param window the window to set hit-testing on + * \param callback the function to call when doing a hit-test + * \param callback_data an app-defined void pointer passed to **callback** + * \returns 0 on success or -1 on error (including unsupported); call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.4. */ extern DECLSPEC int SDLCALL SDL_SetWindowHitTest(SDL_Window * window, SDL_HitTest callback, void *callback_data); /** - * \brief Destroy a window. + * Destroy a window. + * + * If `window` is NULL, this function will return immediately after setting + * the SDL error message to "Invalid window". See SDL_GetError(). + * + * \param window the window to destroy + * + * \sa SDL_CreateWindow + * \sa SDL_CreateWindowFrom */ extern DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_Window * window); /** - * \brief Returns whether the screensaver is currently enabled (default off). + * Check whether the screensaver is currently enabled. * - * \sa SDL_EnableScreenSaver() - * \sa SDL_DisableScreenSaver() + * The screensaver is disabled by default since SDL 2.0.2. Before SDL 2.0.2 + * the screensaver was enabled by default. + * + * The default can also be changed using `SDL_HINT_VIDEO_ALLOW_SCREENSAVER`. + * + * \returns SDL_TRUE if the screensaver is enabled, SDL_FALSE if it is + * disabled. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_DisableScreenSaver + * \sa SDL_EnableScreenSaver */ extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenSaverEnabled(void); /** - * \brief Allow the screen to be blanked by a screensaver + * Allow the screen to be blanked by a screen saver. * - * \sa SDL_IsScreenSaverEnabled() - * \sa SDL_DisableScreenSaver() + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_DisableScreenSaver + * \sa SDL_IsScreenSaverEnabled */ extern DECLSPEC void SDLCALL SDL_EnableScreenSaver(void); /** - * \brief Prevent the screen from being blanked by a screensaver + * Prevent the screen from being blanked by a screen saver. * - * \sa SDL_IsScreenSaverEnabled() - * \sa SDL_EnableScreenSaver() + * If you disable the screensaver, it is automatically re-enabled when SDL + * quits. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_EnableScreenSaver + * \sa SDL_IsScreenSaverEnabled */ extern DECLSPEC void SDLCALL SDL_DisableScreenSaver(void); @@ -1189,147 +1567,304 @@ extern DECLSPEC void SDLCALL SDL_DisableScreenSaver(void); /* @{ */ /** - * \brief Dynamically load an OpenGL library. + * Dynamically load an OpenGL library. * - * \param path The platform dependent OpenGL library name, or NULL to open the - * default OpenGL library. + * This should be done after initializing the video driver, but before + * creating any OpenGL windows. If no OpenGL library is loaded, the default + * library will be loaded upon creation of the first OpenGL window. * - * \return 0 on success, or -1 if the library couldn't be loaded. + * If you do this, you need to retrieve all of the GL functions used in your + * program from the dynamic library using SDL_GL_GetProcAddress(). * - * This should be done after initializing the video driver, but before - * creating any OpenGL windows. If no OpenGL library is loaded, the default - * library will be loaded upon creation of the first OpenGL window. + * \param path the platform dependent OpenGL library name, or NULL to open the + * default OpenGL library + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. * - * \note If you do this, you need to retrieve all of the GL functions used in - * your program from the dynamic library using SDL_GL_GetProcAddress(). - * - * \sa SDL_GL_GetProcAddress() - * \sa SDL_GL_UnloadLibrary() + * \sa SDL_GL_GetProcAddress + * \sa SDL_GL_UnloadLibrary */ extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path); /** - * \brief Get the address of an OpenGL function. + * Get an OpenGL function by name. + * + * If the GL library is loaded at runtime with SDL_GL_LoadLibrary(), then all + * GL functions must be retrieved this way. Usually this is used to retrieve + * function pointers to OpenGL extensions. + * + * There are some quirks to looking up OpenGL functions that require some + * extra care from the application. If you code carefully, you can handle + * these quirks without any platform-specific code, though: + + * - On Windows, function pointers are specific to the current GL context; + * this means you need to have created a GL context and made it current before + * calling SDL_GL_GetProcAddress(). If you recreate your context or create a + * second context, you should assume that any existing function pointers + * aren't valid to use with it. This is (currently) a Windows-specific + * limitation, and in practice lots of drivers don't suffer this limitation, + * but it is still the way the wgl API is documented to work and you should + * expect crashes if you don't respect it. Store a copy of the function + * pointers that comes and goes with context lifespan. + * + * - On X11, function pointers returned by this function are valid for any + * context, and can even be looked up before a context is created at all. This + * means that, for at least some common OpenGL implementations, if you look up + * a function that doesn't exist, you'll get a non-NULL result that is _NOT_ + * safe to call. You must always make sure the function is actually available + * for a given GL context before calling it, by checking for the existence of + * the appropriate extension with SDL_GL_ExtensionSupported(), or verifying + * that the version of OpenGL you're using offers the function as core + * functionality. + * + * - Some OpenGL drivers, on all platforms, *will* return NULL if a function + * isn't supported, but you can't count on this behavior. Check for extensions + * you use, and if you get a NULL anyway, act as if that extension wasn't + * available. This is probably a bug in the driver, but you can code + * defensively for this scenario anyhow. + * + * - Just because you're on Linux/Unix, don't assume you'll be using X11. + * Next-gen display servers are waiting to replace it, and may or may not make + * the same promises about function pointers. + * + * - OpenGL function pointers must be declared `APIENTRY` as in the example + * code. This will ensure the proper calling convention is followed on + * platforms where this matters (Win32) thereby avoiding stack corruption. + * + * \param proc the name of an OpenGL function + * \returns a pointer to the named OpenGL function. The returned pointer + * should be cast to the appropriate function signature. + * + * \sa SDL_GL_ExtensionSupported + * \sa SDL_GL_LoadLibrary + * \sa SDL_GL_UnloadLibrary */ extern DECLSPEC void *SDLCALL SDL_GL_GetProcAddress(const char *proc); /** - * \brief Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary(). + * Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary(). * - * \sa SDL_GL_LoadLibrary() + * \sa SDL_GL_LoadLibrary */ extern DECLSPEC void SDLCALL SDL_GL_UnloadLibrary(void); /** - * \brief Return true if an OpenGL extension is supported for the current - * context. + * Check if an OpenGL extension is supported for the current context. + * + * This function operates on the current GL context; you must have created a + * context and it must be current before calling this function. Do not assume + * that all contexts you create will have the same set of extensions + * available, or that recreating an existing context will offer the same + * extensions again. + * + * While it's probably not a massive overhead, this function is not an O(1) + * operation. Check the extensions you care about after creating the GL + * context and save that information somewhere instead of calling the function + * every time you need to know. + * + * \param extension the name of the extension to check + * \returns SDL_TRUE if the extension is supported, SDL_FALSE otherwise. + * + * \since This function is available since SDL 2.0.0. */ extern DECLSPEC SDL_bool SDLCALL SDL_GL_ExtensionSupported(const char *extension); /** - * \brief Reset all previously set OpenGL context attributes to their default values + * Reset all previously set OpenGL context attributes to their default values. + * + * \since This function is available since SDL 2.0.2. + * + * \sa SDL_GL_GetAttribute + * \sa SDL_GL_SetAttribute + * \sa */ extern DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void); /** - * \brief Set an OpenGL window attribute before window creation. + * Set an OpenGL window attribute before window creation. * - * \return 0 on success, or -1 if the attribute could not be set. + * This function sets the OpenGL attribute `attr` to `value`. The + * requested attributes should be set before creating an OpenGL window. You + * should use SDL_GL_GetAttribute() to check the values after creating the + * OpenGL context, since the values obtained can differ from the requested + * ones. + * + * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to set + * \param value the desired value for the attribute + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_GL_GetAttribute + * \sa SDL_GL_ResetAttributes */ extern DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value); /** - * \brief Get the actual value for an attribute from the current context. + * Get the actual value for an attribute from the current context. * - * \return 0 on success, or -1 if the attribute could not be retrieved. - * The integer at \c value will be modified in either case. + * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to get + * \param value a pointer filled in with the current value of `attr` + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_GL_ResetAttributes + * \sa SDL_GL_SetAttribute */ extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value); /** - * \brief Create an OpenGL context for use with an OpenGL window, and make it - * current. + * Create an OpenGL context for an OpenGL window, and make it current. * - * \sa SDL_GL_DeleteContext() + * Windows users new to OpenGL should note that, for historical reasons, GL + * functions added after OpenGL version 1.1 are not available by default. + * Those functions must be loaded at run-time, either with an OpenGL + * extension-handling library or with SDL_GL_GetProcAddress() and its related + * functions. + * + * SDL_GLContext is an alias for `void *`. It's opaque to the application. + * + * \param window the window to associate with the context + * \returns the OpenGL context associated with `window` or NULL on error; + * call SDL_GetError() for more details. + * + * \sa SDL_GL_DeleteContext + * \sa SDL_GL_MakeCurrent */ extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_Window * window); /** - * \brief Set up an OpenGL context for rendering into an OpenGL window. + * Set up an OpenGL context for rendering into an OpenGL window. * - * \note The context must have been created with a compatible window. + * The context must have been created with a compatible window. + * + * \param window the window to associate with the context + * \param context the OpenGL context to associate with the window + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_GL_CreateContext */ extern DECLSPEC int SDLCALL SDL_GL_MakeCurrent(SDL_Window * window, SDL_GLContext context); /** - * \brief Get the currently active OpenGL window. + * Get the currently active OpenGL window. + * + * \returns the currently active OpenGL window on success or NULL on failure; + * call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. */ extern DECLSPEC SDL_Window* SDLCALL SDL_GL_GetCurrentWindow(void); /** - * \brief Get the currently active OpenGL context. + * Get the currently active OpenGL context. + * + * \returns the currently active OpenGL context or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GL_MakeCurrent */ extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_GetCurrentContext(void); /** - * \brief Get the size of a window's underlying drawable in pixels (for use - * with glViewport). + * Get the size of a window's underlying drawable in pixels. * - * \param window 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 + * This returns info useful for calling glViewport(). * * 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 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. * - * \sa SDL_GetWindowSize() - * \sa SDL_CreateWindow() + * \param window the window from which the drawable size should be queried + * \param w a pointer to variable for storing the width in pixels, may be NULL + * \param h a pointer to variable for storing the height in pixels, may be + * NULL + * + * \since This function is available since SDL 2.0.1. + * + * \sa SDL_CreateWindow + * \sa SDL_GetWindowSize */ extern DECLSPEC void SDLCALL SDL_GL_GetDrawableSize(SDL_Window * window, int *w, int *h); /** - * \brief Set the swap interval for the current OpenGL context. + * Set the swap interval for the current OpenGL context. * - * \param interval 0 for immediate updates, 1 for updates synchronized with the - * vertical retrace. If the system supports it, you may - * specify -1 to allow late swaps to happen immediately - * instead of waiting for the next retrace. + * Some systems allow specifying -1 for the interval, to enable adaptive + * vsync. Adaptive vsync works the same as vsync, but if you've already missed + * the vertical retrace for a given frame, it swaps buffers immediately, which + * might be less jarring for the user during occasional framerate drops. If + * application requests adaptive vsync and the system does not support it, + * this function will fail and return -1. In such a case, you should probably + * retry the call with 1 for the interval. * - * \return 0 on success, or -1 if setting the swap interval is not supported. + * Adaptive vsync is implemented for some glX drivers with + * GLX_EXT_swap_control_tear: * - * \sa SDL_GL_GetSwapInterval() + * https://www.opengl.org/registry/specs/EXT/glx_swap_control_tear.txt + * + * and for some Windows drivers with WGL_EXT_swap_control_tear: + * + * https://www.opengl.org/registry/specs/EXT/wgl_swap_control_tear.txt + * + * Read more on the Khronos wiki: + * https://www.khronos.org/opengl/wiki/Swap_Interval#Adaptive_Vsync + * + * \param interval 0 for immediate updates, 1 for updates synchronized with + * the vertical retrace, -1 for adaptive vsync + * \returns 0 on success or -1 if setting the swap interval is not supported; + * call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GL_GetSwapInterval */ extern DECLSPEC int SDLCALL SDL_GL_SetSwapInterval(int interval); /** - * \brief Get the swap interval for the current OpenGL context. + * Get the swap interval for the current OpenGL context. * - * \return 0 if there is no vertical retrace synchronization, 1 if the buffer + * If the system can't determine the swap interval, or there isn't a valid + * current context, this function will return 0 as a safe default. + * + * \returns 0 if there is no vertical retrace synchronization, 1 if the buffer * swap is synchronized with the vertical retrace, and -1 if late - * swaps happen immediately instead of waiting for the next retrace. - * If the system can't determine the swap interval, or there isn't a - * valid current context, this will return 0 as a safe default. + * swaps happen immediately instead of waiting for the next retrace; + * call SDL_GetError() for more information. * - * \sa SDL_GL_SetSwapInterval() + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GL_SetSwapInterval */ extern DECLSPEC int SDLCALL SDL_GL_GetSwapInterval(void); /** - * \brief Swap the OpenGL buffers for a window, if double-buffering is - * supported. + * Update a window with OpenGL rendering. + * + * This is used with double-buffered OpenGL contexts, which are the default. + * + * On macOS, make sure you bind 0 to the draw framebuffer before swapping + * the window, otherwise nothing will happen. If you aren't using + * glBindFramebuffer(), this is the default and you won't have to do anything + * extra. + * + * \param window the window to change */ extern DECLSPEC void SDLCALL SDL_GL_SwapWindow(SDL_Window * window); /** - * \brief Delete an OpenGL context. + * Delete an OpenGL context. * - * \sa SDL_GL_CreateContext() + * \param context the OpenGL context to be deleted + * + * \sa SDL_GL_CreateContext */ extern DECLSPEC void SDLCALL SDL_GL_DeleteContext(SDL_GLContext context); diff --git a/include/SDL_vulkan.h b/include/SDL_vulkan.h index a3de1cea9..6962574e9 100644 --- a/include/SDL_vulkan.h +++ b/include/SDL_vulkan.h @@ -66,201 +66,140 @@ typedef VkSurfaceKHR SDL_vulkanSurface; /* for compatibility with Tizen */ /* @{ */ /** - * \brief Dynamically load a Vulkan loader library. + * Dynamically load the Vulkan loader library. * - * \param [in] path The platform dependent Vulkan loader library name, or - * \c NULL. + * 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. * - * \return \c 0 on success, or \c -1 if the library couldn't be loaded. + * 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. * - * 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. + * 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. * - * 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. + * 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 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. + * 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 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. + * \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. * - * \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. + * \since This function is available in SDL 2.0.8 * - * \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. - * - * \note This function will fail if there are no working Vulkan drivers - * installed. - * - * \sa SDL_Vulkan_GetVkGetInstanceProcAddr() - * \sa SDL_Vulkan_UnloadLibrary() + * \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);