commit 4dd5fb98c4325b4fb674bce5dec18652fdd5b22a parent dfcf1b407ae44ed17b47230a5ec35993d7ee8ef0 Author: Olav Sørensen <olav.sorensen@live.no> Date: Tue, 4 Mar 2025 18:25:50 +0100 Windows/macOS: Updated SDL to v2.32.2 Diffstat:
139 files changed, 8760 insertions(+), 7444 deletions(-)
diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Headers b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Headers Binary files differ. diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Resources b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Resources Binary files differ. diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/SDL2 b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/SDL2 Binary files differ. diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL.h @@ -25,7 +25,6 @@ * Main include header for the SDL library */ - #ifndef SDL_h_ #define SDL_h_ @@ -70,6 +69,8 @@ extern "C" { #endif +/* WIKI CATEGORY: Init */ + /* As of version 0.5, SDL is loaded dynamically into the application */ /** @@ -130,7 +131,7 @@ extern "C" { * 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 + * \param flags subsystem initialization flags. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_assert.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_assert.h @@ -61,6 +61,8 @@ assert can have unique static variables associated with it. #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "brk #22\n\t" ) #elif defined(__APPLE__) && defined(__arm__) #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "bkpt #22\n\t" ) +#elif defined(_WIN32) && ((defined(__GNUC__) || defined(__clang__)) && (defined(__arm64__) || defined(__aarch64__)) ) + #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "brk #0xF000\n\t" ) #elif defined(__386__) && defined(__WATCOMC__) #define SDL_TriggerBreakpoint() { _asm { int 0x03 } } #elif defined(HAVE_SIGNAL_H) && !defined(__WATCOMC__) @@ -191,8 +193,8 @@ extern DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *, * A callback that fires when an SDL assertion fails. * * \param data a pointer to the SDL_AssertData structure corresponding to the - * current assertion - * \param userdata what was passed as `userdata` to SDL_SetAssertionHandler() + * current assertion. + * \param userdata what was passed as `userdata` to SDL_SetAssertionHandler(). * \returns an SDL_AssertState value indicating how to handle the failure. */ typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)( @@ -212,8 +214,8 @@ typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)( * This callback is NOT reset to SDL's internal handler upon SDL_Quit()! * * \param handler the SDL_AssertionHandler function to call when an assertion - * fails or NULL for the default handler - * \param userdata a pointer that is passed to `handler` + * fails or NULL for the default handler. + * \param userdata a pointer that is passed to `handler`. * * \since This function is available since SDL 2.0.0. * @@ -254,7 +256,7 @@ extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetDefaultAssertionHandler(void * 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() + * 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. diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_atomic.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_atomic.h @@ -20,38 +20,29 @@ */ /** - * \file SDL_atomic.h + * # CategoryAtomic * * Atomic operations. * - * IMPORTANT: - * If you are not an expert in concurrent lockless programming, you should - * only be using the atomic lock and reference counting functions in this - * file. In all other cases you should be protecting your data structures - * with full mutexes. + * IMPORTANT: If you are not an expert in concurrent lockless programming, you + * should not be using any functions in this file. You should be protecting + * your data structures with full mutexes instead. * - * The list of "safe" functions to use are: - * SDL_AtomicLock() - * SDL_AtomicUnlock() - * SDL_AtomicIncRef() - * SDL_AtomicDecRef() + * ***Seriously, here be dragons!*** * - * Seriously, here be dragons! - * ^^^^^^^^^^^^^^^^^^^^^^^^^^^ - * - * You can find out a little more about lockless programming and the - * subtle issues that can arise here: - * http://msdn.microsoft.com/en-us/library/ee418650%28v=vs.85%29.aspx + * You can find out a little more about lockless programming and the subtle + * issues that can arise here: + * https://learn.microsoft.com/en-us/windows/win32/dxtecharts/lockless-programming * * There's also lots of good information here: - * http://www.1024cores.net/home/lock-free-algorithms - * http://preshing.com/ * - * These operations may or may not actually be implemented using - * processor specific atomic operations. When possible they are - * implemented as true processor specific atomic operations. When that - * is not possible the are implemented using locks that *do* use the - * available atomic operations. + * - https://www.1024cores.net/home/lock-free-algorithms + * - https://preshing.com/ + * + * These operations may or may not actually be implemented using processor + * specific atomic operations. When possible they are implemented as true + * processor specific atomic operations. When that is not possible the are + * implemented using locks that *do* use the available atomic operations. * * All of the atomic operations that modify memory are full memory barriers. */ @@ -94,7 +85,7 @@ typedef int SDL_SpinLock; * ***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 + * \param lock a pointer to a lock variable. * \returns SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already * held. * @@ -111,7 +102,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTryLock(SDL_SpinLock *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 + * \param lock a pointer to a lock variable. * * \since This function is available since SDL 2.0.0. * @@ -128,7 +119,7 @@ extern DECLSPEC void SDLCALL SDL_AtomicLock(SDL_SpinLock *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 + * \param lock a pointer to a lock variable. * * \since This function is available since SDL 2.0.0. * @@ -257,10 +248,13 @@ typedef void (*SDL_KernelMemoryBarrierFunc)(); /** - * \brief A type representing an atomic integer value. It is a struct - * so people don't accidentally use numeric operations on it. + * A type representing an atomic integer value. + * + * It is a struct so people don't accidentally use numeric operations on it. */ -typedef struct { int value; } SDL_atomic_t; +typedef struct SDL_atomic_t { + int value; +} SDL_atomic_t; /** * Set an atomic variable to a new value if it is currently an old value. @@ -268,9 +262,9 @@ typedef struct { int value; } SDL_atomic_t; * ***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 + * \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. @@ -289,8 +283,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCAS(SDL_atomic_t *a, int oldval, int * ***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 + * \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. * * \since This function is available since SDL 2.0.2. @@ -305,7 +299,7 @@ extern DECLSPEC int SDLCALL SDL_AtomicSet(SDL_atomic_t *a, int v); * ***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 + * \param a a pointer to an SDL_atomic_t variable. * \returns the current value of an atomic variable. * * \since This function is available since SDL 2.0.2. @@ -322,8 +316,8 @@ extern DECLSPEC int SDLCALL SDL_AtomicGet(SDL_atomic_t *a); * ***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 + * \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. * * \since This function is available since SDL 2.0.2. @@ -356,9 +350,9 @@ extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_atomic_t *a, int v); * ***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 + * \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. @@ -375,8 +369,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCASPtr(void **a, void *oldval, void * * ***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 + * \param a a pointer to a pointer. + * \param v the desired pointer value. * \returns the previous value of the pointer. * * \since This function is available since SDL 2.0.2. @@ -392,7 +386,7 @@ extern DECLSPEC void* SDLCALL SDL_AtomicSetPtr(void **a, void* v); * ***Note: If you don't know what this function is for, you shouldn't use * it!*** * - * \param a a pointer to a pointer + * \param a a pointer to a pointer. * \returns the current value of a pointer. * * \since This function is available since SDL 2.0.2. diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_audio.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_audio.h @@ -22,9 +22,9 @@ /* !!! FIXME: several functions in here need Doxygen comments. */ /** - * \file SDL_audio.h + * # CategoryAudio * - * Access to the raw audio mixing buffer for the SDL library. + * Access to the raw audio mixing buffer for the SDL library. */ #ifndef SDL_audio_h_ @@ -44,24 +44,24 @@ extern "C" { #endif /** - * \brief Audio format flags. - * - * These are what the 16 bits in SDL_AudioFormat currently mean... - * (Unspecified bits are always zero). - * - * \verbatim - ++-----------------------sample is signed if set - || - || ++-----------sample is bigendian if set - || || - || || ++---sample is float if set - || || || - || || || +---sample bit size---+ - || || || | | - 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00 - \endverbatim - * - * There are macros in SDL 2.0 and later to query these bits. + * Audio format flags. + * + * These are what the 16 bits in SDL_AudioFormat currently mean... + * (Unspecified bits are always zero). + * + * ``` + * ++-----------------------sample is signed if set + * || + * || ++-----------sample is bigendian if set + * || || + * || || ++---sample is float if set + * || || || + * || || || +---sample bit size---+ + * || || || | | + * 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00 + * ``` + * + * There are macros in SDL 2.0 and later to query these bits. */ typedef Uint16 SDL_AudioFormat; @@ -149,33 +149,30 @@ typedef Uint16 SDL_AudioFormat; /* @} *//* Audio flags */ /** - * This function is called when the audio device needs more data. - * - * \param userdata An application-specific parameter saved in - * the SDL_AudioSpec structure - * \param stream A pointer to the audio data buffer. - * \param len The length of that buffer in bytes. - * - * Once the callback returns, the buffer will no longer be valid. - * Stereo samples are stored in a LRLRLR ordering. + * This function is called when the audio device needs more data. * - * You can choose to avoid callbacks and use SDL_QueueAudio() instead, if - * you like. Just open your audio device with a NULL callback. + * \param userdata An application-specific parameter saved in the + * SDL_AudioSpec structure. + * \param stream A pointer to the audio data buffer. + * \param len Length of **stream** in bytes. */ typedef void (SDLCALL * SDL_AudioCallback) (void *userdata, Uint8 * stream, int len); /** - * The calculated values in this structure are calculated by SDL_OpenAudio(). - * - * For multi-channel audio, the default SDL channel mapping is: - * 2: FL FR (stereo) - * 3: FL FR LFE (2.1 surround) - * 4: FL FR BL BR (quad) - * 5: FL FR LFE BL BR (4.1 surround) - * 6: FL FR FC LFE SL SR (5.1 surround - last two can also be BL BR) - * 7: FL FR FC LFE BC SL SR (6.1 surround) - * 8: FL FR FC LFE BL BR SL SR (7.1 surround) + * The calculated values in this structure are calculated by SDL_OpenAudio(). + * + * For multi-channel audio, the default SDL channel mapping is: + * + * ``` + * 2: FL FR (stereo) + * 3: FL FR LFE (2.1 surround) + * 4: FL FR BL BR (quad) + * 5: FL FR LFE BL BR (4.1 surround) + * 6: FL FR FC LFE SL SR (5.1 surround - last two can also be BL BR) + * 7: FL FR FC LFE BC SL SR (6.1 surround) + * 8: FL FR FC LFE BL BR SL SR (7.1 surround) + * ``` */ typedef struct SDL_AudioSpec { @@ -196,11 +193,11 @@ typedef void (SDLCALL * SDL_AudioFilter) (struct SDL_AudioCVT * cvt, SDL_AudioFormat format); /** - * \brief Upper limit of filters in SDL_AudioCVT + * Upper limit of filters in SDL_AudioCVT * - * The maximum number of SDL_AudioFilter functions in SDL_AudioCVT is - * currently limited to 9. The SDL_AudioCVT.filters array has 10 pointers, - * one of which is the terminating NULL pointer. + * The maximum number of SDL_AudioFilter functions in SDL_AudioCVT is + * currently limited to 9. The SDL_AudioCVT.filters array has 10 pointers, one + * of which is the terminating NULL pointer. */ #define SDL_AUDIOCVT_MAX_FILTERS 9 @@ -287,7 +284,7 @@ extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void); * meant to be proper names. * * \param index the index of the audio driver; the value ranges from 0 to - * SDL_GetNumAudioDrivers() - 1 + * SDL_GetNumAudioDrivers() - 1. * \returns the name of the audio driver at the requested index, or NULL if an * invalid index was specified. * @@ -314,7 +311,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index); * specific need to designate the audio driver you want to use. You should * normally use SDL_Init() or SDL_InitSubSystem(). * - * \param driver_name the name of the desired audio driver + * \param driver_name the name of the desired audio driver. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -408,13 +405,13 @@ extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired, SDL_AudioSpec * obtained); /** - * SDL Audio Device IDs. + * SDL Audio Device IDs. * - * A successful call to SDL_OpenAudio() is always device id 1, and legacy - * SDL audio APIs assume you want this device ID. SDL_OpenAudioDevice() calls - * always returns devices >= 2 on success. The legacy calls are good both - * for backwards compatibility and when you don't care about multiple, - * specific, or capture devices. + * A successful call to SDL_OpenAudio() is always device id 1, and legacy SDL + * audio APIs assume you want this device ID. SDL_OpenAudioDevice() calls + * always returns devices >= 2 on success. The legacy calls are good both for + * backwards compatibility and when you don't care about multiple, specific, + * or capture devices. */ typedef Uint32 SDL_AudioDeviceID; @@ -452,7 +449,7 @@ typedef Uint32 SDL_AudioDeviceID; * ``` * * \param iscapture zero to request playback devices, non-zero to request - * recording devices + * 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. @@ -478,7 +475,7 @@ extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture); * 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 + * 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 @@ -504,11 +501,11 @@ extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index, * count. * * \param index the index of the audio device; valid values range from 0 to - * SDL_GetNumAudioDevices() - 1 + * 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 + * \returns 0 on success, nonzero on error. * * \since This function is available since SDL 2.0.16. * @@ -542,7 +539,7 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index, * \param spec The SDL_AudioSpec to be initialized by this function. * \param iscapture non-zero to query the default recording device, zero to * query the default output device. - * \returns 0 on success, nonzero on error + * \returns 0 on success, nonzero on error. * * \since This function is available since SDL 2.24.0. * @@ -645,12 +642,12 @@ extern DECLSPEC int SDLCALL SDL_GetDefaultAudioInfo(char **name, * 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 + * recording, not playback. * \param desired an SDL_AudioSpec structure representing the desired output - * format; see SDL_OpenAudio() for more information + * 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 + * 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. * @@ -712,7 +709,7 @@ extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void); * Use this function to get the current audio state of an audio device. * * \param dev the ID of an audio device previously opened with - * SDL_OpenAudioDevice() + * SDL_OpenAudioDevice(). * \returns the SDL_AudioStatus of the specified audio device. * * \since This function is available since SDL 2.0.0. @@ -745,7 +742,7 @@ extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioDeviceStatus(SDL_AudioDevice * * ...and is only useful if you used the legacy SDL_OpenAudio() function. * - * \param pause_on non-zero to pause, 0 to unpause + * \param pause_on non-zero to pause, 0 to unpause. * * \since This function is available since SDL 2.0.0. * @@ -775,8 +772,8 @@ extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on); * callback, you shouldn't pause the audio device, as it will lead to dropouts * in the audio playback. Instead, you should use SDL_LockAudioDevice(). * - * \param dev a device opened by SDL_OpenAudioDevice() - * \param pause_on non-zero to pause, 0 to unpause + * \param dev a device opened by SDL_OpenAudioDevice(). + * \param pause_on non-zero to pause, 0 to unpause. * * \since This function is available since SDL 2.0.0. * @@ -841,14 +838,14 @@ extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev, * 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 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 + * 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 + * 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 @@ -874,8 +871,9 @@ extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src, Uint32 * audio_len); /** - * Loads a WAV from a file. - * Compatibility convenience function. + * Loads a WAV from a file. + * + * Compatibility convenience function. */ #define SDL_LoadWAV(file, spec, audio_buf, audio_len) \ SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len) @@ -888,7 +886,7 @@ extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src, * this function with a NULL pointer. * * \param audio_buf a pointer to the buffer created by SDL_LoadWAV() or - * SDL_LoadWAV_RW() + * SDL_LoadWAV_RW(). * * \since This function is available since SDL 2.0.0. * @@ -912,15 +910,16 @@ extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf); * and then can call SDL_ConvertAudio() to complete the conversion. * * \param cvt an SDL_AudioCVT structure filled in with audio conversion - * information + * 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 + * 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 + * 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. @@ -991,12 +990,12 @@ typedef struct _SDL_AudioStream SDL_AudioStream; /** * 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 - * \param src_rate The sampling rate of the source audio - * \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 + * \param src_format The format of the source audio. + * \param src_channels The number of channels of the source audio. + * \param src_rate The sampling rate of the source audio. + * \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. * \returns 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.7. @@ -1018,9 +1017,9 @@ extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioForm /** * 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 + * \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. * \returns 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.7. @@ -1037,10 +1036,10 @@ extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const vo /** * Get converted/resampled data from the stream * - * \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 - * \returns the number of bytes read from the stream, or -1 on error + * \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. + * \returns the number of bytes read from the stream, or -1 on error. * * \since This function is available since SDL 2.0.7. * @@ -1118,6 +1117,9 @@ extern DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream); */ extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream); +/** + * Maximum volume allowed in calls to SDL_MixAudio and SDL_MixAudioFormat. + */ #define SDL_MIX_MAXVOLUME 128 /** @@ -1132,11 +1134,11 @@ extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream); * ...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 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 + * for full audio volume. * * \since This function is available since SDL 2.0.0. * @@ -1165,13 +1167,13 @@ extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src, * 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 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 + * 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 + * for full audio volume. * * \since This function is available since SDL 2.0.0. */ @@ -1215,9 +1217,9 @@ extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst, * from planar audio formats into a non-planar one (see SDL_AudioFormat) * before queuing audio. * - * \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 + * \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. * @@ -1263,9 +1265,9 @@ extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *da * 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 + * \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 the number of bytes dequeued, which could be less than requested; * call SDL_GetError() for more information. * @@ -1299,7 +1301,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *dat * You should not call SDL_LockAudio() on the device before querying; SDL * handles locking internally for this function. * - * \param dev the device ID of which we will query queued audio size + * \param dev the device ID of which we will query queued audio size. * \returns the number of bytes (not samples!) of queued audio. * * \since This function is available since SDL 2.0.4. @@ -1334,7 +1336,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev); * * This function always succeeds and thus returns void. * - * \param dev the device ID of which to clear the audio queue + * \param dev the device ID of which to clear the audio queue. * * \since This function is available since SDL 2.0.4. * @@ -1406,7 +1408,7 @@ extern DECLSPEC void SDLCALL SDL_LockAudio(void); * at once, not only will you block the audio callback, you'll block the other * thread. * - * \param dev the ID of the device to be locked + * \param dev the ID of the device to be locked. * * \since This function is available since SDL 2.0.0. * @@ -1439,7 +1441,7 @@ extern DECLSPEC void SDLCALL SDL_UnlockAudio(void); * * This function should be paired with a previous SDL_LockAudioDevice() call. * - * \param dev the ID of the device to be unlocked + * \param dev the ID of the device to be unlocked. * * \since This function is available since SDL 2.0.0. * @@ -1481,7 +1483,7 @@ extern DECLSPEC void SDLCALL SDL_CloseAudio(void); * The device ID is invalid as soon as the device is closed, and is eligible * for reuse in a new SDL_OpenAudioDevice() call immediately. * - * \param dev an audio device previously opened with SDL_OpenAudioDevice() + * \param dev an audio device previously opened with SDL_OpenAudioDevice(). * * \since This function is available since SDL 2.0.0. * diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_bits.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_bits.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_bits.h + * # CategoryBits * - * Functions for fiddling with bits and bitmasks. + * Functions for fiddling with bits and bitmasks. */ #ifndef SDL_bits_h_ @@ -56,6 +56,12 @@ extern __inline int _SDL_bsr_watcom(Uint32); modify exact [eax] nomemory; #endif +/** + * Use this function to get the index of the most significant (set) bit in a + * + * \param x the number to find the MSB of. + * \returns the index of the most significant bit of x, or -1 if x is 0. + */ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) { diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_blendmode.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_blendmode.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_blendmode.h + * # CategoryBlendmode * - * Header file declaring the SDL_BlendMode enumeration + * Header file declaring the SDL_BlendMode enumeration */ #ifndef SDL_blendmode_h_ @@ -35,9 +35,9 @@ extern "C" { #endif /** - * \brief The blend mode used in SDL_RenderCopy() and drawing operations. + * The blend mode used in SDL_RenderCopy() and drawing operations. */ -typedef enum +typedef enum SDL_BlendMode { SDL_BLENDMODE_NONE = 0x00000000, /**< no blending dstRGBA = srcRGBA */ @@ -60,9 +60,10 @@ typedef enum } SDL_BlendMode; /** - * \brief The blend operation used when combining source and destination pixel components + * The blend operation used when combining source and destination pixel + * components */ -typedef enum +typedef enum SDL_BlendOperation { SDL_BLENDOPERATION_ADD = 0x1, /**< dst + src: supported by all renderers */ SDL_BLENDOPERATION_SUBTRACT = 0x2, /**< src - dst : supported by D3D9, D3D11, OpenGL, OpenGLES */ @@ -72,9 +73,9 @@ typedef enum } SDL_BlendOperation; /** - * \brief The normalized factor used to multiply pixel components + * The normalized factor used to multiply pixel components */ -typedef enum +typedef enum SDL_BlendFactor { SDL_BLENDFACTOR_ZERO = 0x1, /**< 0, 0, 0, 0 */ SDL_BLENDFACTOR_ONE = 0x2, /**< 1, 1, 1, 1 */ @@ -158,18 +159,18 @@ typedef enum * case. * * \param srcColorFactor the SDL_BlendFactor applied to the red, green, and - * blue components of the source pixels + * blue components of the source pixels. * \param dstColorFactor the SDL_BlendFactor applied to the red, green, and - * blue components of the destination pixels + * 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 + * destination pixels. * \param srcAlphaFactor the SDL_BlendFactor applied to the alpha component of - * the source pixels + * the source pixels. * \param dstAlphaFactor the SDL_BlendFactor applied to the alpha component of - * the destination pixels + * the destination pixels. * \param alphaOperation the SDL_BlendOperation used to combine the alpha - * component of the source and destination pixels + * component of the source and destination pixels. * \returns an SDL_BlendMode that represents the chosen factors and * operations. * diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_clipboard.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_clipboard.h @@ -20,7 +20,7 @@ */ /** - * \file SDL_clipboard.h + * # CategoryClipboard * * Include file for SDL clipboard handling */ @@ -41,7 +41,7 @@ extern "C" { /** * Put UTF-8 text into the clipboard. * - * \param text the text to store in the clipboard + * \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. * @@ -85,7 +85,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasClipboardText(void); /** * Put UTF-8 text into the primary selection. * - * \param text the text to store in the primary selection + * \param text the text to store in the primary selection. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_config.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_config.h @@ -24,9 +24,7 @@ #include <SDL2/SDL_platform.h> -/** - * \file SDL_config.h - */ +/* WIKI CATEGORY: - */ /* Add any platform that doesn't build using the configure system. */ #if defined(__WIN32__) diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_cpuinfo.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_cpuinfo.h @@ -19,10 +19,16 @@ 3. This notice may not be removed or altered from any source distribution. */ +/* WIKI CATEGORY: CPUInfo */ + /** - * \file SDL_cpuinfo.h + * # CategoryCPUInfo + * + * CPU feature detection for SDL. * - * CPU feature detection for SDL. + * These functions are largely concerned with reporting if the system has + * access to various SIMD instruction sets, but also has other important info + * to share, such as number of logical CPU cores. */ #ifndef SDL_cpuinfo_h_ diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_endian.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_endian.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_endian.h + * # CategoryEndian * - * Functions for reading and writing endian-specific values + * Functions for reading and writing endian-specific values */ #ifndef SDL_endian_h_ @@ -59,6 +59,15 @@ _m_prefetch(void *__P) #ifdef __linux__ #include <endian.h> #define SDL_BYTEORDER __BYTE_ORDER +#elif defined(__sun) && defined(__SVR4) /* Solaris */ +#include <sys/byteorder.h> +#if defined(_LITTLE_ENDIAN) +#define SDL_BYTEORDER SDL_LIL_ENDIAN +#elif defined(_BIG_ENDIAN) +#define SDL_BYTEORDER SDL_BIG_ENDIAN +#else +#error Unsupported endianness +#endif #elif defined(__OpenBSD__) || defined(__DragonFly__) #include <endian.h> #define SDL_BYTEORDER BYTE_ORDER @@ -79,7 +88,7 @@ _m_prefetch(void *__P) defined(__m68k__) || defined(mc68000) || defined(_M_M68K) || \ (defined(__MIPS__) && defined(__MIPSEB__)) || \ defined(__ppc__) || defined(__POWERPC__) || defined(__powerpc__) || defined(__PPC__) || \ - defined(__sparc__) + defined(__sparc__) || defined(__sparc) #define SDL_BYTEORDER SDL_BIG_ENDIAN #else #define SDL_BYTEORDER SDL_LIL_ENDIAN @@ -180,6 +189,16 @@ extern __inline Uint16 SDL_Swap16(Uint16); parm [ax] \ modify [ax]; #else + +/** + * Use this function to swap the byte order of a 16-bit value. + * + * \param x the value to be swapped. + * \returns the swapped value. + * + * \sa SDL_SwapBE16 + * \sa SDL_SwapLE16 + */ SDL_FORCE_INLINE Uint16 SDL_Swap16(Uint16 x) { @@ -231,6 +250,16 @@ extern __inline Uint32 SDL_Swap32(Uint32); parm [eax] \ modify [eax]; #else + +/** + * Use this function to swap the byte order of a 32-bit value. + * + * \param x the value to be swapped. + * \returns the swapped value. + * + * \sa SDL_SwapBE32 + * \sa SDL_SwapLE32 + */ SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) { @@ -276,6 +305,16 @@ extern __inline Uint64 SDL_Swap64(Uint64); parm [eax edx] \ modify [eax edx]; #else + +/** + * Use this function to swap the byte order of a 64-bit value. + * + * \param x the value to be swapped. + * \returns the swapped value. + * + * \sa SDL_SwapBE64 + * \sa SDL_SwapLE64 + */ SDL_FORCE_INLINE Uint64 SDL_Swap64(Uint64 x) { @@ -293,6 +332,15 @@ SDL_Swap64(Uint64 x) #endif +/** + * Use this function to swap the byte order of a floating point value. + * + * \param x the value to be swapped. + * \returns the swapped value. + * + * \sa SDL_SwapFloatBE + * \sa SDL_SwapFloatLE + */ SDL_FORCE_INLINE float SDL_SwapFloat(float x) { diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_error.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_error.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_error.h + * # CategoryError * - * Simple error message routines for SDL. + * Simple error message routines for SDL. */ #ifndef SDL_error_h_ @@ -53,9 +53,9 @@ extern "C" { * } * ``` * - * \param fmt a printf()-style message format string + * \param fmt a printf()-style message format string. * \param ... additional parameters matching % tokens in the `fmt` string, if - * any + * any. * \returns always -1. * * \since This function is available since SDL 2.0.0. @@ -109,8 +109,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetError(void); * 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 + * the current thread. + * \param maxlen The size of the buffer pointed to by the errstr parameter. * \returns the pointer passed in as the `errstr` parameter. * * \since This function is available since SDL 2.0.14. diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_events.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_events.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_events.h + * # CategoryEvents * - * Include file for SDL event handling. + * Include file for SDL event handling. */ #ifndef SDL_events_h_ @@ -52,7 +52,7 @@ extern "C" { /** * The types of events that can be delivered. */ -typedef enum +typedef enum SDL_EventType { SDL_FIRSTEVENT = 0, /**< Unused (do not remove) */ @@ -167,7 +167,7 @@ typedef enum /* Internal events */ SDL_POLLSENTINEL = 0x7F00, /**< Signals the end of an event poll cycle */ - /** Events ::SDL_USEREVENT through ::SDL_LASTEVENT are for your use, + /** Events SDL_USEREVENT through SDL_LASTEVENT are for your use, * and should be allocated with SDL_RegisterEvents() */ SDL_USEREVENT = 0x8000, @@ -179,7 +179,7 @@ typedef enum } SDL_EventType; /** - * \brief Fields shared by every event + * Fields shared by every event */ typedef struct SDL_CommonEvent { @@ -188,14 +188,14 @@ typedef struct SDL_CommonEvent } SDL_CommonEvent; /** - * \brief Display state change event data (event.display.*) + * Display state change event data (event.display.*) */ typedef struct SDL_DisplayEvent { - Uint32 type; /**< ::SDL_DISPLAYEVENT */ + Uint32 type; /**< SDL_DISPLAYEVENT */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 display; /**< The associated display index */ - Uint8 event; /**< ::SDL_DisplayEventID */ + Uint8 event; /**< SDL_DisplayEventID */ Uint8 padding1; Uint8 padding2; Uint8 padding3; @@ -203,14 +203,14 @@ typedef struct SDL_DisplayEvent } SDL_DisplayEvent; /** - * \brief Window state change event data (event.window.*) + * Window state change event data (event.window.*) */ typedef struct SDL_WindowEvent { - Uint32 type; /**< ::SDL_WINDOWEVENT */ + Uint32 type; /**< SDL_WINDOWEVENT */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 windowID; /**< The associated window */ - Uint8 event; /**< ::SDL_WindowEventID */ + Uint8 event; /**< SDL_WindowEventID */ Uint8 padding1; Uint8 padding2; Uint8 padding3; @@ -219,14 +219,14 @@ typedef struct SDL_WindowEvent } SDL_WindowEvent; /** - * \brief Keyboard button event structure (event.key.*) + * Keyboard button event structure (event.key.*) */ typedef struct SDL_KeyboardEvent { - Uint32 type; /**< ::SDL_KEYDOWN or ::SDL_KEYUP */ + Uint32 type; /**< SDL_KEYDOWN or SDL_KEYUP */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 windowID; /**< The window with keyboard focus, if any */ - Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */ + Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ Uint8 repeat; /**< Non-zero if this is a key repeat */ Uint8 padding2; Uint8 padding3; @@ -234,12 +234,13 @@ typedef struct SDL_KeyboardEvent } SDL_KeyboardEvent; #define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32) + /** - * \brief Keyboard text editing event structure (event.edit.*) + * Keyboard text editing event structure (event.edit.*) */ typedef struct SDL_TextEditingEvent { - Uint32 type; /**< ::SDL_TEXTEDITING */ + Uint32 type; /**< SDL_TEXTEDITING */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 windowID; /**< The window with keyboard focus, if any */ char text[SDL_TEXTEDITINGEVENT_TEXT_SIZE]; /**< The editing text */ @@ -248,12 +249,12 @@ typedef struct SDL_TextEditingEvent } SDL_TextEditingEvent; /** - * \brief Extended keyboard text editing event structure (event.editExt.*) when text would be - * truncated if stored in the text buffer SDL_TextEditingEvent + * Extended keyboard text editing event structure (event.editExt.*) when text + * would be truncated if stored in the text buffer SDL_TextEditingEvent */ typedef struct SDL_TextEditingExtEvent { - Uint32 type; /**< ::SDL_TEXTEDITING_EXT */ + Uint32 type; /**< SDL_TEXTEDITING_EXT */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 windowID; /**< The window with keyboard focus, if any */ char* text; /**< The editing text, which should be freed with SDL_free(), and will not be NULL */ @@ -261,24 +262,43 @@ typedef struct SDL_TextEditingExtEvent Sint32 length; /**< The length of selected editing text */ } SDL_TextEditingExtEvent; +/** + * The maximum bytes of text that can be supplied in an SDL_TextInputEvent. + */ #define SDL_TEXTINPUTEVENT_TEXT_SIZE (32) + /** - * \brief Keyboard text input event structure (event.text.*) + * Keyboard text input event structure (event.text.*) + * + * `text` is limited to SDL_TEXTINPUTEVENT_TEXT_SIZE bytes. If the incoming + * string is larger than this, SDL will split it and send it in pieces, across + * multiple events. The string is in UTF-8 format, and if split, SDL + * guarantees that it will not split in the middle of a UTF-8 sequence, so any + * event will only contain complete codepoints. However, if there are several + * codepoints that go together into a single glyph (like an emoji "thumbs up" + * followed by a skin color), they may be split between events. + * + * This event will never be delivered unless text input is enabled by calling + * SDL_StartTextInput(). Text input is enabled by default on desktop + * platforms, and disabled by default on mobile platforms! + * + * \sa SDL_StartTextInput + * \sa SDL_StopTextInput */ typedef struct SDL_TextInputEvent { - Uint32 type; /**< ::SDL_TEXTINPUT */ + Uint32 type; /**< SDL_TEXTINPUT */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 windowID; /**< The window with keyboard focus, if any */ - char text[SDL_TEXTINPUTEVENT_TEXT_SIZE]; /**< The input text */ + char text[SDL_TEXTINPUTEVENT_TEXT_SIZE]; /**< The input text; UTF-8 encoded. */ } SDL_TextInputEvent; /** - * \brief Mouse motion event structure (event.motion.*) + * Mouse motion event structure (event.motion.*) */ typedef struct SDL_MouseMotionEvent { - Uint32 type; /**< ::SDL_MOUSEMOTION */ + Uint32 type; /**< SDL_MOUSEMOTION */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 windowID; /**< The window with mouse focus, if any */ Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */ @@ -290,16 +310,16 @@ typedef struct SDL_MouseMotionEvent } SDL_MouseMotionEvent; /** - * \brief Mouse button event structure (event.button.*) + * Mouse button event structure (event.button.*) */ typedef struct SDL_MouseButtonEvent { - Uint32 type; /**< ::SDL_MOUSEBUTTONDOWN or ::SDL_MOUSEBUTTONUP */ + Uint32 type; /**< SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 windowID; /**< The window with mouse focus, if any */ Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */ Uint8 button; /**< The mouse button index */ - Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */ + Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ Uint8 clicks; /**< 1 for single-click, 2 for double-click, etc. */ Uint8 padding1; Sint32 x; /**< X coordinate, relative to window */ @@ -307,11 +327,11 @@ typedef struct SDL_MouseButtonEvent } SDL_MouseButtonEvent; /** - * \brief Mouse wheel event structure (event.wheel.*) + * Mouse wheel event structure (event.wheel.*) */ typedef struct SDL_MouseWheelEvent { - Uint32 type; /**< ::SDL_MOUSEWHEEL */ + Uint32 type; /**< SDL_MOUSEWHEEL */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 windowID; /**< The window with mouse focus, if any */ Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */ @@ -325,11 +345,11 @@ typedef struct SDL_MouseWheelEvent } SDL_MouseWheelEvent; /** - * \brief Joystick axis motion event structure (event.jaxis.*) + * Joystick axis motion event structure (event.jaxis.*) */ typedef struct SDL_JoyAxisEvent { - Uint32 type; /**< ::SDL_JOYAXISMOTION */ + Uint32 type; /**< SDL_JOYAXISMOTION */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_JoystickID which; /**< The joystick instance id */ Uint8 axis; /**< The joystick axis index */ @@ -341,11 +361,11 @@ typedef struct SDL_JoyAxisEvent } SDL_JoyAxisEvent; /** - * \brief Joystick trackball motion event structure (event.jball.*) + * Joystick trackball motion event structure (event.jball.*) */ typedef struct SDL_JoyBallEvent { - Uint32 type; /**< ::SDL_JOYBALLMOTION */ + Uint32 type; /**< SDL_JOYBALLMOTION */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_JoystickID which; /**< The joystick instance id */ Uint8 ball; /**< The joystick trackball index */ @@ -357,18 +377,18 @@ typedef struct SDL_JoyBallEvent } SDL_JoyBallEvent; /** - * \brief Joystick hat position change event structure (event.jhat.*) + * Joystick hat position change event structure (event.jhat.*) */ typedef struct SDL_JoyHatEvent { - Uint32 type; /**< ::SDL_JOYHATMOTION */ + Uint32 type; /**< SDL_JOYHATMOTION */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_JoystickID which; /**< The joystick instance id */ Uint8 hat; /**< The joystick hat index */ Uint8 value; /**< The hat position value. - * \sa ::SDL_HAT_LEFTUP ::SDL_HAT_UP ::SDL_HAT_RIGHTUP - * \sa ::SDL_HAT_LEFT ::SDL_HAT_CENTERED ::SDL_HAT_RIGHT - * \sa ::SDL_HAT_LEFTDOWN ::SDL_HAT_DOWN ::SDL_HAT_RIGHTDOWN + * \sa SDL_HAT_LEFTUP SDL_HAT_UP SDL_HAT_RIGHTUP + * \sa SDL_HAT_LEFT SDL_HAT_CENTERED SDL_HAT_RIGHT + * \sa SDL_HAT_LEFTDOWN SDL_HAT_DOWN SDL_HAT_RIGHTDOWN * * Note that zero means the POV is centered. */ @@ -377,46 +397,51 @@ typedef struct SDL_JoyHatEvent } SDL_JoyHatEvent; /** - * \brief Joystick button event structure (event.jbutton.*) + * Joystick button event structure (event.jbutton.*) */ typedef struct SDL_JoyButtonEvent { - Uint32 type; /**< ::SDL_JOYBUTTONDOWN or ::SDL_JOYBUTTONUP */ + Uint32 type; /**< SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_JoystickID which; /**< The joystick instance id */ Uint8 button; /**< The joystick button index */ - Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */ + Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ Uint8 padding1; Uint8 padding2; } SDL_JoyButtonEvent; /** - * \brief Joystick device event structure (event.jdevice.*) + * Joystick device event structure (event.jdevice.*) + * + * SDL will send JOYSTICK_ADDED events for devices that are already plugged in + * during SDL_Init. + * + * \sa SDL_ControllerDeviceEvent */ typedef struct SDL_JoyDeviceEvent { - Uint32 type; /**< ::SDL_JOYDEVICEADDED or ::SDL_JOYDEVICEREMOVED */ + Uint32 type; /**< SDL_JOYDEVICEADDED or SDL_JOYDEVICEREMOVED */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Sint32 which; /**< The joystick device index for the ADDED event, instance id for the REMOVED event */ } SDL_JoyDeviceEvent; /** - * \brief Joysick battery level change event structure (event.jbattery.*) + * Joysick battery level change event structure (event.jbattery.*) */ typedef struct SDL_JoyBatteryEvent { - Uint32 type; /**< ::SDL_JOYBATTERYUPDATED */ + Uint32 type; /**< SDL_JOYBATTERYUPDATED */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_JoystickID which; /**< The joystick instance id */ SDL_JoystickPowerLevel level; /**< The joystick battery level */ } SDL_JoyBatteryEvent; /** - * \brief Game controller axis motion event structure (event.caxis.*) + * Game controller axis motion event structure (event.caxis.*) */ typedef struct SDL_ControllerAxisEvent { - Uint32 type; /**< ::SDL_CONTROLLERAXISMOTION */ + Uint32 type; /**< SDL_CONTROLLERAXISMOTION */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_JoystickID which; /**< The joystick instance id */ Uint8 axis; /**< The controller axis (SDL_GameControllerAxis) */ @@ -429,36 +454,42 @@ typedef struct SDL_ControllerAxisEvent /** - * \brief Game controller button event structure (event.cbutton.*) + * Game controller button event structure (event.cbutton.*) */ typedef struct SDL_ControllerButtonEvent { - Uint32 type; /**< ::SDL_CONTROLLERBUTTONDOWN or ::SDL_CONTROLLERBUTTONUP */ + Uint32 type; /**< SDL_CONTROLLERBUTTONDOWN or SDL_CONTROLLERBUTTONUP */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_JoystickID which; /**< The joystick instance id */ Uint8 button; /**< The controller button (SDL_GameControllerButton) */ - Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */ + Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ Uint8 padding1; Uint8 padding2; } SDL_ControllerButtonEvent; /** - * \brief Controller device event structure (event.cdevice.*) + * Controller device event structure (event.cdevice.*) + * + * Joysticks that are supported game controllers receive both an + * SDL_JoyDeviceEvent and an SDL_ControllerDeviceEvent. + * + * SDL will send CONTROLLERDEVICEADDED events for joysticks that are already + * plugged in during SDL_Init() and are recognized as game controllers. */ typedef struct SDL_ControllerDeviceEvent { - Uint32 type; /**< ::SDL_CONTROLLERDEVICEADDED, ::SDL_CONTROLLERDEVICEREMOVED, ::SDL_CONTROLLERDEVICEREMAPPED, or ::SDL_CONTROLLERSTEAMHANDLEUPDATED */ + Uint32 type; /**< SDL_CONTROLLERDEVICEADDED, SDL_CONTROLLERDEVICEREMOVED, SDL_CONTROLLERDEVICEREMAPPED, or SDL_CONTROLLERSTEAMHANDLEUPDATED */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Sint32 which; /**< The joystick device index for the ADDED event, instance id for the REMOVED or REMAPPED event */ } SDL_ControllerDeviceEvent; /** - * \brief Game controller touchpad event structure (event.ctouchpad.*) + * Game controller touchpad event structure (event.ctouchpad.*) */ typedef struct SDL_ControllerTouchpadEvent { - Uint32 type; /**< ::SDL_CONTROLLERTOUCHPADDOWN or ::SDL_CONTROLLERTOUCHPADMOTION or ::SDL_CONTROLLERTOUCHPADUP */ + Uint32 type; /**< SDL_CONTROLLERTOUCHPADDOWN or SDL_CONTROLLERTOUCHPADMOTION or SDL_CONTROLLERTOUCHPADUP */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_JoystickID which; /**< The joystick instance id */ Sint32 touchpad; /**< The index of the touchpad */ @@ -469,24 +500,24 @@ typedef struct SDL_ControllerTouchpadEvent } SDL_ControllerTouchpadEvent; /** - * \brief Game controller sensor event structure (event.csensor.*) + * Game controller sensor event structure (event.csensor.*) */ typedef struct SDL_ControllerSensorEvent { - Uint32 type; /**< ::SDL_CONTROLLERSENSORUPDATE */ + Uint32 type; /**< SDL_CONTROLLERSENSORUPDATE */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_JoystickID which; /**< The joystick instance id */ - Sint32 sensor; /**< The type of the sensor, one of the values of ::SDL_SensorType */ + Sint32 sensor; /**< The type of the sensor, one of the values of SDL_SensorType */ float data[3]; /**< Up to 3 values from the sensor, as defined in SDL_sensor.h */ Uint64 timestamp_us; /**< The timestamp of the sensor reading in microseconds, if the hardware provides this information. */ } SDL_ControllerSensorEvent; /** - * \brief Audio device event structure (event.adevice.*) + * Audio device event structure (event.adevice.*) */ typedef struct SDL_AudioDeviceEvent { - Uint32 type; /**< ::SDL_AUDIODEVICEADDED, or ::SDL_AUDIODEVICEREMOVED */ + Uint32 type; /**< SDL_AUDIODEVICEADDED, or SDL_AUDIODEVICEREMOVED */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 which; /**< The audio device index for the ADDED event (valid until next SDL_GetNumAudioDevices() call), SDL_AudioDeviceID for the REMOVED event */ Uint8 iscapture; /**< zero if an output device, non-zero if a capture device. */ @@ -497,11 +528,11 @@ typedef struct SDL_AudioDeviceEvent /** - * \brief Touch finger event structure (event.tfinger.*) + * Touch finger event structure (event.tfinger.*) */ typedef struct SDL_TouchFingerEvent { - Uint32 type; /**< ::SDL_FINGERMOTION or ::SDL_FINGERDOWN or ::SDL_FINGERUP */ + Uint32 type; /**< SDL_FINGERMOTION or SDL_FINGERDOWN or SDL_FINGERUP */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_TouchID touchId; /**< The touch device id */ SDL_FingerID fingerId; @@ -515,11 +546,11 @@ typedef struct SDL_TouchFingerEvent /** - * \brief Multiple Finger Gesture Event (event.mgesture.*) + * Multiple Finger Gesture Event (event.mgesture.*) */ typedef struct SDL_MultiGestureEvent { - Uint32 type; /**< ::SDL_MULTIGESTURE */ + Uint32 type; /**< SDL_MULTIGESTURE */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_TouchID touchId; /**< The touch device id */ float dTheta; @@ -532,11 +563,11 @@ typedef struct SDL_MultiGestureEvent /** - * \brief Dollar Gesture Event (event.dgesture.*) + * Dollar Gesture Event (event.dgesture.*) */ typedef struct SDL_DollarGestureEvent { - Uint32 type; /**< ::SDL_DOLLARGESTURE or ::SDL_DOLLARRECORD */ + Uint32 type; /**< SDL_DOLLARGESTURE or SDL_DOLLARRECORD */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_TouchID touchId; /**< The touch device id */ SDL_GestureID gestureId; @@ -548,13 +579,15 @@ typedef struct SDL_DollarGestureEvent /** - * \brief An event used to request a file open by the system (event.drop.*) - * This event is enabled by default, you can disable it with SDL_EventState(). - * \note If this event is enabled, you must free the filename in the event. + * An event used to request a file open by the system (event.drop.*) + * + * This event is enabled by default, you can disable it with SDL_EventState(). + * + * If this event is enabled, you must free the filename in the event. */ typedef struct SDL_DropEvent { - Uint32 type; /**< ::SDL_DROPBEGIN or ::SDL_DROPFILE or ::SDL_DROPTEXT or ::SDL_DROPCOMPLETE */ + Uint32 type; /**< SDL_DROPBEGIN or SDL_DROPFILE or SDL_DROPTEXT or SDL_DROPCOMPLETE */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ char *file; /**< The file name, which should be freed with SDL_free(), is NULL on begin/complete */ Uint32 windowID; /**< The window that was dropped on, if any */ @@ -562,11 +595,11 @@ typedef struct SDL_DropEvent /** - * \brief Sensor event structure (event.sensor.*) + * Sensor event structure (event.sensor.*) */ typedef struct SDL_SensorEvent { - Uint32 type; /**< ::SDL_SENSORUPDATE */ + Uint32 type; /**< SDL_SENSORUPDATE */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Sint32 which; /**< The instance ID of the sensor */ float data[6]; /**< Up to 6 values from the sensor - additional values can be queried using SDL_SensorGetData() */ @@ -574,20 +607,20 @@ typedef struct SDL_SensorEvent } SDL_SensorEvent; /** - * \brief The "quit requested" event + * The "quit requested" event */ typedef struct SDL_QuitEvent { - Uint32 type; /**< ::SDL_QUIT */ + Uint32 type; /**< SDL_QUIT */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ } SDL_QuitEvent; /** - * \brief A user-defined event type (event.user.*) + * A user-defined event type (event.user.*) */ typedef struct SDL_UserEvent { - Uint32 type; /**< ::SDL_USEREVENT through ::SDL_LASTEVENT-1 */ + Uint32 type; /**< SDL_USEREVENT through SDL_LASTEVENT-1 */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 windowID; /**< The associated window if any */ Sint32 code; /**< User defined event code */ @@ -600,20 +633,24 @@ struct SDL_SysWMmsg; typedef struct SDL_SysWMmsg SDL_SysWMmsg; /** - * \brief A video driver dependent system event (event.syswm.*) - * This event is disabled by default, you can enable it with SDL_EventState() + * A video driver dependent system event (event.syswm.*) + * + * This event is disabled by default, you can enable it with SDL_EventState() * - * \note If you want to use this event, you should include SDL_syswm.h. + * If you want to use this event, you should include SDL_syswm.h. */ typedef struct SDL_SysWMEvent { - Uint32 type; /**< ::SDL_SYSWMEVENT */ + Uint32 type; /**< SDL_SYSWMEVENT */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_SysWMmsg *msg; /**< driver dependent data, defined in SDL_syswm.h */ } SDL_SysWMEvent; /** - * \brief General event structure + * General event structure + * + * The SDL_Event structure is the core of all event handling in SDL. SDL_Event + * is a union of all event structures used in SDL. */ typedef union SDL_Event { @@ -696,7 +733,7 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL extern DECLSPEC void SDLCALL SDL_PumpEvents(void); /* @{ */ -typedef enum +typedef enum SDL_eventaction { SDL_ADDEVENT, SDL_PEEKEVENT, @@ -723,15 +760,15 @@ typedef enum * * This function is thread-safe. * - * \param events destination buffer for the retrieved events + * \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 + * 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 + * SDL_FIRSTEVENT is a safe choice. * \param maxType maximum value of the event type to be considered; - * SDL_LASTEVENT is a safe choice + * 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. * @@ -752,7 +789,7 @@ extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents, * 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 + * \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. * @@ -769,9 +806,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type); * 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 + * SDL_EventType for details. * \param maxType the high end of event type to be queried, inclusive; see - * SDL_EventType for details + * SDL_EventType for details. * \returns SDL_TRUE if events with type >= `minType` and <= `maxType` are * present, or SDL_FALSE if not. * @@ -795,7 +832,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType); * 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 + * \param type the type of event to be cleared; see SDL_EventType for details. * * \since This function is available since SDL 2.0.0. * @@ -818,9 +855,9 @@ extern DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type); * 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 + * SDL_EventType for details. * \param maxType the high end of event type to be cleared, inclusive; see - * SDL_EventType for details + * SDL_EventType for details. * * \since This function is available since SDL 2.0.0. * @@ -861,7 +898,7 @@ extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType); * ``` * * \param event the SDL_Event structure to be filled with the next event from - * the queue, or NULL + * the queue, or NULL. * \returns 1 if there is a pending event or 0 if there are none available. * * \since This function is available since SDL 2.0.0. @@ -885,7 +922,7 @@ extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event); * 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 + * 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. * @@ -908,9 +945,9 @@ extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event); * 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 + * from the queue, or NULL. * \param timeout the maximum number of milliseconds to wait for the next - * available event + * 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. @@ -945,7 +982,7 @@ extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event, * 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 + * \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. @@ -961,11 +998,11 @@ 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 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. + * \param userdata what was passed as `userdata` to SDL_SetEventFilter() or + * SDL_AddEventWatch, etc. + * \param event the event that triggered the callback. + * \returns 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 @@ -988,7 +1025,7 @@ typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event); * 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 + * 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. @@ -1003,8 +1040,8 @@ typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event); * 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` + * \param filter An SDL_EventFilter function to call when an event happens. + * \param userdata a pointer that is passed to `filter`. * * \since This function is available since SDL 2.0.0. * @@ -1023,9 +1060,9 @@ extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter 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 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 + * be stored here. * \returns SDL_TRUE on success or SDL_FALSE if there is no event filter set. * * \since This function is available since SDL 2.0.0. @@ -1054,7 +1091,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter, * through SDL_PeepEvents(). * * \param filter an SDL_EventFilter function to call when an event happens. - * \param userdata a pointer that is passed to `filter` + * \param userdata a pointer that is passed to `filter`. * * \since This function is available since SDL 2.0.0. * @@ -1070,8 +1107,8 @@ extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, * 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() + * \param filter the function originally passed to SDL_AddEventWatch(). + * \param userdata the pointer originally passed to SDL_AddEventWatch(). * * \since This function is available since SDL 2.0.0. * @@ -1088,8 +1125,8 @@ extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter, * 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` + * \param filter the SDL_EventFilter function to call when an event happens. + * \param userdata a pointer that is passed to `filter`. * * \since This function is available since SDL 2.0.0. * @@ -1115,8 +1152,8 @@ extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter, * 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 + * \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. * @@ -1138,7 +1175,7 @@ extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state); * 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 + * \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. * diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_filesystem.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_filesystem.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_filesystem.h + * # CategoryFilesystem * - * \brief Include file for filesystem SDL API functions + * Include file for filesystem SDL API functions */ #ifndef SDL_filesystem_h_ @@ -126,8 +126,8 @@ extern DECLSPEC char *SDLCALL SDL_GetBasePath(void); * 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 + * \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.). diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_gamecontroller.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_gamecontroller.h @@ -19,10 +19,12 @@ 3. This notice may not be removed or altered from any source distribution. */ +/* WIKI CATEGORY: GameController */ + /** - * \file SDL_gamecontroller.h + * # CategoryGameController * - * Include file for SDL game controller event handling + * Include file for SDL game controller event handling */ #ifndef SDL_gamecontroller_h_ @@ -44,7 +46,7 @@ extern "C" { * \file SDL_gamecontroller.h * * In order to use these functions, SDL_Init() must have been called - * with the ::SDL_INIT_GAMECONTROLLER flag. This causes SDL to scan the system + * with the SDL_INIT_GAMECONTROLLER flag. This causes SDL to scan the system * for game controllers, and load appropriate drivers. * * If you would like to receive controller updates while the application @@ -58,7 +60,7 @@ extern "C" { struct _SDL_GameController; typedef struct _SDL_GameController SDL_GameController; -typedef enum +typedef enum SDL_GameControllerType { SDL_CONTROLLER_TYPE_UNKNOWN = 0, SDL_CONTROLLER_TYPE_XBOX360, @@ -77,7 +79,7 @@ typedef enum SDL_CONTROLLER_TYPE_MAX } SDL_GameControllerType; -typedef enum +typedef enum SDL_GameControllerBindType { SDL_CONTROLLER_BINDTYPE_NONE = 0, SDL_CONTROLLER_BINDTYPE_BUTTON, @@ -86,7 +88,7 @@ typedef enum } SDL_GameControllerBindType; /** - * Get the SDL joystick layer binding for this controller button/axis mapping + * Get the SDL joystick layer binding for this controller button/axis mapping */ typedef struct SDL_GameControllerButtonBind { @@ -144,6 +146,10 @@ typedef struct SDL_GameControllerButtonBind * If a new mapping is loaded for an already known controller GUID, the later * version will overwrite the one currently loaded. * + * If this function is called before SDL_Init, SDL will generate an + * SDL_CONTROLLERDEVICEADDED event for matching controllers that are plugged + * in at the time that SDL_Init is called. + * * 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). @@ -152,8 +158,8 @@ typedef struct SDL_GameControllerButtonBind * 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 + * \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. * @@ -162,13 +168,15 @@ typedef struct SDL_GameControllerButtonBind * \sa SDL_GameControllerAddMapping * \sa SDL_GameControllerAddMappingsFromFile * \sa SDL_GameControllerMappingForGUID + * \sa SDL_CONTROLLERDEVICEADDED */ extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw, int freerw); /** - * Load a set of mappings from a file, filtered by the current SDL_GetPlatform() + * Load a set of mappings from a file, filtered by the current + * SDL_GetPlatform() * - * Convenience macro. + * Convenience macro. */ #define SDL_GameControllerAddMappingsFromFile(file) SDL_GameControllerAddMappingsFromRW(SDL_RWFromFile(file, "rb"), 1) @@ -190,7 +198,11 @@ extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw, * "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 + * If this function is called before SDL_Init, SDL will generate an + * SDL_CONTROLLERDEVICEADDED event for matching controllers that are plugged + * in at the time that SDL_Init is called. + * + * \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. * @@ -198,6 +210,7 @@ extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw, * * \sa SDL_GameControllerMapping * \sa SDL_GameControllerMappingForGUID + * \sa SDL_CONTROLLERDEVICEADDED */ extern DECLSPEC int SDLCALL SDL_GameControllerAddMapping(const char* mappingString); @@ -225,7 +238,7 @@ extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForIndex(int mapping_ind * * The returned string must be freed with SDL_free(). * - * \param guid a structure containing the GUID for which a mapping is desired + * \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. * @@ -244,7 +257,7 @@ extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForGUID(SDL_JoystickGUID * Details about mappings are discussed with SDL_GameControllerAddMapping(). * * \param gamecontroller the game controller you want to get the current - * mapping for + * mapping for. * \returns a string that has the controller's mapping or NULL if no mapping * is available; call SDL_GetError() for more information. * @@ -262,7 +275,7 @@ extern DECLSPEC char * SDLCALL SDL_GameControllerMapping(SDL_GameController *gam * SDL_JoystickOpen(). * * \param joystick_index the device_index of a device, up to - * SDL_NumJoysticks() + * 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. * @@ -282,7 +295,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IsGameController(int joystick_index); * SDL_JoystickOpen(). * * \param joystick_index the device_index of a device, from zero to - * SDL_NumJoysticks()-1 + * SDL_NumJoysticks()-1. * \returns the implementation-dependent name for the game controller, or NULL * if there is no name or the index is invalid. * @@ -303,7 +316,7 @@ extern DECLSPEC const char *SDLCALL SDL_GameControllerNameForIndex(int joystick_ * SDL_JoystickOpen(). * * \param joystick_index the device_index of a device, from zero to - * SDL_NumJoysticks()-1 + * SDL_NumJoysticks()-1. * \returns the implementation-dependent path for the game controller, or NULL * if there is no path or the index is invalid. * @@ -319,7 +332,7 @@ extern DECLSPEC const char *SDLCALL SDL_GameControllerPathForIndex(int joystick_ * This can be called before any controllers are opened. * * \param joystick_index the device_index of a device, from zero to - * SDL_NumJoysticks()-1 + * SDL_NumJoysticks()-1. * \returns the controller type. * * \since This function is available since SDL 2.0.12. @@ -332,7 +345,7 @@ extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerTypeForIndex(in * This can be called before any controllers are opened. * * \param joystick_index the device_index of a device, from zero to - * SDL_NumJoysticks()-1 + * SDL_NumJoysticks()-1. * \returns the mapping string. Must be freed with SDL_free(). Returns NULL if * no mapping is available. * @@ -352,7 +365,7 @@ extern DECLSPEC char *SDLCALL SDL_GameControllerMappingForDeviceIndex(int joysti * be used there instead. * * \param joystick_index the device_index of a device, up to - * SDL_NumJoysticks() + * SDL_NumJoysticks(). * \returns a gamecontroller identifier or NULL if an error occurred; call * SDL_GetError() for more information. * @@ -367,7 +380,7 @@ extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerOpen(int joystick_ /** * Get the SDL_GameController associated with an instance id. * - * \param joyid the instance id to get the SDL_GameController for + * \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. * @@ -399,7 +412,7 @@ extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromPlayerIndex(in * it takes a controller identifier instead of the (unstable) device index. * * \param gamecontroller a game controller identifier previously returned by - * SDL_GameControllerOpen() + * SDL_GameControllerOpen(). * \returns the implementation dependent name for the game controller, or NULL * if there is no name or the identifier passed is invalid. * @@ -417,7 +430,7 @@ extern DECLSPEC const char *SDLCALL SDL_GameControllerName(SDL_GameController *g * it takes a controller identifier instead of the (unstable) device index. * * \param gamecontroller a game controller identifier previously returned by - * SDL_GameControllerOpen() + * SDL_GameControllerOpen(). * \returns the implementation dependent path for the game controller, or NULL * if there is no path or the identifier passed is invalid. * @@ -527,8 +540,8 @@ extern DECLSPEC const char * SDLCALL SDL_GameControllerGetSerial(SDL_GameControl /** * Get the Steam Input handle of an opened controller, if available. * - * Returns an InputHandle_t for the controller that can be used with Steam Input API: - * https://partner.steamgames.com/doc/api/ISteamInput + * Returns an InputHandle_t for the controller that can be used with Steam + * Input API: https://partner.steamgames.com/doc/api/ISteamInput * * \param gamecontroller the game controller object to query. * \returns the gamepad handle, or 0 if unavailable. @@ -542,7 +555,7 @@ extern DECLSPEC Uint64 SDLCALL SDL_GameControllerGetSteamHandle(SDL_GameControll * Check if a controller has been opened and is currently connected. * * \param gamecontroller a game controller identifier previously returned by - * SDL_GameControllerOpen() + * SDL_GameControllerOpen(). * \returns SDL_TRUE if the controller has been opened and is currently * connected, or SDL_FALSE if not. * @@ -567,7 +580,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerGetAttached(SDL_GameControlle * cause SDL to crash. * * \param gamecontroller the game controller object that you want to get a - * joystick from + * joystick from. * \returns a SDL_Joystick object; call SDL_GetError() for more information. * * \since This function is available since SDL 2.0.0. @@ -584,7 +597,7 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_GameControllerGetJoystick(SDL_GameCont * 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` + * \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. * @@ -607,17 +620,19 @@ extern DECLSPEC void SDLCALL SDL_GameControllerUpdate(void); /** - * The list of axes available from a controller + * The list of axes available from a controller * - * Thumbstick axis values range from SDL_JOYSTICK_AXIS_MIN to SDL_JOYSTICK_AXIS_MAX, - * and are centered within ~8000 of zero, though advanced UI will allow users to set - * or autodetect the dead zone, which varies between controllers. + * Thumbstick axis values range from SDL_JOYSTICK_AXIS_MIN to + * SDL_JOYSTICK_AXIS_MAX, and are centered within ~8000 of zero, though + * advanced UI will allow users to set or autodetect the dead zone, which + * varies between controllers. * - * Trigger axis values range from 0 (released) to SDL_JOYSTICK_AXIS_MAX - * (fully pressed) when reported by SDL_GameControllerGetAxis(). Note that this is not the - * same range that will be reported by the lower-level SDL_GetJoystickAxis(). + * Trigger axis values range from 0 (released) to SDL_JOYSTICK_AXIS_MAX (fully + * pressed) when reported by SDL_GameControllerGetAxis(). Note that this is + * not the same range that will be reported by the lower-level + * SDL_GetJoystickAxis(). */ -typedef enum +typedef enum SDL_GameControllerAxis { SDL_CONTROLLER_AXIS_INVALID = -1, SDL_CONTROLLER_AXIS_LEFTX, @@ -641,7 +656,7 @@ typedef enum * `SDL_CONTROLLER_AXIS_TRIGGERRIGHT` and `SDL_CONTROLLER_AXIS_TRIGGERLEFT`, * respectively. * - * \param str string representing a SDL_GameController axis + * \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. * @@ -656,7 +671,7 @@ extern DECLSPEC SDL_GameControllerAxis SDLCALL SDL_GameControllerGetAxisFromStri * * The caller should not SDL_free() the returned string. * - * \param axis an enum value for a given SDL_GameControllerAxis + * \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. @@ -670,8 +685,8 @@ extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForAxis(SDL_GameC /** * 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) + * \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`. @@ -690,8 +705,8 @@ SDL_GameControllerGetBindForAxis(SDL_GameController *gamecontroller, * 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) + * \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. * * \since This function is available since SDL 2.0.14. @@ -704,16 +719,15 @@ SDL_GameControllerHasAxis(SDL_GameController *gamecontroller, SDL_GameController * * The axis indices start at index 0. * - * For thumbsticks, the state is a value ranging from -32768 (up/left) - * to 32767 (down/right). + * For thumbsticks, the state is a value ranging from -32768 (up/left) to + * 32767 (down/right). * - * Triggers range from 0 when released to 32767 when fully pressed, and - * never return a negative value. Note that this differs from the value - * reported by the lower-level SDL_GetJoystickAxis(), which normally uses - * the full range. + * Triggers range from 0 when released to 32767 when fully pressed, and never + * return a negative value. Note that this differs from the value reported by + * the lower-level SDL_JoystickGetAxis(), which normally uses the full range. * - * \param gamecontroller a game controller - * \param axis an axis index (one of the SDL_GameControllerAxis values) + * \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. * @@ -725,9 +739,9 @@ extern DECLSPEC Sint16 SDLCALL SDL_GameControllerGetAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis); /** - * The list of buttons available from a controller + * The list of buttons available from a controller */ -typedef enum +typedef enum SDL_GameControllerButton { SDL_CONTROLLER_BUTTON_INVALID = -1, SDL_CONTROLLER_BUTTON_A, @@ -762,7 +776,7 @@ typedef enum * 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 + * \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. * @@ -775,7 +789,7 @@ extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFrom * * The caller should not SDL_free() the returned string. * - * \param button an enum value for a given SDL_GameControllerButton + * \param button an enum value for a given SDL_GameControllerButton. * \returns a string for the given button, or NULL if an invalid button is * specified. The string returned is of the format used by * SDL_GameController mapping strings. @@ -789,8 +803,8 @@ extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForButton(SDL_Gam /** * 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) + * \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`. @@ -809,8 +823,8 @@ SDL_GameControllerGetBindForButton(SDL_GameController *gamecontroller, * 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) + * \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. * * \since This function is available since SDL 2.0.14. @@ -821,8 +835,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasButton(SDL_GameController /** * Get the current state of a button on a game controller. * - * \param gamecontroller a game controller - * \param button a button index (one of the SDL_GameControllerButton values) + * \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. * @@ -858,8 +872,8 @@ extern DECLSPEC int SDLCALL SDL_GameControllerGetTouchpadFinger(SDL_GameControll /** * 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. * \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.14. @@ -869,9 +883,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasSensor(SDL_GameController /** * 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. * \returns 0 or -1 if an error occurred. * * \since This function is available since SDL 2.0.14. @@ -881,8 +895,8 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSetSensorEnabled(SDL_GameControlle /** * 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. * \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.14. @@ -893,8 +907,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerIsSensorEnabled(SDL_GameContr * Get the data rate (number of events per second) of a game controller * 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 the data rate, or 0.0f if the data rate is not available. * * \since This function is available since SDL 2.0.16. @@ -907,10 +921,10 @@ extern DECLSPEC float SDLCALL SDL_GameControllerGetSensorDataRate(SDL_GameContro * 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 + * \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. * * \since This function is available since SDL 2.0.14. @@ -924,12 +938,12 @@ extern DECLSPEC int SDLCALL SDL_GameControllerGetSensorData(SDL_GameController * * 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 gamecontroller The controller to query. + * \param type The type of sensor to query. * \param timestamp A pointer filled with the timestamp in microseconds of the - * current sensor reading if available, or 0 if not - * \param data A pointer filled with the current sensor state - * \param num_values The number of values to write to data + * current sensor reading if available, or 0 if not. + * \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. * * \since This function is available since SDL 2.26.0. @@ -942,13 +956,13 @@ extern DECLSPEC int SDLCALL SDL_GameControllerGetSensorDataWithTimestamp(SDL_Gam * Each call to this function cancels any previous rumble effect, and calling * it with 0 intensity stops any rumbling. * - * \param gamecontroller The controller to vibrate + * \param gamecontroller The controller to vibrate. * \param low_frequency_rumble The intensity of the low frequency (left) - * rumble motor, from 0 to 0xFFFF + * 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 + * 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. * * \since This function is available since SDL 2.0.9. * @@ -967,13 +981,13 @@ extern DECLSPEC int SDLCALL SDL_GameControllerRumble(SDL_GameController *gamecon * want the (more common) whole-controller rumble, use * SDL_GameControllerRumble() instead. * - * \param gamecontroller The controller to vibrate + * \param gamecontroller The controller to vibrate. * \param left_rumble The intensity of the left trigger rumble motor, from 0 - * to 0xFFFF + * 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 + * 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. * * \since This function is available since SDL 2.0.14. * @@ -984,9 +998,9 @@ extern DECLSPEC int SDLCALL SDL_GameControllerRumbleTriggers(SDL_GameController /** * Query whether a game controller has an LED. * - * \param gamecontroller The controller to query + * \param gamecontroller The controller to query. * \returns SDL_TRUE, or SDL_FALSE if this controller does not have a - * modifiable LED + * modifiable LED. * * \since This function is available since SDL 2.0.14. */ @@ -995,9 +1009,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasLED(SDL_GameController *ga /** * Query whether a game controller has rumble support. * - * \param gamecontroller The controller to query + * \param gamecontroller The controller to query. * \returns SDL_TRUE, or SDL_FALSE if this controller does not have rumble - * support + * support. * * \since This function is available since SDL 2.0.18. * @@ -1008,9 +1022,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasRumble(SDL_GameController /** * Query whether a game controller has rumble support on triggers. * - * \param gamecontroller The controller to query + * \param gamecontroller The controller to query. * \returns SDL_TRUE, or SDL_FALSE if this controller does not have trigger - * rumble support + * rumble support. * * \since This function is available since SDL 2.0.18. * @@ -1021,11 +1035,11 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasRumbleTriggers(SDL_GameCon /** * 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 - * \returns 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. * * \since This function is available since SDL 2.0.14. */ @@ -1034,11 +1048,11 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSetLED(SDL_GameController *gamecon /** * Send a controller specific effect packet * - * \param gamecontroller The controller to affect - * \param data The data to send to the controller - * \param size The size of the data to send to the controller + * \param gamecontroller The controller to affect. + * \param data The data to send to the controller. + * \param size The size of the data to send to the controller. * \returns 0, or -1 if this controller or driver doesn't support effect - * packets + * packets. * * \since This function is available since SDL 2.0.16. */ @@ -1048,7 +1062,7 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSendEffect(SDL_GameController *gam * Close a game controller previously opened with SDL_GameControllerOpen(). * * \param gamecontroller a game controller identifier previously returned by - * SDL_GameControllerOpen() + * SDL_GameControllerOpen(). * * \since This function is available since SDL 2.0.0. * @@ -1060,9 +1074,9 @@ extern DECLSPEC void SDLCALL SDL_GameControllerClose(SDL_GameController *gamecon * Return the sfSymbolsName for a given button on a game controller on Apple * platforms. * - * \param gamecontroller the controller to query - * \param button a button on the game controller - * \returns the sfSymbolsName or NULL if the name can't be found + * \param gamecontroller the controller to query. + * \param button a button on the game controller. + * \returns the sfSymbolsName or NULL if the name can't be found. * * \since This function is available since SDL 2.0.18. * @@ -1074,9 +1088,9 @@ extern DECLSPEC const char* SDLCALL SDL_GameControllerGetAppleSFSymbolsNameForBu * Return the sfSymbolsName for a given axis on a game controller on Apple * platforms. * - * \param gamecontroller the controller to query - * \param axis an axis on the game controller - * \returns the sfSymbolsName or NULL if the name can't be found + * \param gamecontroller the controller to query. + * \param axis an axis on the game controller. + * \returns the sfSymbolsName or NULL if the name can't be found. * * \since This function is available since SDL 2.0.18. * diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_gesture.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_gesture.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_gesture.h + * # CategoryGesture * - * Include file for SDL gesture event handling. + * Include file for SDL gesture event handling. */ #ifndef SDL_gesture_h_ @@ -51,7 +51,7 @@ typedef Sint64 SDL_GestureID; * 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 + * \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. @@ -64,7 +64,7 @@ extern DECLSPEC int SDLCALL SDL_RecordGesture(SDL_TouchID touchId); /** * Save all currently loaded Dollar Gesture templates. * - * \param dst a SDL_RWops to save to + * \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. * @@ -78,8 +78,8 @@ extern DECLSPEC int SDLCALL SDL_SaveAllDollarTemplates(SDL_RWops *dst); /** * Save a currently loaded Dollar Gesture template. * - * \param gestureId a gesture id - * \param dst a SDL_RWops to save to + * \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. * @@ -94,8 +94,8 @@ extern DECLSPEC int SDLCALL SDL_SaveDollarTemplate(SDL_GestureID gestureId,SDL_R /** * Load Dollar Gesture templates from a file. * - * \param touchId a touch id - * \param src a SDL_RWops to load from + * \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. * diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_guid.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_guid.h @@ -19,10 +19,13 @@ 3. This notice may not be removed or altered from any source distribution. */ +/* WIKI CATEGORY: GUID */ + /** - * \file SDL_guid.h + * # CategoryGUID * - * Include file for handling ::SDL_GUID values. + * A GUID is a 128-bit value that represents something that is uniquely + * identifiable by this value: "globally unique." */ #ifndef SDL_guid_h_ @@ -38,34 +41,38 @@ extern "C" { #endif /** - * An SDL_GUID is a 128-bit identifier for an input device that - * identifies that device across runs of SDL programs on the same - * platform. If the device is detached and then re-attached to a - * different port, or if the base system is rebooted, the device - * should still report the same GUID. + * An SDL_GUID is a 128-bit identifier. + * + * This is an acronym for "Globally Unique ID." + * + * While a GUID can be used to assign a unique value to almost anything, in + * SDL these are largely used to identify input devices across runs of SDL + * programs on the same platform.If the device is detached and then + * re-attached to a different port, or if the base system is rebooted, the + * device should still report the same GUID. * - * GUIDs are as precise as possible but are not guaranteed to - * distinguish physically distinct but equivalent devices. For - * example, two game controllers from the same vendor with the same - * product ID and revision may have the same GUID. + * GUIDs are as precise as possible but are not guaranteed to distinguish + * physically distinct but equivalent devices. For example, two game + * controllers from the same vendor with the same product ID and revision may + * have the same GUID. * - * GUIDs may be platform-dependent (i.e., the same device may report - * different GUIDs on different operating systems). + * GUIDs may be platform-dependent (i.e., the same device may report different + * GUIDs on different operating systems). */ -typedef struct { +typedef struct SDL_GUID { Uint8 data[16]; } SDL_GUID; /* Function prototypes */ /** - * Get an ASCII string representation for a given ::SDL_GUID. + * Get an ASCII string representation for a given SDL_GUID. * * You should supply at least 33 bytes for pszGUID. * - * \param guid the ::SDL_GUID you wish to convert to string - * \param pszGUID buffer in which to write the ASCII string - * \param cbGUID the size of pszGUID + * \param guid the SDL_GUID you wish to convert to string. + * \param pszGUID buffer in which to write the ASCII string. + * \param cbGUID the size of pszGUID. * * \since This function is available since SDL 2.24.0. * @@ -74,14 +81,14 @@ typedef struct { extern DECLSPEC void SDLCALL SDL_GUIDToString(SDL_GUID guid, char *pszGUID, int cbGUID); /** - * Convert a GUID string into a ::SDL_GUID structure. + * Convert a GUID string into a SDL_GUID 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_GUID structure. + * \param pchGUID string containing an ASCII representation of a GUID. + * \returns a SDL_GUID structure. * * \since This function is available since SDL 2.24.0. * diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_haptic.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_haptic.h @@ -20,24 +20,25 @@ */ /** - * \file SDL_haptic.h - * - * \brief The SDL haptic subsystem allows you to control haptic (force feedback) - * devices. - * - * The basic usage is as follows: - * - Initialize the subsystem (::SDL_INIT_HAPTIC). - * - Open a haptic device. - * - SDL_HapticOpen() to open from index. - * - SDL_HapticOpenFromJoystick() to open from an existing joystick. - * - Create an effect (::SDL_HapticEffect). - * - Upload the effect with SDL_HapticNewEffect(). - * - Run the effect with SDL_HapticRunEffect(). - * - (optional) Free the effect with SDL_HapticDestroyEffect(). - * - Close the haptic device with SDL_HapticClose(). - * - * \par Simple rumble example: - * \code + * # CategoryHaptic + * + * SDL haptic subsystem allows you to control haptic (force feedback) devices. + * + * The basic usage is as follows: + * + * - Initialize the subsystem (SDL_INIT_HAPTIC). + * - Open a haptic device. + * - SDL_HapticOpen() to open from index. + * - SDL_HapticOpenFromJoystick() to open from an existing joystick. + * - Create an effect (SDL_HapticEffect). + * - Upload the effect with SDL_HapticNewEffect(). + * - Run the effect with SDL_HapticRunEffect(). + * - (optional) Free the effect with SDL_HapticDestroyEffect(). + * - Close the haptic device with SDL_HapticClose(). + * + * Simple rumble example: + * + * ```c * SDL_Haptic *haptic; * * // Open the device @@ -56,10 +57,11 @@ * * // Clean up * SDL_HapticClose( haptic ); - * \endcode + * ``` + * + * Complete example: * - * \par Complete example: - * \code + * ```c * int test_haptic( SDL_Joystick * joystick ) { * SDL_Haptic *haptic; * SDL_HapticEffect effect; @@ -101,7 +103,7 @@ * * return 0; // Success * } - * \endcode + * ``` */ #ifndef SDL_haptic_h_ @@ -154,31 +156,29 @@ typedef struct _SDL_Haptic SDL_Haptic; /* @{ */ /** - * \brief Constant effect supported. + * Constant effect supported. * - * Constant haptic effect. + * Constant haptic effect. * - * \sa SDL_HapticCondition + * \sa SDL_HapticCondition */ #define SDL_HAPTIC_CONSTANT (1u<<0) /** - * \brief Sine wave effect supported. + * Sine wave effect supported. * - * Periodic haptic effect that simulates sine waves. + * Periodic haptic effect that simulates sine waves. * - * \sa SDL_HapticPeriodic + * \sa SDL_HapticPeriodic */ #define SDL_HAPTIC_SINE (1u<<1) /** - * \brief Left/Right effect supported. + * Left/Right effect supported. * - * Haptic effect for direct control over high/low frequency motors. + * Haptic effect for direct control over high/low frequency motors. * - * \sa SDL_HapticLeftRight - * \warning this value was SDL_HAPTIC_SQUARE right before 2.0.0 shipped. Sorry, - * we ran out of bits, and this is important for XInput devices. + * \sa SDL_HapticLeftRight */ #define SDL_HAPTIC_LEFTRIGHT (1u<<2) @@ -186,85 +186,85 @@ typedef struct _SDL_Haptic SDL_Haptic; /* #define SDL_HAPTIC_SQUARE (1<<2) */ /** - * \brief Triangle wave effect supported. + * Triangle wave effect supported. * - * Periodic haptic effect that simulates triangular waves. + * Periodic haptic effect that simulates triangular waves. * - * \sa SDL_HapticPeriodic + * \sa SDL_HapticPeriodic */ #define SDL_HAPTIC_TRIANGLE (1u<<3) /** - * \brief Sawtoothup wave effect supported. + * Sawtoothup wave effect supported. * - * Periodic haptic effect that simulates saw tooth up waves. + * Periodic haptic effect that simulates saw tooth up waves. * - * \sa SDL_HapticPeriodic + * \sa SDL_HapticPeriodic */ #define SDL_HAPTIC_SAWTOOTHUP (1u<<4) /** - * \brief Sawtoothdown wave effect supported. + * Sawtoothdown wave effect supported. * - * Periodic haptic effect that simulates saw tooth down waves. + * Periodic haptic effect that simulates saw tooth down waves. * - * \sa SDL_HapticPeriodic + * \sa SDL_HapticPeriodic */ #define SDL_HAPTIC_SAWTOOTHDOWN (1u<<5) /** - * \brief Ramp effect supported. + * Ramp effect supported. * - * Ramp haptic effect. + * Ramp haptic effect. * - * \sa SDL_HapticRamp + * \sa SDL_HapticRamp */ #define SDL_HAPTIC_RAMP (1u<<6) /** - * \brief Spring effect supported - uses axes position. + * Spring effect supported - uses axes position. * - * Condition haptic effect that simulates a spring. Effect is based on the - * axes position. + * Condition haptic effect that simulates a spring. Effect is based on the + * axes position. * - * \sa SDL_HapticCondition + * \sa SDL_HapticCondition */ #define SDL_HAPTIC_SPRING (1u<<7) /** - * \brief Damper effect supported - uses axes velocity. + * Damper effect supported - uses axes velocity. * - * Condition haptic effect that simulates dampening. Effect is based on the - * axes velocity. + * Condition haptic effect that simulates dampening. Effect is based on the + * axes velocity. * - * \sa SDL_HapticCondition + * \sa SDL_HapticCondition */ #define SDL_HAPTIC_DAMPER (1u<<8) /** - * \brief Inertia effect supported - uses axes acceleration. + * Inertia effect supported - uses axes acceleration. * - * Condition haptic effect that simulates inertia. Effect is based on the axes - * acceleration. + * Condition haptic effect that simulates inertia. Effect is based on the axes + * acceleration. * - * \sa SDL_HapticCondition + * \sa SDL_HapticCondition */ #define SDL_HAPTIC_INERTIA (1u<<9) /** - * \brief Friction effect supported - uses axes movement. + * Friction effect supported - uses axes movement. * - * Condition haptic effect that simulates friction. Effect is based on the - * axes movement. + * Condition haptic effect that simulates friction. Effect is based on the + * axes movement. * - * \sa SDL_HapticCondition + * \sa SDL_HapticCondition */ #define SDL_HAPTIC_FRICTION (1u<<10) /** - * \brief Custom effect is supported. + * Custom effect is supported. * - * User defined custom haptic effect. + * User defined custom haptic effect. */ #define SDL_HAPTIC_CUSTOM (1u<<11) @@ -273,39 +273,39 @@ typedef struct _SDL_Haptic SDL_Haptic; /* These last few are features the device has, not effects */ /** - * \brief Device can set global gain. + * Device can set global gain. * - * Device supports setting the global gain. + * Device supports setting the global gain. * - * \sa SDL_HapticSetGain + * \sa SDL_HapticSetGain */ #define SDL_HAPTIC_GAIN (1u<<12) /** - * \brief Device can set autocenter. + * Device can set autocenter. * - * Device supports setting autocenter. + * Device supports setting autocenter. * - * \sa SDL_HapticSetAutocenter + * \sa SDL_HapticSetAutocenter */ #define SDL_HAPTIC_AUTOCENTER (1u<<13) /** - * \brief Device can be queried for effect status. + * Device can be queried for effect status. * - * Device supports querying effect status. + * Device supports querying effect status. * - * \sa SDL_HapticGetEffectStatus + * \sa SDL_HapticGetEffectStatus */ #define SDL_HAPTIC_STATUS (1u<<14) /** - * \brief Device can be paused. + * Device can be paused. * - * Devices supports being paused. + * Devices supports being paused. * - * \sa SDL_HapticPause - * \sa SDL_HapticUnpause + * \sa SDL_HapticPause + * \sa SDL_HapticUnpause */ #define SDL_HAPTIC_PAUSE (1u<<15) @@ -316,31 +316,33 @@ typedef struct _SDL_Haptic SDL_Haptic; /* @{ */ /** - * \brief Uses polar coordinates for the direction. + * Uses polar coordinates for the direction. * - * \sa SDL_HapticDirection + * \sa SDL_HapticDirection */ #define SDL_HAPTIC_POLAR 0 /** - * \brief Uses cartesian coordinates for the direction. + * Uses cartesian coordinates for the direction. * - * \sa SDL_HapticDirection + * \sa SDL_HapticDirection */ #define SDL_HAPTIC_CARTESIAN 1 /** - * \brief Uses spherical coordinates for the direction. + * Uses spherical coordinates for the direction. * - * \sa SDL_HapticDirection + * \sa SDL_HapticDirection */ #define SDL_HAPTIC_SPHERICAL 2 /** - * \brief Use this value to play an effect on the steering wheel axis. This - * provides better compatibility across platforms and devices as SDL will guess - * the correct axis. - * \sa SDL_HapticDirection + * Use this value to play an effect on the steering wheel axis. + * + * This provides better compatibility across platforms and devices as SDL will + * guess the correct axis. + * + * \sa SDL_HapticDirection */ #define SDL_HAPTIC_STEERING_AXIS 3 @@ -353,7 +355,7 @@ typedef struct _SDL_Haptic SDL_Haptic; */ /** - * \brief Used to play a device an infinite number of times. + * Used to play a device an infinite number of times. * * \sa SDL_HapticRunEffect */ @@ -361,77 +363,82 @@ typedef struct _SDL_Haptic SDL_Haptic; /** - * \brief Structure that represents a haptic direction. - * - * This is the direction where the force comes from, - * instead of the direction in which the force is exerted. - * - * Directions can be specified by: - * - ::SDL_HAPTIC_POLAR : Specified by polar coordinates. - * - ::SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates. - * - ::SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates. - * - * Cardinal directions of the haptic device are relative to the positioning - * of the device. North is considered to be away from the user. - * - * The following diagram represents the cardinal directions: - * \verbatim - .--. - |__| .-------. - |=.| |.-----.| - |--| || || - | | |'-----'| - |__|~')_____(' - [ COMPUTER ] - - - North (0,-1) - ^ - | - | - (-1,0) West <----[ HAPTIC ]----> East (1,0) - | - | - v - South (0,1) - - - [ USER ] - \|||/ - (o o) - ---ooO-(_)-Ooo--- - \endverbatim - * - * If type is ::SDL_HAPTIC_POLAR, direction is encoded by hundredths of a - * degree starting north and turning clockwise. ::SDL_HAPTIC_POLAR only uses - * the first \c dir parameter. The cardinal directions would be: - * - North: 0 (0 degrees) - * - East: 9000 (90 degrees) - * - South: 18000 (180 degrees) - * - West: 27000 (270 degrees) - * - * If type is ::SDL_HAPTIC_CARTESIAN, direction is encoded by three positions - * (X axis, Y axis and Z axis (with 3 axes)). ::SDL_HAPTIC_CARTESIAN uses - * the first three \c dir parameters. The cardinal directions would be: - * - North: 0,-1, 0 - * - East: 1, 0, 0 - * - South: 0, 1, 0 - * - West: -1, 0, 0 - * - * The Z axis represents the height of the effect if supported, otherwise - * it's unused. In cartesian encoding (1, 2) would be the same as (2, 4), you - * can use any multiple you want, only the direction matters. - * - * If type is ::SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations. - * The first two \c dir parameters are used. The \c dir parameters are as - * follows (all values are in hundredths of degrees): - * - Degrees from (1, 0) rotated towards (0, 1). - * - Degrees towards (0, 0, 1) (device needs at least 3 axes). - * - * - * Example of force coming from the south with all encodings (force coming - * from the south means the user will have to pull the stick to counteract): - * \code + * Structure that represents a haptic direction. + * + * This is the direction where the force comes from, instead of the direction + * in which the force is exerted. + * + * Directions can be specified by: + * + * - SDL_HAPTIC_POLAR : Specified by polar coordinates. + * - SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates. + * - SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates. + * + * Cardinal directions of the haptic device are relative to the positioning of + * the device. North is considered to be away from the user. + * + * The following diagram represents the cardinal directions: + * + * ``` + * .--. + * |__| .-------. + * |=.| |.-----.| + * |--| || || + * | | |'-----'| + * |__|~')_____(' + * [ COMPUTER ] + * + * + * North (0,-1) + * ^ + * | + * | + * (-1,0) West <----[ HAPTIC ]----> East (1,0) + * | + * | + * v + * South (0,1) + * + * + * [ USER ] + * \|||/ + * (o o) + * ---ooO-(_)-Ooo--- + * ``` + * + * If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a degree + * starting north and turning clockwise. SDL_HAPTIC_POLAR only uses the first + * `dir` parameter. The cardinal directions would be: + * + * - North: 0 (0 degrees) + * - East: 9000 (90 degrees) + * - South: 18000 (180 degrees) + * - West: 27000 (270 degrees) + * + * If type is SDL_HAPTIC_CARTESIAN, direction is encoded by three positions (X + * axis, Y axis and Z axis (with 3 axes)). SDL_HAPTIC_CARTESIAN uses the first + * three `dir` parameters. The cardinal directions would be: + * + * - North: 0,-1, 0 + * - East: 1, 0, 0 + * - South: 0, 1, 0 + * - West: -1, 0, 0 + * + * The Z axis represents the height of the effect if supported, otherwise it's + * unused. In cartesian encoding (1, 2) would be the same as (2, 4), you can + * use any multiple you want, only the direction matters. + * + * If type is SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations. The + * first two `dir` parameters are used. The `dir` parameters are as follows + * (all values are in hundredths of degrees): + * + * - Degrees from (1, 0) rotated towards (0, 1). + * - Degrees towards (0, 0, 1) (device needs at least 3 axes). + * + * Example of force coming from the south with all encodings (force coming + * from the south means the user will have to pull the stick to counteract): + * + * ```c * SDL_HapticDirection direction; * * // Cartesian directions @@ -447,14 +454,14 @@ typedef struct _SDL_Haptic SDL_Haptic; * // Spherical coordinates * direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding * direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters. - * \endcode + * ``` * - * \sa SDL_HAPTIC_POLAR - * \sa SDL_HAPTIC_CARTESIAN - * \sa SDL_HAPTIC_SPHERICAL - * \sa SDL_HAPTIC_STEERING_AXIS - * \sa SDL_HapticEffect - * \sa SDL_HapticNumAxes + * \sa SDL_HAPTIC_POLAR + * \sa SDL_HAPTIC_CARTESIAN + * \sa SDL_HAPTIC_SPHERICAL + * \sa SDL_HAPTIC_STEERING_AXIS + * \sa SDL_HapticEffect + * \sa SDL_HapticNumAxes */ typedef struct SDL_HapticDirection { @@ -464,20 +471,20 @@ typedef struct SDL_HapticDirection /** - * \brief A structure containing a template for a Constant effect. + * A structure containing a template for a Constant effect. * - * This struct is exclusively for the ::SDL_HAPTIC_CONSTANT effect. + * This struct is exclusively for the SDL_HAPTIC_CONSTANT effect. * - * A constant effect applies a constant force in the specified direction - * to the joystick. + * A constant effect applies a constant force in the specified direction to + * the joystick. * - * \sa SDL_HAPTIC_CONSTANT - * \sa SDL_HapticEffect + * \sa SDL_HAPTIC_CONSTANT + * \sa SDL_HapticEffect */ typedef struct SDL_HapticConstant { /* Header */ - Uint16 type; /**< ::SDL_HAPTIC_CONSTANT */ + Uint16 type; /**< SDL_HAPTIC_CONSTANT */ SDL_HapticDirection direction; /**< Direction of the effect. */ /* Replay */ @@ -499,68 +506,71 @@ typedef struct SDL_HapticConstant } SDL_HapticConstant; /** - * \brief A structure containing a template for a Periodic effect. - * - * The struct handles the following effects: - * - ::SDL_HAPTIC_SINE - * - ::SDL_HAPTIC_LEFTRIGHT - * - ::SDL_HAPTIC_TRIANGLE - * - ::SDL_HAPTIC_SAWTOOTHUP - * - ::SDL_HAPTIC_SAWTOOTHDOWN - * - * A periodic effect consists in a wave-shaped effect that repeats itself - * over time. The type determines the shape of the wave and the parameters - * determine the dimensions of the wave. - * - * Phase is given by hundredth of a degree meaning that giving the phase a value - * of 9000 will displace it 25% of its period. Here are sample values: - * - 0: No phase displacement. - * - 9000: Displaced 25% of its period. - * - 18000: Displaced 50% of its period. - * - 27000: Displaced 75% of its period. - * - 36000: Displaced 100% of its period, same as 0, but 0 is preferred. - * - * Examples: - * \verbatim - SDL_HAPTIC_SINE - __ __ __ __ - / \ / \ / \ / - / \__/ \__/ \__/ - - SDL_HAPTIC_SQUARE - __ __ __ __ __ - | | | | | | | | | | - | |__| |__| |__| |__| | - - SDL_HAPTIC_TRIANGLE - /\ /\ /\ /\ /\ - / \ / \ / \ / \ / - / \/ \/ \/ \/ - - SDL_HAPTIC_SAWTOOTHUP - /| /| /| /| /| /| /| - / | / | / | / | / | / | / | - / |/ |/ |/ |/ |/ |/ | - - SDL_HAPTIC_SAWTOOTHDOWN - \ |\ |\ |\ |\ |\ |\ | - \ | \ | \ | \ | \ | \ | \ | - \| \| \| \| \| \| \| - \endverbatim - * - * \sa SDL_HAPTIC_SINE - * \sa SDL_HAPTIC_LEFTRIGHT - * \sa SDL_HAPTIC_TRIANGLE - * \sa SDL_HAPTIC_SAWTOOTHUP - * \sa SDL_HAPTIC_SAWTOOTHDOWN - * \sa SDL_HapticEffect + * A structure containing a template for a Periodic effect. + * + * The struct handles the following effects: + * + * - SDL_HAPTIC_SINE + * - SDL_HAPTIC_SQUARE + * - SDL_HAPTIC_TRIANGLE + * - SDL_HAPTIC_SAWTOOTHUP + * - SDL_HAPTIC_SAWTOOTHDOWN + * + * A periodic effect consists in a wave-shaped effect that repeats itself over + * time. The type determines the shape of the wave and the parameters + * determine the dimensions of the wave. + * + * Phase is given by hundredth of a degree meaning that giving the phase a + * value of 9000 will displace it 25% of its period. Here are sample values: + * + * - 0: No phase displacement. + * - 9000: Displaced 25% of its period. + * - 18000: Displaced 50% of its period. + * - 27000: Displaced 75% of its period. + * - 36000: Displaced 100% of its period, same as 0, but 0 is preferred. + * + * Examples: + * + * ``` + * SDL_HAPTIC_SINE + * __ __ __ __ + * / \ / \ / \ / + * / \__/ \__/ \__/ + * + * SDL_HAPTIC_SQUARE + * __ __ __ __ __ + * | | | | | | | | | | + * | |__| |__| |__| |__| | + * + * SDL_HAPTIC_TRIANGLE + * /\ /\ /\ /\ /\ + * / \ / \ / \ / \ / + * / \/ \/ \/ \/ + * + * SDL_HAPTIC_SAWTOOTHUP + * /| /| /| /| /| /| /| + * / | / | / | / | / | / | / | + * / |/ |/ |/ |/ |/ |/ | + * + * SDL_HAPTIC_SAWTOOTHDOWN + * \ |\ |\ |\ |\ |\ |\ | + * \ | \ | \ | \ | \ | \ | \ | + * \| \| \| \| \| \| \| + * ``` + * + * \sa SDL_HAPTIC_SINE + * \sa SDL_HAPTIC_LEFTRIGHT + * \sa SDL_HAPTIC_TRIANGLE + * \sa SDL_HAPTIC_SAWTOOTHUP + * \sa SDL_HAPTIC_SAWTOOTHDOWN + * \sa SDL_HapticEffect */ typedef struct SDL_HapticPeriodic { /* Header */ - Uint16 type; /**< ::SDL_HAPTIC_SINE, ::SDL_HAPTIC_LEFTRIGHT, - ::SDL_HAPTIC_TRIANGLE, ::SDL_HAPTIC_SAWTOOTHUP or - ::SDL_HAPTIC_SAWTOOTHDOWN */ + Uint16 type; /**< SDL_HAPTIC_SINE, SDL_HAPTIC_LEFTRIGHT, + SDL_HAPTIC_TRIANGLE, SDL_HAPTIC_SAWTOOTHUP or + SDL_HAPTIC_SAWTOOTHDOWN */ SDL_HapticDirection direction; /**< Direction of the effect. */ /* Replay */ @@ -585,35 +595,36 @@ typedef struct SDL_HapticPeriodic } SDL_HapticPeriodic; /** - * \brief A structure containing a template for a Condition effect. + * A structure containing a template for a Condition effect. * - * The struct handles the following effects: - * - ::SDL_HAPTIC_SPRING: Effect based on axes position. - * - ::SDL_HAPTIC_DAMPER: Effect based on axes velocity. - * - ::SDL_HAPTIC_INERTIA: Effect based on axes acceleration. - * - ::SDL_HAPTIC_FRICTION: Effect based on axes movement. + * The struct handles the following effects: * - * Direction is handled by condition internals instead of a direction member. - * The condition effect specific members have three parameters. The first - * refers to the X axis, the second refers to the Y axis and the third - * refers to the Z axis. The right terms refer to the positive side of the - * axis and the left terms refer to the negative side of the axis. Please - * refer to the ::SDL_HapticDirection diagram for which side is positive and - * which is negative. + * - SDL_HAPTIC_SPRING: Effect based on axes position. + * - SDL_HAPTIC_DAMPER: Effect based on axes velocity. + * - SDL_HAPTIC_INERTIA: Effect based on axes acceleration. + * - SDL_HAPTIC_FRICTION: Effect based on axes movement. * - * \sa SDL_HapticDirection - * \sa SDL_HAPTIC_SPRING - * \sa SDL_HAPTIC_DAMPER - * \sa SDL_HAPTIC_INERTIA - * \sa SDL_HAPTIC_FRICTION - * \sa SDL_HapticEffect + * Direction is handled by condition internals instead of a direction member. + * The condition effect specific members have three parameters. The first + * refers to the X axis, the second refers to the Y axis and the third refers + * to the Z axis. The right terms refer to the positive side of the axis and + * the left terms refer to the negative side of the axis. Please refer to the + * SDL_HapticDirection diagram for which side is positive and which is + * negative. + * + * \sa SDL_HapticDirection + * \sa SDL_HAPTIC_SPRING + * \sa SDL_HAPTIC_DAMPER + * \sa SDL_HAPTIC_INERTIA + * \sa SDL_HAPTIC_FRICTION + * \sa SDL_HapticEffect */ typedef struct SDL_HapticCondition { /* Header */ - Uint16 type; /**< ::SDL_HAPTIC_SPRING, ::SDL_HAPTIC_DAMPER, - ::SDL_HAPTIC_INERTIA or ::SDL_HAPTIC_FRICTION */ - SDL_HapticDirection direction; /**< Direction of the effect - Not used ATM. */ + Uint16 type; /**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER, + SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION */ + SDL_HapticDirection direction; /**< Direction of the effect. */ /* Replay */ Uint32 length; /**< Duration of the effect. */ @@ -633,22 +644,22 @@ typedef struct SDL_HapticCondition } SDL_HapticCondition; /** - * \brief A structure containing a template for a Ramp effect. + * A structure containing a template for a Ramp effect. * - * This struct is exclusively for the ::SDL_HAPTIC_RAMP effect. + * This struct is exclusively for the SDL_HAPTIC_RAMP effect. * - * The ramp effect starts at start strength and ends at end strength. - * It augments in linear fashion. If you use attack and fade with a ramp - * the effects get added to the ramp effect making the effect become - * quadratic instead of linear. + * The ramp effect starts at start strength and ends at end strength. It + * augments in linear fashion. If you use attack and fade with a ramp the + * effects get added to the ramp effect making the effect become quadratic + * instead of linear. * - * \sa SDL_HAPTIC_RAMP - * \sa SDL_HapticEffect + * \sa SDL_HAPTIC_RAMP + * \sa SDL_HapticEffect */ typedef struct SDL_HapticRamp { /* Header */ - Uint16 type; /**< ::SDL_HAPTIC_RAMP */ + Uint16 type; /**< SDL_HAPTIC_RAMP */ SDL_HapticDirection direction; /**< Direction of the effect. */ /* Replay */ @@ -671,9 +682,9 @@ typedef struct SDL_HapticRamp } SDL_HapticRamp; /** - * \brief A structure containing a template for a Left/Right effect. + * A structure containing a template for a Left/Right effect. * - * This struct is exclusively for the ::SDL_HAPTIC_LEFTRIGHT effect. + * This struct is exclusively for the SDL_HAPTIC_LEFTRIGHT effect. * * The Left/Right effect is used to explicitly control the large and small * motors, commonly found in modern game controllers. The small (right) motor @@ -685,7 +696,7 @@ typedef struct SDL_HapticRamp typedef struct SDL_HapticLeftRight { /* Header */ - Uint16 type; /**< ::SDL_HAPTIC_LEFTRIGHT */ + Uint16 type; /**< SDL_HAPTIC_LEFTRIGHT */ /* Replay */ Uint32 length; /**< Duration of the effect in milliseconds. */ @@ -696,24 +707,24 @@ typedef struct SDL_HapticLeftRight } SDL_HapticLeftRight; /** - * \brief A structure containing a template for the ::SDL_HAPTIC_CUSTOM effect. + * A structure containing a template for the SDL_HAPTIC_CUSTOM effect. * - * This struct is exclusively for the ::SDL_HAPTIC_CUSTOM effect. + * This struct is exclusively for the SDL_HAPTIC_CUSTOM effect. * - * A custom force feedback effect is much like a periodic effect, where the - * application can define its exact shape. You will have to allocate the - * data yourself. Data should consist of channels * samples Uint16 samples. + * A custom force feedback effect is much like a periodic effect, where the + * application can define its exact shape. You will have to allocate the data + * yourself. Data should consist of channels * samples Uint16 samples. * - * If channels is one, the effect is rotated using the defined direction. - * Otherwise it uses the samples in data for the different axes. + * If channels is one, the effect is rotated using the defined direction. + * Otherwise it uses the samples in data for the different axes. * - * \sa SDL_HAPTIC_CUSTOM - * \sa SDL_HapticEffect + * \sa SDL_HAPTIC_CUSTOM + * \sa SDL_HapticEffect */ typedef struct SDL_HapticCustom { /* Header */ - Uint16 type; /**< ::SDL_HAPTIC_CUSTOM */ + Uint16 type; /**< SDL_HAPTIC_CUSTOM */ SDL_HapticDirection direction; /**< Direction of the effect. */ /* Replay */ @@ -738,27 +749,28 @@ typedef struct SDL_HapticCustom } SDL_HapticCustom; /** - * \brief The generic template for any haptic effect. + * The generic template for any haptic effect. + * + * All values max at 32767 (0x7FFF). Signed values also can be negative. Time + * values unless specified otherwise are in milliseconds. * - * All values max at 32767 (0x7FFF). Signed values also can be negative. - * Time values unless specified otherwise are in milliseconds. + * You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value. + * Neither delay, interval, attack_length nor fade_length support + * SDL_HAPTIC_INFINITY. Fade will also not be used since effect never ends. * - * You can also pass ::SDL_HAPTIC_INFINITY to length instead of a 0-32767 - * value. Neither delay, interval, attack_length nor fade_length support - * ::SDL_HAPTIC_INFINITY. Fade will also not be used since effect never ends. + * Additionally, the SDL_HAPTIC_RAMP effect does not support a duration of + * SDL_HAPTIC_INFINITY. * - * Additionally, the ::SDL_HAPTIC_RAMP effect does not support a duration of - * ::SDL_HAPTIC_INFINITY. + * Button triggers may not be supported on all devices, it is advised to not + * use them if possible. Buttons start at index 1 instead of index 0 like the + * joystick. * - * Button triggers may not be supported on all devices, it is advised to not - * use them if possible. Buttons start at index 1 instead of index 0 like - * the joystick. + * If both attack_length and fade_level are 0, the envelope is not used, + * otherwise both values are used. * - * If both attack_length and fade_level are 0, the envelope is not used, - * otherwise both values are used. + * Common parts: * - * Common parts: - * \code + * ```c * // Replay - All effects have this * Uint32 length; // Duration of effect (ms). * Uint16 delay; // Delay before starting effect. @@ -772,39 +784,39 @@ typedef struct SDL_HapticCustom * Uint16 attack_level; // Level at the start of the attack. * Uint16 fade_length; // Duration of the fade out (ms). * Uint16 fade_level; // Level at the end of the fade. - * \endcode - * - * - * Here we have an example of a constant effect evolution in time: - * \verbatim - Strength - ^ - | - | effect level --> _________________ - | / \ - | / \ - | / \ - | / \ - | attack_level --> | \ - | | | <--- fade_level - | - +--------------------------------------------------> Time - [--] [---] - attack_length fade_length - - [------------------][-----------------------] - delay length - \endverbatim - * - * Note either the attack_level or the fade_level may be above the actual - * effect level. - * - * \sa SDL_HapticConstant - * \sa SDL_HapticPeriodic - * \sa SDL_HapticCondition - * \sa SDL_HapticRamp - * \sa SDL_HapticLeftRight - * \sa SDL_HapticCustom + * ``` + * + * Here we have an example of a constant effect evolution in time: + * + * ``` + * Strength + * ^ + * | + * | effect level --> _________________ + * | / \ + * | / \ + * | / \ + * | / \ + * | attack_level --> | \ + * | | | <--- fade_level + * | + * +--------------------------------------------------> Time + * [--] [---] + * attack_length fade_length + * + * [------------------][-----------------------] + * delay length + * ``` + * + * Note either the attack_level or the fade_level may be above the actual + * effect level. + * + * \sa SDL_HapticConstant + * \sa SDL_HapticPeriodic + * \sa SDL_HapticCondition + * \sa SDL_HapticRamp + * \sa SDL_HapticLeftRight + * \sa SDL_HapticCustom */ typedef union SDL_HapticEffect { @@ -859,7 +871,7 @@ extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index); * autocenter will be disabled. To modify these values use SDL_HapticSetGain() * and SDL_HapticSetAutocenter(). * - * \param device_index index of the device to open + * \param device_index index of the device to open. * \returns the device identifier or NULL on failure; call SDL_GetError() for * more information. * @@ -879,7 +891,7 @@ extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index); /** * Check if the haptic device at the designated index has been opened. * - * \param device_index the index of the device to query + * \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. * @@ -893,7 +905,7 @@ extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index); /** * Get the index of a haptic device. * - * \param haptic the SDL_Haptic device to query + * \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. * @@ -931,7 +943,7 @@ extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void); /** * Query if a joystick has haptic features. * - * \param joystick the SDL_Joystick to test for haptic capabilities + * \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. @@ -953,7 +965,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick); * device will also get unallocated and you'll be unable to use force feedback * on that device. * - * \param joystick the SDL_Joystick to create a haptic device from + * \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. * @@ -969,7 +981,7 @@ extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick * /** * Close a haptic device previously opened with SDL_HapticOpen(). * - * \param haptic the SDL_Haptic device to close + * \param haptic the SDL_Haptic device to close. * * \since This function is available since SDL 2.0.0. * @@ -984,7 +996,7 @@ extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic); * approximation. Always check to see if your created effect was actually * created and do not rely solely on SDL_HapticNumEffects(). * - * \param haptic the SDL_Haptic device to query + * \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. * @@ -1000,7 +1012,7 @@ extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic); * * This is not supported on all platforms, but will always return a value. * - * \param haptic the SDL_Haptic device to query maximum playing effects + * \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. @@ -1015,7 +1027,7 @@ extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic); /** * Get the haptic device's supported features in bitwise manner. * - * \param haptic the SDL_Haptic device to query + * \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. * @@ -1033,7 +1045,7 @@ extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic); * The number of haptic axes might be useful if working with the * SDL_HapticDirection effect. * - * \param haptic the SDL_Haptic device to query + * \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. * @@ -1044,8 +1056,8 @@ extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic); /** * Check to see if an effect is supported by a haptic device. * - * \param haptic the SDL_Haptic device to query - * \param effect the desired effect to query + * \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. @@ -1062,9 +1074,9 @@ extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic, /** * Create a new haptic effect on a specified device. * - * \param haptic an SDL_Haptic device to create the effect on + * \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 + * 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. * @@ -1085,10 +1097,10 @@ extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic, * start playing from the start. You also cannot change the type either when * running SDL_HapticUpdateEffect(). * - * \param haptic the SDL_Haptic device that has the effect - * \param effect the identifier of the effect to update + * \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 + * properties to use. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1111,10 +1123,10 @@ extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic, * set the effect's `length` in its structure/union to `SDL_HAPTIC_INFINITY` * instead. * - * \param haptic the SDL_Haptic device to run the effect on - * \param effect the ID of the haptic effect to run + * \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 + * `SDL_HAPTIC_INFINITY` to repeat forever. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1133,8 +1145,8 @@ extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic, * * * * - * \param haptic the SDL_Haptic device to stop the effect on - * \param effect the ID of the haptic effect to stop + * \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. * @@ -1152,8 +1164,8 @@ extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic, * This will stop the effect if it's running. Effects are automatically * destroyed when the device is closed. * - * \param haptic the SDL_Haptic device to destroy the effect on - * \param effect the ID of the haptic effect to destroy + * \param haptic the SDL_Haptic device to destroy the effect on. + * \param effect the ID of the haptic effect to destroy. * * \since This function is available since SDL 2.0.0. * @@ -1167,8 +1179,8 @@ extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic, * * Device must support the SDL_HAPTIC_STATUS feature. * - * \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 + * \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. * @@ -1190,8 +1202,9 @@ extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic, * SDL_HapticSetGain() will scale linearly using `SDL_HAPTIC_GAIN_MAX` as the * maximum. * - * \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) + * \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. * @@ -1209,8 +1222,8 @@ extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain); * * Device must support the SDL_HAPTIC_AUTOCENTER feature. * - * \param haptic the SDL_Haptic device to set autocentering on - * \param autocenter value to set autocenter to (0-100) + * \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. * @@ -1230,7 +1243,7 @@ extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic, * Do not modify the effects nor add new ones while the device is paused. That * can cause all sorts of weird errors. * - * \param haptic the SDL_Haptic device to pause + * \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. * @@ -1245,7 +1258,7 @@ extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic); * * Call to unpause after SDL_HapticPause(). * - * \param haptic the SDL_Haptic device to unpause + * \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. * @@ -1258,7 +1271,7 @@ extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic); /** * Stop all the currently playing effects on a haptic device. * - * \param haptic the SDL_Haptic device to stop + * \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. * @@ -1269,7 +1282,7 @@ extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic); /** * Check whether rumble is supported on a haptic device. * - * \param haptic haptic device to check for rumble support + * \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. @@ -1285,7 +1298,7 @@ extern DECLSPEC int SDLCALL SDL_HapticRumbleSupported(SDL_Haptic * haptic); /** * Initialize a haptic device for simple rumble playback. * - * \param haptic the haptic device to initialize for simple rumble playback + * \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. * @@ -1301,9 +1314,9 @@ extern DECLSPEC int SDLCALL SDL_HapticRumbleInit(SDL_Haptic * haptic); /** * Run a simple rumble effect on a haptic device. * - * \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 + * \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. * @@ -1318,7 +1331,7 @@ extern DECLSPEC int SDLCALL SDL_HapticRumblePlay(SDL_Haptic * haptic, float stre /** * Stop the simple rumble on a haptic device. * - * \param haptic the haptic device to stop the rumble effect on + * \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. * diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_hidapi.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_hidapi.h @@ -19,44 +19,35 @@ 3. This notice may not be removed or altered from any source distribution. */ +/* WIKI CATEGORY: HIDAPI */ + /** - * \file SDL_hidapi.h - * - * Header file for SDL HIDAPI functions. - * - * This is an adaptation of the original HIDAPI interface by Alan Ott, - * and includes source code licensed under the following BSD license: - * - Copyright (c) 2010, Alan Ott, Signal 11 Software - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright notice, - this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - * Neither the name of Signal 11 Software nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE - LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS - INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. + * # CategoryHIDAPI + * + * Header file for SDL HIDAPI functions. + * + * This is an adaptation of the original HIDAPI interface by Alan Ott, and + * includes source code licensed under the following license: + * + * ``` + * HIDAPI - Multi-Platform library for + * communication with HID devices. + * + * Copyright 2009, Alan Ott, Signal 11 Software. + * All Rights Reserved. + * + * This software may be used by anyone for any reason so + * long as the copyright notice in the source files + * remains intact. + * ``` + * + * (Note that this license is the same as item three of SDL's zlib license, so + * it adds no new requirements on the user.) * * If you would like a version of SDL without this code, you can build SDL - * with SDL_HIDAPI_DISABLED defined to 1. You might want to do this for example - * on iOS or tvOS to avoid a dependency on the CoreBluetooth framework. + * with SDL_HIDAPI_DISABLED defined to 1. You might want to do this for + * example on iOS or tvOS to avoid a dependency on the CoreBluetooth + * framework. */ #ifndef SDL_hidapi_h_ @@ -71,14 +62,15 @@ extern "C" { #endif /** - * \brief A handle representing an open HID device + * A handle representing an open HID device */ struct SDL_hid_device_; typedef struct SDL_hid_device_ SDL_hid_device; /**< opaque hidapi structure */ /** hidapi info structure */ + /** - * \brief Information about a connected HID device + * Information about a connected HID device */ typedef struct SDL_hid_device_info { @@ -234,13 +226,13 @@ extern DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_id, * The path name be determined by calling SDL_hid_enumerate(), or a * platform-specific path name can be used (eg: /dev/hidraw0 on Linux). * - * \param path The path name of the device to open + * \param path The path name of the device to open. * \returns a pointer to a SDL_hid_device object on success or NULL on * failure. * * \since This function is available since SDL 2.0.18. */ -extern DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path, int bExclusive /* = false */); +extern DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path, int bExclusive); /** * Write an Output report to a HID device. @@ -434,7 +426,7 @@ extern DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev, int /** * Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers * - * \param active SDL_TRUE to start the scan, SDL_FALSE to stop the scan + * \param active SDL_TRUE to start the scan, SDL_FALSE to stop the scan. * * \since This function is available since SDL 2.0.18. */ diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_hints.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_hints.h @@ -20,20 +20,20 @@ */ /** - * \file SDL_hints.h + * # CategoryHints * - * Official documentation for SDL configuration variables + * Official documentation for SDL configuration variables * - * This file contains functions to set and get configuration hints, - * as well as listing each of them alphabetically. + * This file contains functions to set and get configuration hints, as well as + * listing each of them alphabetically. * - * The convention for naming hints is SDL_HINT_X, where "SDL_X" is - * the environment variable that can be used to override the default. + * The convention for naming hints is SDL_HINT_X, where "SDL_X" is the + * environment variable that can be used to override the default. * - * In general these hints are just that - they may or may not be - * supported or applicable on any given platform, but they provide - * a way for an application or user to give the library a hint as - * to how they would like the library to work. + * In general these hints are just that - they may or may not be supported or + * applicable on any given platform, but they provide a way for an application + * or user to give the library a hint as to how they would like the library to + * work. */ #ifndef SDL_hints_h_ @@ -48,110 +48,132 @@ extern "C" { #endif /** - * \brief A variable controlling whether the Android / iOS built-in - * accelerometer should be listed as a joystick device. + * A variable controlling whether the Android / iOS built-in accelerometer + * should be listed as a joystick device. * - * This variable can be set to the following values: - * "0" - The accelerometer is not listed as a joystick - * "1" - The accelerometer is available as a 3 axis joystick (the default). + * This variable can be set to the following values: + * + * - "0": The accelerometer is not listed as a joystick + * - "1": The accelerometer is available as a 3 axis joystick (the default). */ #define SDL_HINT_ACCELEROMETER_AS_JOYSTICK "SDL_ACCELEROMETER_AS_JOYSTICK" /** - * \brief Specify the behavior of Alt+Tab while the keyboard is grabbed. + * Specify the behavior of Alt+Tab while the keyboard is grabbed. * - * By default, SDL emulates Alt+Tab functionality while the keyboard is grabbed - * and your window is full-screen. This prevents the user from getting stuck in - * your application if you've enabled keyboard grab. + * By default, SDL emulates Alt+Tab functionality while the keyboard is + * grabbed and your window is full-screen. This prevents the user from getting + * stuck in your application if you've enabled keyboard grab. * * The variable can be set to the following values: - * "0" - SDL will not handle Alt+Tab. Your application is responsible - for handling Alt+Tab while the keyboard is grabbed. - * "1" - SDL will minimize your window when Alt+Tab is pressed (default) -*/ + * + * - "0": SDL will not handle Alt+Tab. Your application is responsible for + * handling Alt+Tab while the keyboard is grabbed. + * - "1": SDL will minimize your window when Alt+Tab is pressed (default) + */ #define SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED "SDL_ALLOW_ALT_TAB_WHILE_GRABBED" /** - * \brief If set to "0" then never set the top most bit on a SDL Window, even if the video mode expects it. - * This is a debugging aid for developers and not expected to be used by end users. The default is "1" + * If set to "0" then never set the top most bit on a SDL Window, even if the + * video mode expects it. + * + * This is a debugging aid for developers and not expected to be used by end + * users. The default is "1" * - * This variable can be set to the following values: - * "0" - don't allow topmost - * "1" - allow topmost + * This variable can be set to the following values: + * + * - "0": don't allow topmost + * - "1": allow topmost */ #define SDL_HINT_ALLOW_TOPMOST "SDL_ALLOW_TOPMOST" /** - * \brief Android APK expansion main file version. Should be a string number like "1", "2" etc. + * Android APK expansion main file version. + * + * Should be a string number like "1", "2" etc. * - * Must be set together with SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION. + * Must be set together with + * SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION. * * If both hints were set then SDL_RWFromFile() will look into expansion files - * after a given relative path was not found in the internal storage and assets. + * after a given relative path was not found in the internal storage and + * assets. * - * By default this hint is not set and the APK expansion files are not searched. + * By default this hint is not set and the APK expansion files are not + * searched. */ #define SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION "SDL_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION" /** - * \brief Android APK expansion patch file version. Should be a string number like "1", "2" etc. + * Android APK expansion patch file version. + * + * Should be a string number like "1", "2" etc. * * Must be set together with SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION. * * If both hints were set then SDL_RWFromFile() will look into expansion files - * after a given relative path was not found in the internal storage and assets. + * after a given relative path was not found in the internal storage and + * assets. * - * By default this hint is not set and the APK expansion files are not searched. + * By default this hint is not set and the APK expansion files are not + * searched. */ #define SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION "SDL_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION" /** - * \brief A variable to control whether the event loop will block itself when the app is paused. + * A variable to control whether the event loop will block itself when the app + * is paused. * * The variable can be set to the following values: - * "0" - Non blocking. - * "1" - Blocking. (default) + * + * - "0": Non blocking. + * - "1": Blocking. (default) * * The value should be set before SDL is initialized. */ #define SDL_HINT_ANDROID_BLOCK_ON_PAUSE "SDL_ANDROID_BLOCK_ON_PAUSE" /** - * \brief A variable to control whether SDL will pause audio in background - * (Requires SDL_ANDROID_BLOCK_ON_PAUSE as "Non blocking") + * A variable to control whether SDL will pause audio in background (Requires + * SDL_ANDROID_BLOCK_ON_PAUSE as "Non blocking") * * The variable can be set to the following values: - * "0" - Non paused. - * "1" - Paused. (default) + * + * - "0": Non paused. + * - "1": Paused. (default) * * The value should be set before SDL is initialized. */ #define SDL_HINT_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO "SDL_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO" /** - * \brief A variable to control whether we trap the Android back button to handle it manually. - * This is necessary for the right mouse button to work on some Android devices, or - * to be able to trap the back button for use in your code reliably. If set to true, - * the back button will show up as an SDL_KEYDOWN / SDL_KEYUP pair with a keycode of - * SDL_SCANCODE_AC_BACK. + * A variable to control whether we trap the Android back button to handle it + * manually. + * + * This is necessary for the right mouse button to work on some Android + * devices, or to be able to trap the back button for use in your code + * reliably. If set to true, the back button will show up as an SDL_KEYDOWN / + * SDL_KEYUP pair with a keycode of SDL_SCANCODE_AC_BACK. * * The variable can be set to the following values: - * "0" - Back button will be handled as usual for system. (default) - * "1" - Back button will be trapped, allowing you to handle the key press - * manually. (This will also let right mouse click work on systems - * where the right mouse button functions as back.) * - * The value of this hint is used at runtime, so it can be changed at any time. + * - "0": Back button will be handled as usual for system. (default) + * - "1": Back button will be trapped, allowing you to handle the key press + * manually. (This will also let right mouse click work on systems where the + * right mouse button functions as back.) + * + * The value of this hint is used at runtime, so it can be changed at any + * time. */ #define SDL_HINT_ANDROID_TRAP_BACK_BUTTON "SDL_ANDROID_TRAP_BACK_BUTTON" /** - * \brief Specify an application name. + * Specify an application name. * * This hint lets you specify the application name sent to the OS when * required. For example, this will often appear in volume control applets for * audio streams, and in lists of applications which are inhibiting the - * screensaver. You should use a string that describes your program ("My Game + * screensaver. You should use a string that describes your program ("My Game * 2: The Revenge") * * Setting this to "" or leaving it unset will have SDL use a reasonable @@ -166,48 +188,51 @@ extern "C" { #define SDL_HINT_APP_NAME "SDL_APP_NAME" /** - * \brief A variable controlling whether controllers used with the Apple TV - * generate UI events. + * A variable controlling whether controllers used with the Apple TV generate + * UI events. * * When UI events are generated by controller input, the app will be - * backgrounded when the Apple TV remote's menu button is pressed, and when the - * pause or B buttons on gamepads are pressed. + * backgrounded when the Apple TV remote's menu button is pressed, and when + * the pause or B buttons on gamepads are pressed. * * More information about properly making use of controllers for the Apple TV * can be found here: * https://developer.apple.com/tvos/human-interface-guidelines/remote-and-controllers/ * - * This variable can be set to the following values: - * "0" - Controller input does not generate UI events (the default). - * "1" - Controller input generates UI events. + * This variable can be set to the following values: + * + * - "0": Controller input does not generate UI events (the default). + * - "1": Controller input generates UI events. */ #define SDL_HINT_APPLE_TV_CONTROLLER_UI_EVENTS "SDL_APPLE_TV_CONTROLLER_UI_EVENTS" /** - * \brief A variable controlling whether the Apple TV remote's joystick axes - * will automatically match the rotation of the remote. + * A variable controlling whether the Apple TV remote's joystick axes will + * automatically match the rotation of the remote. * - * This variable can be set to the following values: - * "0" - Remote orientation does not affect joystick axes (the default). - * "1" - Joystick axes are based on the orientation of the remote. + * This variable can be set to the following values: + * + * - "0": Remote orientation does not affect joystick axes (the default). + * - "1": Joystick axes are based on the orientation of the remote. */ #define SDL_HINT_APPLE_TV_REMOTE_ALLOW_ROTATION "SDL_APPLE_TV_REMOTE_ALLOW_ROTATION" /** - * \brief A variable controlling the audio category on iOS and Mac OS X + * A variable controlling the audio category on iOS and Mac OS X * - * This variable can be set to the following values: + * This variable can be set to the following values: * - * "ambient" - Use the AVAudioSessionCategoryAmbient audio category, will be muted by the phone mute switch (default) - * "playback" - Use the AVAudioSessionCategoryPlayback category + * - "ambient": Use the AVAudioSessionCategoryAmbient audio category, will be + * muted by the phone mute switch (default) + * - "playback": Use the AVAudioSessionCategoryPlayback category * - * For more information, see Apple's documentation: - * https://developer.apple.com/library/content/documentation/Audio/Conceptual/AudioSessionProgrammingGuide/AudioSessionCategoriesandModes/AudioSessionCategoriesandModes.html + * For more information, see Apple's documentation: + * https://developer.apple.com/library/content/documentation/Audio/Conceptual/AudioSessionProgrammingGuide/AudioSessionCategoriesandModes/AudioSessionCategoriesandModes.html */ #define SDL_HINT_AUDIO_CATEGORY "SDL_AUDIO_CATEGORY" /** - * \brief Specify an application name for an audio device. + * Specify an application name for an audio device. * * Some audio backends (such as PulseAudio) allow you to describe your audio * stream. Among other things, this description might show up in a system @@ -228,7 +253,7 @@ extern "C" { #define SDL_HINT_AUDIO_DEVICE_APP_NAME "SDL_AUDIO_DEVICE_APP_NAME" /** - * \brief Specify an application name for an audio device. + * Specify an application name for an audio device. * * Some audio backends (such as PulseAudio) allow you to describe your audio * stream. Among other things, this description might show up in a system @@ -249,11 +274,11 @@ extern "C" { #define SDL_HINT_AUDIO_DEVICE_STREAM_NAME "SDL_AUDIO_DEVICE_STREAM_NAME" /** - * \brief Specify an application role for an audio device. + * Specify an application role for an audio device. * * Some audio backends (such as Pipewire) allow you to describe the role of - * your audio stream. Among other things, this description might show up in - * a system control panel or software for displaying and manipulating media + * your audio stream. Among other things, this description might show up in a + * system control panel or software for displaying and manipulating media * playback/capture graphs. * * This hints lets you transmit that information to the OS. The contents of @@ -269,1168 +294,1384 @@ extern "C" { #define SDL_HINT_AUDIO_DEVICE_STREAM_ROLE "SDL_AUDIO_DEVICE_STREAM_ROLE" /** - * \brief A variable controlling speed/quality tradeoff of audio resampling. + * A variable controlling speed/quality tradeoff of audio resampling. * - * If available, SDL can use libsamplerate ( http://www.mega-nerd.com/SRC/ ) - * to handle audio resampling. There are different resampling modes available - * that produce different levels of quality, using more CPU. + * If available, SDL can use libsamplerate ( http://www.mega-nerd.com/SRC/ ) + * to handle audio resampling. There are different resampling modes available + * that produce different levels of quality, using more CPU. * - * If this hint isn't specified to a valid setting, or libsamplerate isn't - * available, SDL will use the default, internal resampling algorithm. + * If this hint isn't specified to a valid setting, or libsamplerate isn't + * available, SDL will use the default, internal resampling algorithm. * - * As of SDL 2.26, SDL_ConvertAudio() respects this hint when libsamplerate is available. + * As of SDL 2.26, SDL_ConvertAudio() respects this hint when libsamplerate is + * available. * - * This hint is currently only checked at audio subsystem initialization. + * This hint is currently only checked at audio subsystem initialization. * - * This variable can be set to the following values: + * This variable can be set to the following values: * - * "0" or "default" - Use SDL's internal resampling (Default when not set - low quality, fast) - * "1" or "fast" - Use fast, slightly higher quality resampling, if available - * "2" or "medium" - Use medium quality resampling, if available - * "3" or "best" - Use high quality resampling, if available + * - "0" or "default": Use SDL's internal resampling (Default when not set - + * low quality, fast) + * - "1" or "fast": Use fast, slightly higher quality resampling, if available + * - "2" or "medium": Use medium quality resampling, if available + * - "3" or "best": Use high quality resampling, if available */ #define SDL_HINT_AUDIO_RESAMPLING_MODE "SDL_AUDIO_RESAMPLING_MODE" /** - * \brief A variable controlling whether SDL updates joystick state when getting input events + * A variable controlling whether SDL updates joystick state when getting + * input events * - * This variable can be set to the following values: + * This variable can be set to the following values: * - * "0" - You'll call SDL_JoystickUpdate() manually - * "1" - SDL will automatically call SDL_JoystickUpdate() (default) + * - "0": You'll call SDL_JoystickUpdate() manually + * - "1": SDL will automatically call SDL_JoystickUpdate() (default) * - * This hint can be toggled on and off at runtime. + * This hint can be toggled on and off at runtime. */ #define SDL_HINT_AUTO_UPDATE_JOYSTICKS "SDL_AUTO_UPDATE_JOYSTICKS" /** - * \brief A variable controlling whether SDL updates sensor state when getting input events + * A variable controlling whether SDL updates sensor state when getting input + * events * - * This variable can be set to the following values: + * This variable can be set to the following values: * - * "0" - You'll call SDL_SensorUpdate() manually - * "1" - SDL will automatically call SDL_SensorUpdate() (default) + * - "0": You'll call SDL_SensorUpdate() manually + * - "1": SDL will automatically call SDL_SensorUpdate() (default) * - * This hint can be toggled on and off at runtime. + * This hint can be toggled on and off at runtime. */ #define SDL_HINT_AUTO_UPDATE_SENSORS "SDL_AUTO_UPDATE_SENSORS" /** - * \brief Prevent SDL from using version 4 of the bitmap header when saving BMPs. + * Prevent SDL from using version 4 of the bitmap header when saving BMPs. * - * The bitmap header version 4 is required for proper alpha channel support and - * SDL will use it when required. Should this not be desired, this hint can - * force the use of the 40 byte header version which is supported everywhere. + * The bitmap header version 4 is required for proper alpha channel support + * and SDL will use it when required. Should this not be desired, this hint + * can force the use of the 40 byte header version which is supported + * everywhere. * * The variable can be set to the following values: - * "0" - Surfaces with a colorkey or an alpha channel are saved to a - * 32-bit BMP file with an alpha mask. SDL will use the bitmap - * header version 4 and set the alpha mask accordingly. - * "1" - Surfaces with a colorkey or an alpha channel are saved to a - * 32-bit BMP file without an alpha mask. The alpha channel data - * will be in the file, but applications are going to ignore it. + * + * - "0": Surfaces with a colorkey or an alpha channel are saved to a 32-bit + * BMP file with an alpha mask. SDL will use the bitmap header version 4 and + * set the alpha mask accordingly. + * - "1": Surfaces with a colorkey or an alpha channel are saved to a 32-bit + * BMP file without an alpha mask. The alpha channel data will be in the + * file, but applications are going to ignore it. * * The default value is "0". */ #define SDL_HINT_BMP_SAVE_LEGACY_FORMAT "SDL_BMP_SAVE_LEGACY_FORMAT" /** - * \brief Override for SDL_GetDisplayUsableBounds() + * Override for SDL_GetDisplayUsableBounds() * - * If set, this hint will override the expected results for - * SDL_GetDisplayUsableBounds() for display index 0. Generally you don't want - * to do this, but this allows an embedded system to request that some of the - * screen be reserved for other uses when paired with a well-behaved - * application. + * If set, this hint will override the expected results for + * SDL_GetDisplayUsableBounds() for display index 0. Generally you don't want + * to do this, but this allows an embedded system to request that some of the + * screen be reserved for other uses when paired with a well-behaved + * application. * - * The contents of this hint must be 4 comma-separated integers, the first - * is the bounds x, then y, width and height, in that order. + * The contents of this hint must be 4 comma-separated integers, the first is + * the bounds x, then y, width and height, in that order. */ #define SDL_HINT_DISPLAY_USABLE_BOUNDS "SDL_DISPLAY_USABLE_BOUNDS" /** - * \brief Disable giving back control to the browser automatically - * when running with asyncify + * Disable giving back control to the browser automatically when running with + * asyncify * - * With -s ASYNCIFY, SDL2 calls emscripten_sleep during operations - * such as refreshing the screen or polling events. + * With -s ASYNCIFY, SDL2 calls emscripten_sleep during operations such as + * refreshing the screen or polling events. * * This hint only applies to the emscripten platform * * The variable can be set to the following values: - * "0" - Disable emscripten_sleep calls (if you give back browser control manually or use asyncify for other purposes) - * "1" - Enable emscripten_sleep calls (the default) + * + * - "0": Disable emscripten_sleep calls (if you give back browser control + * manually or use asyncify for other purposes) + * - "1": Enable emscripten_sleep calls (the default) */ #define SDL_HINT_EMSCRIPTEN_ASYNCIFY "SDL_EMSCRIPTEN_ASYNCIFY" /** - * \brief override the binding element for keyboard inputs for Emscripten builds + * override the binding element for keyboard inputs for Emscripten builds * - * This hint only applies to the emscripten platform + * This hint only applies to the emscripten platform. * - * The variable can be one of - * "#window" - The javascript window object (this is the default) - * "#document" - The javascript document object - * "#screen" - the javascript window.screen object - * "#canvas" - the WebGL canvas element - * any other string without a leading # sign applies to the element on the page with that ID. - */ -#define SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT "SDL_EMSCRIPTEN_KEYBOARD_ELEMENT" - -/** - * \brief A variable that controls whether the on-screen keyboard should be shown when text input is active + * The variable can be one of: * - * The variable can be set to the following values: - * "0" - Do not show the on-screen keyboard - * "1" - Show the on-screen keyboard + * - "#window": the javascript window object (this is the default) + * - "#document": the javascript document object + * - "#screen": the javascript window.screen object + * - "#canvas": the WebGL canvas element * - * The default value is "1". This hint must be set before text input is activated. + * Any other string without a leading # sign applies to the element on the + * page with that ID. */ -#define SDL_HINT_ENABLE_SCREEN_KEYBOARD "SDL_ENABLE_SCREEN_KEYBOARD" +#define SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT "SDL_EMSCRIPTEN_KEYBOARD_ELEMENT" /** - * \brief A variable that controls whether Steam Controllers should be exposed using the SDL joystick and game controller APIs + * A variable that controls whether the on-screen keyboard should be shown + * when text input is active + * + * The variable can be set to the following values: * - * The variable can be set to the following values: - * "0" - Do not scan for Steam Controllers - * "1" - Scan for Steam Controllers (the default) + * - "0": Do not show the on-screen keyboard + * - "1": Show the on-screen keyboard * - * The default value is "1". This hint must be set before initializing the joystick subsystem. + * The default value is "1". This hint must be set before text input is + * activated. */ -#define SDL_HINT_ENABLE_STEAM_CONTROLLERS "SDL_ENABLE_STEAM_CONTROLLERS" +#define SDL_HINT_ENABLE_SCREEN_KEYBOARD "SDL_ENABLE_SCREEN_KEYBOARD" /** - * \brief A variable controlling verbosity of the logging of SDL events pushed onto the internal queue. + * A variable controlling verbosity of the logging of SDL events pushed onto + * the internal queue. * - * This variable can be set to the following values, from least to most verbose: + * This variable can be set to the following values, from least to most + * verbose: * - * "0" - Don't log any events (default) - * "1" - Log most events (other than the really spammy ones). - * "2" - Include mouse and finger motion events. - * "3" - Include SDL_SysWMEvent events. + * - "0": Don't log any events (default) + * - "1": Log most events (other than the really spammy ones). + * - "2": Include mouse and finger motion events. + * - "3": Include SDL_SysWMEvent events. * - * This is generally meant to be used to debug SDL itself, but can be useful - * for application developers that need better visibility into what is going - * on in the event queue. Logged events are sent through SDL_Log(), which - * means by default they appear on stdout on most platforms or maybe - * OutputDebugString() on Windows, and can be funneled by the app with - * SDL_LogSetOutputFunction(), etc. + * This is generally meant to be used to debug SDL itself, but can be useful + * for application developers that need better visibility into what is going + * on in the event queue. Logged events are sent through SDL_Log(), which + * means by default they appear on stdout on most platforms or maybe + * OutputDebugString() on Windows, and can be funneled by the app with + * SDL_LogSetOutputFunction(), etc. * - * This hint can be toggled on and off at runtime, if you only need to log - * events for a small subset of program execution. + * This hint can be toggled on and off at runtime, if you only need to log + * events for a small subset of program execution. */ #define SDL_HINT_EVENT_LOGGING "SDL_EVENT_LOGGING" /** - * \brief A variable controlling whether raising the window should be done more forcefully + * A variable controlling whether raising the window should be done more + * forcefully + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - No forcing (the default) - * "1" - Extra level of forcing + * - "0": No forcing (the default) + * - "1": Extra level of forcing * - * At present, this is only an issue under MS Windows, which makes it nearly impossible to - * programmatically move a window to the foreground, for "security" reasons. See - * http://stackoverflow.com/a/34414846 for a discussion. + * At present, this is only an issue under MS Windows, which makes it nearly + * impossible to programmatically move a window to the foreground, for + * "security" reasons. See http://stackoverflow.com/a/34414846 for a + * discussion. */ #define SDL_HINT_FORCE_RAISEWINDOW "SDL_HINT_FORCE_RAISEWINDOW" /** - * \brief A variable controlling how 3D acceleration is used to accelerate the SDL screen surface. + * A variable controlling how 3D acceleration is used to accelerate the SDL + * screen surface. + * + * SDL can try to accelerate the SDL screen surface by using streaming + * textures with a 3D rendering engine. This variable controls whether and how + * this is done. * - * SDL can try to accelerate the SDL screen surface by using streaming - * textures with a 3D rendering engine. This variable controls whether and - * how this is done. + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Disable 3D acceleration - * "1" - Enable 3D acceleration, using the default renderer. - * "X" - Enable 3D acceleration, using X where X is one of the valid rendering drivers. (e.g. "direct3d", "opengl", etc.) + * - "0": Disable 3D acceleration + * - "1": Enable 3D acceleration, using the default renderer. + * - "X": Enable 3D acceleration, using X where X is one of the valid + * rendering drivers. (e.g. "direct3d", "opengl", etc.) * - * By default SDL tries to make a best guess for each platform whether - * to use acceleration or not. + * By default SDL tries to make a best guess for each platform whether to use + * acceleration or not. */ #define SDL_HINT_FRAMEBUFFER_ACCELERATION "SDL_FRAMEBUFFER_ACCELERATION" /** - * \brief A variable that lets you manually hint extra gamecontroller db entries. + * A variable that lets you manually hint extra gamecontroller db entries. * - * The variable should be newline delimited rows of gamecontroller config data, see SDL_gamecontroller.h + * The variable should be newline delimited rows of gamecontroller config + * data, see SDL_gamecontroller.h * - * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) - * You can update mappings after the system is initialized with SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping() + * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) You + * can update mappings after the system is initialized with + * SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping() */ #define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG" /** - * \brief A variable that lets you provide a file with extra gamecontroller db entries. + * A variable that lets you provide a file with extra gamecontroller db + * entries. * - * The file should contain lines of gamecontroller config data, see SDL_gamecontroller.h + * The file should contain lines of gamecontroller config data, see + * SDL_gamecontroller.h * - * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) - * You can update mappings after the system is initialized with SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping() + * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) You + * can update mappings after the system is initialized with + * SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping() */ #define SDL_HINT_GAMECONTROLLERCONFIG_FILE "SDL_GAMECONTROLLERCONFIG_FILE" /** - * \brief A variable that overrides the automatic controller type detection + * A variable that overrides the automatic controller type detection * - * The variable should be comma separated entries, in the form: VID/PID=type + * The variable should be comma separated entries, in the form: VID/PID=type * - * The VID and PID should be hexadecimal with exactly 4 digits, e.g. 0x00fd + * The VID and PID should be hexadecimal with exactly 4 digits, e.g. 0x00fd * - * The type should be one of: - * Xbox360 - * XboxOne - * PS3 - * PS4 - * PS5 - * SwitchPro + * The type should be one of: Xbox360 XboxOne PS3 PS4 PS5 SwitchPro * - * This hint affects what driver is used, and must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) + * This hint affects what driver is used, and must be set before calling + * SDL_Init(SDL_INIT_GAMECONTROLLER) */ #define SDL_HINT_GAMECONTROLLERTYPE "SDL_GAMECONTROLLERTYPE" /** - * \brief A variable containing a list of devices to skip when scanning for game controllers. + * A variable containing a list of devices to skip when scanning for game + * controllers. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES "SDL_GAMECONTROLLER_IGNORE_DEVICES" /** - * \brief If set, all devices will be skipped when scanning for game controllers except for the ones listed in this variable. + * If set, all devices will be skipped when scanning for game controllers + * except for the ones listed in this variable. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT" /** - * \brief If set, game controller face buttons report their values according to their labels instead of their positional layout. + * If set, game controller face buttons report their values according to their + * labels instead of their positional layout. * - * For example, on Nintendo Switch controllers, normally you'd get: + * For example, on Nintendo Switch controllers, normally you'd get: * + * ``` * (Y) * (X) (B) * (A) + * ``` * - * but if this hint is set, you'll get: + * but if this hint is set, you'll get: * + * ``` * (X) * (Y) (A) * (B) + * ``` * - * The variable can be set to the following values: - * "0" - Report the face buttons by position, as though they were on an Xbox controller. - * "1" - Report the face buttons by label instead of position + * The variable can be set to the following values: + * + * - "0": Report the face buttons by position, as though they were on an Xbox + * controller. + * - "1": Report the face buttons by label instead of position * - * The default value is "1". This hint may be set at any time. + * The default value is "1". This hint may be set at any time. */ #define SDL_HINT_GAMECONTROLLER_USE_BUTTON_LABELS "SDL_GAMECONTROLLER_USE_BUTTON_LABELS" /** - * \brief A variable controlling whether grabbing input grabs the keyboard + * A variable controlling whether grabbing input grabs the keyboard * - * This variable can be set to the following values: - * "0" - Grab will affect only the mouse - * "1" - Grab will affect mouse and keyboard + * This variable can be set to the following values: * - * By default SDL will not grab the keyboard so system shortcuts still work. + * - "0": Grab will affect only the mouse + * - "1": Grab will affect mouse and keyboard + * + * By default SDL will not grab the keyboard so system shortcuts still work. */ #define SDL_HINT_GRAB_KEYBOARD "SDL_GRAB_KEYBOARD" /** - * \brief A variable containing a list of devices to ignore in SDL_hid_enumerate() + * A variable containing a list of devices to ignore in SDL_hid_enumerate() * - * For example, to ignore the Shanwan DS3 controller and any Valve controller, you might - * have the string "0x2563/0x0523,0x28de/0x0000" + * For example, to ignore the Shanwan DS3 controller and any Valve controller, + * you might have the string "0x2563/0x0523,0x28de/0x0000" */ #define SDL_HINT_HIDAPI_IGNORE_DEVICES "SDL_HIDAPI_IGNORE_DEVICES" /** - * \brief A variable controlling whether the idle timer is disabled on iOS. + * A variable controlling whether the idle timer is disabled on iOS. + * + * When an iOS app does not receive touches for some time, the screen is + * dimmed automatically. For games where the accelerometer is the only input + * this is problematic. This functionality can be disabled by setting this + * hint. * - * When an iOS app does not receive touches for some time, the screen is - * dimmed automatically. For games where the accelerometer is the only input - * this is problematic. This functionality can be disabled by setting this - * hint. + * As of SDL 2.0.4, SDL_EnableScreenSaver() and SDL_DisableScreenSaver() + * accomplish the same thing on iOS. They should be preferred over this hint. * - * As of SDL 2.0.4, SDL_EnableScreenSaver() and SDL_DisableScreenSaver() - * accomplish the same thing on iOS. They should be preferred over this hint. + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Enable idle timer - * "1" - Disable idle timer + * - "0": Enable idle timer + * - "1": Disable idle timer */ #define SDL_HINT_IDLE_TIMER_DISABLED "SDL_IOS_IDLE_TIMER_DISABLED" /** - * \brief A variable to control whether certain IMEs should handle text editing internally instead of sending SDL_TEXTEDITING events. + * A variable to control whether certain IMEs should handle text editing + * internally instead of sending SDL_TEXTEDITING events. * * The variable can be set to the following values: - * "0" - SDL_TEXTEDITING events are sent, and it is the application's - * responsibility to render the text from these events and - * differentiate it somehow from committed text. (default) - * "1" - If supported by the IME then SDL_TEXTEDITING events are not sent, - * and text that is being composed will be rendered in its own UI. + * + * - "0": SDL_TEXTEDITING events are sent, and it is the application's + * responsibility to render the text from these events and differentiate it + * somehow from committed text. (default) + * - "1": If supported by the IME then SDL_TEXTEDITING events are not sent, + * and text that is being composed will be rendered in its own UI. */ #define SDL_HINT_IME_INTERNAL_EDITING "SDL_IME_INTERNAL_EDITING" /** - * \brief A variable to control whether certain IMEs should show native UI components (such as the Candidate List) instead of suppressing them. + * A variable to control whether certain IMEs should show native UI components + * (such as the Candidate List) instead of suppressing them. * * The variable can be set to the following values: - * "0" - Native UI components are not display. (default) - * "1" - Native UI components are displayed. + * + * - "0": Native UI components are not display. (default) + * - "1": Native UI components are displayed. */ #define SDL_HINT_IME_SHOW_UI "SDL_IME_SHOW_UI" /** - * \brief A variable to control if extended IME text support is enabled. - * If enabled then SDL_TextEditingExtEvent will be issued if the text would be truncated otherwise. - * Additionally SDL_TextInputEvent will be dispatched multiple times so that it is not truncated. + * A variable to control if extended IME text support is enabled. + * + * If enabled then SDL_TextEditingExtEvent will be issued if the text would be + * truncated otherwise. Additionally SDL_TextInputEvent will be dispatched + * multiple times so that it is not truncated. * * The variable can be set to the following values: - * "0" - Legacy behavior. Text can be truncated, no heap allocations. (default) - * "1" - Modern behavior. + * + * - "0": Legacy behavior. Text can be truncated, no heap allocations. + * (default) + * - "1": Modern behavior. */ #define SDL_HINT_IME_SUPPORT_EXTENDED_TEXT "SDL_IME_SUPPORT_EXTENDED_TEXT" /** - * \brief A variable controlling whether the home indicator bar on iPhone X - * should be hidden. + * A variable controlling whether the home indicator bar on iPhone X should be + * hidden. * - * This variable can be set to the following values: - * "0" - The indicator bar is not hidden (default for windowed applications) - * "1" - The indicator bar is hidden and is shown when the screen is touched (useful for movie playback applications) - * "2" - The indicator bar is dim and the first swipe makes it visible and the second swipe performs the "home" action (default for fullscreen applications) + * This variable can be set to the following values: + * + * - "0": The indicator bar is not hidden (default for windowed applications) + * - "1": The indicator bar is hidden and is shown when the screen is touched + * (useful for movie playback applications) + * - "2": The indicator bar is dim and the first swipe makes it visible and + * the second swipe performs the "home" action (default for fullscreen + * applications) */ #define SDL_HINT_IOS_HIDE_HOME_INDICATOR "SDL_IOS_HIDE_HOME_INDICATOR" /** - * \brief A variable that lets you enable joystick (and gamecontroller) events even when your app is in the background. + * A variable that lets you enable joystick (and gamecontroller) events even + * when your app is in the background. + * + * The variable can be set to the following values: * - * The variable can be set to the following values: - * "0" - Disable joystick & gamecontroller input events when the - * application is in the background. - * "1" - Enable joystick & gamecontroller input events when the - * application is in the background. + * - "0": Disable joystick & gamecontroller input events when the application + * is in the background. + * - "1": Enable joystick & gamecontroller input events when the application + * is in the background. * - * The default value is "0". This hint may be set at any time. + * The default value is "0". This hint may be set at any time. */ #define SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS "SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS" /** - * A variable containing a list of arcade stick style controllers. + * A variable containing a list of arcade stick style controllers. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES "SDL_JOYSTICK_ARCADESTICK_DEVICES" /** - * A variable containing a list of devices that are not arcade stick style controllers. This will override SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES and the built in device list. + * A variable containing a list of devices that are not arcade stick style + * controllers. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * This will override SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES and the built in + * device list. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED" /** - * A variable containing a list of devices that should not be considerd joysticks. + * A variable containing a list of devices that should not be considerd + * joysticks. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES "SDL_JOYSTICK_BLACKLIST_DEVICES" /** - * A variable containing a list of devices that should be considered joysticks. This will override SDL_HINT_JOYSTICK_BLACKLIST_DEVICES and the built in device list. + * A variable containing a list of devices that should be considered + * joysticks. + * + * This will override SDL_HINT_JOYSTICK_BLACKLIST_DEVICES and the built in + * device list. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED "SDL_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED" /** - * A variable containing a list of flightstick style controllers. + * A variable containing a list of flightstick style controllers. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES "SDL_JOYSTICK_FLIGHTSTICK_DEVICES" /** - * A variable containing a list of devices that are not flightstick style controllers. This will override SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES and the built in device list. + * A variable containing a list of devices that are not flightstick style + * controllers. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * This will override SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES and the built in + * device list. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED" /** - * A variable containing a list of devices known to have a GameCube form factor. + * A variable containing a list of devices known to have a GameCube form + * factor. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES "SDL_JOYSTICK_GAMECUBE_DEVICES" /** - * A variable containing a list of devices known not to have a GameCube form factor. This will override SDL_HINT_JOYSTICK_GAMECUBE_DEVICES and the built in device list. + * A variable containing a list of devices known not to have a GameCube form + * factor. + * + * This will override SDL_HINT_JOYSTICK_GAMECUBE_DEVICES and the built in + * device list. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED "SDL_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED" /** - * \brief A variable controlling whether the HIDAPI joystick drivers should be used. + * A variable controlling whether the HIDAPI joystick drivers should be used. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - HIDAPI drivers are not used - * "1" - HIDAPI drivers are used (the default) + * - "0": HIDAPI drivers are not used + * - "1": HIDAPI drivers are used (the default) * - * This variable is the default for all drivers, but can be overridden by the hints for specific drivers below. + * This variable is the default for all drivers, but can be overridden by the + * hints for specific drivers below. */ #define SDL_HINT_JOYSTICK_HIDAPI "SDL_JOYSTICK_HIDAPI" /** - * \brief A variable controlling whether the HIDAPI driver for Nintendo GameCube controllers should be used. + * A variable controlling whether the HIDAPI driver for Nintendo GameCube + * controllers should be used. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI */ #define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE "SDL_JOYSTICK_HIDAPI_GAMECUBE" /** - * \brief A variable controlling whether "low_frequency_rumble" and "high_frequency_rumble" is used to implement - * the GameCube controller's 3 rumble modes, Stop(0), Rumble(1), and StopHard(2) - * this is useful for applications that need full compatibility for things like ADSR envelopes. - * Stop is implemented by setting "low_frequency_rumble" to "0" and "high_frequency_rumble" ">0" - * Rumble is both at any arbitrary value, - * StopHard is implemented by setting both "low_frequency_rumble" and "high_frequency_rumble" to "0" + * A variable controlling whether "low_frequency_rumble" and + * "high_frequency_rumble" is used to implement the GameCube controller's 3 + * rumble modes, Stop(0), Rumble(1), and StopHard(2) this is useful for + * applications that need full compatibility for things like ADSR envelopes. * - * This variable can be set to the following values: - * "0" - Normal rumble behavior is behavior is used (default) - * "1" - Proper GameCube controller rumble behavior is used + * Stop is implemented by setting "low_frequency_rumble" to "0" and + * "high_frequency_rumble" ">0" Rumble is both at any arbitrary value, + * StopHard is implemented by setting both "low_frequency_rumble" and + * "high_frequency_rumble" to "0" * + * This variable can be set to the following values: + * + * - "0": Normal rumble behavior is behavior is used (default) + * - "1": Proper GameCube controller rumble behavior is used */ #define SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE "SDL_JOYSTICK_GAMECUBE_RUMBLE_BRAKE" /** - * \brief A variable controlling whether the HIDAPI driver for Nintendo Switch Joy-Cons should be used. - * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used - * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI - */ + * A variable controlling whether the HIDAPI driver for Nintendo Switch + * Joy-Cons should be used. + * + * This variable can be set to the following values: + * + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + */ #define SDL_HINT_JOYSTICK_HIDAPI_JOY_CONS "SDL_JOYSTICK_HIDAPI_JOY_CONS" /** - * \brief A variable controlling whether Nintendo Switch Joy-Con controllers will be combined into a single Pro-like controller when using the HIDAPI driver - * - * This variable can be set to the following values: - * "0" - Left and right Joy-Con controllers will not be combined and each will be a mini-gamepad - * "1" - Left and right Joy-Con controllers will be combined into a single controller (the default) - */ + * A variable controlling whether Nintendo Switch Joy-Con controllers will be + * combined into a single Pro-like controller when using the HIDAPI driver + * + * This variable can be set to the following values: + * + * - "0": Left and right Joy-Con controllers will not be combined and each + * will be a mini-gamepad + * - "1": Left and right Joy-Con controllers will be combined into a single + * controller (the default) + */ #define SDL_HINT_JOYSTICK_HIDAPI_COMBINE_JOY_CONS "SDL_JOYSTICK_HIDAPI_COMBINE_JOY_CONS" /** - * \brief A variable controlling whether Nintendo Switch Joy-Con controllers will be in vertical mode when using the HIDAPI driver - * - * This variable can be set to the following values: - * "0" - Left and right Joy-Con controllers will not be in vertical mode (the default) - * "1" - Left and right Joy-Con controllers will be in vertical mode - * - * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) - */ + * A variable controlling whether Nintendo Switch Joy-Con controllers will be + * in vertical mode when using the HIDAPI driver + * + * This variable can be set to the following values: + * + * - "0": Left and right Joy-Con controllers will not be in vertical mode (the + * default) + * - "1": Left and right Joy-Con controllers will be in vertical mode + * + * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) + */ #define SDL_HINT_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS "SDL_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS" /** - * \brief A variable controlling whether the HIDAPI driver for Amazon Luna controllers connected via Bluetooth should be used. - * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used - * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI - */ + * A variable controlling whether the HIDAPI driver for Amazon Luna + * controllers connected via Bluetooth should be used. + * + * This variable can be set to the following values: + * + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + */ #define SDL_HINT_JOYSTICK_HIDAPI_LUNA "SDL_JOYSTICK_HIDAPI_LUNA" /** - * \brief A variable controlling whether the HIDAPI driver for Nintendo Online classic controllers should be used. - * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used - * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI - */ + * A variable controlling whether the HIDAPI driver for Nintendo Online + * classic controllers should be used. + * + * This variable can be set to the following values: + * + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + */ #define SDL_HINT_JOYSTICK_HIDAPI_NINTENDO_CLASSIC "SDL_JOYSTICK_HIDAPI_NINTENDO_CLASSIC" /** - * \brief A variable controlling whether the HIDAPI driver for NVIDIA SHIELD controllers should be used. - * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used - * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI - */ + * A variable controlling whether the HIDAPI driver for NVIDIA SHIELD + * controllers should be used. + * + * This variable can be set to the following values: + * + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + */ #define SDL_HINT_JOYSTICK_HIDAPI_SHIELD "SDL_JOYSTICK_HIDAPI_SHIELD" /** - * \brief A variable controlling whether the HIDAPI driver for PS3 controllers should be used. + * A variable controlling whether the HIDAPI driver for PS3 controllers should + * be used. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI on macOS, and "0" on other platforms. + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI on macOS, and "0" on + * other platforms. * - * It is not possible to use this driver on Windows, due to limitations in the default drivers - * installed. See https://github.com/ViGEm/DsHidMini for an alternative driver on Windows. + * It is not possible to use this driver on Windows, due to limitations in the + * default drivers installed. See https://github.com/ViGEm/DsHidMini for an + * alternative driver on Windows. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS3 "SDL_JOYSTICK_HIDAPI_PS3" /** - * \brief A variable controlling whether the HIDAPI driver for PS4 controllers should be used. + * A variable controlling whether the HIDAPI driver for PS4 controllers should + * be used. * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used + * This variable can be set to the following values: + * + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI */ #define SDL_HINT_JOYSTICK_HIDAPI_PS4 "SDL_JOYSTICK_HIDAPI_PS4" /** - * \brief A variable controlling whether extended input reports should be used for PS4 controllers when using the HIDAPI driver. + * A variable controlling whether extended input reports should be used for + * PS4 controllers when using the HIDAPI driver. * - * This variable can be set to the following values: - * "0" - extended reports are not enabled (the default) - * "1" - extended reports + * This variable can be set to the following values: * - * Extended input reports allow rumble on Bluetooth PS4 controllers, but - * break DirectInput handling for applications that don't use SDL. + * - "0": extended reports are not enabled (the default) + * - "1": extended reports * - * Once extended reports are enabled, they can not be disabled without - * power cycling the controller. + * Extended input reports allow rumble on Bluetooth PS4 controllers, but break + * DirectInput handling for applications that don't use SDL. * - * For compatibility with applications written for versions of SDL prior - * to the introduction of PS5 controller support, this value will also - * control the state of extended reports on PS5 controllers when the - * SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE hint is not explicitly set. + * Once extended reports are enabled, they can not be disabled without power + * cycling the controller. + * + * For compatibility with applications written for versions of SDL prior to + * the introduction of PS5 controller support, this value will also control + * the state of extended reports on PS5 controllers when the + * SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE hint is not explicitly set. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE "SDL_JOYSTICK_HIDAPI_PS4_RUMBLE" /** - * \brief A variable controlling whether the HIDAPI driver for PS5 controllers should be used. + * A variable controlling whether the HIDAPI driver for PS5 controllers should + * be used. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI */ #define SDL_HINT_JOYSTICK_HIDAPI_PS5 "SDL_JOYSTICK_HIDAPI_PS5" /** - * \brief A variable controlling whether the player LEDs should be lit to indicate which player is associated with a PS5 controller. + * A variable controlling whether the player LEDs should be lit to indicate + * which player is associated with a PS5 controller. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - player LEDs are not enabled - * "1" - player LEDs are enabled (the default) + * - "0": player LEDs are not enabled + * - "1": player LEDs are enabled (the default) */ #define SDL_HINT_JOYSTICK_HIDAPI_PS5_PLAYER_LED "SDL_JOYSTICK_HIDAPI_PS5_PLAYER_LED" /** - * \brief A variable controlling whether extended input reports should be used for PS5 controllers when using the HIDAPI driver. + * A variable controlling whether extended input reports should be used for + * PS5 controllers when using the HIDAPI driver. * - * This variable can be set to the following values: - * "0" - extended reports are not enabled (the default) - * "1" - extended reports + * This variable can be set to the following values: + * + * - "0": extended reports are not enabled (the default) + * - "1": extended reports * - * Extended input reports allow rumble on Bluetooth PS5 controllers, but - * break DirectInput handling for applications that don't use SDL. + * Extended input reports allow rumble on Bluetooth PS5 controllers, but break + * DirectInput handling for applications that don't use SDL. * - * Once extended reports are enabled, they can not be disabled without - * power cycling the controller. + * Once extended reports are enabled, they can not be disabled without power + * cycling the controller. * - * For compatibility with applications written for versions of SDL prior - * to the introduction of PS5 controller support, this value defaults to - * the value of SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE. + * For compatibility with applications written for versions of SDL prior to + * the introduction of PS5 controller support, this value defaults to the + * value of SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE "SDL_JOYSTICK_HIDAPI_PS5_RUMBLE" /** - * \brief A variable controlling whether the HIDAPI driver for Google Stadia controllers should be used. + * A variable controlling whether the HIDAPI driver for Google Stadia + * controllers should be used. * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used + * This variable can be set to the following values: * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI */ #define SDL_HINT_JOYSTICK_HIDAPI_STADIA "SDL_JOYSTICK_HIDAPI_STADIA" /** - * \brief A variable controlling whether the HIDAPI driver for Bluetooth Steam Controllers should be used. + * A variable controlling whether the HIDAPI driver for Bluetooth Steam + * Controllers should be used. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used for Steam Controllers, which requires Bluetooth access - * and may prompt the user for permission on iOS and Android. + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used for Steam Controllers, which requires + * Bluetooth access and may prompt the user for permission on iOS and + * Android. * - * The default is "0" + * The default is "0" */ #define SDL_HINT_JOYSTICK_HIDAPI_STEAM "SDL_JOYSTICK_HIDAPI_STEAM" /** - * \brief A variable controlling whether the HIDAPI driver for the Steam Deck builtin controller should be used. + * A variable controlling whether the HIDAPI driver for the Steam Deck builtin + * controller should be used. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI */ #define SDL_HINT_JOYSTICK_HIDAPI_STEAMDECK "SDL_JOYSTICK_HIDAPI_STEAMDECK" /** - * \brief A variable controlling whether the HIDAPI driver for Nintendo Switch controllers should be used. + * A variable controlling whether the HIDAPI driver for Nintendo Switch + * controllers should be used. * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used + * This variable can be set to the following values: + * + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI */ #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH "SDL_JOYSTICK_HIDAPI_SWITCH" /** - * \brief A variable controlling whether the Home button LED should be turned on when a Nintendo Switch Pro controller is opened + * A variable controlling whether the Home button LED should be turned on when + * a Nintendo Switch Pro controller is opened + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - home button LED is turned off - * "1" - home button LED is turned on + * - "0": home button LED is turned off + * - "1": home button LED is turned on * - * By default the Home button LED state is not changed. This hint can also be set to a floating point value between 0.0 and 1.0 which controls the brightness of the Home button LED. + * By default the Home button LED state is not changed. This hint can also be + * set to a floating point value between 0.0 and 1.0 which controls the + * brightness of the Home button LED. */ #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_HOME_LED "SDL_JOYSTICK_HIDAPI_SWITCH_HOME_LED" /** - * \brief A variable controlling whether the Home button LED should be turned on when a Nintendo Switch Joy-Con controller is opened + * A variable controlling whether the Home button LED should be turned on when + * a Nintendo Switch Joy-Con controller is opened + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - home button LED is turned off - * "1" - home button LED is turned on + * - "0": home button LED is turned off + * - "1": home button LED is turned on * - * By default the Home button LED state is not changed. This hint can also be set to a floating point value between 0.0 and 1.0 which controls the brightness of the Home button LED. + * By default the Home button LED state is not changed. This hint can also be + * set to a floating point value between 0.0 and 1.0 which controls the + * brightness of the Home button LED. */ #define SDL_HINT_JOYSTICK_HIDAPI_JOYCON_HOME_LED "SDL_JOYSTICK_HIDAPI_JOYCON_HOME_LED" /** - * \brief A variable controlling whether the player LEDs should be lit to indicate which player is associated with a Nintendo Switch controller. + * A variable controlling whether the player LEDs should be lit to indicate + * which player is associated with a Nintendo Switch controller. * - * This variable can be set to the following values: - * "0" - player LEDs are not enabled - * "1" - player LEDs are enabled (the default) + * This variable can be set to the following values: + * + * - "0": player LEDs are not enabled + * - "1": player LEDs are enabled (the default) */ #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED "SDL_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED" /** - * \brief A variable controlling whether the HIDAPI driver for Nintendo Wii and Wii U controllers should be used. + * A variable controlling whether the HIDAPI driver for Nintendo Wii and Wii U + * controllers should be used. * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used + * This variable can be set to the following values: * - * This driver doesn't work with the dolphinbar, so the default is SDL_FALSE for now. + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used + * + * This driver doesn't work with the dolphinbar, so the default is SDL_FALSE + * for now. */ #define SDL_HINT_JOYSTICK_HIDAPI_WII "SDL_JOYSTICK_HIDAPI_WII" /** - * \brief A variable controlling whether the player LEDs should be lit to indicate which player is associated with a Wii controller. + * A variable controlling whether the player LEDs should be lit to indicate + * which player is associated with a Wii controller. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - player LEDs are not enabled - * "1" - player LEDs are enabled (the default) + * - "0": player LEDs are not enabled + * - "1": player LEDs are enabled (the default) */ #define SDL_HINT_JOYSTICK_HIDAPI_WII_PLAYER_LED "SDL_JOYSTICK_HIDAPI_WII_PLAYER_LED" /** - * \brief A variable controlling whether the HIDAPI driver for XBox controllers should be used. + * A variable controlling whether the HIDAPI driver for XBox controllers + * should be used. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used * - * The default is "0" on Windows, otherwise the value of SDL_HINT_JOYSTICK_HIDAPI + * The default is "0" on Windows, otherwise the value of + * SDL_HINT_JOYSTICK_HIDAPI */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX "SDL_JOYSTICK_HIDAPI_XBOX" /** - * \brief A variable controlling whether the HIDAPI driver for XBox 360 controllers should be used. + * A variable controlling whether the HIDAPI driver for XBox 360 controllers + * should be used. * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used + * This variable can be set to the following values: + * + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 "SDL_JOYSTICK_HIDAPI_XBOX_360" /** - * \brief A variable controlling whether the player LEDs should be lit to indicate which player is associated with an Xbox 360 controller. + * A variable controlling whether the player LEDs should be lit to indicate + * which player is associated with an Xbox 360 controller. * - * This variable can be set to the following values: - * "0" - player LEDs are not enabled - * "1" - player LEDs are enabled (the default) + * This variable can be set to the following values: + * + * - "0": player LEDs are not enabled + * - "1": player LEDs are enabled (the default) */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED "SDL_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED" /** - * \brief A variable controlling whether the HIDAPI driver for XBox 360 wireless controllers should be used. + * A variable controlling whether the HIDAPI driver for XBox 360 wireless + * controllers should be used. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_WIRELESS "SDL_JOYSTICK_HIDAPI_XBOX_360_WIRELESS" /** - * \brief A variable controlling whether the HIDAPI driver for XBox One controllers should be used. + * A variable controlling whether the HIDAPI driver for XBox One controllers + * should be used. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE "SDL_JOYSTICK_HIDAPI_XBOX_ONE" /** - * \brief A variable controlling whether the Home button LED should be turned on when an Xbox One controller is opened + * A variable controlling whether the Home button LED should be turned on when + * an Xbox One controller is opened * - * This variable can be set to the following values: - * "0" - home button LED is turned off - * "1" - home button LED is turned on + * This variable can be set to the following values: + * + * - "0": home button LED is turned off + * - "1": home button LED is turned on * - * By default the Home button LED state is not changed. This hint can also be set to a floating point value between 0.0 and 1.0 which controls the brightness of the Home button LED. The default brightness is 0.4. + * By default the Home button LED state is not changed. This hint can also be + * set to a floating point value between 0.0 and 1.0 which controls the + * brightness of the Home button LED. The default brightness is 0.4. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED "SDL_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED" /** - * A variable controlling whether IOKit should be used for controller handling. - * - * This variable can be set to the following values: - * "0" - IOKit is not used - * "1" - IOKit is used (the default) - */ + * A variable controlling whether IOKit should be used for controller + * handling. + * + * This variable can be set to the following values: + * + * - "0": IOKit is not used + * - "1": IOKit is used (the default) + */ #define SDL_HINT_JOYSTICK_IOKIT "SDL_JOYSTICK_IOKIT" /** - * A variable controlling whether GCController should be used for controller handling. - * - * This variable can be set to the following values: - * "0" - GCController is not used - * "1" - GCController is used (the default) - */ + * A variable controlling whether GCController should be used for controller + * handling. + * + * This variable can be set to the following values: + * + * - "0": GCController is not used + * - "1": GCController is used (the default) + */ #define SDL_HINT_JOYSTICK_MFI "SDL_JOYSTICK_MFI" /** - * \brief A variable controlling whether the RAWINPUT joystick drivers should be used for better handling XInput-capable devices. - * - * This variable can be set to the following values: - * "0" - RAWINPUT drivers are not used - * "1" - RAWINPUT drivers are used (the default) - */ + * A variable controlling whether the RAWINPUT joystick drivers should be used + * for better handling XInput-capable devices. + * + * This variable can be set to the following values: + * + * - "0": RAWINPUT drivers are not used + * - "1": RAWINPUT drivers are used (the default) + */ #define SDL_HINT_JOYSTICK_RAWINPUT "SDL_JOYSTICK_RAWINPUT" /** - * \brief A variable controlling whether the RAWINPUT driver should pull correlated data from XInput. - * - * This variable can be set to the following values: - * "0" - RAWINPUT driver will only use data from raw input APIs - * "1" - RAWINPUT driver will also pull data from XInput, providing - * better trigger axes, guide button presses, and rumble support - * for Xbox controllers - * - * The default is "1". This hint applies to any joysticks opened after setting the hint. - */ + * A variable controlling whether the RAWINPUT driver should pull correlated + * data from XInput. + * + * This variable can be set to the following values: + * + * - "0": RAWINPUT driver will only use data from raw input APIs + * - "1": RAWINPUT driver will also pull data from XInput, providing better + * trigger axes, guide button presses, and rumble support for Xbox + * controllers + * + * The default is "1". This hint applies to any joysticks opened after setting + * the hint. + */ #define SDL_HINT_JOYSTICK_RAWINPUT_CORRELATE_XINPUT "SDL_JOYSTICK_RAWINPUT_CORRELATE_XINPUT" /** - * \brief A variable controlling whether the ROG Chakram mice should show up as joysticks - * - * This variable can be set to the following values: - * "0" - ROG Chakram mice do not show up as joysticks (the default) - * "1" - ROG Chakram mice show up as joysticks - */ + * A variable controlling whether the ROG Chakram mice should show up as + * joysticks + * + * This variable can be set to the following values: + * + * - "0": ROG Chakram mice do not show up as joysticks (the default) + * - "1": ROG Chakram mice show up as joysticks + */ #define SDL_HINT_JOYSTICK_ROG_CHAKRAM "SDL_JOYSTICK_ROG_CHAKRAM" /** - * \brief A variable controlling whether a separate thread should be used - * for handling joystick detection and raw input messages on Windows - * - * This variable can be set to the following values: - * "0" - A separate thread is not used (the default) - * "1" - A separate thread is used for handling raw input messages - * - */ + * A variable controlling whether a separate thread should be used for + * handling joystick detection and raw input messages on Windows + * + * This variable can be set to the following values: + * + * - "0": A separate thread is not used (the default) + * - "1": A separate thread is used for handling raw input messages + */ #define SDL_HINT_JOYSTICK_THREAD "SDL_JOYSTICK_THREAD" /** - * A variable containing a list of throttle style controllers. + * A variable containing a list of throttle style controllers. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_THROTTLE_DEVICES "SDL_JOYSTICK_THROTTLE_DEVICES" /** - * A variable containing a list of devices that are not throttle style controllers. This will override SDL_HINT_JOYSTICK_THROTTLE_DEVICES and the built in device list. + * A variable containing a list of devices that are not throttle style + * controllers. + * + * This will override SDL_HINT_JOYSTICK_THROTTLE_DEVICES and the built in + * device list. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_THROTTLE_DEVICES_EXCLUDED "SDL_JOYSTICK_THROTTLE_DEVICES_EXCLUDED" /** - * \brief A variable controlling whether Windows.Gaming.Input should be used for controller handling. - * - * This variable can be set to the following values: - * "0" - WGI is not used - * "1" - WGI is used (the default) - */ + * A variable controlling whether Windows.Gaming.Input should be used for + * controller handling. + * + * This variable can be set to the following values: + * + * - "0": WGI is not used + * - "1": WGI is used (the default) + */ #define SDL_HINT_JOYSTICK_WGI "SDL_JOYSTICK_WGI" /** - * A variable containing a list of wheel style controllers. + * A variable containing a list of wheel style controllers. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_WHEEL_DEVICES "SDL_JOYSTICK_WHEEL_DEVICES" /** - * A variable containing a list of devices that are not wheel style controllers. This will override SDL_HINT_JOYSTICK_WHEEL_DEVICES and the built in device list. + * A variable containing a list of devices that are not wheel style + * controllers. + * + * This will override SDL_HINT_JOYSTICK_WHEEL_DEVICES and the built in device + * list. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_WHEEL_DEVICES_EXCLUDED "SDL_JOYSTICK_WHEEL_DEVICES_EXCLUDED" /** - * A variable containing a list of devices known to have all axes centered at zero. + * A variable containing a list of devices known to have all axes centered at + * zero. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_ZERO_CENTERED_DEVICES "SDL_JOYSTICK_ZERO_CENTERED_DEVICES" /** - * \brief Determines whether SDL enforces that DRM master is required in order - * to initialize the KMSDRM video backend. + * Determines whether SDL enforces that DRM master is required in order to + * initialize the KMSDRM video backend. * - * The DRM subsystem has a concept of a "DRM master" which is a DRM client that - * has the ability to set planes, set cursor, etc. When SDL is DRM master, it - * can draw to the screen using the SDL rendering APIs. Without DRM master, SDL - * is still able to process input and query attributes of attached displays, - * but it cannot change display state or draw to the screen directly. + * The DRM subsystem has a concept of a "DRM master" which is a DRM client + * that has the ability to set planes, set cursor, etc. When SDL is DRM + * master, it can draw to the screen using the SDL rendering APIs. Without DRM + * master, SDL is still able to process input and query attributes of attached + * displays, but it cannot change display state or draw to the screen + * directly. * - * In some cases, it can be useful to have the KMSDRM backend even if it cannot - * be used for rendering. An app may want to use SDL for input processing while - * using another rendering API (such as an MMAL overlay on Raspberry Pi) or - * using its own code to render to DRM overlays that SDL doesn't support. + * In some cases, it can be useful to have the KMSDRM backend even if it + * cannot be used for rendering. An app may want to use SDL for input + * processing while using another rendering API (such as an MMAL overlay on + * Raspberry Pi) or using its own code to render to DRM overlays that SDL + * doesn't support. * * This hint must be set before initializing the video subsystem. * * This variable can be set to the following values: - * "0" - SDL will allow usage of the KMSDRM backend without DRM master - * "1" - SDL Will require DRM master to use the KMSDRM backend (default) + * + * - "0": SDL will allow usage of the KMSDRM backend without DRM master + * - "1": SDL Will require DRM master to use the KMSDRM backend (default) */ #define SDL_HINT_KMSDRM_REQUIRE_DRM_MASTER "SDL_KMSDRM_REQUIRE_DRM_MASTER" /** - * \brief A comma separated list of devices to open as joysticks - * - * This variable is currently only used by the Linux joystick driver. - */ + * A comma separated list of devices to open as joysticks + * + * This variable is currently only used by the Linux joystick driver. + */ #define SDL_HINT_JOYSTICK_DEVICE "SDL_JOYSTICK_DEVICE" + /** - * \brief A variable controlling whether joysticks on Linux will always treat 'hat' axis inputs (ABS_HAT0X - ABS_HAT3Y) as 8-way digital hats without checking whether they may be analog. - * - * This variable can be set to the following values: - * "0" - Only map hat axis inputs to digital hat outputs if the input axes appear to actually be digital (the default) - * "1" - Always handle the input axes numbered ABS_HAT0X to ABS_HAT3Y as digital hats - */ + * A variable containing a list of devices and their desired number of haptic + * (force feedback) enabled axis. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form plus the number of desired axes, e.g. + * + * `0xAAAA/0xBBBB/1,0xCCCC/0xDDDD/3` + * + * This hint supports a "wildcard" device that will set the number of haptic + * axes on all initialized haptic devices which were not defined explicitly in + * this hint. + * + * `0xFFFF/0xFFFF/1` + * + * This hint should be set before a controller is opened. The number of haptic + * axes won't exceed the number of real axes found on the device. + */ +#define SDL_HINT_JOYSTICK_HAPTIC_AXES "SDL_JOYSTICK_HAPTIC_AXES" + +/** + * A variable controlling whether joysticks on Linux will always treat 'hat' + * axis inputs (ABS_HAT0X - ABS_HAT3Y) as 8-way digital hats without checking + * whether they may be analog. + * + * This variable can be set to the following values: + * + * - "0": Only map hat axis inputs to digital hat outputs if the input axes + * appear to actually be digital (the default) + * - "1": Always handle the input axes numbered ABS_HAT0X to ABS_HAT3Y as + * digital hats + */ #define SDL_HINT_LINUX_DIGITAL_HATS "SDL_LINUX_DIGITAL_HATS" /** - * \brief A variable controlling whether digital hats on Linux will apply deadzones to their underlying input axes or use unfiltered values. - * - * This variable can be set to the following values: - * "0" - Return digital hat values based on unfiltered input axis values - * "1" - Return digital hat values with deadzones on the input axes taken into account (the default) - */ + * A variable controlling whether digital hats on Linux will apply deadzones + * to their underlying input axes or use unfiltered values. + * + * This variable can be set to the following values: + * + * - "0": Return digital hat values based on unfiltered input axis values + * - "1": Return digital hat values with deadzones on the input axes taken + * into account (the default) + */ #define SDL_HINT_LINUX_HAT_DEADZONES "SDL_LINUX_HAT_DEADZONES" /** - * \brief A variable controlling whether to use the classic /dev/input/js* joystick interface or the newer /dev/input/event* joystick interface on Linux - * - * This variable can be set to the following values: - * "0" - Use /dev/input/event* - * "1" - Use /dev/input/js* - * - * By default the /dev/input/event* interfaces are used - */ + * A variable controlling whether to use the classic /dev/input/js* joystick + * interface or the newer /dev/input/event* joystick interface on Linux + * + * This variable can be set to the following values: + * + * - "0": Use /dev/input/event* + * - "1": Use /dev/input/js* + * + * By default the /dev/input/event* interfaces are used + */ #define SDL_HINT_LINUX_JOYSTICK_CLASSIC "SDL_LINUX_JOYSTICK_CLASSIC" /** - * \brief A variable controlling whether joysticks on Linux adhere to their HID-defined deadzones or return unfiltered values. - * - * This variable can be set to the following values: - * "0" - Return unfiltered joystick axis values (the default) - * "1" - Return axis values with deadzones taken into account - */ + * A variable controlling whether joysticks on Linux adhere to their + * HID-defined deadzones or return unfiltered values. + * + * This variable can be set to the following values: + * + * - "0": Return unfiltered joystick axis values (the default) + * - "1": Return axis values with deadzones taken into account + */ #define SDL_HINT_LINUX_JOYSTICK_DEADZONES "SDL_LINUX_JOYSTICK_DEADZONES" /** - * \brief A variable controlling the default SDL log levels. + * A variable controlling the default SDL log levels. * - * This variable is a comma separated set of category=level tokens that define the default logging levels for SDL applications. + * This variable is a comma separated set of category=level tokens that define + * the default logging levels for SDL applications. * - * The category can be a numeric category, one of "app", "error", "assert", "system", "audio", "video", "render", "input", "test", or `*` for any unspecified category. + * The category can be a numeric category, one of "app", "error", "assert", + * "system", "audio", "video", "render", "input", "test", or `*` for any + * unspecified category. * - * The level can be a numeric level, one of "verbose", "debug", "info", "warn", "error", "critical", or "quiet" to disable that category. + * The level can be a numeric level, one of "verbose", "debug", "info", + * "warn", "error", "critical", or "quiet" to disable that category. * - * You can omit the category if you want to set the logging level for all categories. + * You can omit the category if you want to set the logging level for all + * categories. * - * If this hint isn't set, the default log levels are equivalent to: - * "app=info,assert=warn,test=verbose,*=error" + * If this hint isn't set, the default log levels are equivalent to: + * "app=info,assert=warn,test=verbose,*=error" */ #define SDL_HINT_LOGGING "SDL_LOGGING" /** -* \brief When set don't force the SDL app to become a foreground process -* -* This hint only applies to Mac OS X. -* -*/ + * When set don't force the SDL app to become a foreground process + * + * This hint only applies to Mac OS X. + */ #define SDL_HINT_MAC_BACKGROUND_APP "SDL_MAC_BACKGROUND_APP" /** - * \brief A variable that determines whether ctrl+click should generate a right-click event on Mac + * A variable that determines whether ctrl+click should generate a right-click + * event on Mac * - * If present, holding ctrl while left clicking will generate a right click - * event when on Mac. + * If present, holding ctrl while left clicking will generate a right click + * event when on Mac. */ #define SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK "SDL_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK" /** - * \brief A variable controlling whether dispatching OpenGL context updates should block the dispatching thread until the main thread finishes processing + * A variable controlling whether dispatching OpenGL context updates should + * block the dispatching thread until the main thread finishes processing * - * This variable can be set to the following values: - * "0" - Dispatching OpenGL context updates will block the dispatching thread until the main thread finishes processing (default). - * "1" - Dispatching OpenGL context updates will allow the dispatching thread to continue execution. + * This variable can be set to the following values: * - * Generally you want the default, but if you have OpenGL code in a background thread on a Mac, and the main thread - * hangs because it's waiting for that background thread, but that background thread is also hanging because it's - * waiting for the main thread to do an update, this might fix your issue. + * - "0": Dispatching OpenGL context updates will block the dispatching thread + * until the main thread finishes processing (default). + * - "1": Dispatching OpenGL context updates will allow the dispatching thread + * to continue execution. * - * This hint only applies to macOS. + * Generally you want the default, but if you have OpenGL code in a background + * thread on a Mac, and the main thread hangs because it's waiting for that + * background thread, but that background thread is also hanging because it's + * waiting for the main thread to do an update, this might fix your issue. * - * This hint is available since SDL 2.24.0. + * This hint only applies to macOS. * + * This hint is available since SDL 2.24.0. */ #define SDL_HINT_MAC_OPENGL_ASYNC_DISPATCH "SDL_MAC_OPENGL_ASYNC_DISPATCH" /** - * \brief A variable setting the double click radius, in pixels. + * A variable setting the double click radius, in pixels. */ #define SDL_HINT_MOUSE_DOUBLE_CLICK_RADIUS "SDL_MOUSE_DOUBLE_CLICK_RADIUS" /** - * \brief A variable setting the double click time, in milliseconds. + * A variable setting the double click time, in milliseconds. */ #define SDL_HINT_MOUSE_DOUBLE_CLICK_TIME "SDL_MOUSE_DOUBLE_CLICK_TIME" /** - * \brief Allow mouse click events when clicking to focus an SDL window + * Allow mouse click events when clicking to focus an SDL window * - * This variable can be set to the following values: - * "0" - Ignore mouse clicks that activate a window - * "1" - Generate events for mouse clicks that activate a window + * This variable can be set to the following values: + * + * - "0": Ignore mouse clicks that activate a window + * - "1": Generate events for mouse clicks that activate a window * - * By default SDL will ignore mouse clicks that activate a window + * By default SDL will ignore mouse clicks that activate a window */ #define SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH "SDL_MOUSE_FOCUS_CLICKTHROUGH" /** - * \brief A variable setting the speed scale for mouse motion, in floating point, when the mouse is not in relative mode + * A variable setting the speed scale for mouse motion, in floating point, + * when the mouse is not in relative mode */ #define SDL_HINT_MOUSE_NORMAL_SPEED_SCALE "SDL_MOUSE_NORMAL_SPEED_SCALE" /** - * \brief A variable controlling whether relative mouse mode constrains the mouse to the center of the window + * A variable controlling whether relative mouse mode constrains the mouse to + * the center of the window + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Relative mouse mode constrains the mouse to the window - * "1" - Relative mouse mode constrains the mouse to the center of the window + * - "0": Relative mouse mode constrains the mouse to the window + * - "1": Relative mouse mode constrains the mouse to the center of the window * - * Constraining to the center of the window works better for FPS games and when the - * application is running over RDP. Constraining to the whole window works better - * for 2D games and increases the chance that the mouse will be in the correct - * position when using high DPI mice. + * Constraining to the center of the window works better for FPS games and + * when the application is running over RDP. Constraining to the whole window + * works better for 2D games and increases the chance that the mouse will be + * in the correct position when using high DPI mice. * - * By default SDL will constrain the mouse to the center of the window + * By default SDL will constrain the mouse to the center of the window */ #define SDL_HINT_MOUSE_RELATIVE_MODE_CENTER "SDL_MOUSE_RELATIVE_MODE_CENTER" /** - * \brief A variable controlling whether relative mouse mode is implemented using mouse warping + * A variable controlling whether relative mouse mode is implemented using + * mouse warping + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Relative mouse mode uses raw input - * "1" - Relative mouse mode uses mouse warping + * - "0": Relative mouse mode uses raw input + * - "1": Relative mouse mode uses mouse warping * - * By default SDL will use raw input for relative mouse mode + * By default SDL will use raw input for relative mouse mode */ #define SDL_HINT_MOUSE_RELATIVE_MODE_WARP "SDL_MOUSE_RELATIVE_MODE_WARP" /** - * \brief A variable controlling whether relative mouse motion is affected by renderer scaling + * A variable controlling whether relative mouse motion is affected by + * renderer scaling * - * This variable can be set to the following values: - * "0" - Relative motion is unaffected by DPI or renderer's logical size - * "1" - Relative motion is scaled according to DPI scaling and logical size + * This variable can be set to the following values: + * + * - "0": Relative motion is unaffected by DPI or renderer's logical size + * - "1": Relative motion is scaled according to DPI scaling and logical size * - * By default relative mouse deltas are affected by DPI and renderer scaling + * By default relative mouse deltas are affected by DPI and renderer scaling */ #define SDL_HINT_MOUSE_RELATIVE_SCALING "SDL_MOUSE_RELATIVE_SCALING" /** - * \brief A variable setting the scale for mouse motion, in floating point, when the mouse is in relative mode + * A variable setting the scale for mouse motion, in floating point, when the + * mouse is in relative mode */ #define SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE "SDL_MOUSE_RELATIVE_SPEED_SCALE" /** - * \brief A variable controlling whether the system mouse acceleration curve is used for relative mouse motion. + * A variable controlling whether the system mouse acceleration curve is used + * for relative mouse motion. * - * This variable can be set to the following values: - * "0" - Relative mouse motion will be unscaled (the default) - * "1" - Relative mouse motion will be scaled using the system mouse acceleration curve. + * This variable can be set to the following values: * - * If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will override the system speed scale. + * - "0": Relative mouse motion will be unscaled (the default) + * - "1": Relative mouse motion will be scaled using the system mouse + * acceleration curve. + * + * If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will override the + * system speed scale. */ #define SDL_HINT_MOUSE_RELATIVE_SYSTEM_SCALE "SDL_MOUSE_RELATIVE_SYSTEM_SCALE" /** - * \brief A variable controlling whether a motion event should be generated for mouse warping in relative mode. + * A variable controlling whether a motion event should be generated for mouse + * warping in relative mode. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Warping the mouse will not generate a motion event in relative mode - * "1" - Warping the mouse will generate a motion event in relative mode + * - "0": Warping the mouse will not generate a motion event in relative mode + * - "1": Warping the mouse will generate a motion event in relative mode * - * By default warping the mouse will not generate motion events in relative mode. This avoids the application having to filter out large relative motion due to warping. + * By default warping the mouse will not generate motion events in relative + * mode. This avoids the application having to filter out large relative + * motion due to warping. */ #define SDL_HINT_MOUSE_RELATIVE_WARP_MOTION "SDL_MOUSE_RELATIVE_WARP_MOTION" /** - * \brief A variable controlling whether the hardware cursor stays visible when relative mode is active. + * A variable controlling whether the hardware cursor stays visible when + * relative mode is active. * - * This variable can be set to the following values: - * "0" - The cursor will be hidden while relative mode is active (default) - * "1" - The cursor will remain visible while relative mode is active + * This variable can be set to the following values: "0" - The cursor will be + * hidden while relative mode is active (default) "1" - The cursor will remain + * visible while relative mode is active * - * Note that for systems without raw hardware inputs, relative mode is implemented using warping, so the hardware cursor will visibly warp between frames if this is enabled on those systems. + * Note that for systems without raw hardware inputs, relative mode is + * implemented using warping, so the hardware cursor will visibly warp between + * frames if this is enabled on those systems. */ #define SDL_HINT_MOUSE_RELATIVE_CURSOR_VISIBLE "SDL_MOUSE_RELATIVE_CURSOR_VISIBLE" @@ -1438,330 +1679,382 @@ extern "C" { * A variable controlling whether mouse events should generate synthetic touch * events * - * This variable can be set to the following values: - * "0" - Mouse events will not generate touch events (default for desktop platforms) - * "1" - Mouse events will generate touch events (default for mobile platforms, such as Android and iOS) + * This variable can be set to the following values: + * + * - "0": Mouse events will not generate touch events (default for desktop + * platforms) + * - "1": Mouse events will generate touch events (default for mobile + * platforms, such as Android and iOS) */ #define SDL_HINT_MOUSE_TOUCH_EVENTS "SDL_MOUSE_TOUCH_EVENTS" /** - * \brief A variable controlling whether the mouse is captured while mouse buttons are pressed + * A variable controlling whether the mouse is captured while mouse buttons + * are pressed * - * This variable can be set to the following values: - * "0" - The mouse is not captured while mouse buttons are pressed - * "1" - The mouse is captured while mouse buttons are pressed + * This variable can be set to the following values: + * + * - "0": The mouse is not captured while mouse buttons are pressed + * - "1": The mouse is captured while mouse buttons are pressed * - * By default the mouse is captured while mouse buttons are pressed so if the mouse is dragged - * outside the window, the application continues to receive mouse events until the button is - * released. + * By default the mouse is captured while mouse buttons are pressed so if the + * mouse is dragged outside the window, the application continues to receive + * mouse events until the button is released. */ #define SDL_HINT_MOUSE_AUTO_CAPTURE "SDL_MOUSE_AUTO_CAPTURE" /** - * \brief Tell SDL not to catch the SIGINT or SIGTERM signals. + * Tell SDL not to catch the SIGINT or SIGTERM signals. * - * This hint only applies to Unix-like platforms, and should set before - * any calls to SDL_Init() + * This hint only applies to Unix-like platforms, and should set before any + * calls to SDL_Init() * * The variable can be set to the following values: - * "0" - SDL will install a SIGINT and SIGTERM handler, and when it - * catches a signal, convert it into an SDL_QUIT event. - * "1" - SDL will not install a signal handler at all. + * + * - "0": SDL will install a SIGINT and SIGTERM handler, and when it catches a + * signal, convert it into an SDL_QUIT event. + * - "1": SDL will not install a signal handler at all. */ #define SDL_HINT_NO_SIGNAL_HANDLERS "SDL_NO_SIGNAL_HANDLERS" /** - * \brief A variable controlling what driver to use for OpenGL ES contexts. + * A variable controlling what driver to use for OpenGL ES contexts. * - * On some platforms, currently Windows and X11, OpenGL drivers may support - * creating contexts with an OpenGL ES profile. By default SDL uses these - * profiles, when available, otherwise it attempts to load an OpenGL ES - * library, e.g. that provided by the ANGLE project. This variable controls - * whether SDL follows this default behaviour or will always load an - * OpenGL ES library. + * On some platforms, currently Windows and X11, OpenGL drivers may support + * creating contexts with an OpenGL ES profile. By default SDL uses these + * profiles, when available, otherwise it attempts to load an OpenGL ES + * library, e.g. that provided by the ANGLE project. This variable controls + * whether SDL follows this default behaviour or will always load an OpenGL ES + * library. * - * Circumstances where this is useful include - * - Testing an app with a particular OpenGL ES implementation, e.g ANGLE, - * or emulator, e.g. those from ARM, Imagination or Qualcomm. - * - Resolving OpenGL ES function addresses at link time by linking with - * the OpenGL ES library instead of querying them at run time with - * SDL_GL_GetProcAddress(). + * Circumstances where this is useful include - Testing an app with a + * particular OpenGL ES implementation, e.g ANGLE, or emulator, e.g. those + * from ARM, Imagination or Qualcomm. - Resolving OpenGL ES function addresses + * at link time by linking with the OpenGL ES library instead of querying them + * at run time with SDL_GL_GetProcAddress(). * - * Caution: for an application to work with the default behaviour across - * different OpenGL drivers it must query the OpenGL ES function - * addresses at run time using SDL_GL_GetProcAddress(). + * Caution: for an application to work with the default behaviour across + * different OpenGL drivers it must query the OpenGL ES function addresses at + * run time using SDL_GL_GetProcAddress(). * - * This variable is ignored on most platforms because OpenGL ES is native - * or not supported. + * This variable is ignored on most platforms because OpenGL ES is native or + * not supported. * - * This variable can be set to the following values: - * "0" - Use ES profile of OpenGL, if available. (Default when not set.) - * "1" - Load OpenGL ES library using the default library names. + * This variable can be set to the following values: * + * - "0": Use ES profile of OpenGL, if available. (Default when not set.) + * - "1": Load OpenGL ES library using the default library names. */ #define SDL_HINT_OPENGL_ES_DRIVER "SDL_OPENGL_ES_DRIVER" /** - * \brief A variable controlling which orientations are allowed on iOS/Android. + * A variable controlling which orientations are allowed on iOS/Android. + * + * In some circumstances it is necessary to be able to explicitly control + * which UI orientations are allowed. * - * In some circumstances it is necessary to be able to explicitly control - * which UI orientations are allowed. + * This variable is a space delimited list of the following values: * - * This variable is a space delimited list of the following values: - * "LandscapeLeft", "LandscapeRight", "Portrait" "PortraitUpsideDown" + * - "LandscapeLeft" + * - "LandscapeRight" + * - "Portrait" + * - "PortraitUpsideDown" */ #define SDL_HINT_ORIENTATIONS "SDL_IOS_ORIENTATIONS" /** - * \brief A variable controlling the use of a sentinel event when polling the event queue + * A variable controlling the use of a sentinel event when polling the event + * queue * - * This variable can be set to the following values: - * "0" - Disable poll sentinels - * "1" - Enable poll sentinels + * This variable can be set to the following values: * - * When polling for events, SDL_PumpEvents is used to gather new events from devices. - * If a device keeps producing new events between calls to SDL_PumpEvents, a poll loop will - * become stuck until the new events stop. - * This is most noticeable when moving a high frequency mouse. + * - "0": Disable poll sentinels + * - "1": Enable poll sentinels * - * By default, poll sentinels are enabled. + * When polling for events, SDL_PumpEvents is used to gather new events from + * devices. If a device keeps producing new events between calls to + * SDL_PumpEvents, a poll loop will become stuck until the new events stop. + * This is most noticeable when moving a high frequency mouse. + * + * By default, poll sentinels are enabled. */ #define SDL_HINT_POLL_SENTINEL "SDL_POLL_SENTINEL" /** - * \brief Override for SDL_GetPreferredLocales() + * Override for SDL_GetPreferredLocales() * - * If set, this will be favored over anything the OS might report for the - * user's preferred locales. Changing this hint at runtime will not generate - * a SDL_LOCALECHANGED event (but if you can change the hint, you can push - * your own event, if you want). + * If set, this will be favored over anything the OS might report for the + * user's preferred locales. Changing this hint at runtime will not generate a + * SDL_LOCALECHANGED event (but if you can change the hint, you can push your + * own event, if you want). * - * The format of this hint is a comma-separated list of language and locale, - * combined with an underscore, as is a common format: "en_GB". Locale is - * optional: "en". So you might have a list like this: "en_GB,jp,es_PT" + * The format of this hint is a comma-separated list of language and locale, + * combined with an underscore, as is a common format: "en_GB". Locale is + * optional: "en". So you might have a list like this: "en_GB,jp,es_PT" */ #define SDL_HINT_PREFERRED_LOCALES "SDL_PREFERRED_LOCALES" /** - * \brief A variable describing the content orientation on QtWayland-based platforms. + * A variable describing the content orientation on QtWayland-based platforms. + * + * On QtWayland platforms, windows are rotated client-side to allow for custom + * transitions. In order to correctly position overlays (e.g. volume bar) and + * gestures (e.g. events view, close/minimize gestures), the system needs to + * know in which orientation the application is currently drawing its + * contents. * - * On QtWayland platforms, windows are rotated client-side to allow for custom - * transitions. In order to correctly position overlays (e.g. volume bar) and - * gestures (e.g. events view, close/minimize gestures), the system needs to - * know in which orientation the application is currently drawing its contents. + * This does not cause the window to be rotated or resized, the application + * needs to take care of drawing the content in the right orientation (the + * framebuffer is always in portrait mode). * - * This does not cause the window to be rotated or resized, the application - * needs to take care of drawing the content in the right orientation (the - * framebuffer is always in portrait mode). + * This variable can be one of the following values: * - * This variable can be one of the following values: - * "primary" (default), "portrait", "landscape", "inverted-portrait", "inverted-landscape" + * - "primary" (default) + * - "portrait" + * - "landscape" + * - "inverted-portrait" + * - "inverted-landscape" * - * Since SDL 2.0.22 this variable accepts a comma-separated list of values above. + * Since SDL 2.0.22 this variable accepts a comma-separated list of values + * above. */ #define SDL_HINT_QTWAYLAND_CONTENT_ORIENTATION "SDL_QTWAYLAND_CONTENT_ORIENTATION" /** - * \brief Flags to set on QtWayland windows to integrate with the native window manager. + * Flags to set on QtWayland windows to integrate with the native window + * manager. * - * On QtWayland platforms, this hint controls the flags to set on the windows. - * For example, on Sailfish OS "OverridesSystemGestures" disables swipe gestures. + * On QtWayland platforms, this hint controls the flags to set on the windows. + * For example, on Sailfish OS "OverridesSystemGestures" disables swipe + * gestures. * - * This variable is a space-separated list of the following values (empty = no flags): - * "OverridesSystemGestures", "StaysOnTop", "BypassWindowManager" + * This variable is a space-separated list of the following values (empty = no + * flags): + * + * - "OverridesSystemGestures" + * - "StaysOnTop" + * - "BypassWindowManager" */ #define SDL_HINT_QTWAYLAND_WINDOW_FLAGS "SDL_QTWAYLAND_WINDOW_FLAGS" /** - * \brief A variable controlling whether the 2D render API is compatible or efficient. - * - * This variable can be set to the following values: + * A variable controlling whether the 2D render API is compatible or + * efficient. * - * "0" - Don't use batching to make rendering more efficient. - * "1" - Use batching, but might cause problems if app makes its own direct OpenGL calls. + * This variable can be set to the following values: * - * Up to SDL 2.0.9, the render API would draw immediately when requested. Now - * it batches up draw requests and sends them all to the GPU only when forced - * to (during SDL_RenderPresent, when changing render targets, by updating a - * texture that the batch needs, etc). This is significantly more efficient, - * but it can cause problems for apps that expect to render on top of the - * render API's output. As such, SDL will disable batching if a specific - * render backend is requested (since this might indicate that the app is - * planning to use the underlying graphics API directly). This hint can - * be used to explicitly request batching in this instance. It is a contract - * that you will either never use the underlying graphics API directly, or - * if you do, you will call SDL_RenderFlush() before you do so any current - * batch goes to the GPU before your work begins. Not following this contract - * will result in undefined behavior. + * - "0": Don't use batching to make rendering more efficient. + * - "1": Use batching, but might cause problems if app makes its own direct + * OpenGL calls. + * + * Up to SDL 2.0.9, the render API would draw immediately when requested. Now + * it batches up draw requests and sends them all to the GPU only when forced + * to (during SDL_RenderPresent, when changing render targets, by updating a + * texture that the batch needs, etc). This is significantly more efficient, + * but it can cause problems for apps that expect to render on top of the + * render API's output. As such, SDL will disable batching if a specific + * render backend is requested (since this might indicate that the app is + * planning to use the underlying graphics API directly). This hint can be + * used to explicitly request batching in this instance. It is a contract that + * you will either never use the underlying graphics API directly, or if you + * do, you will call SDL_RenderFlush() before you do so any current batch goes + * to the GPU before your work begins. Not following this contract will result + * in undefined behavior. */ #define SDL_HINT_RENDER_BATCHING "SDL_RENDER_BATCHING" /** - * \brief A variable controlling how the 2D render API renders lines + * A variable controlling how the 2D render API renders lines * - * This variable can be set to the following values: - * "0" - Use the default line drawing method (Bresenham's line algorithm as of SDL 2.0.20) - * "1" - Use the driver point API using Bresenham's line algorithm (correct, draws many points) - * "2" - Use the driver line API (occasionally misses line endpoints based on hardware driver quirks, was the default before 2.0.20) - * "3" - Use the driver geometry API (correct, draws thicker diagonal lines) + * This variable can be set to the following values: + * + * - "0": Use the default line drawing method (Bresenham's line algorithm as + * of SDL 2.0.20) + * - "1": Use the driver point API using Bresenham's line algorithm (correct, + * draws many points) + * - "2": Use the driver line API (occasionally misses line endpoints based on + * hardware driver quirks, was the default before 2.0.20) + * - "3": Use the driver geometry API (correct, draws thicker diagonal lines) * - * This variable should be set when the renderer is created. + * This variable should be set when the renderer is created. */ #define SDL_HINT_RENDER_LINE_METHOD "SDL_RENDER_LINE_METHOD" /** - * \brief A variable controlling whether to enable Direct3D 11+'s Debug Layer. + * A variable controlling whether to enable Direct3D 11+'s Debug Layer. * - * This variable does not have any effect on the Direct3D 9 based renderer. + * This variable does not have any effect on the Direct3D 9 based renderer. * - * This variable can be set to the following values: - * "0" - Disable Debug Layer use - * "1" - Enable Debug Layer use + * This variable can be set to the following values: * - * By default, SDL does not use Direct3D Debug Layer. + * - "0": Disable Debug Layer use + * - "1": Enable Debug Layer use + * + * By default, SDL does not use Direct3D Debug Layer. */ #define SDL_HINT_RENDER_DIRECT3D11_DEBUG "SDL_RENDER_DIRECT3D11_DEBUG" /** - * \brief A variable controlling whether the Direct3D device is initialized for thread-safe operations. + * A variable controlling whether the Direct3D device is initialized for + * thread-safe operations. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Thread-safety is not enabled (faster) - * "1" - Thread-safety is enabled + * - "0": Thread-safety is not enabled (faster) + * - "1": Thread-safety is enabled * - * By default the Direct3D device is created with thread-safety disabled. + * By default the Direct3D device is created with thread-safety disabled. */ #define SDL_HINT_RENDER_DIRECT3D_THREADSAFE "SDL_RENDER_DIRECT3D_THREADSAFE" /** - * \brief A variable specifying which render driver to use. + * A variable specifying which render driver to use. * - * If the application doesn't pick a specific renderer to use, this variable - * specifies the name of the preferred renderer. If the preferred renderer - * can't be initialized, the normal default renderer is used. + * If the application doesn't pick a specific renderer to use, this variable + * specifies the name of the preferred renderer. If the preferred renderer + * can't be initialized, the normal default renderer is used. * - * This variable is case insensitive and can be set to the following values: - * "direct3d" - * "direct3d11" - * "direct3d12" - * "opengl" - * "opengles2" - * "opengles" - * "metal" - * "software" + * This variable is case insensitive and can be set to the following values: * - * The default varies by platform, but it's the first one in the list that - * is available on the current platform. + * - "direct3d" + * - "direct3d11" + * - "direct3d12" + * - "opengl" + * - "opengles2" + * - "opengles" + * - "metal" + * - "software" + * + * The default varies by platform, but it's the first one in the list that is + * available on the current platform. */ #define SDL_HINT_RENDER_DRIVER "SDL_RENDER_DRIVER" /** - * \brief A variable controlling the scaling policy for SDL_RenderSetLogicalSize. + * A variable controlling the scaling policy for SDL_RenderSetLogicalSize. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" or "letterbox" - Uses letterbox/sidebars to fit the entire rendering on screen - * "1" or "overscan" - Will zoom the rendering so it fills the entire screen, allowing edges to be drawn offscreen + * "0" or "letterbox" - Uses letterbox/sidebars to fit the entire rendering on + * screen "1" or "overscan" - Will zoom the rendering so it fills the entire + * screen, allowing edges to be drawn offscreen * - * By default letterbox is used + * By default letterbox is used */ #define SDL_HINT_RENDER_LOGICAL_SIZE_MODE "SDL_RENDER_LOGICAL_SIZE_MODE" /** - * \brief A variable controlling whether the OpenGL render driver uses shaders if they are available. + * A variable controlling whether the OpenGL render driver uses shaders if + * they are available. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Disable shaders - * "1" - Enable shaders + * - "0": Disable shaders + * - "1": Enable shaders * - * By default shaders are used if OpenGL supports them. + * By default shaders are used if OpenGL supports them. */ #define SDL_HINT_RENDER_OPENGL_SHADERS "SDL_RENDER_OPENGL_SHADERS" /** - * \brief A variable controlling the scaling quality + * A variable controlling the scaling quality * - * This variable can be set to the following values: - * "0" or "nearest" - Nearest pixel sampling - * "1" or "linear" - Linear filtering (supported by OpenGL and Direct3D) - * "2" or "best" - Currently this is the same as "linear" + * This variable can be set to the following values: + * + * - "0" or "nearest": Nearest pixel sampling + * - "1" or "linear": Linear filtering (supported by OpenGL and Direct3D) + * - "2" or "best": Currently this is the same as "linear" * - * By default nearest pixel sampling is used + * By default nearest pixel sampling is used */ #define SDL_HINT_RENDER_SCALE_QUALITY "SDL_RENDER_SCALE_QUALITY" /** - * \brief A variable controlling whether updates to the SDL screen surface should be synchronized with the vertical refresh, to avoid tearing. + * A variable controlling whether updates to the SDL screen surface should be + * synchronized with the vertical refresh, to avoid tearing. * - * This variable can be set to the following values: - * "0" - Disable vsync - * "1" - Enable vsync + * This variable can be set to the following values: * - * By default SDL does not sync screen surface updates with vertical refresh. + * - "0": Disable vsync + * - "1": Enable vsync + * + * By default SDL does not sync screen surface updates with vertical refresh. */ #define SDL_HINT_RENDER_VSYNC "SDL_RENDER_VSYNC" /** - * \brief A variable controlling whether the Metal render driver select low power device over default one + * A variable controlling whether the Metal render driver select low power + * device over default one + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Use the prefered OS device - * "1" - Select a low power one + * - "0": Use the prefered OS device + * - "1": Select a low power one * - * By default the prefered OS device is used. + * By default the prefered OS device is used. */ #define SDL_HINT_RENDER_METAL_PREFER_LOW_POWER_DEVICE "SDL_RENDER_METAL_PREFER_LOW_POWER_DEVICE" /** - * A variable containing a list of ROG gamepad capable mice. + * A variable containing a list of ROG gamepad capable mice. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_ROG_GAMEPAD_MICE "SDL_ROG_GAMEPAD_MICE" /** - * A variable containing a list of devices that are not ROG gamepad capable mice. This will override SDL_HINT_ROG_GAMEPAD_MICE and the built in device list. + * A variable containing a list of devices that are not ROG gamepad capable + * mice. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * This will override SDL_HINT_ROG_GAMEPAD_MICE and the built in device list. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_ROG_GAMEPAD_MICE_EXCLUDED "SDL_ROG_GAMEPAD_MICE_EXCLUDED" /** - * \brief A variable controlling if VSYNC is automatically disable if doesn't reach the enough FPS + * A variable controlling if VSYNC is automatically disable if doesn't reach + * the enough FPS + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - It will be using VSYNC as defined in the main flag. Default - * "1" - If VSYNC was previously enabled, then it will disable VSYNC if doesn't reach enough speed + * - "0": It will be using VSYNC as defined in the main flag. Default + * - "1": If VSYNC was previously enabled, then it will disable VSYNC if + * doesn't reach enough speed * - * By default SDL does not enable the automatic VSYNC + * By default SDL does not enable the automatic VSYNC */ #define SDL_HINT_PS2_DYNAMIC_VSYNC "SDL_PS2_DYNAMIC_VSYNC" /** - * \brief A variable to control whether the return key on the soft keyboard - * should hide the soft keyboard on Android and iOS. + * A variable to control whether the return key on the soft keyboard should + * hide the soft keyboard on Android and iOS. * * The variable can be set to the following values: - * "0" - The return key will be handled as a key event. This is the behaviour of SDL <= 2.0.3. (default) - * "1" - The return key will hide the keyboard. * - * The value of this hint is used at runtime, so it can be changed at any time. + * - "0": The return key will be handled as a key event. This is the behaviour + * of SDL <= 2.0.3. (default) + * - "1": The return key will hide the keyboard. + * + * The value of this hint is used at runtime, so it can be changed at any + * time. */ #define SDL_HINT_RETURN_KEY_HIDES_IME "SDL_RETURN_KEY_HIDES_IME" /** - * \brief Tell SDL which Dispmanx layer to use on a Raspberry PI + * Tell SDL which Dispmanx layer to use on a Raspberry PI * * Also known as Z-order. The variable can take a negative or positive value. * The default is 10000. @@ -1769,7 +2062,7 @@ extern "C" { #define SDL_HINT_RPI_VIDEO_LAYER "SDL_RPI_VIDEO_LAYER" /** - * \brief Specify an "activity name" for screensaver inhibition. + * Specify an "activity name" for screensaver inhibition. * * Some platforms, notably Linux desktops, list the applications which are * inhibiting the screensaver or other power-saving features. @@ -1778,7 +2071,7 @@ extern "C" { * SDL_DisableScreenSaver() is used (or the screensaver is automatically * disabled). The contents of this hint are used when the screensaver is * disabled. You should use a string that describes what your program is doing - * (and, therefore, why the screensaver is disabled). For example, "Playing a + * (and, therefore, why the screensaver is disabled). For example, "Playing a * game" or "Watching a video". * * Setting this to "" or leaving it unset will have SDL use a reasonable @@ -1789,125 +2082,140 @@ extern "C" { #define SDL_HINT_SCREENSAVER_INHIBIT_ACTIVITY_NAME "SDL_SCREENSAVER_INHIBIT_ACTIVITY_NAME" /** - * \brief Specifies whether SDL_THREAD_PRIORITY_TIME_CRITICAL should be treated as realtime. + * Specifies whether SDL_THREAD_PRIORITY_TIME_CRITICAL should be treated as + * realtime. + * + * On some platforms, like Linux, a realtime priority thread may be subject to + * restrictions that require special handling by the application. This hint + * exists to let SDL know that the app is prepared to handle said + * restrictions. * - * On some platforms, like Linux, a realtime priority thread may be subject to restrictions - * that require special handling by the application. This hint exists to let SDL know that - * the app is prepared to handle said restrictions. + * On Linux, SDL will apply the following configuration to any thread that + * becomes realtime: * - * On Linux, SDL will apply the following configuration to any thread that becomes realtime: - * * The SCHED_RESET_ON_FORK bit will be set on the scheduling policy, - * * An RLIMIT_RTTIME budget will be configured to the rtkit specified limit. - * * Exceeding this limit will result in the kernel sending SIGKILL to the app, - * * Refer to the man pages for more information. + * - The SCHED_RESET_ON_FORK bit will be set on the scheduling policy. + * - An RLIMIT_RTTIME budget will be configured to the rtkit specified limit. + * - Exceeding this limit will result in the kernel sending SIGKILL to the + * app. + * + * Refer to the man pages for more information. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - default platform specific behaviour - * "1" - Force SDL_THREAD_PRIORITY_TIME_CRITICAL to a realtime scheduling policy + * - "0": default platform specific behaviour + * - "1": Force SDL_THREAD_PRIORITY_TIME_CRITICAL to a realtime scheduling + * policy */ #define SDL_HINT_THREAD_FORCE_REALTIME_TIME_CRITICAL "SDL_THREAD_FORCE_REALTIME_TIME_CRITICAL" /** -* \brief A string specifying additional information to use with SDL_SetThreadPriority. -* -* By default SDL_SetThreadPriority will make appropriate system changes in order to -* apply a thread priority. For example on systems using pthreads the scheduler policy -* is changed automatically to a policy that works well with a given priority. -* Code which has specific requirements can override SDL's default behavior with this hint. -* -* pthread hint values are "current", "other", "fifo" and "rr". -* Currently no other platform hint values are defined but may be in the future. -* -* \note On Linux, the kernel may send SIGKILL to realtime tasks which exceed the distro -* configured execution budget for rtkit. This budget can be queried through RLIMIT_RTTIME -* after calling SDL_SetThreadPriority(). -*/ + * A string specifying additional information to use with + * SDL_SetThreadPriority. + * + * By default SDL_SetThreadPriority will make appropriate system changes in + * order to apply a thread priority. For example on systems using pthreads the + * scheduler policy is changed automatically to a policy that works well with + * a given priority. Code which has specific requirements can override SDL's + * default behavior with this hint. + * + * pthread hint values are "current", "other", "fifo" and "rr". Currently no + * other platform hint values are defined but may be in the future. + */ #define SDL_HINT_THREAD_PRIORITY_POLICY "SDL_THREAD_PRIORITY_POLICY" /** -* \brief A string specifying SDL's threads stack size in bytes or "0" for the backend's default size -* -* Use this hint in case you need to set SDL's threads stack size to other than the default. -* This is specially useful if you build SDL against a non glibc libc library (such as musl) which -* provides a relatively small default thread stack size (a few kilobytes versus the default 8MB glibc uses). -* Support for this hint is currently available only in the pthread, Windows, and PSP backend. -* -* Instead of this hint, in 2.0.9 and later, you can use -* SDL_CreateThreadWithStackSize(). This hint only works with the classic -* SDL_CreateThread(). -*/ + * A string specifying SDL's threads stack size in bytes or "0" for the + * backend's default size + * + * Use this hint in case you need to set SDL's threads stack size to other + * than the default. This is specially useful if you build SDL against a non + * glibc libc library (such as musl) which provides a relatively small default + * thread stack size (a few kilobytes versus the default 8MB glibc uses). + * Support for this hint is currently available only in the pthread, Windows, + * and PSP backend. + * + * Instead of this hint, in 2.0.9 and later, you can use + * SDL_CreateThreadWithStackSize(). This hint only works with the classic + * SDL_CreateThread(). + */ #define SDL_HINT_THREAD_STACK_SIZE "SDL_THREAD_STACK_SIZE" /** - * \brief A variable that controls the timer resolution, in milliseconds. + * A variable that controls the timer resolution, in milliseconds. * - * The higher resolution the timer, the more frequently the CPU services - * timer interrupts, and the more precise delays are, but this takes up - * power and CPU time. This hint is only used on Windows. + * The higher resolution the timer, the more frequently the CPU services timer + * interrupts, and the more precise delays are, but this takes up power and + * CPU time. This hint is only used on Windows. * - * See this blog post for more information: - * http://randomascii.wordpress.com/2013/07/08/windows-timer-resolution-megawatts-wasted/ + * See this blog post for more information: + * http://randomascii.wordpress.com/2013/07/08/windows-timer-resolution-megawatts-wasted/ * - * If this variable is set to "0", the system timer resolution is not set. + * If this variable is set to "0", the system timer resolution is not set. * - * The default value is "1". This hint may be set at any time. + * The default value is "1". This hint may be set at any time. */ #define SDL_HINT_TIMER_RESOLUTION "SDL_TIMER_RESOLUTION" /** - * \brief A variable controlling whether touch events should generate synthetic mouse events + * A variable controlling whether touch events should generate synthetic mouse + * events + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Touch events will not generate mouse events - * "1" - Touch events will generate mouse events + * - "0": Touch events will not generate mouse events + * - "1": Touch events will generate mouse events * - * By default SDL will generate mouse events for touch events + * By default SDL will generate mouse events for touch events */ #define SDL_HINT_TOUCH_MOUSE_EVENTS "SDL_TOUCH_MOUSE_EVENTS" /** - * \brief A variable controlling which touchpad should generate synthetic mouse events + * A variable controlling which touchpad should generate synthetic mouse + * events + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Only front touchpad should generate mouse events. Default - * "1" - Only back touchpad should generate mouse events. - * "2" - Both touchpads should generate mouse events. + * - "0": Only front touchpad should generate mouse events. Default + * - "1": Only back touchpad should generate mouse events. + * - "2": Both touchpads should generate mouse events. * - * By default SDL will generate mouse events for all touch devices + * By default SDL will generate mouse events for all touch devices */ #define SDL_HINT_VITA_TOUCH_MOUSE_DEVICE "SDL_HINT_VITA_TOUCH_MOUSE_DEVICE" /** - * \brief A variable controlling whether the Android / tvOS remotes - * should be listed as joystick devices, instead of sending keyboard events. + * A variable controlling whether the Android / tvOS remotes should be listed + * as joystick devices, instead of sending keyboard events. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Remotes send enter/escape/arrow key events - * "1" - Remotes are available as 2 axis, 2 button joysticks (the default). + * - "0": Remotes send enter/escape/arrow key events + * - "1": Remotes are available as 2 axis, 2 button joysticks (the default). */ #define SDL_HINT_TV_REMOTE_AS_JOYSTICK "SDL_TV_REMOTE_AS_JOYSTICK" /** - * \brief A variable controlling whether the screensaver is enabled. + * A variable controlling whether the screensaver is enabled. * - * This variable can be set to the following values: - * "0" - Disable screensaver - * "1" - Enable screensaver + * This variable can be set to the following values: + * + * - "0": Disable screensaver + * - "1": Enable screensaver * - * By default SDL will disable the screensaver. + * By default SDL will disable the screensaver. */ #define SDL_HINT_VIDEO_ALLOW_SCREENSAVER "SDL_VIDEO_ALLOW_SCREENSAVER" /** - * \brief Tell the video driver that we only want a double buffer. + * Tell the video driver that we only want a double buffer. * * By default, most lowlevel 2D APIs will use a triple buffer scheme that * wastes no CPU time on waiting for vsync after issuing a flip, but * introduces a frame of latency. On the other hand, using a double buffer * scheme instead is recommended for cases where low latency is an important - * factor because we save a whole frame of latency. - * We do so by waiting for vsync immediately after issuing a flip, usually just - * after eglSwapBuffers call in the backend's *_SwapWindow function. + * factor because we save a whole frame of latency. We do so by waiting for + * vsync immediately after issuing a flip, usually just after eglSwapBuffers + * call in the backend's *_SwapWindow function. * * Since it's driver-specific, it's only supported where possible and * implemented. Currently supported the following drivers: @@ -1919,499 +2227,570 @@ extern "C" { #define SDL_HINT_VIDEO_DOUBLE_BUFFER "SDL_VIDEO_DOUBLE_BUFFER" /** - * \brief A variable controlling whether the EGL window is allowed to be - * composited as transparent, rather than opaque. + * A variable controlling whether the EGL window is allowed to be composited + * as transparent, rather than opaque. * * Most window systems will always render windows opaque, even if the surface - * format has an alpha channel. This is not always true, however, so by default - * SDL will try to enforce opaque composition. To override this behavior, you - * can set this hint to "1". + * format has an alpha channel. This is not always true, however, so by + * default SDL will try to enforce opaque composition. To override this + * behavior, you can set this hint to "1". */ #define SDL_HINT_VIDEO_EGL_ALLOW_TRANSPARENCY "SDL_VIDEO_EGL_ALLOW_TRANSPARENCY" /** - * \brief A variable controlling whether the graphics context is externally managed. + * A variable controlling whether the graphics context is externally managed. * * This variable can be set to the following values: - * "0" - SDL will manage graphics contexts that are attached to windows. - * "1" - Disable graphics context management on windows. * - * By default SDL will manage OpenGL contexts in certain situations. For example, on Android the - * context will be automatically saved and restored when pausing the application. Additionally, some - * platforms will assume usage of OpenGL if Vulkan isn't used. Setting this to "1" will prevent this - * behavior, which is desireable when the application manages the graphics context, such as - * an externally managed OpenGL context or attaching a Vulkan surface to the window. + * - "0": SDL will manage graphics contexts that are attached to windows. + * - "1": Disable graphics context management on windows. + * + * By default SDL will manage OpenGL contexts in certain situations. For + * example, on Android the context will be automatically saved and restored + * when pausing the application. Additionally, some platforms will assume + * usage of OpenGL if Vulkan isn't used. Setting this to "1" will prevent this + * behavior, which is desireable when the application manages the graphics + * context, such as an externally managed OpenGL context or attaching a Vulkan + * surface to the window. */ #define SDL_HINT_VIDEO_EXTERNAL_CONTEXT "SDL_VIDEO_EXTERNAL_CONTEXT" /** - * \brief If set to 1, then do not allow high-DPI windows. ("Retina" on Mac and iOS) + * If set to 1, then do not allow high-DPI windows. + * + * ("Retina" on Mac and iOS) */ #define SDL_HINT_VIDEO_HIGHDPI_DISABLED "SDL_VIDEO_HIGHDPI_DISABLED" /** - * \brief A variable that dictates policy for fullscreen Spaces on Mac OS X. + * A variable that dictates policy for fullscreen Spaces on Mac OS X. + * + * This hint only applies to Mac OS X. * - * This hint only applies to Mac OS X. + * The variable can be set to the following values: * - * The variable can be set to the following values: - * "0" - Disable Spaces support (FULLSCREEN_DESKTOP won't use them and - * SDL_WINDOW_RESIZABLE windows won't offer the "fullscreen" - * button on their titlebars). - * "1" - Enable Spaces support (FULLSCREEN_DESKTOP will use them and - * SDL_WINDOW_RESIZABLE windows will offer the "fullscreen" - * button on their titlebars). + * - "0": Disable Spaces support (FULLSCREEN_DESKTOP won't use them and + * SDL_WINDOW_RESIZABLE windows won't offer the "fullscreen" button on their + * titlebars). + * - "1": Enable Spaces support (FULLSCREEN_DESKTOP will use them and + * SDL_WINDOW_RESIZABLE windows will offer the "fullscreen" button on their + * titlebars). * - * The default value is "1". This hint must be set before any windows are created. + * The default value is "1". This hint must be set before any windows are + * created. */ #define SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES "SDL_VIDEO_MAC_FULLSCREEN_SPACES" /** - * \brief Minimize your SDL_Window if it loses key focus when in fullscreen mode. Defaults to false. - * \warning Before SDL 2.0.14, this defaulted to true! In 2.0.14, we're - * seeing if "true" causes more problems than it solves in modern times. + * Minimize your SDL_Window if it loses key focus when in fullscreen mode. * + * Defaults to false. */ #define SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS "SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS" /** - * \brief A variable controlling whether the libdecor Wayland backend is allowed to be used. + * A variable controlling whether the libdecor Wayland backend is allowed to + * be used. * - * This variable can be set to the following values: - * "0" - libdecor use is disabled. - * "1" - libdecor use is enabled (default). + * This variable can be set to the following values: + * + * - "0": libdecor use is disabled. + * - "1": libdecor use is enabled (default). * - * libdecor is used over xdg-shell when xdg-decoration protocol is unavailable. + * libdecor is used over xdg-shell when xdg-decoration protocol is + * unavailable. */ #define SDL_HINT_VIDEO_WAYLAND_ALLOW_LIBDECOR "SDL_VIDEO_WAYLAND_ALLOW_LIBDECOR" /** - * \brief A variable controlling whether the libdecor Wayland backend is preferred over native decrations. + * A variable controlling whether the libdecor Wayland backend is preferred + * over native decorations. * - * When this hint is set, libdecor will be used to provide window decorations, even if xdg-decoration is - * available. (Note that, by default, libdecor will use xdg-decoration itself if available). + * When this hint is set, libdecor will be used to provide window decorations, + * even if xdg-decoration is available. (Note that, by default, libdecor will + * use xdg-decoration itself if available). * - * This variable can be set to the following values: - * "0" - libdecor is enabled only if server-side decorations are unavailable. - * "1" - libdecor is always enabled if available. + * This variable can be set to the following values: * - * libdecor is used over xdg-shell when xdg-decoration protocol is unavailable. + * - "0": libdecor is enabled only if server-side decorations are unavailable. + * - "1": libdecor is always enabled if available. + * + * libdecor is used over xdg-shell when xdg-decoration protocol is + * unavailable. */ #define SDL_HINT_VIDEO_WAYLAND_PREFER_LIBDECOR "SDL_VIDEO_WAYLAND_PREFER_LIBDECOR" /** - * \brief A variable controlling whether video mode emulation is enabled under Wayland. + * A variable controlling whether video mode emulation is enabled under + * Wayland. + * + * When this hint is set, a standard set of emulated CVT video modes will be + * exposed for use by the application. If it is disabled, the only modes + * exposed will be the logical desktop size and, in the case of a scaled + * desktop, the native display resolution. * - * When this hint is set, a standard set of emulated CVT video modes will be exposed for use by the application. - * If it is disabled, the only modes exposed will be the logical desktop size and, in the case of a scaled - * desktop, the native display resolution. + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Video mode emulation is disabled. - * "1" - Video mode emulation is enabled. + * - "0": Video mode emulation is disabled. + * - "1": Video mode emulation is enabled. * - * By default video mode emulation is enabled. + * By default video mode emulation is enabled. */ #define SDL_HINT_VIDEO_WAYLAND_MODE_EMULATION "SDL_VIDEO_WAYLAND_MODE_EMULATION" /** - * \brief Enable or disable mouse pointer warp emulation, needed by some older games. + * Enable or disable mouse pointer warp emulation, needed by some older games. + * + * When this hint is set, any SDL will emulate mouse warps using relative + * mouse mode. This is required for some older games (such as Source engine + * games), which warp the mouse to the centre of the screen rather than using + * relative mouse motion. Note that relative mouse mode may have different + * mouse acceleration behaviour than pointer warps. * - * When this hint is set, any SDL will emulate mouse warps using relative mouse mode. - * This is required for some older games (such as Source engine games), which warp the - * mouse to the centre of the screen rather than using relative mouse motion. Note that - * relative mouse mode may have different mouse acceleration behaviour than pointer warps. + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - All mouse warps fail, as mouse warping is not available under wayland. - * "1" - Some mouse warps will be emulated by forcing relative mouse mode. + * - "0": All mouse warps fail, as mouse warping is not available under + * wayland. + * - "1": Some mouse warps will be emulated by forcing relative mouse mode. * - * If not set, this is automatically enabled unless an application uses relative mouse - * mode directly. + * If not set, this is automatically enabled unless an application uses + * relative mouse mode directly. */ #define SDL_HINT_VIDEO_WAYLAND_EMULATE_MOUSE_WARP "SDL_VIDEO_WAYLAND_EMULATE_MOUSE_WARP" /** -* \brief A variable that is the address of another SDL_Window* (as a hex string formatted with "%p"). -* -* If this hint is set before SDL_CreateWindowFrom() and the SDL_Window* it is set to has -* SDL_WINDOW_OPENGL set (and running on WGL only, currently), then two things will occur on the newly -* created SDL_Window: -* -* 1. Its pixel format will be set to the same pixel format as this SDL_Window. This is -* needed for example when sharing an OpenGL context across multiple windows. -* -* 2. The flag SDL_WINDOW_OPENGL will be set on the new window so it can be used for -* OpenGL rendering. -* -* This variable can be set to the following values: -* The address (as a string "%p") of the SDL_Window* that new windows created with SDL_CreateWindowFrom() should -* share a pixel format with. -*/ + * A variable that is the address of another SDL_Window* (as a hex string + * formatted with "%p"). + * + * If this hint is set before SDL_CreateWindowFrom() and the SDL_Window* it is + * set to has SDL_WINDOW_OPENGL set (and running on WGL only, currently), then + * two things will occur on the newly created SDL_Window: + * + * 1. Its pixel format will be set to the same pixel format as this + * SDL_Window. This is needed for example when sharing an OpenGL context + * across multiple windows. + * + * 2. The flag SDL_WINDOW_OPENGL will be set on the new window so it can be + * used for OpenGL rendering. + * + * This variable can be set to the following values: The address (as a string + * "%p") of the SDL_Window* that new windows created with + * SDL_CreateWindowFrom() should share a pixel format with. + */ #define SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT "SDL_VIDEO_WINDOW_SHARE_PIXEL_FORMAT" /** - * \brief When calling SDL_CreateWindowFrom(), make the window compatible with OpenGL. + * When calling SDL_CreateWindowFrom(), make the window compatible with + * OpenGL. * * This variable can be set to the following values: - * "0" - Don't add any graphics flags to the SDL_WindowFlags - * "1" - Add SDL_WINDOW_OPENGL to the SDL_WindowFlags + * + * - "0": Don't add any graphics flags to the SDL_WindowFlags + * - "1": Add SDL_WINDOW_OPENGL to the SDL_WindowFlags * * By default SDL will not make the foreign window compatible with OpenGL. */ #define SDL_HINT_VIDEO_FOREIGN_WINDOW_OPENGL "SDL_VIDEO_FOREIGN_WINDOW_OPENGL" /** - * \brief When calling SDL_CreateWindowFrom(), make the window compatible with Vulkan. + * When calling SDL_CreateWindowFrom(), make the window compatible with + * Vulkan. * * This variable can be set to the following values: - * "0" - Don't add any graphics flags to the SDL_WindowFlags - * "1" - Add SDL_WINDOW_VULKAN to the SDL_WindowFlags + * + * - "0": Don't add any graphics flags to the SDL_WindowFlags + * - "1": Add SDL_WINDOW_VULKAN to the SDL_WindowFlags * * By default SDL will not make the foreign window compatible with Vulkan. */ #define SDL_HINT_VIDEO_FOREIGN_WINDOW_VULKAN "SDL_VIDEO_FOREIGN_WINDOW_VULKAN" /** -* \brief A variable specifying which shader compiler to preload when using the Chrome ANGLE binaries -* -* SDL has EGL and OpenGL ES2 support on Windows via the ANGLE project. It -* can use two different sets of binaries, those compiled by the user from source -* or those provided by the Chrome browser. In the later case, these binaries require -* that SDL loads a DLL providing the shader compiler. -* -* This variable can be set to the following values: -* "d3dcompiler_46.dll" - default, best for Vista or later. -* "d3dcompiler_43.dll" - for XP support. -* "none" - do not load any library, useful if you compiled ANGLE from source and included the compiler in your binaries. -* -*/ + * A variable specifying which shader compiler to preload when using the + * Chrome ANGLE binaries + * + * SDL has EGL and OpenGL ES2 support on Windows via the ANGLE project. It can + * use two different sets of binaries, those compiled by the user from source + * or those provided by the Chrome browser. In the later case, these binaries + * require that SDL loads a DLL providing the shader compiler. + * + * This variable can be set to the following values: + * + * - "d3dcompiler_46.dll: default, best for Vista or later. + * - "d3dcompiler_43.dll: for XP support. + * - "none": do not load any library, useful if you compiled ANGLE from source + * and included the compiler in your binaries. + */ #define SDL_HINT_VIDEO_WIN_D3DCOMPILER "SDL_VIDEO_WIN_D3DCOMPILER" /** - * \brief A variable controlling whether X11 should use GLX or EGL by default + * A variable controlling whether X11 should use GLX or EGL by default * * This variable can be set to the following values: - * "0" - Use GLX - * "1" - Use EGL + * + * - "0": Use GLX + * - "1": Use EGL * * By default SDL will use GLX when both are present. */ #define SDL_HINT_VIDEO_X11_FORCE_EGL "SDL_VIDEO_X11_FORCE_EGL" /** - * \brief A variable controlling whether the X11 _NET_WM_BYPASS_COMPOSITOR hint should be used. + * A variable controlling whether the X11 _NET_WM_BYPASS_COMPOSITOR hint + * should be used. * * This variable can be set to the following values: - * "0" - Disable _NET_WM_BYPASS_COMPOSITOR - * "1" - Enable _NET_WM_BYPASS_COMPOSITOR * - * By default SDL will use _NET_WM_BYPASS_COMPOSITOR + * - "0": Disable _NET_WM_BYPASS_COMPOSITOR + * - "1": Enable _NET_WM_BYPASS_COMPOSITOR * + * By default SDL will use _NET_WM_BYPASS_COMPOSITOR */ #define SDL_HINT_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR "SDL_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR" /** - * \brief A variable controlling whether the X11 _NET_WM_PING protocol should be supported. + * A variable controlling whether the X11 _NET_WM_PING protocol should be + * supported. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Disable _NET_WM_PING - * "1" - Enable _NET_WM_PING + * - "0": Disable _NET_WM_PING + * - "1": Enable _NET_WM_PING * - * By default SDL will use _NET_WM_PING, but for applications that know they - * will not always be able to respond to ping requests in a timely manner they can - * turn it off to avoid the window manager thinking the app is hung. - * The hint is checked in CreateWindow. + * By default SDL will use _NET_WM_PING, but for applications that know they + * will not always be able to respond to ping requests in a timely manner they + * can turn it off to avoid the window manager thinking the app is hung. The + * hint is checked in CreateWindow. */ #define SDL_HINT_VIDEO_X11_NET_WM_PING "SDL_VIDEO_X11_NET_WM_PING" /** - * \brief A variable forcing the visual ID chosen for new X11 windows - * + * A variable forcing the visual ID chosen for new X11 windows */ #define SDL_HINT_VIDEO_X11_WINDOW_VISUALID "SDL_VIDEO_X11_WINDOW_VISUALID" /** - * \brief A no-longer-used variable controlling whether the X11 Xinerama extension should be used. + * A no-longer-used variable controlling whether the X11 Xinerama extension + * should be used. * - * Before SDL 2.0.24, this would let apps and users disable Xinerama support on X11. - * Now SDL never uses Xinerama, and does not check for this hint at all. - * The preprocessor define is left here for source compatibility. + * Before SDL 2.0.24, this would let apps and users disable Xinerama support + * on X11. Now SDL never uses Xinerama, and does not check for this hint at + * all. The preprocessor define is left here for source compatibility. */ #define SDL_HINT_VIDEO_X11_XINERAMA "SDL_VIDEO_X11_XINERAMA" /** - * \brief A variable controlling whether the X11 XRandR extension should be used. + * A variable controlling whether the X11 XRandR extension should be used. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Disable XRandR - * "1" - Enable XRandR + * - "0": Disable XRandR + * - "1": Enable XRandR * - * By default SDL will use XRandR. + * By default SDL will use XRandR. */ #define SDL_HINT_VIDEO_X11_XRANDR "SDL_VIDEO_X11_XRANDR" /** - * \brief A no-longer-used variable controlling whether the X11 VidMode extension should be used. + * A no-longer-used variable controlling whether the X11 VidMode extension + * should be used. * - * Before SDL 2.0.24, this would let apps and users disable XVidMode support on X11. - * Now SDL never uses XVidMode, and does not check for this hint at all. - * The preprocessor define is left here for source compatibility. + * Before SDL 2.0.24, this would let apps and users disable XVidMode support + * on X11. Now SDL never uses XVidMode, and does not check for this hint at + * all. The preprocessor define is left here for source compatibility. */ #define SDL_HINT_VIDEO_X11_XVIDMODE "SDL_VIDEO_X11_XVIDMODE" /** - * \brief Controls how the fact chunk affects the loading of a WAVE file. + * Controls how the fact chunk affects the loading of a WAVE file. * - * The fact chunk stores information about the number of samples of a WAVE - * file. The Standards Update from Microsoft notes that this value can be used - * to 'determine the length of the data in seconds'. This is especially useful - * for compressed formats (for which this is a mandatory chunk) if they produce - * multiple sample frames per block and truncating the block is not allowed. - * The fact chunk can exactly specify how many sample frames there should be - * in this case. + * The fact chunk stores information about the number of samples of a WAVE + * file. The Standards Update from Microsoft notes that this value can be used + * to 'determine the length of the data in seconds'. This is especially useful + * for compressed formats (for which this is a mandatory chunk) if they + * produce multiple sample frames per block and truncating the block is not + * allowed. The fact chunk can exactly specify how many sample frames there + * should be in this case. * - * Unfortunately, most application seem to ignore the fact chunk and so SDL - * ignores it by default as well. + * Unfortunately, most application seem to ignore the fact chunk and so SDL + * ignores it by default as well. * - * This variable can be set to the following values: + * This variable can be set to the following values: * - * "truncate" - Use the number of samples to truncate the wave data if - * the fact chunk is present and valid - * "strict" - Like "truncate", but raise an error if the fact chunk - * is invalid, not present for non-PCM formats, or if the - * data chunk doesn't have that many samples - * "ignorezero" - Like "truncate", but ignore fact chunk if the number of - * samples is zero - * "ignore" - Ignore fact chunk entirely (default) + * - "truncate": Use the number of samples to truncate the wave data if the + * fact chunk is present and valid + * - "strict": Like "truncate", but raise an error if the fact chunk is + * invalid, not present for non-PCM formats, or if the data chunk doesn't + * have that many samples + * - "ignorezero": Like "truncate", but ignore fact chunk if the number of + * samples is zero + * - "ignore": Ignore fact chunk entirely (default) */ #define SDL_HINT_WAVE_FACT_CHUNK "SDL_WAVE_FACT_CHUNK" /** - * \brief Controls how the size of the RIFF chunk affects the loading of a WAVE file. + * Controls how the size of the RIFF chunk affects the loading of a WAVE file. * - * The size of the RIFF chunk (which includes all the sub-chunks of the WAVE - * file) is not always reliable. In case the size is wrong, it's possible to - * just ignore it and step through the chunks until a fixed limit is reached. + * The size of the RIFF chunk (which includes all the sub-chunks of the WAVE + * file) is not always reliable. In case the size is wrong, it's possible to + * just ignore it and step through the chunks until a fixed limit is reached. * - * Note that files that have trailing data unrelated to the WAVE file or - * corrupt files may slow down the loading process without a reliable boundary. - * By default, SDL stops after 10000 chunks to prevent wasting time. Use the - * environment variable SDL_WAVE_CHUNK_LIMIT to adjust this value. + * Note that files that have trailing data unrelated to the WAVE file or + * corrupt files may slow down the loading process without a reliable + * boundary. By default, SDL stops after 10000 chunks to prevent wasting time. + * Use the environment variable SDL_WAVE_CHUNK_LIMIT to adjust this value. * - * This variable can be set to the following values: + * This variable can be set to the following values: * - * "force" - Always use the RIFF chunk size as a boundary for the chunk search - * "ignorezero" - Like "force", but a zero size searches up to 4 GiB (default) - * "ignore" - Ignore the RIFF chunk size and always search up to 4 GiB - * "maximum" - Search for chunks until the end of file (not recommended) + * - "force": Always use the RIFF chunk size as a boundary for the chunk + * search + * - "ignorezero": Like "force", but a zero size searches up to 4 GiB + * (default) + * - "ignore": Ignore the RIFF chunk size and always search up to 4 GiB + * - "maximum": Search for chunks until the end of file (not recommended) */ #define SDL_HINT_WAVE_RIFF_CHUNK_SIZE "SDL_WAVE_RIFF_CHUNK_SIZE" /** - * \brief Controls how a truncated WAVE file is handled. + * Controls how a truncated WAVE file is handled. * - * A WAVE file is considered truncated if any of the chunks are incomplete or - * the data chunk size is not a multiple of the block size. By default, SDL - * decodes until the first incomplete block, as most applications seem to do. + * A WAVE file is considered truncated if any of the chunks are incomplete or + * the data chunk size is not a multiple of the block size. By default, SDL + * decodes until the first incomplete block, as most applications seem to do. * - * This variable can be set to the following values: + * This variable can be set to the following values: * - * "verystrict" - Raise an error if the file is truncated - * "strict" - Like "verystrict", but the size of the RIFF chunk is ignored - * "dropframe" - Decode until the first incomplete sample frame - * "dropblock" - Decode until the first incomplete block (default) + * - "verystrict": Raise an error if the file is truncated + * - "strict": Like "verystrict", but the size of the RIFF chunk is ignored + * - "dropframe": Decode until the first incomplete sample frame + * - "dropblock": Decode until the first incomplete block (default) */ #define SDL_HINT_WAVE_TRUNCATION "SDL_WAVE_TRUNCATION" /** - * \brief Tell SDL not to name threads on Windows with the 0x406D1388 Exception. - * The 0x406D1388 Exception is a trick used to inform Visual Studio of a - * thread's name, but it tends to cause problems with other debuggers, - * and the .NET runtime. Note that SDL 2.0.6 and later will still use - * the (safer) SetThreadDescription API, introduced in the Windows 10 - * Creators Update, if available. + * Tell SDL not to name threads on Windows with the 0x406D1388 Exception. + * + * The 0x406D1388 Exception is a trick used to inform Visual Studio of a + * thread's name, but it tends to cause problems with other debuggers, and the + * .NET runtime. Note that SDL 2.0.6 and later will still use the (safer) + * SetThreadDescription API, introduced in the Windows 10 Creators Update, if + * available. * * The variable can be set to the following values: - * "0" - SDL will raise the 0x406D1388 Exception to name threads. - * This is the default behavior of SDL <= 2.0.4. - * "1" - SDL will not raise this exception, and threads will be unnamed. (default) - * This is necessary with .NET languages or debuggers that aren't Visual Studio. + * + * - "0": SDL will raise the 0x406D1388 Exception to name threads. This is the + * default behavior of SDL <= 2.0.4. + * - "1": SDL will not raise this exception, and threads will be unnamed. + * (default) This is necessary with .NET languages or debuggers that aren't + * Visual Studio. */ #define SDL_HINT_WINDOWS_DISABLE_THREAD_NAMING "SDL_WINDOWS_DISABLE_THREAD_NAMING" /** - * \brief Controls whether menus can be opened with their keyboard shortcut (Alt+mnemonic). + * Controls whether menus can be opened with their keyboard shortcut + * (Alt+mnemonic). * - * If the mnemonics are enabled, then menus can be opened by pressing the Alt - * key and the corresponding mnemonic (for example, Alt+F opens the File menu). - * However, in case an invalid mnemonic is pressed, Windows makes an audible - * beep to convey that nothing happened. This is true even if the window has - * no menu at all! + * If the mnemonics are enabled, then menus can be opened by pressing the Alt + * key and the corresponding mnemonic (for example, Alt+F opens the File + * menu). However, in case an invalid mnemonic is pressed, Windows makes an + * audible beep to convey that nothing happened. This is true even if the + * window has no menu at all! * - * Because most SDL applications don't have menus, and some want to use the Alt - * key for other purposes, SDL disables mnemonics (and the beeping) by default. + * Because most SDL applications don't have menus, and some want to use the + * Alt key for other purposes, SDL disables mnemonics (and the beeping) by + * default. * - * Note: This also affects keyboard events: with mnemonics enabled, when a - * menu is opened from the keyboard, you will not receive a KEYUP event for - * the mnemonic key, and *might* not receive one for Alt. + * Note: This also affects keyboard events: with mnemonics enabled, when a + * menu is opened from the keyboard, you will not receive a KEYUP event for + * the mnemonic key, and *might* not receive one for Alt. * - * This variable can be set to the following values: - * "0" - Alt+mnemonic does nothing, no beeping. (default) - * "1" - Alt+mnemonic opens menus, invalid mnemonics produce a beep. + * This variable can be set to the following values: + * + * - "0": Alt+mnemonic does nothing, no beeping. (default) + * - "1": Alt+mnemonic opens menus, invalid mnemonics produce a beep. */ #define SDL_HINT_WINDOWS_ENABLE_MENU_MNEMONICS "SDL_WINDOWS_ENABLE_MENU_MNEMONICS" /** - * \brief A variable controlling whether the windows message loop is processed by SDL + * A variable controlling whether the windows message loop is processed by SDL * - * This variable can be set to the following values: - * "0" - The window message loop is not run - * "1" - The window message loop is processed in SDL_PumpEvents() + * This variable can be set to the following values: * - * By default SDL will process the windows message loop + * - "0": The window message loop is not run + * - "1": The window message loop is processed in SDL_PumpEvents() + * + * By default SDL will process the windows message loop */ #define SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP "SDL_WINDOWS_ENABLE_MESSAGELOOP" /** - * \brief Force SDL to use Critical Sections for mutexes on Windows. - * On Windows 7 and newer, Slim Reader/Writer Locks are available. - * They offer better performance, allocate no kernel ressources and - * use less memory. SDL will fall back to Critical Sections on older - * OS versions or if forced to by this hint. + * Force SDL to use Critical Sections for mutexes on Windows. + * + * On Windows 7 and newer, Slim Reader/Writer Locks are available. They offer + * better performance, allocate no kernel resources and use less memory. SDL + * will fall back to Critical Sections on older OS versions or if forced to by + * this hint. * - * This variable can be set to the following values: - * "0" - Use SRW Locks when available. If not, fall back to Critical Sections. (default) - * "1" - Force the use of Critical Sections in all cases. + * This variable can be set to the following values: * + * - "0": Use SRW Locks when available. If not, fall back to Critical + * Sections. (default) + * - "1": Force the use of Critical Sections in all cases. */ #define SDL_HINT_WINDOWS_FORCE_MUTEX_CRITICAL_SECTIONS "SDL_WINDOWS_FORCE_MUTEX_CRITICAL_SECTIONS" /** - * \brief Force SDL to use Kernel Semaphores on Windows. - * Kernel Semaphores are inter-process and require a context - * switch on every interaction. On Windows 8 and newer, the - * WaitOnAddress API is available. Using that and atomics to - * implement semaphores increases performance. - * SDL will fall back to Kernel Objects on older OS versions - * or if forced to by this hint. + * Force SDL to use Kernel Semaphores on Windows. * - * This variable can be set to the following values: - * "0" - Use Atomics and WaitOnAddress API when available. If not, fall back to Kernel Objects. (default) - * "1" - Force the use of Kernel Objects in all cases. + * Kernel Semaphores are inter-process and require a context switch on every + * interaction. On Windows 8 and newer, the WaitOnAddress API is available. + * Using that and atomics to implement semaphores increases performance. SDL + * will fall back to Kernel Objects on older OS versions or if forced to by + * this hint. * + * This variable can be set to the following values: + * + * - "0": Use Atomics and WaitOnAddress API when available. If not, fall back + * to Kernel Objects. (default) + * - "1": Force the use of Kernel Objects in all cases. */ #define SDL_HINT_WINDOWS_FORCE_SEMAPHORE_KERNEL "SDL_WINDOWS_FORCE_SEMAPHORE_KERNEL" /** - * \brief A variable to specify custom icon resource id from RC file on Windows platform + * A variable to specify custom icon resource id from RC file on Windows + * platform */ #define SDL_HINT_WINDOWS_INTRESOURCE_ICON "SDL_WINDOWS_INTRESOURCE_ICON" + +/** + * A variable to specify custom icon resource id from RC file on Windows + * platform + */ #define SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL "SDL_WINDOWS_INTRESOURCE_ICON_SMALL" /** - * \brief Tell SDL not to generate window-close events for Alt+F4 on Windows. + * Tell SDL not to generate window-close events for Alt+F4 on Windows. * * The variable can be set to the following values: - * "0" - SDL will generate a window-close event when it sees Alt+F4. - * "1" - SDL will only do normal key handling for Alt+F4. + * + * - "0": SDL will generate a window-close event when it sees Alt+F4. + * - "1": SDL will only do normal key handling for Alt+F4. */ #define SDL_HINT_WINDOWS_NO_CLOSE_ON_ALT_F4 "SDL_WINDOWS_NO_CLOSE_ON_ALT_F4" /** - * \brief Use the D3D9Ex API introduced in Windows Vista, instead of normal D3D9. - * Direct3D 9Ex contains changes to state management that can eliminate device - * loss errors during scenarios like Alt+Tab or UAC prompts. D3D9Ex may require - * some changes to your application to cope with the new behavior, so this - * is disabled by default. + * Use the D3D9Ex API introduced in Windows Vista, instead of normal D3D9. * - * This hint must be set before initializing the video subsystem. + * Direct3D 9Ex contains changes to state management that can eliminate device + * loss errors during scenarios like Alt+Tab or UAC prompts. D3D9Ex may + * require some changes to your application to cope with the new behavior, so + * this is disabled by default. + * + * This hint must be set before initializing the video subsystem. * - * For more information on Direct3D 9Ex, see: - * - https://docs.microsoft.com/en-us/windows/win32/direct3darticles/graphics-apis-in-windows-vista#direct3d-9ex - * - https://docs.microsoft.com/en-us/windows/win32/direct3darticles/direct3d-9ex-improvements + * For more information on Direct3D 9Ex, see: - + * https://docs.microsoft.com/en-us/windows/win32/direct3darticles/graphics-apis-in-windows-vista#direct3d-9ex + * - + * https://docs.microsoft.com/en-us/windows/win32/direct3darticles/direct3d-9ex-improvements * - * This variable can be set to the following values: - * "0" - Use the original Direct3D 9 API (default) - * "1" - Use the Direct3D 9Ex API on Vista and later (and fall back if D3D9Ex is unavailable) + * This variable can be set to the following values: * + * - "0": Use the original Direct3D 9 API (default) + * - "1": Use the Direct3D 9Ex API on Vista and later (and fall back if D3D9Ex + * is unavailable) */ #define SDL_HINT_WINDOWS_USE_D3D9EX "SDL_WINDOWS_USE_D3D9EX" /** - * \brief Controls whether SDL will declare the process to be DPI aware. + * Controls whether SDL will declare the process to be DPI aware. + * + * This hint must be set before initializing the video subsystem. * - * This hint must be set before initializing the video subsystem. + * The main purpose of declaring DPI awareness is to disable OS bitmap scaling + * of SDL windows on monitors with a DPI scale factor. * - * The main purpose of declaring DPI awareness is to disable OS bitmap scaling of SDL windows on monitors with - * a DPI scale factor. + * This hint is equivalent to requesting DPI awareness via external means + * (e.g. calling SetProcessDpiAwarenessContext) and does not cause SDL to use + * a virtualized coordinate system, so it will generally give you 1 SDL + * coordinate = 1 pixel even on high-DPI displays. * - * This hint is equivalent to requesting DPI awareness via external means (e.g. calling SetProcessDpiAwarenessContext) - * and does not cause SDL to use a virtualized coordinate system, so it will generally give you 1 SDL coordinate = 1 pixel - * even on high-DPI displays. + * For more information, see: + * https://docs.microsoft.com/en-us/windows/win32/hidpi/high-dpi-desktop-application-development-on-windows * - * For more information, see: - * https://docs.microsoft.com/en-us/windows/win32/hidpi/high-dpi-desktop-application-development-on-windows + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "" - Do not change the DPI awareness (default). - * "unaware" - Declare the process as DPI unaware. (Windows 8.1 and later). - * "system" - Request system DPI awareness. (Vista and later). - * "permonitor" - Request per-monitor DPI awareness. (Windows 8.1 and later). - * "permonitorv2" - Request per-monitor V2 DPI awareness. (Windows 10, version 1607 and later). - * The most visible difference from "permonitor" is that window title bar will be scaled - * to the visually correct size when dragging between monitors with different scale factors. - * This is the preferred DPI awareness level. + * - "": Do not change the DPI awareness (default). + * - "unaware": Declare the process as DPI unaware. (Windows 8.1 and later). + * - "system": Request system DPI awareness. (Vista and later). + * - "permonitor": Request per-monitor DPI awareness. (Windows 8.1 and later). + * - "permonitorv2": Request per-monitor V2 DPI awareness. (Windows 10, + * version 1607 and later). The most visible difference from "permonitor" is + * that window title bar will be scaled to the visually correct size when + * dragging between monitors with different scale factors. This is the + * preferred DPI awareness level. * - * If the requested DPI awareness is not available on the currently running OS, SDL will try to request the best - * available match. + * If the requested DPI awareness is not available on the currently running + * OS, SDL will try to request the best available match. */ #define SDL_HINT_WINDOWS_DPI_AWARENESS "SDL_WINDOWS_DPI_AWARENESS" /** - * \brief Uses DPI-scaled points as the SDL coordinate system on Windows. + * Uses DPI-scaled points as the SDL coordinate system on Windows. + * + * This changes the SDL coordinate system units to be DPI-scaled points, + * rather than pixels everywhere. This means windows will be appropriately + * sized, even when created on high-DPI displays with scaling. * - * This changes the SDL coordinate system units to be DPI-scaled points, rather than pixels everywhere. - * This means windows will be appropriately sized, even when created on high-DPI displays with scaling. + * e.g. requesting a 640x480 window from SDL, on a display with 125% scaling + * in Windows display settings, will create a window with an 800x600 client + * area (in pixels). * - * e.g. requesting a 640x480 window from SDL, on a display with 125% scaling in Windows display settings, - * will create a window with an 800x600 client area (in pixels). + * Setting this to "1" implicitly requests process DPI awareness (setting + * SDL_WINDOWS_DPI_AWARENESS is unnecessary), and forces + * SDL_WINDOW_ALLOW_HIGHDPI on all windows. * - * Setting this to "1" implicitly requests process DPI awareness (setting SDL_WINDOWS_DPI_AWARENESS is unnecessary), - * and forces SDL_WINDOW_ALLOW_HIGHDPI on all windows. + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - SDL coordinates equal Windows coordinates. No automatic window resizing when dragging - * between monitors with different scale factors (unless this is performed by - * Windows itself, which is the case when the process is DPI unaware). - * "1" - SDL coordinates are in DPI-scaled points. Automatically resize windows as needed on - * displays with non-100% scale factors. + * - "0": SDL coordinates equal Windows coordinates. No automatic window + * resizing when dragging between monitors with different scale factors + * (unless this is performed by Windows itself, which is the case when the + * process is DPI unaware). + * - "1": SDL coordinates are in DPI-scaled points. Automatically resize + * windows as needed on displays with non-100% scale factors. */ #define SDL_HINT_WINDOWS_DPI_SCALING "SDL_WINDOWS_DPI_SCALING" /** - * \brief A variable controlling whether the window frame and title bar are interactive when the cursor is hidden + * A variable controlling whether the window frame and title bar are + * interactive when the cursor is hidden * - * This variable can be set to the following values: - * "0" - The window frame is not interactive when the cursor is hidden (no move, resize, etc) - * "1" - The window frame is interactive when the cursor is hidden + * This variable can be set to the following values: + * + * - "0": The window frame is not interactive when the cursor is hidden (no + * move, resize, etc) + * - "1": The window frame is interactive when the cursor is hidden * - * By default SDL will allow interaction with the window frame when the cursor is hidden + * By default SDL will allow interaction with the window frame when the cursor + * is hidden */ #define SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN "SDL_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN" /** -* \brief A variable controlling whether the window is activated when the SDL_ShowWindow function is called -* -* This variable can be set to the following values: -* "0" - The window is activated when the SDL_ShowWindow function is called -* "1" - The window is not activated when the SDL_ShowWindow function is called -* -* By default SDL will activate the window when the SDL_ShowWindow function is called -*/ + * A variable controlling whether the window is activated when the + * SDL_ShowWindow function is called + * + * This variable can be set to the following values: + * + * - "0": The window is activated when the SDL_ShowWindow function is called + * - "1": The window is not activated when the SDL_ShowWindow function is + * called + * + * By default SDL will activate the window when the SDL_ShowWindow function is + * called + */ #define SDL_HINT_WINDOW_NO_ACTIVATION_WHEN_SHOWN "SDL_WINDOW_NO_ACTIVATION_WHEN_SHOWN" -/** \brief Allows back-button-press events on Windows Phone to be marked as handled +/** Allows back-button-press events on Windows Phone to be marked as handled * * Windows Phone devices typically feature a Back button. When pressed, * the OS will emit back-button-press events, which apps are expected to @@ -2459,11 +2838,12 @@ extern "C" { * * More details on back button behavior in Windows Phone apps can be found * at the following page, on Microsoft's developer site: + * * http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj247550(v=vs.105).aspx */ #define SDL_HINT_WINRT_HANDLE_BACK_BUTTON "SDL_WINRT_HANDLE_BACK_BUTTON" -/** \brief Label text for a WinRT app's privacy policy link +/** Label text for a WinRT app's privacy policy link * * Network-enabled WinRT apps must include a privacy policy. On Windows 8, 8.1, and RT, * Microsoft mandates that this policy be available via the Windows Settings charm. @@ -2485,213 +2865,221 @@ extern "C" { #define SDL_HINT_WINRT_PRIVACY_POLICY_LABEL "SDL_WINRT_PRIVACY_POLICY_LABEL" /** - * \brief A URL to a WinRT app's privacy policy + * A URL to a WinRT app's privacy policy * - * All network-enabled WinRT apps must make a privacy policy available to its - * users. On Windows 8, 8.1, and RT, Microsoft mandates that this policy be - * be available in the Windows Settings charm, as accessed from within the app. - * SDL provides code to add a URL-based link there, which can point to the app's - * privacy policy. + * All network-enabled WinRT apps must make a privacy policy available to its + * users. On Windows 8, 8.1, and RT, Microsoft mandates that this policy be be + * available in the Windows Settings charm, as accessed from within the app. + * SDL provides code to add a URL-based link there, which can point to the + * app's privacy policy. * - * To setup a URL to an app's privacy policy, set SDL_HINT_WINRT_PRIVACY_POLICY_URL - * before calling any SDL_Init() functions. The contents of the hint should - * be a valid URL. For example, "http://www.example.com". + * To setup a URL to an app's privacy policy, set + * SDL_HINT_WINRT_PRIVACY_POLICY_URL before calling any SDL_Init() functions. + * The contents of the hint should be a valid URL. For example, + * "http://www.example.com". * - * The default value is "", which will prevent SDL from adding a privacy policy - * link to the Settings charm. This hint should only be set during app init. + * The default value is "", which will prevent SDL from adding a privacy + * policy link to the Settings charm. This hint should only be set during app + * init. * - * The label text of an app's "Privacy Policy" link may be customized via another - * hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL. + * The label text of an app's "Privacy Policy" link may be customized via + * another hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL. * - * Please note that on Windows Phone, Microsoft does not provide standard UI - * for displaying a privacy policy link, and as such, SDL_HINT_WINRT_PRIVACY_POLICY_URL - * will not get used on that platform. Network-enabled phone apps should display - * their privacy policy through some other, in-app means. + * Please note that on Windows Phone, Microsoft does not provide standard UI + * for displaying a privacy policy link, and as such, + * SDL_HINT_WINRT_PRIVACY_POLICY_URL will not get used on that platform. + * Network-enabled phone apps should display their privacy policy through some + * other, in-app means. */ #define SDL_HINT_WINRT_PRIVACY_POLICY_URL "SDL_WINRT_PRIVACY_POLICY_URL" /** - * \brief Mark X11 windows as override-redirect. + * Mark X11 windows as override-redirect. * - * If set, this _might_ increase framerate at the expense of the desktop - * not working as expected. Override-redirect windows aren't noticed by the - * window manager at all. + * If set, this _might_ increase framerate at the expense of the desktop not + * working as expected. Override-redirect windows aren't noticed by the window + * manager at all. * - * You should probably only use this for fullscreen windows, and you probably - * shouldn't even use it for that. But it's here if you want to try! + * You should probably only use this for fullscreen windows, and you probably + * shouldn't even use it for that. But it's here if you want to try! */ #define SDL_HINT_X11_FORCE_OVERRIDE_REDIRECT "SDL_X11_FORCE_OVERRIDE_REDIRECT" /** - * \brief A variable that lets you disable the detection and use of Xinput gamepad devices + * A variable that lets you disable the detection and use of Xinput gamepad + * devices + * + * The variable can be set to the following values: * - * The variable can be set to the following values: - * "0" - Disable XInput detection (only uses direct input) - * "1" - Enable XInput detection (the default) + * - "0": Disable XInput detection (only uses direct input) + * - "1": Enable XInput detection (the default) */ #define SDL_HINT_XINPUT_ENABLED "SDL_XINPUT_ENABLED" - /** - * \brief A variable that lets you disable the detection and use of DirectInput gamepad devices - * - * The variable can be set to the following values: - * "0" - Disable DirectInput detection (only uses XInput) - * "1" - Enable DirectInput detection (the default) - */ +/** + * A variable that lets you disable the detection and use of DirectInput + * gamepad devices + * + * The variable can be set to the following values: + * + * - "0": Disable DirectInput detection (only uses XInput) + * - "1": Enable DirectInput detection (the default) + */ #define SDL_HINT_DIRECTINPUT_ENABLED "SDL_DIRECTINPUT_ENABLED" /** - * \brief A variable that causes SDL to use the old axis and button mapping for XInput devices. + * A variable that causes SDL to use the old axis and button mapping for + * XInput devices. * - * This hint is for backwards compatibility only and will be removed in SDL 2.1 + * This hint is for backwards compatibility only and will be removed in SDL + * 2.1 * - * The default value is "0". This hint must be set before SDL_Init() + * The default value is "0". This hint must be set before SDL_Init() */ #define SDL_HINT_XINPUT_USE_OLD_JOYSTICK_MAPPING "SDL_XINPUT_USE_OLD_JOYSTICK_MAPPING" /** - * \brief A variable that causes SDL to not ignore audio "monitors" + * A variable that causes SDL to not ignore audio "monitors" * - * This is currently only used for PulseAudio and ignored elsewhere. + * This is currently only used for PulseAudio and ignored elsewhere. * - * By default, SDL ignores audio devices that aren't associated with physical - * hardware. Changing this hint to "1" will expose anything SDL sees that - * appears to be an audio source or sink. This will add "devices" to the list - * that the user probably doesn't want or need, but it can be useful in - * scenarios where you want to hook up SDL to some sort of virtual device, - * etc. + * By default, SDL ignores audio devices that aren't associated with physical + * hardware. Changing this hint to "1" will expose anything SDL sees that + * appears to be an audio source or sink. This will add "devices" to the list + * that the user probably doesn't want or need, but it can be useful in + * scenarios where you want to hook up SDL to some sort of virtual device, + * etc. * - * The default value is "0". This hint must be set before SDL_Init(). + * The default value is "0". This hint must be set before SDL_Init(). * - * This hint is available since SDL 2.0.16. Before then, virtual devices are - * always ignored. + * This hint is available since SDL 2.0.16. Before then, virtual devices are + * always ignored. */ #define SDL_HINT_AUDIO_INCLUDE_MONITORS "SDL_AUDIO_INCLUDE_MONITORS" /** - * \brief A variable that forces X11 windows to create as a custom type. + * A variable that forces X11 windows to create as a custom type. * - * This is currently only used for X11 and ignored elsewhere. + * This is currently only used for X11 and ignored elsewhere. * - * During SDL_CreateWindow, SDL uses the _NET_WM_WINDOW_TYPE X11 property - * to report to the window manager the type of window it wants to create. - * This might be set to various things if SDL_WINDOW_TOOLTIP or - * SDL_WINDOW_POPUP_MENU, etc, were specified. For "normal" windows that - * haven't set a specific type, this hint can be used to specify a custom - * type. For example, a dock window might set this to - * "_NET_WM_WINDOW_TYPE_DOCK". + * During SDL_CreateWindow, SDL uses the _NET_WM_WINDOW_TYPE X11 property to + * report to the window manager the type of window it wants to create. This + * might be set to various things if SDL_WINDOW_TOOLTIP or + * SDL_WINDOW_POPUP_MENU, etc, were specified. For "normal" windows that + * haven't set a specific type, this hint can be used to specify a custom + * type. For example, a dock window might set this to + * "_NET_WM_WINDOW_TYPE_DOCK". * - * If not set or set to "", this hint is ignored. This hint must be set - * before the SDL_CreateWindow() call that it is intended to affect. + * If not set or set to "", this hint is ignored. This hint must be set before + * the SDL_CreateWindow() call that it is intended to affect. * - * This hint is available since SDL 2.0.22. + * This hint is available since SDL 2.0.22. */ #define SDL_HINT_X11_WINDOW_TYPE "SDL_X11_WINDOW_TYPE" /** - * \brief A variable that decides whether to send SDL_QUIT when closing the final window. + * A variable that decides whether to send SDL_QUIT when closing the final + * window. * - * By default, SDL sends an SDL_QUIT event when there is only one window - * and it receives an SDL_WINDOWEVENT_CLOSE event, under the assumption most - * apps would also take the loss of this window as a signal to terminate the - * program. + * By default, SDL sends an SDL_QUIT event when there is only one window and + * it receives an SDL_WINDOWEVENT_CLOSE event, under the assumption most apps + * would also take the loss of this window as a signal to terminate the + * program. * - * However, it's not unreasonable in some cases to have the program continue - * to live on, perhaps to create new windows later. + * However, it's not unreasonable in some cases to have the program continue + * to live on, perhaps to create new windows later. * - * Changing this hint to "0" will cause SDL to not send an SDL_QUIT event - * when the final window is requesting to close. Note that in this case, - * there are still other legitimate reasons one might get an SDL_QUIT - * event: choosing "Quit" from the macOS menu bar, sending a SIGINT (ctrl-c) - * on Unix, etc. + * Changing this hint to "0" will cause SDL to not send an SDL_QUIT event when + * the final window is requesting to close. Note that in this case, there are + * still other legitimate reasons one might get an SDL_QUIT event: choosing + * "Quit" from the macOS menu bar, sending a SIGINT (ctrl-c) on Unix, etc. * - * The default value is "1". This hint can be changed at any time. + * The default value is "1". This hint can be changed at any time. * - * This hint is available since SDL 2.0.22. Before then, you always get - * an SDL_QUIT event when closing the final window. + * This hint is available since SDL 2.0.22. Before then, you always get an + * SDL_QUIT event when closing the final window. */ #define SDL_HINT_QUIT_ON_LAST_WINDOW_CLOSE "SDL_QUIT_ON_LAST_WINDOW_CLOSE" /** - * \brief A variable that decides what video backend to use. + * A variable that decides what video backend to use. * - * By default, SDL will try all available video backends in a reasonable - * order until it finds one that can work, but this hint allows the app - * or user to force a specific target, such as "x11" if, say, you are - * on Wayland but want to try talking to the X server instead. + * By default, SDL will try all available video backends in a reasonable order + * until it finds one that can work, but this hint allows the app or user to + * force a specific target, such as "x11" if, say, you are on Wayland but want + * to try talking to the X server instead. * - * This functionality has existed since SDL 2.0.0 (indeed, before that) - * but before 2.0.22 this was an environment variable only. In 2.0.22, - * it was upgraded to a full SDL hint, so you can set the environment - * variable as usual or programatically set the hint with SDL_SetHint, - * which won't propagate to child processes. + * This functionality has existed since SDL 2.0.0 (indeed, before that) but + * before 2.0.22 this was an environment variable only. In 2.0.22, it was + * upgraded to a full SDL hint, so you can set the environment variable as + * usual or programatically set the hint with SDL_SetHint, which won't + * propagate to child processes. * - * The default value is unset, in which case SDL will try to figure out - * the best video backend on your behalf. This hint needs to be set - * before SDL_Init() is called to be useful. + * The default value is unset, in which case SDL will try to figure out the + * best video backend on your behalf. This hint needs to be set before + * SDL_Init() is called to be useful. * - * This hint is available since SDL 2.0.22. Before then, you could set - * the environment variable to get the same effect. + * This hint is available since SDL 2.0.22. Before then, you could set the + * environment variable to get the same effect. */ #define SDL_HINT_VIDEODRIVER "SDL_VIDEODRIVER" /** - * \brief A variable that decides what audio backend to use. + * A variable that decides what audio backend to use. * - * By default, SDL will try all available audio backends in a reasonable - * order until it finds one that can work, but this hint allows the app - * or user to force a specific target, such as "alsa" if, say, you are - * on PulseAudio but want to try talking to the lower level instead. + * By default, SDL will try all available audio backends in a reasonable order + * until it finds one that can work, but this hint allows the app or user to + * force a specific target, such as "alsa" if, say, you are on PulseAudio but + * want to try talking to the lower level instead. * - * This functionality has existed since SDL 2.0.0 (indeed, before that) - * but before 2.0.22 this was an environment variable only. In 2.0.22, - * it was upgraded to a full SDL hint, so you can set the environment - * variable as usual or programatically set the hint with SDL_SetHint, - * which won't propagate to child processes. + * This functionality has existed since SDL 2.0.0 (indeed, before that) but + * before 2.0.22 this was an environment variable only. In 2.0.22, it was + * upgraded to a full SDL hint, so you can set the environment variable as + * usual or programatically set the hint with SDL_SetHint, which won't + * propagate to child processes. * - * The default value is unset, in which case SDL will try to figure out - * the best audio backend on your behalf. This hint needs to be set - * before SDL_Init() is called to be useful. + * The default value is unset, in which case SDL will try to figure out the + * best audio backend on your behalf. This hint needs to be set before + * SDL_Init() is called to be useful. * - * This hint is available since SDL 2.0.22. Before then, you could set - * the environment variable to get the same effect. + * This hint is available since SDL 2.0.22. Before then, you could set the + * environment variable to get the same effect. */ #define SDL_HINT_AUDIODRIVER "SDL_AUDIODRIVER" /** - * \brief A variable that decides what KMSDRM device to use. + * A variable that decides what KMSDRM device to use. * - * Internally, SDL might open something like "/dev/dri/cardNN" to - * access KMSDRM functionality, where "NN" is a device index number. + * Internally, SDL might open something like "/dev/dri/cardNN" to access + * KMSDRM functionality, where "NN" is a device index number. * - * SDL makes a guess at the best index to use (usually zero), but the - * app or user can set this hint to a number between 0 and 99 to - * force selection. + * SDL makes a guess at the best index to use (usually zero), but the app or + * user can set this hint to a number between 0 and 99 to force selection. * - * This hint is available since SDL 2.24.0. + * This hint is available since SDL 2.24.0. */ #define SDL_HINT_KMSDRM_DEVICE_INDEX "SDL_KMSDRM_DEVICE_INDEX" /** - * \brief A variable that treats trackpads as touch devices. + * A variable that treats trackpads as touch devices. * - * On macOS (and possibly other platforms in the future), SDL will report - * touches on a trackpad as mouse input, which is generally what users - * expect from this device; however, these are often actually full - * multitouch-capable touch devices, so it might be preferable to some apps - * to treat them as such. + * On macOS (and possibly other platforms in the future), SDL will report + * touches on a trackpad as mouse input, which is generally what users expect + * from this device; however, these are often actually full multitouch-capable + * touch devices, so it might be preferable to some apps to treat them as + * such. * - * Setting this hint to true will make the trackpad input report as a - * multitouch device instead of a mouse. The default is false. + * Setting this hint to true will make the trackpad input report as a + * multitouch device instead of a mouse. The default is false. * - * Note that most platforms don't support this hint. As of 2.24.0, it - * only supports MacBooks' trackpads on macOS. Others may follow later. + * Note that most platforms don't support this hint. As of 2.24.0, it only + * supports MacBooks' trackpads on macOS. Others may follow later. * - * This hint is checked during SDL_Init and can not be changed after. + * This hint is checked during SDL_Init and can not be changed after. * - * This hint is available since SDL 2.24.0. + * This hint is available since SDL 2.24.0. */ #define SDL_HINT_TRACKPAD_IS_TOUCH_ONLY "SDL_TRACKPAD_IS_TOUCH_ONLY" @@ -2699,23 +3087,45 @@ extern "C" { * Cause SDL to call dbus_shutdown() on quit. * * This is useful as a debug tool to validate memory leaks, but shouldn't ever - * be set in production applications, as other libraries used by the application - * might use dbus under the hood and this cause cause crashes if they continue - * after SDL_Quit(). + * be set in production applications, as other libraries used by the + * application might use dbus under the hood and this cause cause crashes if + * they continue after SDL_Quit(). * * This variable can be set to the following values: - * "0" - SDL will not call dbus_shutdown() on quit (default) - * "1" - SDL will call dbus_shutdown() on quit + * + * - "0": SDL will not call dbus_shutdown() on quit (default) + * - "1": SDL will call dbus_shutdown() on quit * * This hint is available since SDL 2.30.0. */ #define SDL_HINT_SHUTDOWN_DBUS_ON_QUIT "SDL_SHUTDOWN_DBUS_ON_QUIT" +/** + * Specify if SDL_RWFromFile should use the resource dir on Apple platforms. + * + * SDL2 has always done this on Apple platforms, but it can be surprising to + * try opening a path to discover that SDL adjusts the path to elsewhere, so + * this hint allows that behavior to be disabled. + * + * If running from a App Bundle, this will be MyApp.app/Contents/Resources. If + * running as a normal Unix-like process, this will be the directory where the + * running binary lives. Setting this hint to 0 avoids this and just uses the + * requested path as-is. + * + * This variable can be set to the following values: + * + * - "0": SDL will not use the app resource directory. + * - "1": SDL will use the app's resource directory (default). + * + * This hint is available since SDL 2.32.0. + */ +#define SDL_HINT_APPLE_RWFROMFILE_USE_RESOURCES "SDL_APPLE_RWFROMFILE_USE_RESOURCES" + /** - * \brief An enumeration of hint priorities + * An enumeration of hint priorities */ -typedef enum +typedef enum SDL_HintPriority { SDL_HINT_DEFAULT, SDL_HINT_NORMAL, @@ -2730,9 +3140,9 @@ typedef enum * value. Hints will replace existing hints of their priority and lower. * Environment variables are considered to have override priority. * - * \param name the hint to set - * \param value the value of the hint variable - * \param priority the SDL_HintPriority level for the hint + * \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. * * \since This function is available since SDL 2.0.0. @@ -2751,8 +3161,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name, * 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 + * \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. * * \since This function is available since SDL 2.0.0. @@ -2770,7 +3180,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name, * the environment isn't set. Callbacks will be called normally with this * change. * - * \param name the hint to set + * \param name the hint to set. * \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise. * * \since This function is available since SDL 2.24.0. @@ -2798,7 +3208,7 @@ extern DECLSPEC void SDLCALL SDL_ResetHints(void); /** * Get the value of a hint. * - * \param name the hint to query + * \param name the hint to query. * \returns the string value of a hint or NULL if the hint isn't set. * * \since This function is available since SDL 2.0.0. @@ -2811,8 +3221,8 @@ extern DECLSPEC const char * SDLCALL SDL_GetHint(const char *name); /** * Get 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 + * \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. * @@ -2826,20 +3236,20 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bool d /** * 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 + * \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); /** * Add a function to watch a particular hint. * - * \param name the hint to watch + * \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 + * hint value changes. + * \param userdata a pointer to pass to the callback function. * * \since This function is available since SDL 2.0.0. * @@ -2852,10 +3262,10 @@ extern DECLSPEC void SDLCALL SDL_AddHintCallback(const char *name, /** * Remove a function watching a particular hint. * - * \param name the hint being watched + * \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 + * hint value changes. + * \param userdata a pointer being passed to the callback function. * * \since This function is available since SDL 2.0.0. * diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_joystick.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_joystick.h @@ -20,22 +20,26 @@ */ /** - * \file SDL_joystick.h + * # CategoryJoystick * - * Include file for SDL joystick event handling + * Include file for SDL joystick event handling * - * The term "device_index" identifies currently plugged in joystick devices between 0 and SDL_NumJoysticks(), with the exact joystick - * behind a device_index changing as joysticks are plugged and unplugged. + * The term "device_index" identifies currently plugged in joystick devices + * between 0 and SDL_NumJoysticks(), with the exact joystick behind a + * device_index changing as joysticks are plugged and unplugged. * - * 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 "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. + * 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. + * 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_ @@ -56,7 +60,7 @@ extern "C" { * \file SDL_joystick.h * * In order to use these functions, SDL_Init() must have been called - * with the ::SDL_INIT_JOYSTICK flag. This causes SDL to scan the system + * with the SDL_INIT_JOYSTICK flag. This causes SDL to scan the system * for joysticks, and load appropriate drivers. * * If you would like to receive joystick updates while the application @@ -73,15 +77,21 @@ extern SDL_mutex *SDL_joystick_lock; struct _SDL_Joystick; typedef struct _SDL_Joystick SDL_Joystick; -/* A structure that encodes the stable unique id for a joystick device */ +/** + * A structure that encodes the stable unique id for a joystick device. + * + * This is just a standard SDL_GUID by a different name. + */ typedef SDL_GUID SDL_JoystickGUID; /** - * This is a unique ID for a joystick for the time it is connected to the system, - * and is never reused for the lifetime of the application. If the joystick is - * disconnected and reconnected, it will get a new ID. + * This is a unique ID for a joystick for the time it is connected to the + * system, and is never reused for the lifetime of the application. + * + * If the joystick is disconnected and reconnected, it will get a new ID. * - * The ID value starts at 0 and increments from there. The value -1 is an invalid ID. + * The ID value starts at 0 and increments from there. The value -1 is an + * invalid ID. */ typedef Sint32 SDL_JoystickID; @@ -172,7 +182,7 @@ extern DECLSPEC int SDLCALL SDL_NumJoysticks(void); * 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) + * 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. * @@ -189,7 +199,7 @@ extern DECLSPEC const char *SDLCALL SDL_JoystickNameForIndex(int device_index); * 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) + * on the system). * \returns the path of the selected joystick. If no path can be found, this * function returns NULL; call SDL_GetError() for more information. * @@ -215,9 +225,9 @@ extern DECLSPEC int SDLCALL SDL_JoystickGetDevicePlayerIndex(int 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 + * on the system. * \returns the GUID of the selected joystick. If called on an invalid index, - * this function returns a zero GUID + * this function returns a zero GUID. * * \since This function is available since SDL 2.0.0. * @@ -233,9 +243,9 @@ extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetDeviceGUID(int device_in * available this function returns 0. * * \param device_index the index of the joystick to query (the N'th joystick - * on the system + * on the system. * \returns the USB vendor ID of the selected joystick. If called on an - * invalid index, this function returns zero + * invalid index, this function returns zero. * * \since This function is available since SDL 2.0.6. */ @@ -248,9 +258,9 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceVendor(int device_index); * available this function returns 0. * * \param device_index the index of the joystick to query (the N'th joystick - * on the system + * on the system. * \returns the USB product ID of the selected joystick. If called on an - * invalid index, this function returns zero + * invalid index, this function returns zero. * * \since This function is available since SDL 2.0.6. */ @@ -263,9 +273,9 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProduct(int device_index); * isn't available this function returns 0. * * \param device_index the index of the joystick to query (the N'th joystick - * on the system + * on the system. * \returns the product version of the selected joystick. If called on an - * invalid index, this function returns zero + * invalid index, this function returns zero. * * \since This function is available since SDL 2.0.6. */ @@ -277,9 +287,9 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProductVersion(int device_in * 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 + * on the system. * \returns the SDL_JoystickType of the selected joystick. If called on an - * invalid index, this function returns `SDL_JOYSTICK_TYPE_UNKNOWN` + * invalid index, this function returns `SDL_JOYSTICK_TYPE_UNKNOWN`. * * \since This function is available since SDL 2.0.6. */ @@ -291,7 +301,7 @@ extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetDeviceType(int device_in * 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 + * on the system. * \returns the instance id of the selected joystick. If called on an invalid * index, this function returns -1. * @@ -310,7 +320,7 @@ extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickGetDeviceInstanceID(int devic * The joystick subsystem must be initialized before a joystick can be opened * for use. * - * \param device_index the index of the joystick to query + * \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. * @@ -324,7 +334,7 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickOpen(int device_index); /** * Get the SDL_Joystick associated with an instance id. * - * \param instance_id the instance id to get the SDL_Joystick for + * \param instance_id 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. * @@ -335,7 +345,7 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickFromInstanceID(SDL_JoystickID /** * Get the SDL_Joystick associated with a player index. * - * \param player_index the player index to get the SDL_Joystick for + * \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. * @@ -358,8 +368,10 @@ extern DECLSPEC int SDLCALL SDL_JoystickAttachVirtual(SDL_JoystickType type, /** * The structure that defines an extended virtual joystick description * - * The caller must zero the structure and then initialize the version with `SDL_VIRTUAL_JOYSTICK_DESC_VERSION` before passing it to SDL_JoystickAttachVirtualEx() - * All other elements of this structure are optional and can be left 0. + * The caller must zero the structure and then initialize the version with + * `SDL_VIRTUAL_JOYSTICK_DESC_VERSION` before passing it to + * SDL_JoystickAttachVirtualEx() All other elements of this structure are + * optional and can be left 0. * * \sa SDL_JoystickAttachVirtualEx */ @@ -390,7 +402,7 @@ typedef struct SDL_VirtualJoystickDesc } SDL_VirtualJoystickDesc; /** - * \brief The current version of the SDL_VirtualJoystickDesc structure + * The current version of the SDL_VirtualJoystickDesc structure */ #define SDL_VIRTUAL_JOYSTICK_DESC_VERSION 1 @@ -407,7 +419,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickAttachVirtualEx(const SDL_VirtualJoystic * Detach a virtual joystick. * * \param device_index a value previously returned from - * SDL_JoystickAttachVirtual() + * SDL_JoystickAttachVirtual(). * \returns 0 on success, or -1 if an error occurred. * * \since This function is available since SDL 2.0.14. @@ -485,7 +497,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualHat(SDL_Joystick *joystick, in /** * Get the implementation dependent name of a joystick. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \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. * @@ -499,7 +511,7 @@ extern DECLSPEC const char *SDLCALL SDL_JoystickName(SDL_Joystick *joystick); /** * Get the implementation dependent path of a joystick. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the path of the selected joystick. If no path can be found, this * function returns NULL; call SDL_GetError() for more information. * @@ -515,7 +527,7 @@ extern DECLSPEC const char *SDLCALL SDL_JoystickPath(SDL_Joystick *joystick); * 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() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the player index, or -1 if it's not available. * * \since This function is available since SDL 2.0.9. @@ -525,7 +537,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickGetPlayerIndex(SDL_Joystick *joystick); /** * Set the player index of an opened joystick. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \param player_index Player index to assign to this joystick, or -1 to clear * the player index and turn off player LEDs. * @@ -538,7 +550,7 @@ extern DECLSPEC void SDLCALL SDL_JoystickSetPlayerIndex(SDL_Joystick *joystick, * * This function requires an open joystick. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \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. @@ -555,7 +567,7 @@ extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetGUID(SDL_Joystick *joyst * * If the vendor ID isn't available this function returns 0. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the USB vendor ID of the selected joystick, or 0 if unavailable. * * \since This function is available since SDL 2.0.6. @@ -567,7 +579,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetVendor(SDL_Joystick *joystick); * * If the product ID isn't available this function returns 0. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the USB product ID of the selected joystick, or 0 if unavailable. * * \since This function is available since SDL 2.0.6. @@ -579,7 +591,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProduct(SDL_Joystick *joystick); * * If the product version isn't available this function returns 0. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the product version of the selected joystick, or 0 if unavailable. * * \since This function is available since SDL 2.0.6. @@ -591,7 +603,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProductVersion(SDL_Joystick *joyst * * If the firmware version isn't available this function returns 0. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the firmware version of the selected joystick, or 0 if * unavailable. * @@ -604,7 +616,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetFirmwareVersion(SDL_Joystick *joys * * Returns the serial number of the joystick, or NULL if it is not available. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the serial number of the selected joystick, or NULL if * unavailable. * @@ -615,7 +627,7 @@ extern DECLSPEC const char * SDLCALL SDL_JoystickGetSerial(SDL_Joystick *joystic /** * Get the type of an opened joystick. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the SDL_JoystickType of the selected joystick. * * \since This function is available since SDL 2.0.6. @@ -627,9 +639,9 @@ extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetType(SDL_Joystick *joyst * * 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 + * \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. * * \since This function is available since SDL 2.0.0. * @@ -646,7 +658,7 @@ extern DECLSPEC void SDLCALL SDL_JoystickGetGUIDString(SDL_JoystickGUID guid, ch * 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 + * \param pchGUID string containing an ASCII representation of a GUID. * \returns a SDL_JoystickGUID structure. * * \since This function is available since SDL 2.0.0. @@ -658,15 +670,15 @@ extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetGUIDFromString(const cha /** * Get the device information encoded in a SDL_JoystickGUID structure * - * \param guid the SDL_JoystickGUID you wish to get info about + * \param guid the SDL_JoystickGUID you wish to get info about. * \param vendor A pointer filled in with the device VID, or 0 if not - * available + * available. * \param product A pointer filled in with the device PID, or 0 if not - * available + * available. * \param version A pointer filled in with the device version, or 0 if not - * available + * available. * \param crc16 A pointer filled in with a CRC used to distinguish different - * products with the same VID/PID, or 0 if not available + * products with the same VID/PID, or 0 if not available. * * \since This function is available since SDL 2.26.0. * @@ -677,7 +689,7 @@ extern DECLSPEC void SDLCALL SDL_GetJoystickGUIDInfo(SDL_JoystickGUID guid, Uint /** * Get the status of a specified joystick. * - * \param joystick the joystick to query + * \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. * @@ -691,7 +703,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAttached(SDL_Joystick *joystick) /** * Get the instance ID of an opened joystick. * - * \param joystick an SDL_Joystick structure containing joystick information + * \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. * @@ -708,7 +720,7 @@ extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickInstanceID(SDL_Joystick *joys * 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 + * \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. @@ -728,7 +740,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickNumAxes(SDL_Joystick *joystick); * * Most joysticks do not have trackballs. * - * \param joystick an SDL_Joystick structure containing joystick information + * \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. * @@ -741,7 +753,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(SDL_Joystick *joystick); /** * Get the number of POV hats on a joystick. * - * \param joystick an SDL_Joystick structure containing joystick information + * \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. * @@ -755,7 +767,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickNumHats(SDL_Joystick *joystick); /** * Get the number of buttons on a joystick. * - * \param joystick an SDL_Joystick structure containing joystick information + * \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. * @@ -794,10 +806,10 @@ extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void); * `SDL_ENABLE`, this function accepts any value, with any non-zero value that * isn't `SDL_QUERY` being treated as `SDL_ENABLE`. * - * If SDL was built with events disabled (extremely uncommon!), this will - * do nothing and always return `SDL_IGNORE`. + * If SDL was built with events disabled (extremely uncommon!), this will do + * nothing and always return `SDL_IGNORE`. * - * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE` + * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`. * \returns If `state` is `SDL_QUERY` then the current state is returned, * otherwise `state` is returned (even if it was not one of the * allowed values). @@ -808,6 +820,7 @@ extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void); */ extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state); +/* Limits for joystick axes... */ #define SDL_JOYSTICK_AXIS_MAX 32767 #define SDL_JOYSTICK_AXIS_MIN -32768 @@ -824,8 +837,8 @@ extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state); * 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 + * \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. * @@ -843,8 +856,8 @@ extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick *joystick, * * The axis indices start at index 0. * - * \param joystick an SDL_Joystick structure containing joystick information - * \param axis the axis to query; the axis indices start at index 0 + * \param 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. * @@ -883,8 +896,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAxisInitialState(SDL_Joystick *j * - `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; indices start at index 0 + * \param joystick an SDL_Joystick structure containing joystick information. + * \param hat the hat index to get the state from; indices start at index 0. * \returns the current hat position. * * \since This function is available since SDL 2.0.0. @@ -902,10 +915,10 @@ extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick *joystick, * * 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 + * \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. * @@ -919,9 +932,9 @@ extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick *joystick, /** * Get the current state of a button on a joystick. * - * \param joystick an SDL_Joystick structure containing joystick information + * \param joystick an SDL_Joystick structure containing joystick information. * \param button the button index to get the state from; indices start at - * index 0 + * index 0. * \returns 1 if the specified button is pressed, 0 otherwise. * * \since This function is available since SDL 2.0.0. @@ -937,13 +950,13 @@ extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick *joystick, * Each call to this function cancels any previous rumble effect, and calling * it with 0 intensity stops any rumbling. * - * \param joystick The joystick to vibrate + * \param joystick The joystick to vibrate. * \param low_frequency_rumble The intensity of the low frequency (left) - * rumble motor, from 0 to 0xFFFF + * 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 + * 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. * * \since This function is available since SDL 2.0.9. * @@ -962,13 +975,13 @@ extern DECLSPEC int SDLCALL SDL_JoystickRumble(SDL_Joystick *joystick, Uint16 lo * want the (more common) whole-controller rumble, use SDL_JoystickRumble() * instead. * - * \param joystick The joystick to vibrate + * \param joystick The joystick to vibrate. * \param left_rumble The intensity of the left trigger rumble motor, from 0 - * to 0xFFFF + * 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 + * 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. * * \since This function is available since SDL 2.0.14. * @@ -982,7 +995,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickRumbleTriggers(SDL_Joystick *joystick, U * An example of a joystick LED is the light on the back of a PlayStation 4's * DualShock 4 controller. * - * \param joystick The joystick to query + * \param joystick The joystick to query. * \return SDL_TRUE if the joystick has a modifiable LED, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.14. @@ -992,7 +1005,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasLED(SDL_Joystick *joystick); /** * Query whether a joystick has rumble support. * - * \param joystick The joystick to query + * \param joystick The joystick to query. * \return SDL_TRUE if the joystick has rumble, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.18. @@ -1004,7 +1017,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasRumble(SDL_Joystick *joystick); /** * Query whether a joystick has rumble support on triggers. * - * \param joystick The joystick to query + * \param joystick The joystick to query. * \return SDL_TRUE if the joystick has trigger rumble, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.18. @@ -1019,11 +1032,11 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasRumbleTriggers(SDL_Joystick *joy * An example of a joystick LED is the light on the back of a PlayStation 4's * DualShock 4 controller. * - * \param joystick The joystick to update - * \param red The intensity of the red LED - * \param green The intensity of the green LED - * \param blue The intensity of the blue LED - * \returns 0 on success, -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. * * \since This function is available since SDL 2.0.14. */ @@ -1032,10 +1045,11 @@ extern DECLSPEC int SDLCALL SDL_JoystickSetLED(SDL_Joystick *joystick, Uint8 red /** * Send a joystick specific effect packet * - * \param joystick The joystick to affect - * \param data The data to send to the joystick - * \param size The size of the data to send to the joystick - * \returns 0, or -1 if this joystick or driver doesn't support effect packets + * \param joystick The joystick to affect. + * \param data The data to send to the joystick. + * \param size The size of the data to send to the joystick. + * \returns 0, or -1 if this joystick or driver doesn't support effect + * packets. * * \since This function is available since SDL 2.0.16. */ @@ -1044,7 +1058,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickSendEffect(SDL_Joystick *joystick, const /** * Close a joystick previously opened with SDL_JoystickOpen(). * - * \param joystick The joystick device to close + * \param joystick The joystick device to close. * * \since This function is available since SDL 2.0.0. * @@ -1055,9 +1069,9 @@ extern DECLSPEC void SDLCALL SDL_JoystickClose(SDL_Joystick *joystick); /** * Get the battery level of a joystick as SDL_JoystickPowerLevel. * - * \param joystick the SDL_Joystick to query + * \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 + * `SDL_JOYSTICK_POWER_UNKNOWN` if it is unknown. * * \since This function is available since SDL 2.0.4. */ diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_keyboard.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_keyboard.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_keyboard.h + * # CategoryKeyboard * - * Include file for SDL keyboard event handling + * Include file for SDL keyboard event handling */ #ifndef SDL_keyboard_h_ @@ -40,14 +40,15 @@ extern "C" { #endif /** - * \brief The SDL keysym structure, used in key events. + * The SDL keysym structure, used in key events. * - * \note If you are looking for translated character input, see the ::SDL_TEXTINPUT event. + * If you are looking for translated character input, see the SDL_TEXTINPUT + * event. */ typedef struct SDL_Keysym { - SDL_Scancode scancode; /**< SDL physical key code - see ::SDL_Scancode for details */ - SDL_Keycode sym; /**< SDL virtual key code - see ::SDL_Keycode for details */ + SDL_Scancode scancode; /**< SDL physical key code - see SDL_Scancode for details */ + SDL_Keycode sym; /**< SDL virtual key code - see SDL_Keycode for details */ Uint16 mod; /**< current key modifiers */ Uint32 unused; } SDL_Keysym; @@ -84,7 +85,7 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); * 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 + * \param numkeys if non-NULL, receives the length of the returned array. * \returns a pointer to an array of key states. * * \since This function is available since SDL 2.0.0. @@ -129,7 +130,7 @@ extern DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void); * This does not change the keyboard state, only the key modifier flags that * SDL reports. * - * \param modstate the desired SDL_Keymod for the keyboard + * \param modstate the desired SDL_Keymod for the keyboard. * * \since This function is available since SDL 2.0.0. * @@ -143,7 +144,7 @@ extern DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate); * * See SDL_Keycode for details. * - * \param scancode the desired SDL_Scancode to query + * \param scancode the desired SDL_Scancode to query. * \returns the SDL_Keycode that corresponds to the given SDL_Scancode. * * \since This function is available since SDL 2.0.0. @@ -159,7 +160,7 @@ extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode * * See SDL_Scancode for details. * - * \param key the desired SDL_Keycode to query + * \param key the desired SDL_Keycode to query. * \returns the SDL_Scancode that corresponds to the given SDL_Keycode. * * \since This function is available since SDL 2.0.0. @@ -183,7 +184,7 @@ extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key); * unsuitable for creating a stable cross-platform two-way mapping between * strings and scancodes. * - * \param scancode the desired SDL_Scancode to query + * \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 (""). * @@ -197,7 +198,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_Scancode scancode); /** * Get a scancode from a human-readable name. * - * \param name the human-readable scancode name + * \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. * @@ -214,7 +215,7 @@ extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *name); * * See SDL_Scancode and SDL_Keycode for details. * - * \param key the desired SDL_Keycode to query + * \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 @@ -231,7 +232,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDL_Keycode key); /** * Get a key code from a human-readable name. * - * \param name the human-readable key name + * \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. * @@ -253,6 +254,10 @@ extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name); * * On some platforms using this function activates the screen keyboard. * + * On desktop platforms, SDL_StartTextInput() is implicitly called on SDL + * video subsystem initialization which will cause SDL_TextInputEvent and + * SDL_TextEditingEvent to begin emitting. + * * \since This function is available since SDL 2.0.0. * * \sa SDL_SetTextInputRect @@ -298,10 +303,11 @@ extern DECLSPEC void SDLCALL SDL_ClearComposition(void); extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputShown(void); /** - * Set the rectangle used to type Unicode text inputs. Native input methods - * will place a window with word suggestions near it, without covering the - * text being inputted. - * + * Set the rectangle used to type Unicode text inputs. + * + * Native input methods will place a window with word suggestions near it, + * without covering the text being inputted. + * * To start text input in a given location, this function is intended to be * called before SDL_StartTextInput, although some platforms support moving * the rectangle even while text input (and a composition) is active. @@ -311,7 +317,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputShown(void); * any feedback. * * \param rect the SDL_Rect structure representing the rectangle to receive - * text (ignored if NULL) + * text (ignored if NULL). * * \since This function is available since SDL 2.0.0. * @@ -335,7 +341,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void); /** * 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. * * \since This function is available since SDL 2.0.0. diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_keycode.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_keycode.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_keycode.h + * # CategoryKeycode * - * Defines constants which identify keyboard keys and modifiers. + * Defines constants which identify keyboard keys and modifiers. */ #ifndef SDL_keycode_h_ @@ -32,22 +32,22 @@ #include <SDL2/SDL_scancode.h> /** - * \brief The SDL virtual key representation. + * The SDL virtual key representation. * - * Values of this type are used to represent keyboard keys using the current - * layout of the keyboard. These values include Unicode values representing - * the unmodified character that would be generated by pressing the key, or - * an SDLK_* constant for those keys that do not generate characters. + * Values of this type are used to represent keyboard keys using the current + * layout of the keyboard. These values include Unicode values representing + * the unmodified character that would be generated by pressing the key, or an + * SDLK_* constant for those keys that do not generate characters. * - * A special exception is the number keys at the top of the keyboard which - * map to SDLK_0...SDLK_9 on AZERTY layouts. + * A special exception is the number keys at the top of the keyboard which map + * to SDLK_0...SDLK_9 on AZERTY layouts. */ typedef Sint32 SDL_Keycode; #define SDLK_SCANCODE_MASK (1<<30) #define SDL_SCANCODE_TO_KEYCODE(X) (X | SDLK_SCANCODE_MASK) -typedef enum +typedef enum SDL_KeyCode { SDLK_UNKNOWN = 0, @@ -327,9 +327,9 @@ typedef enum } SDL_KeyCode; /** - * \brief Enumeration of valid key mods (possibly OR'd together). + * Enumeration of valid key mods (possibly OR'd together). */ -typedef enum +typedef enum SDL_Keymod { KMOD_NONE = 0x0000, KMOD_LSHIFT = 0x0001, diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_loadso.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_loadso.h @@ -19,23 +19,25 @@ 3. This notice may not be removed or altered from any source distribution. */ +/* WIKI CATEGORY: LoadSO */ + /** - * \file SDL_loadso.h - * - * System dependent library loading routines - * - * Some things to keep in mind: - * \li These functions only work on C function names. Other languages may - * have name mangling and intrinsic language support that varies from - * compiler to compiler. - * \li 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. - * \li Avoid namespace collisions. If you load a symbol from the library, - * it is not defined whether or not it goes into the global symbol - * namespace for the application. If it does and it conflicts with - * symbols in your code or other shared libraries, you will not get - * the results you expect. :) + * # CategoryLoadSO + * + * System-dependent library loading routines. + * + * Some things to keep in mind: + * + * - These functions only work on C function names. Other languages may have + * name mangling and intrinsic language support that varies from compiler to + * compiler. + * - Make sure you declare your function pointers with the same calling + * convention as the actual library function. Your code will crash + * mysteriously if you do not do this. + * - Avoid namespace collisions. If you load a symbol from the library, it is + * not defined whether or not it goes into the global symbol namespace for + * the application. If it does and it conflicts with symbols in your code or + * other shared libraries, you will not get the results you expect. :) */ #ifndef SDL_loadso_h_ @@ -53,7 +55,7 @@ extern "C" { /** * Dynamically load a shared object. * - * \param sofile a system-dependent name of the object file + * \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. * @@ -79,8 +81,8 @@ extern DECLSPEC void *SDLCALL SDL_LoadObject(const char *sofile); * * 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 + * \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. * @@ -95,7 +97,7 @@ extern DECLSPEC void *SDLCALL SDL_LoadFunction(void *handle, /** * Unload a shared object from memory. * - * \param handle a valid shared object handle returned by SDL_LoadObject() + * \param handle a valid shared object handle returned by SDL_LoadObject(). * * \since This function is available since SDL 2.0.0. * diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_locale.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_locale.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_locale.h + * # CategoryLocale * - * Include file for SDL locale services + * Include file for SDL locale services */ #ifndef _SDL_locale_h diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_log.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_log.h @@ -20,18 +20,19 @@ */ /** - * \file SDL_log.h + * # CategoryLog * - * Simple log messages with categories and priorities. + * Simple log messages with categories and priorities. * - * By default logs are quiet, but if you're debugging SDL you might want: + * By default logs are quiet, but if you're debugging SDL you might want: * - * SDL_LogSetAllPriority(SDL_LOG_PRIORITY_WARN); + * SDL_LogSetAllPriority(SDL_LOG_PRIORITY_WARN); * - * Here's where the messages go on different platforms: - * Windows: debug output stream - * Android: log output - * Others: standard error output (stderr) + * Here's where the messages go on different platforms: + * + * - Windows: debug output stream + * - Android: log output + * - Others: standard error output (stderr) */ #ifndef SDL_log_h_ @@ -47,21 +48,20 @@ extern "C" { /** - * \brief The maximum size of a log message prior to SDL 2.0.24 + * The maximum size of a log message prior to SDL 2.0.24 * - * As of 2.0.24 there is no limit to the length of SDL log messages. + * As of 2.0.24 there is no limit to the length of SDL log messages. */ #define SDL_MAX_LOG_MESSAGE 4096 /** - * \brief The predefined log categories + * The predefined log categories * - * By default the application category is enabled at the INFO level, - * the assert category is enabled at the WARN level, test is enabled - * at the VERBOSE level and all other categories are enabled at the - * ERROR level. + * By default the application category is enabled at the INFO level, the + * assert category is enabled at the WARN level, test is enabled at the + * VERBOSE level and all other categories are enabled at the ERROR level. */ -typedef enum +typedef enum SDL_LogCategory { SDL_LOG_CATEGORY_APPLICATION, SDL_LOG_CATEGORY_ERROR, @@ -97,9 +97,9 @@ typedef enum } SDL_LogCategory; /** - * \brief The predefined log priorities + * The predefined log priorities */ -typedef enum +typedef enum SDL_LogPriority { SDL_LOG_PRIORITY_VERBOSE = 1, SDL_LOG_PRIORITY_DEBUG, @@ -114,7 +114,7 @@ typedef enum /** * Set the priority of all log categories. * - * \param priority the SDL_LogPriority to assign + * \param priority the SDL_LogPriority to assign. * * \since This function is available since SDL 2.0.0. * @@ -125,8 +125,8 @@ extern DECLSPEC void SDLCALL SDL_LogSetAllPriority(SDL_LogPriority priority); /** * Set the priority of a particular log category. * - * \param category the category to assign a priority to - * \param priority the SDL_LogPriority to assign + * \param category the category to assign a priority to. + * \param priority the SDL_LogPriority to assign. * * \since This function is available since SDL 2.0.0. * @@ -139,8 +139,8 @@ extern DECLSPEC void SDLCALL SDL_LogSetPriority(int category, /** * Get the priority of a particular log category. * - * \param category the category to query - * \returns the SDL_LogPriority for the requested category + * \param category the category to query. + * \returns the SDL_LogPriority for the requested category. * * \since This function is available since SDL 2.0.0. * @@ -166,7 +166,7 @@ extern DECLSPEC void SDLCALL SDL_LogResetPriorities(void); * = * \param fmt a printf() style message format string * * \param ... additional parameters matching % tokens in the `fmt` string, if - * any + * any. * * \since This function is available since SDL 2.0.0. * @@ -184,10 +184,10 @@ extern DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, . /** * Log a message with SDL_LOG_PRIORITY_VERBOSE. * - * \param category the category of the message - * \param fmt a printf() style message format string + * \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 + * if any. * * \since This function is available since SDL 2.0.0. * @@ -205,10 +205,10 @@ extern DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRI /** * Log a message with SDL_LOG_PRIORITY_DEBUG. * - * \param category the category of the message - * \param fmt a printf() style message format string + * \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 + * if any. * * \since This function is available since SDL 2.0.0. * @@ -226,10 +226,10 @@ extern DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_STRING /** * Log a message with SDL_LOG_PRIORITY_INFO. * - * \param category the category of the message - * \param fmt a printf() style message format string + * \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 + * if any. * * \since This function is available since SDL 2.0.0. * @@ -247,10 +247,10 @@ extern DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STRING /** * Log a message with SDL_LOG_PRIORITY_WARN. * - * \param category the category of the message - * \param fmt a printf() style message format string + * \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 + * if any. * * \since This function is available since SDL 2.0.0. * @@ -268,10 +268,10 @@ extern DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING /** * Log a message with SDL_LOG_PRIORITY_ERROR. * - * \param category the category of the message - * \param fmt a printf() style message format string + * \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 + * if any. * * \since This function is available since SDL 2.0.0. * @@ -289,10 +289,10 @@ extern DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING /** * Log a message with SDL_LOG_PRIORITY_CRITICAL. * - * \param category the category of the message - * \param fmt a printf() style message format string + * \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 + * if any. * * \since This function is available since SDL 2.0.0. * @@ -310,11 +310,11 @@ extern DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT_STR /** * 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 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 + * if any. * * \since This function is available since SDL 2.0.0. * @@ -334,10 +334,10 @@ extern DECLSPEC void SDLCALL SDL_LogMessage(int category, /** * 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 + * \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. * @@ -359,10 +359,11 @@ extern DECLSPEC void SDLCALL SDL_LogMessageV(int category, * * 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 + * \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); @@ -370,9 +371,9 @@ typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_ * Get the current log output function. * * \param callback an SDL_LogOutputFunction filled in with the current log - * callback + * callback. * \param userdata a pointer filled in with the pointer that is passed to - * `callback` + * `callback`. * * \since This function is available since SDL 2.0.0. * @@ -383,8 +384,8 @@ extern DECLSPEC void SDLCALL SDL_LogGetOutputFunction(SDL_LogOutputFunction *cal /** * 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` + * \param callback an SDL_LogOutputFunction to call instead of the default. + * \param userdata a pointer that is passed to `callback`. * * \since This function is available since SDL 2.0.0. * diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_main.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_main.h @@ -25,9 +25,9 @@ #include <SDL2/SDL_stdinc.h> /** - * \file SDL_main.h + * # CategoryMain * - * Redefine main() on some platforms so that it is called by SDL. + * Redefine main() on some platforms so that it is called by SDL. */ #ifndef SDL_MAIN_HANDLED @@ -129,14 +129,14 @@ * * The application's main() function must be called with C linkage, * and should be declared like this: - * \code + * ```c * #ifdef __cplusplus * extern "C" * #endif * int main(int argc, char *argv[]) * { * } - * \endcode + * ``` */ #if defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE) @@ -149,7 +149,7 @@ extern "C" { #endif /** - * The prototype for the application's main() function + * The prototype for the application's main() function */ typedef int (*SDL_main_func)(int argc, char *argv[]); extern SDLMAIN_DECLSPEC int SDL_main(int argc, char *argv[]); @@ -222,8 +222,8 @@ extern DECLSPEC void SDLCALL SDL_UnregisterApp(void); /** * Initialize and launch an SDL/WinRT application. * - * \param mainFunction the SDL app's C-style main(), an SDL_main_func - * \param reserved reserved for future use; should be NULL + * \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. * @@ -238,10 +238,10 @@ extern DECLSPEC int SDLCALL SDL_WinRTRunApp(SDL_main_func mainFunction, void * r /** * 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(), an SDL_main_func - * \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. * * \since This function is available since SDL 2.0.10. */ @@ -254,8 +254,8 @@ extern DECLSPEC int SDLCALL SDL_UIKitRunApp(int argc, char *argv[], SDL_main_fun /** * Initialize and launch an SDL GDK application. * - * \param mainFunction the SDL app's C-style main(), an SDL_main_func - * \param reserved reserved for future use; should be NULL + * \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. * diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_messagebox.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_messagebox.h @@ -32,9 +32,11 @@ extern "C" { #endif /** - * SDL_MessageBox flags. If supported will display warning icon, etc. + * SDL_MessageBox flags. + * + * If supported will display warning icon, etc. */ -typedef enum +typedef enum SDL_MessageBoxFlags { SDL_MESSAGEBOX_ERROR = 0x00000010, /**< error dialog */ SDL_MESSAGEBOX_WARNING = 0x00000020, /**< warning dialog */ @@ -46,7 +48,7 @@ typedef enum /** * Flags for SDL_MessageBoxButtonData. */ -typedef enum +typedef enum SDL_MessageBoxButtonFlags { SDL_MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT = 0x00000001, /**< Marks the default button when return is hit */ SDL_MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT = 0x00000002 /**< Marks the default button when escape is hit */ @@ -55,9 +57,9 @@ typedef enum /** * Individual button data. */ -typedef struct +typedef struct SDL_MessageBoxButtonData { - Uint32 flags; /**< ::SDL_MessageBoxButtonFlags */ + Uint32 flags; /**< SDL_MessageBoxButtonFlags */ int buttonid; /**< User defined button id (value returned via SDL_ShowMessageBox) */ const char * text; /**< The UTF-8 button text */ } SDL_MessageBoxButtonData; @@ -65,12 +67,12 @@ typedef struct /** * RGB value used in a message box color scheme */ -typedef struct +typedef struct SDL_MessageBoxColor { Uint8 r, g, b; } SDL_MessageBoxColor; -typedef enum +typedef enum SDL_MessageBoxColorType { SDL_MESSAGEBOX_COLOR_BACKGROUND, SDL_MESSAGEBOX_COLOR_TEXT, @@ -83,7 +85,7 @@ typedef enum /** * A set of colors to use for message box dialogs */ -typedef struct +typedef struct SDL_MessageBoxColorScheme { SDL_MessageBoxColor colors[SDL_MESSAGEBOX_COLOR_MAX]; } SDL_MessageBoxColorScheme; @@ -91,9 +93,9 @@ typedef struct /** * MessageBox structure containing title, text, window, etc. */ -typedef struct +typedef struct SDL_MessageBoxData { - Uint32 flags; /**< ::SDL_MessageBoxFlags */ + Uint32 flags; /**< SDL_MessageBoxFlags */ SDL_Window *window; /**< Parent window, can be NULL */ const char *title; /**< UTF-8 title */ const char *message; /**< UTF-8 message text */ @@ -101,7 +103,7 @@ typedef struct int numbuttons; const SDL_MessageBoxButtonData *buttons; - const SDL_MessageBoxColorScheme *colorScheme; /**< ::SDL_MessageBoxColorScheme, can be NULL to use system settings */ + const SDL_MessageBoxColorScheme *colorScheme; /**< SDL_MessageBoxColorScheme, can be NULL to use system settings */ } SDL_MessageBoxData; /** @@ -128,8 +130,9 @@ typedef struct * 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 + * 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. * @@ -168,10 +171,10 @@ extern DECLSPEC int SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *message * 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 + * \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. * diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_metal.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_metal.h @@ -20,9 +20,10 @@ */ /** - * \file SDL_metal.h + * # CategoryMetal * - * Header file for functions to creating Metal layers and views on SDL windows. + * Header file for functions to creating Metal layers and views on SDL + * windows. */ #ifndef SDL_metal_h_ @@ -37,9 +38,9 @@ extern "C" { #endif /** - * \brief A handle to a CAMetalLayer-backed NSView (macOS) or UIView (iOS/tvOS). + * A handle to a CAMetalLayer-backed NSView (macOS) or UIView (iOS/tvOS). * - * \note This can be cast directly to an NSView or UIView. + * This can be cast directly to an NSView or UIView. */ typedef void *SDL_MetalView; @@ -90,9 +91,9 @@ extern DECLSPEC void *SDLCALL SDL_Metal_GetLayer(SDL_MetalView view); * 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 + * \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. * * \since This function is available since SDL 2.0.14. * diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_misc.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_misc.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_misc.h + * # CategoryMisc * - * \brief Include file for SDL API functions that don't fit elsewhere. + * Include file for SDL API functions that don't fit elsewhere. */ #ifndef SDL_misc_h_ diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_mouse.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_mouse.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_mouse.h + * # CategoryMouse * - * Include file for SDL mouse event handling. + * Include file for SDL mouse event handling. */ #ifndef SDL_mouse_h_ @@ -41,9 +41,9 @@ extern "C" { typedef struct SDL_Cursor SDL_Cursor; /**< Implementation dependent */ /** - * \brief Cursor types for SDL_CreateSystemCursor(). + * Cursor types for SDL_CreateSystemCursor(). */ -typedef enum +typedef enum SDL_SystemCursor { SDL_SYSTEM_CURSOR_ARROW, /**< Arrow */ SDL_SYSTEM_CURSOR_IBEAM, /**< I-beam */ @@ -61,9 +61,9 @@ typedef enum } SDL_SystemCursor; /** - * \brief Scroll direction types for the Scroll event + * Scroll direction types for the Scroll event */ -typedef enum +typedef enum SDL_MouseWheelDirection { SDL_MOUSEWHEEL_NORMAL, /**< The scroll direction is normal */ SDL_MOUSEWHEEL_FLIPPED /**< The scroll direction is flipped / natural */ @@ -90,9 +90,9 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void); * either `x` or `y`. * * \param x the x coordinate of the mouse cursor position relative to the - * focus window + * focus window. * \param y the y coordinate of the mouse cursor position relative to the - * focus window + * focus window. * \returns a 32-bit button bitmask of the current button state. * * \since This function is available since SDL 2.0.0. @@ -120,9 +120,9 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetMouseState(int *x, int *y); * reason to use this function, you probably want SDL_GetMouseState() instead. * * \param x filled in with the current X coord relative to the desktop; can be - * NULL + * NULL. * \param y filled in with the current Y coord relative to the desktop; can be - * NULL + * NULL. * \returns the current button state as a bitmask which can be tested using * the SDL_BUTTON(X) macros. * @@ -141,8 +141,8 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetGlobalMouseState(int *x, int *y); * 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 + * \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. * * \since This function is available since SDL 2.0.0. @@ -162,9 +162,9 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetRelativeMouseState(int *x, int *y); * mouse when used over Microsoft Remote Desktop. * * \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 + * mouse focus. + * \param x the x coordinate within the window. + * \param y the y coordinate within the window. * * \since This function is available since SDL 2.0.0. * @@ -184,8 +184,8 @@ extern DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * window, * Note that this function will appear to succeed, but not actually move the * mouse when used over Microsoft Remote Desktop. * - * \param x the x coordinate - * \param y the y coordinate + * \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. * @@ -297,14 +297,14 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(void); * 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 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 + * 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 + * 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. * @@ -322,9 +322,9 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data, /** * Create a color cursor. * - * \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 + * \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. * @@ -340,7 +340,7 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateColorCursor(SDL_Surface *surface, /** * Create a system cursor. * - * \param id an SDL_SystemCursor enum value + * \param id an SDL_SystemCursor enum value. * \returns a cursor on success or NULL on failure; call SDL_GetError() for * more information. * @@ -358,7 +358,7 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor id); * 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 + * \param cursor a cursor to make active. * * \since This function is available since SDL 2.0.0. * @@ -402,7 +402,7 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetDefaultCursor(void); * Use this function to free cursor resources created with SDL_CreateCursor(), * SDL_CreateColorCursor() or SDL_CreateSystemCursor(). * - * \param cursor the cursor to free + * \param cursor the cursor to free. * * \since This function is available since SDL 2.0.0. * @@ -437,9 +437,9 @@ extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle); /** * Used as a mask when testing buttons in buttonstate. * - * - Button 1: Left mouse button - * - Button 2: Middle mouse button - * - Button 3: Right mouse button + * - Button 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 diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_mutex.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_mutex.h @@ -23,9 +23,9 @@ #define SDL_mutex_h_ /** - * \file SDL_mutex.h + * # CategoryMutex * - * Functions to provide thread synchronization primitives. + * Functions to provide thread synchronization primitives. */ #include <SDL2/SDL_stdinc.h> @@ -112,13 +112,13 @@ extern "C" { #endif /** - * Synchronization functions which can time out return this value - * if they time out. + * Synchronization functions which can time out return this value if they time + * out. */ #define SDL_MUTEX_TIMEDOUT 1 /** - * This is the timeout value which corresponds to never time out. + * This is the timeout value which corresponds to never time out. */ #define SDL_MUTEX_MAXWAIT (~(Uint32)0) @@ -165,7 +165,7 @@ extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void); * 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 + * \param mutex the mutex to lock. * \return 0, or -1 on error. * * \since This function is available since SDL 2.0.0. @@ -182,7 +182,7 @@ extern DECLSPEC int SDLCALL SDL_LockMutex(SDL_mutex * mutex) SDL_ACQUIRE(mutex); * 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 + * \param mutex the mutex to try to lock. * \returns 0, `SDL_MUTEX_TIMEDOUT`, or -1 on error; call SDL_GetError() for * more information. * @@ -224,7 +224,7 @@ extern DECLSPEC int SDLCALL SDL_UnlockMutex(SDL_mutex * mutex) SDL_RELEASE(mutex * to destroy a locked mutex, and may result in undefined behavior depending * on the platform. * - * \param mutex the mutex to destroy + * \param mutex the mutex to destroy. * * \since This function is available since SDL 2.0.0. * @@ -256,7 +256,7 @@ typedef struct SDL_semaphore SDL_sem; * 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 + * \param initial_value the starting value of the semaphore. * \returns a new semaphore or NULL on failure; call SDL_GetError() for more * information. * @@ -277,7 +277,7 @@ extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value); * It is not safe to destroy a semaphore if there are threads currently * waiting on it. * - * \param sem the semaphore to destroy + * \param sem the semaphore to destroy. * * \since This function is available since SDL 2.0.0. * @@ -301,7 +301,7 @@ extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem); * This function is the equivalent of calling SDL_SemWaitTimeout() with a time * length of `SDL_MUTEX_MAXWAIT`. * - * \param sem the semaphore wait on + * \param sem the semaphore wait on. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -325,7 +325,7 @@ extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem); * the semaphore doesn't have a positive value, the function immediately * returns SDL_MUTEX_TIMEDOUT. * - * \param sem the semaphore to wait on + * \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. @@ -349,8 +349,8 @@ extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem); * signal or error, or the specified time has elapsed. If the call is * successful it will atomically decrement the semaphore value. * - * \param sem the semaphore to wait on - * \param timeout the length of the timeout, in milliseconds + * \param sem the semaphore to wait on. + * \param timeout 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. @@ -369,7 +369,7 @@ extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem *sem, Uint32 timeout); /** * Atomically increment a semaphore's value and wake waiting threads. * - * \param sem the semaphore to increment + * \param sem the semaphore to increment. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -387,7 +387,7 @@ extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem); /** * Get the current value of a semaphore. * - * \param sem the semaphore to query + * \param sem the semaphore to query. * \returns the current value of the semaphore. * * \since This function is available since SDL 2.0.0. @@ -427,7 +427,7 @@ extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void); /** * Destroy a condition variable. * - * \param cond the condition variable to destroy + * \param cond the condition variable to destroy. * * \since This function is available since SDL 2.0.0. * @@ -442,7 +442,7 @@ extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * cond); /** * Restart one of the threads that are waiting on the condition variable. * - * \param cond the condition variable to signal + * \param cond the condition variable to signal. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -459,7 +459,7 @@ extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * cond); /** * Restart all threads that are waiting on the condition variable. * - * \param cond the condition variable to signal + * \param cond the condition variable to signal. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -486,8 +486,8 @@ extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond); * 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 + * \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. * @@ -512,10 +512,10 @@ extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mutex); * * 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 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 + * 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. diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_opengl.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_opengl.h @@ -19,17 +19,11 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** - * \file SDL_opengl.h - * - * This is a simple file to encapsulate the OpenGL API headers. - */ - -/** - * \def NO_SDL_GLEXT +/* + * This is a simple file to encapsulate the OpenGL API headers. * - * Define this if you have your own version of glext.h and want to disable the - * version included in SDL_opengl.h. + * Define NO_SDL_GLEXT if you have your own version of glext.h and want + * to disable the version included in SDL_opengl.h. */ #ifndef SDL_opengl_h_ diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_opengles.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_opengles.h @@ -19,11 +19,10 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** - * \file SDL_opengles.h - * - * This is a simple file to encapsulate the OpenGL ES 1.X API headers. +/* + * This is a simple file to encapsulate the OpenGL ES 1.X API headers. */ + #include <SDL2/SDL_config.h> #ifdef __IPHONEOS__ diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_opengles2.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_opengles2.h @@ -19,11 +19,10 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** - * \file SDL_opengles2.h - * - * This is a simple file to encapsulate the OpenGL ES 2.0 API headers. +/* + * This is a simple file to encapsulate the OpenGL ES 2.0 API headers. */ + #include <SDL2/SDL_config.h> #if !defined(_MSC_VER) && !defined(SDL_USE_BUILTIN_OPENGL_DEFINITIONS) diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_pixels.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_pixels.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_pixels.h + * # CategoryPixels * - * Header for the enumerated pixel format definitions. + * Header for the enumerated pixel format definitions. */ #ifndef SDL_pixels_h_ @@ -320,9 +320,10 @@ typedef enum } SDL_PixelFormatEnum; /** - * The bits of this structure can be directly reinterpreted as an integer-packed - * color which uses the SDL_PIXELFORMAT_RGBA32 format (SDL_PIXELFORMAT_ABGR8888 - * on little-endian systems and SDL_PIXELFORMAT_RGBA8888 on big-endian systems). + * The bits of this structure can be directly reinterpreted as an + * integer-packed color which uses the SDL_PIXELFORMAT_RGBA32 format + * (SDL_PIXELFORMAT_ABGR8888 on little-endian systems and + * SDL_PIXELFORMAT_RGBA8888 on big-endian systems). */ typedef struct SDL_Color { @@ -342,7 +343,30 @@ typedef struct SDL_Palette } SDL_Palette; /** - * \note Everything in the pixel format structure is read-only. + * A structure that contains pixel format information. + * + * Everything in the pixel format structure is read-only. + * + * A pixel format has either a palette or masks. If a palette is used `Rmask`, + * `Gmask`, `Bmask`, and `Amask` will be 0. + * + * An SDL_PixelFormat describes the format of the pixel data stored at the + * `pixels` field of an SDL_Surface. Every surface stores an SDL_PixelFormat + * in the `format` field. + * + * If you wish to do pixel level modifications on a surface, then + * understanding how SDL stores its color information is essential. + * + * For information on modern pixel color spaces, see the following Wikipedia + * article: http://en.wikipedia.org/wiki/RGBA_color_space + * + * \sa SDL_ConvertSurface + * \sa SDL_GetRGB + * \sa SDL_GetRGBA + * \sa SDL_MapRGB + * \sa SDL_MapRGBA + * \sa SDL_AllocFormat + * \sa SDL_FreeFormat */ typedef struct SDL_PixelFormat { @@ -370,7 +394,7 @@ typedef struct SDL_PixelFormat /** * Get the human readable name of a pixel format. * - * \param format the pixel format to query + * \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. * @@ -381,12 +405,12 @@ extern DECLSPEC const char* SDLCALL SDL_GetPixelFormatName(Uint32 format); /** * Convert one of the enumerated pixel formats to a bpp value and RGBA masks. * - * \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 + * \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. * @@ -407,12 +431,12 @@ extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format, * This will return `SDL_PIXELFORMAT_UNKNOWN` if the conversion wasn't * possible. * - * \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 + * \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. * * \since This function is available since SDL 2.0.0. * @@ -431,7 +455,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp, * 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 + * \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. * @@ -444,7 +468,7 @@ extern DECLSPEC SDL_PixelFormat * SDLCALL SDL_AllocFormat(Uint32 pixel_format); /** * Free an SDL_PixelFormat structure allocated by SDL_AllocFormat(). * - * \param format the SDL_PixelFormat structure to free + * \param format the SDL_PixelFormat structure to free. * * \since This function is available since SDL 2.0.0. * @@ -457,7 +481,7 @@ extern DECLSPEC void SDLCALL SDL_FreeFormat(SDL_PixelFormat *format); * * The palette entries are initialized to white. * - * \param ncolors represents the number of color entries in the color palette + * \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. @@ -471,8 +495,8 @@ extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors); /** * 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 + * \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. * @@ -487,10 +511,10 @@ extern DECLSPEC int SDLCALL SDL_SetPixelFormatPalette(SDL_PixelFormat * format, /** * Set a range of colors in a palette. * - * \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 + * \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. * @@ -506,7 +530,7 @@ extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette, /** * Free a palette created with SDL_AllocPalette(). * - * \param palette the SDL_Palette structure to be freed + * \param palette the SDL_Palette structure to be freed. * * \since This function is available since SDL 2.0.0. * @@ -532,11 +556,11 @@ extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette); * 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 + * \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. * * \since This function is available since SDL 2.0.0. * @@ -566,12 +590,12 @@ extern DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format, * 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 + * 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. * * \since This function is available since SDL 2.0.0. * @@ -591,12 +615,12 @@ extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format, * (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 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 + * 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. * * \since This function is available since SDL 2.0.0. * @@ -619,13 +643,13 @@ extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, * If the surface has no alpha component, the alpha will be returned as 0xff * (100% opaque). * - * \param pixel a pixel value + * \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 + * 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. * * \since This function is available since SDL 2.0.0. * @@ -641,8 +665,8 @@ extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel, /** * 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 + * \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. * * \since This function is available since SDL 2.0.0. * diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_platform.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_platform.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_platform.h + * # CategoryPlatform * - * Try to get a standard set of platform defines. + * Try to get a standard set of platform defines. */ #ifndef SDL_platform_h_ diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_power.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_power.h @@ -23,9 +23,9 @@ #define SDL_power_h_ /** - * \file SDL_power.h + * # CategoryPower * - * Header for the SDL power management routines. + * Header for the SDL power management routines. */ #include <SDL2/SDL_stdinc.h> @@ -37,9 +37,9 @@ extern "C" { #endif /** - * The basic state for the system's power supply. + * The basic state for the system's power supply. */ -typedef enum +typedef enum SDL_PowerState { SDL_POWERSTATE_UNKNOWN, /**< cannot determine power status */ SDL_POWERSTATE_ON_BATTERY, /**< Not plugged in, running on the battery */ @@ -66,10 +66,10 @@ typedef enum * * \param seconds 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 + * value, or we're not running on a battery. * \param percent 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 + * can't determine a value, or we're not running on a battery. * \returns an SDL_PowerState enum representing the current battery state. * * \since This function is available since SDL 2.0.0. diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_quit.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_quit.h @@ -20,9 +20,20 @@ */ /** - * \file SDL_quit.h + * # CategoryQuit * - * Include file for SDL quit event handling. + * An SDL_QUIT event is generated when the user tries to close the application + * window. If it is ignored or filtered out, the window will remain open. If + * it is not ignored or filtered, it is queued normally and the window is + * allowed to close. When the window is closed, screen updates will complete, + * but have no effect. + * + * SDL_Init() installs signal handlers for SIGINT (keyboard interrupt) and + * SIGTERM (system termination request), if handlers do not already exist, + * that generate SDL_QUIT events as well. There is no way to determine the + * cause of an SDL_QUIT event, but setting a signal handler in your + * application will override the default generation of quit events for that + * signal. */ #ifndef SDL_quit_h_ @@ -31,25 +42,6 @@ #include <SDL2/SDL_stdinc.h> #include <SDL2/SDL_error.h> -/** - * \file SDL_quit.h - * - * An ::SDL_QUIT event is generated when the user tries to close the application - * window. If it is ignored or filtered out, the window will remain open. - * If it is not ignored or filtered, it is queued normally and the window - * is allowed to close. When the window is closed, screen updates will - * complete, but have no effect. - * - * SDL_Init() installs signal handlers for SIGINT (keyboard interrupt) - * and SIGTERM (system termination request), if handlers do not already - * exist, that generate ::SDL_QUIT events as well. There is no way - * to determine the cause of an ::SDL_QUIT event, but setting a signal - * handler in your application will override the default generation of - * quit events for that signal. - * - * \sa SDL_Quit() - */ - /* There are no functions directly affecting the quit event */ #define SDL_QuitRequested() \ diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_rect.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_rect.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_rect.h + * # CategoryRect * - * Header file for SDL_rect definition and management functions. + * Header file for SDL_rect definition and management functions. */ #ifndef SDL_rect_h_ @@ -135,8 +135,8 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEquals(const SDL_Rect *a, const SDL_Rect *b) * * 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 + * \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. @@ -151,10 +151,10 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasIntersection(const SDL_Rect * A, * * 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 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` + * 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. @@ -168,10 +168,10 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IntersectRect(const SDL_Rect * A, /** * 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 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` + * `A` and `B`. * * \since This function is available since SDL 2.0.0. */ @@ -186,11 +186,11 @@ extern DECLSPEC void SDLCALL SDL_UnionRect(const SDL_Rect * A, * 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 + * 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 + * rectangle. * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the * points were outside of the clipping rectangle. * @@ -210,11 +210,11 @@ extern DECLSPEC SDL_bool SDLCALL SDL_EnclosePoints(const SDL_Point * points, * 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 + * \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. * * \since This function is available since SDL 2.0.0. @@ -274,8 +274,8 @@ SDL_FORCE_INLINE SDL_bool SDL_FRectEquals(const SDL_FRect *a, const SDL_FRect *b * * If either pointer is NULL the function will return SDL_FALSE. * - * \param A an SDL_FRect structure representing the first rectangle - * \param B an SDL_FRect structure representing the second rectangle + * \param A an SDL_FRect structure representing the first rectangle. + * \param B an SDL_FRect 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.22. @@ -290,10 +290,10 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasIntersectionF(const SDL_FRect * A, * * If `result` is NULL then this function will return SDL_FALSE. * - * \param A an SDL_FRect structure representing the first rectangle - * \param B an SDL_FRect structure representing the second rectangle + * \param A an SDL_FRect structure representing the first rectangle. + * \param B an SDL_FRect structure representing the second rectangle. * \param result an SDL_FRect structure filled in with the intersection of - * rectangles `A` and `B` + * rectangles `A` and `B`. * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.22. @@ -307,10 +307,10 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IntersectFRect(const SDL_FRect * A, /** * Calculate the union of two rectangles with float precision. * - * \param A an SDL_FRect structure representing the first rectangle - * \param B an SDL_FRect structure representing the second rectangle + * \param A an SDL_FRect structure representing the first rectangle. + * \param B an SDL_FRect structure representing the second rectangle. * \param result an SDL_FRect structure filled in with the union of rectangles - * `A` and `B` + * `A` and `B`. * * \since This function is available since SDL 2.0.22. */ @@ -326,11 +326,11 @@ extern DECLSPEC void SDLCALL SDL_UnionFRect(const SDL_FRect * A, * considered. * * \param points an array of SDL_FPoint structures representing points to be - * enclosed - * \param count the number of structures in the `points` array - * \param clip an SDL_FRect used for clipping or NULL to enclose all points + * enclosed. + * \param count the number of structures in the `points` array. + * \param clip an SDL_FRect used for clipping or NULL to enclose all points. * \param result an SDL_FRect structure filled in with the minimal enclosing - * rectangle + * rectangle. * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the * points were outside of the clipping rectangle. * @@ -351,11 +351,11 @@ extern DECLSPEC SDL_bool SDLCALL SDL_EncloseFPoints(const SDL_FPoint * points, * 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_FRect 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 + * \param rect an SDL_FRect 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. * * \since This function is available since SDL 2.0.22. diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_render.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_render.h @@ -20,29 +20,30 @@ */ /** - * \file SDL_render.h + * # CategoryRender * - * Header file for SDL 2D rendering functions. + * Header file for SDL 2D rendering functions. * - * This API supports the following features: - * * single pixel points - * * single pixel lines - * * filled rectangles - * * texture images + * This API supports the following features: * - * The primitives may be drawn in opaque, blended, or additive modes. + * - single pixel points + * - single pixel lines + * - filled rectangles + * - texture images * - * The texture images may be drawn in opaque, blended, or additive modes. - * They can have an additional color tint or alpha modulation applied to - * them, and may also be stretched with linear interpolation. + * The primitives may be drawn in opaque, blended, or additive modes. * - * This API is designed to accelerate simple 2D operations. You may - * want more functionality such as polygons and particle effects and - * in that case you should use SDL's OpenGL/Direct3D support or one - * of the many good 3D engines. + * The texture images may be drawn in opaque, blended, or additive modes. They + * can have an additional color tint or alpha modulation applied to them, and + * may also be stretched with linear interpolation. * - * These functions must be called from the main thread. - * See this bug for details: https://github.com/libsdl-org/SDL/issues/986 + * This API is designed to accelerate simple 2D operations. You may want more + * functionality such as polygons and particle effects and in that case you + * should use SDL's OpenGL/Direct3D support or one of the many good 3D + * engines. + * + * These functions must be called from the main thread. See this bug for + * details: https://github.com/libsdl-org/SDL/issues/986 */ #ifndef SDL_render_h_ @@ -61,7 +62,7 @@ extern "C" { /** * Flags used when creating a rendering context */ -typedef enum +typedef enum SDL_RendererFlags { SDL_RENDERER_SOFTWARE = 0x00000001, /**< The renderer is a software fallback */ SDL_RENDERER_ACCELERATED = 0x00000002, /**< The renderer uses hardware @@ -78,7 +79,7 @@ typedef enum typedef struct SDL_RendererInfo { const char *name; /**< The name of the renderer */ - Uint32 flags; /**< Supported ::SDL_RendererFlags */ + Uint32 flags; /**< Supported SDL_RendererFlags */ Uint32 num_texture_formats; /**< The number of available texture formats */ Uint32 texture_formats[16]; /**< The available texture formats */ int max_texture_width; /**< The maximum texture width */ @@ -86,7 +87,7 @@ typedef struct SDL_RendererInfo } SDL_RendererInfo; /** - * Vertex structure + * Vertex structure */ typedef struct SDL_Vertex { @@ -98,7 +99,7 @@ typedef struct SDL_Vertex /** * The scaling mode for a texture. */ -typedef enum +typedef enum SDL_ScaleMode { SDL_ScaleModeNearest, /**< nearest pixel sampling */ SDL_ScaleModeLinear, /**< linear filtering */ @@ -108,7 +109,7 @@ typedef enum /** * The access pattern allowed for a texture. */ -typedef enum +typedef enum SDL_TextureAccess { SDL_TEXTUREACCESS_STATIC, /**< Changes rarely, not lockable */ SDL_TEXTUREACCESS_STREAMING, /**< Changes frequently, lockable */ @@ -118,7 +119,7 @@ typedef enum /** * The texture channel modulation used in SDL_RenderCopy(). */ -typedef enum +typedef enum SDL_TextureModulate { SDL_TEXTUREMODULATE_NONE = 0x00000000, /**< No modulation */ SDL_TEXTUREMODULATE_COLOR = 0x00000001, /**< srcC = srcC * color */ @@ -128,7 +129,7 @@ typedef enum /** * Flip constants for SDL_RenderCopyEx */ -typedef enum +typedef enum SDL_RendererFlip { SDL_FLIP_NONE = 0x00000000, /**< Do not flip */ SDL_FLIP_HORIZONTAL = 0x00000001, /**< flip horizontally */ @@ -171,9 +172,9 @@ extern DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void); /** * Get info about a specific 2D rendering driver for the current display. * - * \param index the index of the driver to query information about + * \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 + * the rendering driver. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -188,12 +189,12 @@ extern DECLSPEC int SDLCALL SDL_GetRenderDriverInfo(int index, /** * Create a window and default renderer. * - * \param width the width of the window - * \param height the height of the window + * \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 + * 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. * @@ -210,10 +211,10 @@ extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer( /** * Create a 2D rendering context for a window. * - * \param window the window where rendering is displayed + * \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 + * 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. * @@ -236,7 +237,7 @@ extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window * window, * SDL_Window as the final destination and not an SDL_Surface. * * \param surface the SDL_Surface structure representing the surface where - * rendering is done + * rendering is done. * \returns a valid rendering context or NULL if there was an error; call * SDL_GetError() for more information. * @@ -251,7 +252,7 @@ extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateSoftwareRenderer(SDL_Surface * /** * Get the renderer associated with a window. * - * \param window the window to query + * \param window the window to query. * \returns the rendering context on success or NULL on failure; call * SDL_GetError() for more information. * @@ -264,7 +265,7 @@ extern DECLSPEC SDL_Renderer * SDLCALL SDL_GetRenderer(SDL_Window * window); /** * Get the window associated with a renderer. * - * \param renderer the renderer to query + * \param renderer the renderer to query. * \returns the window on success or NULL on failure; call SDL_GetError() for * more information. * @@ -275,9 +276,9 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_RenderGetWindow(SDL_Renderer *renderer) /** * Get information about a rendering context. * - * \param renderer the rendering context + * \param renderer the rendering context. * \param info an SDL_RendererInfo structure filled with information about the - * current renderer + * current renderer. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -295,9 +296,9 @@ extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_Renderer * renderer, * 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 + * \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. * @@ -314,11 +315,11 @@ extern DECLSPEC int SDLCALL SDL_GetRendererOutputSize(SDL_Renderer * renderer, * You can set the texture scaling method by setting * `SDL_HINT_RENDER_SCALE_QUALITY` before creating the texture. * - * \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 + * \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. @@ -347,9 +348,9 @@ extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTexture(SDL_Renderer * renderer, * format of the surface. Use SDL_QueryTexture() to query the pixel format of * the texture. * - * \param renderer the rendering context + * \param renderer the rendering context. * \param surface the SDL_Surface structure containing pixel data used to fill - * the texture + * the texture. * \returns the created texture or NULL on failure; call SDL_GetError() for * more information. * @@ -364,7 +365,7 @@ extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer /** * Query the attributes of a texture. * - * \param texture the texture to query + * \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). This argument @@ -399,10 +400,10 @@ extern DECLSPEC int SDLCALL SDL_QueryTexture(SDL_Texture * texture, * 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 + * \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. * @@ -418,10 +419,10 @@ extern DECLSPEC int SDLCALL SDL_SetTextureColorMod(SDL_Texture * texture, /** * 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. * @@ -445,8 +446,8 @@ extern DECLSPEC int SDLCALL SDL_GetTextureColorMod(SDL_Texture * texture, * 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 + * \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. * @@ -461,8 +462,8 @@ extern DECLSPEC int SDLCALL SDL_SetTextureAlphaMod(SDL_Texture * texture, /** * 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. * @@ -480,8 +481,8 @@ extern DECLSPEC int SDLCALL SDL_GetTextureAlphaMod(SDL_Texture * texture, * If the blend mode is not supported, the closest supported mode is chosen * and this function returns -1. * - * \param texture the texture to update - * \param blendMode the SDL_BlendMode to use for texture blending + * \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. * @@ -496,8 +497,8 @@ extern DECLSPEC int SDLCALL SDL_SetTextureBlendMode(SDL_Texture * texture, /** * Get the blend mode used for texture copy operations. * - * \param texture the texture to query - * \param blendMode a pointer filled in with the current SDL_BlendMode + * \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. * @@ -579,12 +580,12 @@ extern DECLSPEC void * SDLCALL SDL_GetTextureUserData(SDL_Texture * texture); * While this function will work with streaming textures, for optimization * reasons you may not get the pixels back if you lock the texture afterward. * - * \param texture the texture to update + * \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 + * 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 + * between lines. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -606,18 +607,18 @@ extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_Texture * texture, * block of Y and U/V planes in the proper order, but this function is * available if your pixel data is not contiguous. * - * \param texture the texture to update + * \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 + * 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 + * 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 + * 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 + * plane. * \returns 0 on success or -1 if the texture is not valid; call * SDL_GetError() for more information. * @@ -638,7 +639,7 @@ extern DECLSPEC int SDLCALL SDL_UpdateYUVTexture(SDL_Texture * texture, * 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 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. @@ -668,13 +669,13 @@ extern DECLSPEC int SDLCALL SDL_UpdateNVTexture(SDL_Texture * texture, * changes. * * \param texture the texture to lock for access, which was created with - * `SDL_TEXTUREACCESS_STREAMING` + * `SDL_TEXTUREACCESS_STREAMING`. * \param rect an SDL_Rect structure representing the area to lock for access; - * NULL to lock the entire texture + * 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 + * 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 + * 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. @@ -706,13 +707,13 @@ extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_Texture * texture, * or SDL_DestroyTexture(). The caller should not free it. * * \param texture the texture to lock for access, which was created with - * `SDL_TEXTUREACCESS_STREAMING` + * `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 + * NULL, the entire texture will be locked. * \param surface this is filled in with an SDL surface representing the - * locked area + * locked area. * \returns 0 on success, or -1 if the texture is not valid or was not created - * with `SDL_TEXTUREACCESS_STREAMING` + * with `SDL_TEXTUREACCESS_STREAMING`. * * \since This function is available since SDL 2.0.12. * @@ -734,7 +735,7 @@ extern DECLSPEC int SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture, * 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() + * \param texture a texture locked by SDL_LockTexture(). * * \since This function is available since SDL 2.0.0. * @@ -745,7 +746,7 @@ extern DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_Texture * texture); /** * 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. * * \since This function is available since SDL 2.0.0. @@ -763,9 +764,12 @@ extern DECLSPEC SDL_bool SDLCALL SDL_RenderTargetSupported(SDL_Renderer *rendere * * 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`. + * function with a NULL `texture`. This will reset the renderer's viewport, + * clipping rectangle, and scaling settings to the state they were in before + * setting a non-NULL `texture` target, losing any changes made in the + * meantime. * - * \param renderer the rendering context + * \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. @@ -785,7 +789,7 @@ extern DECLSPEC int SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, * The default render target is the window for which the renderer was created, * and is reported a NULL here. * - * \param renderer the rendering context + * \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. @@ -810,9 +814,9 @@ extern DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *renderer * 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 + * \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. * @@ -833,9 +837,9 @@ extern DECLSPEC int SDLCALL SDL_RenderSetLogicalSize(SDL_Renderer * renderer, in * When using a target texture: Never return 0 for `w` and `h` at first. Then * it returns the logical width and height that are set. * - * \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 + * \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. * @@ -850,8 +854,8 @@ extern DECLSPEC void SDLCALL SDL_RenderGetLogicalSize(SDL_Renderer * renderer, i * 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 + * \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. * @@ -866,7 +870,7 @@ extern DECLSPEC int SDLCALL SDL_RenderSetIntegerScale(SDL_Renderer * renderer, /** * 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. * @@ -882,9 +886,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_RenderGetIntegerScale(SDL_Renderer * render * When the window is resized, the viewport is reset to fill the entire new * window size. * - * \param renderer the rendering context + * \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 + * 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. * @@ -898,8 +902,8 @@ extern DECLSPEC int SDLCALL SDL_RenderSetViewport(SDL_Renderer * renderer, /** * Get the drawing area for the current target. * - * \param renderer the rendering context - * \param rect an SDL_Rect structure filled in with the current drawing area + * \param renderer the rendering context. + * \param rect an SDL_Rect structure filled in with the current drawing area. * * \since This function is available since SDL 2.0.0. * @@ -912,9 +916,9 @@ extern DECLSPEC void SDLCALL SDL_RenderGetViewport(SDL_Renderer * renderer, * Set the clip rectangle for rendering on the specified target. * * \param renderer the rendering context for which clip rectangle should be - * set + * set. * \param rect an SDL_Rect structure representing the clip area, relative to - * the viewport, or NULL to disable clipping + * the viewport, or NULL to disable clipping. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -930,9 +934,9 @@ extern DECLSPEC int SDLCALL SDL_RenderSetClipRect(SDL_Renderer * renderer, * Get the clip rectangle for the current target. * * \param renderer the rendering context from which clip rectangle should be - * queried + * queried. * \param rect an SDL_Rect structure filled in with the current clipping area - * or an empty rectangle if clipping is disabled + * or an empty rectangle if clipping is disabled. * * \since This function is available since SDL 2.0.0. * @@ -945,7 +949,7 @@ extern DECLSPEC void SDLCALL SDL_RenderGetClipRect(SDL_Renderer * 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. * @@ -968,9 +972,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_RenderIsClipEnabled(SDL_Renderer * renderer * 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 + * \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. * @@ -985,9 +989,9 @@ extern DECLSPEC int SDLCALL SDL_RenderSetScale(SDL_Renderer * renderer, /** * 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. * * \since This function is available since SDL 2.0.0. * @@ -1004,11 +1008,11 @@ extern DECLSPEC void SDLCALL SDL_RenderGetScale(SDL_Renderer * renderer, * and logical renderer size set * * \param renderer the renderer from which the logical coordinates should be - * calculated - * \param windowX the real X coordinate in the window - * \param windowY the real Y coordinate in the window - * \param logicalX the pointer filled with the logical x coordinate - * \param logicalY the pointer filled with the logical y coordinate + * calculated. + * \param windowX the real X coordinate in the window. + * \param windowY the real Y coordinate in the window. + * \param logicalX the pointer filled with the logical x coordinate. + * \param logicalY the pointer filled with the logical y coordinate. * * \since This function is available since SDL 2.0.18. * @@ -1030,11 +1034,11 @@ extern DECLSPEC void SDLCALL SDL_RenderWindowToLogical(SDL_Renderer * renderer, * and logical renderer size set * * \param renderer the renderer from which the window coordinates should be - * calculated - * \param logicalX the logical x coordinate - * \param logicalY the logical y coordinate - * \param windowX the pointer filled with the real X coordinate in the window - * \param windowY the pointer filled with the real Y coordinate in the window + * calculated. + * \param logicalX the logical x coordinate. + * \param logicalY the logical y coordinate. + * \param windowX the pointer filled with the real X coordinate in the window. + * \param windowY the pointer filled with the real Y coordinate in the window. * * \since This function is available since SDL 2.0.18. * @@ -1053,13 +1057,13 @@ extern DECLSPEC void SDLCALL SDL_RenderLogicalToWindow(SDL_Renderer * renderer, * Set the color for drawing or filling rectangles, lines, and points, and for * SDL_RenderClear(). * - * \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 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 + * specify how the alpha channel is used. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1083,15 +1087,15 @@ extern DECLSPEC int SDLCALL SDL_SetRenderDrawColor(SDL_Renderer * renderer, /** * Get the color used for drawing operations (Rect, Line and Clear). * - * \param renderer the rendering context + * \param renderer the rendering context. * \param r a pointer filled in with the red value used to draw on the - * rendering target + * rendering target. * \param g a pointer filled in with the green value used to draw on the - * rendering target + * rendering target. * \param b a pointer filled in with the blue value used to draw on the - * rendering target + * rendering target. * \param a a pointer filled in with the alpha value used to draw on the - * rendering target; usually `SDL_ALPHA_OPAQUE` (255) + * rendering target; usually `SDL_ALPHA_OPAQUE` (255). * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1108,8 +1112,8 @@ extern DECLSPEC int SDLCALL SDL_GetRenderDrawColor(SDL_Renderer * renderer, * * If the blend mode is not supported, the closest supported mode is chosen. * - * \param renderer the rendering context - * \param blendMode the SDL_BlendMode to use for blending + * \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. * @@ -1131,8 +1135,8 @@ extern DECLSPEC int SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer * renderer, /** * Get the blend mode used for drawing operations. * - * \param renderer the rendering context - * \param blendMode a pointer filled in with the current SDL_BlendMode + * \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. * @@ -1149,7 +1153,7 @@ extern DECLSPEC int SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer * renderer, * This function clears the entire rendering target, ignoring the viewport and * the clip rectangle. * - * \param renderer the rendering context + * \param renderer the rendering context. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1165,9 +1169,9 @@ extern DECLSPEC int SDLCALL SDL_RenderClear(SDL_Renderer * renderer); * SDL_RenderDrawPoint() draws a single point. If you want to draw multiple, * use SDL_RenderDrawPoints() instead. * - * \param renderer the rendering context - * \param x the x coordinate of the point - * \param y the y coordinate of the point + * \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. * @@ -1190,10 +1194,10 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawPoint(SDL_Renderer * renderer, /** * Draw multiple points on the current rendering target. * - * \param renderer the rendering context + * \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 + * 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. * @@ -1220,11 +1224,11 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawPoints(SDL_Renderer * renderer, * SDL_RenderDrawLine() draws the line to include both end points. If you want * to draw multiple, connecting lines use SDL_RenderDrawLines() instead. * - * \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 + * \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. * @@ -1247,10 +1251,10 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawLine(SDL_Renderer * renderer, /** * Draw a series of connected lines on the current rendering target. * - * \param renderer the rendering context + * \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 + * 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. * @@ -1274,9 +1278,9 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawLines(SDL_Renderer * renderer, /** * Draw a rectangle on the current rendering target. * - * \param renderer the rendering context + * \param renderer the rendering context. * \param rect an SDL_Rect structure representing the rectangle to draw, or - * NULL to outline the entire rendering target + * NULL to outline the entire rendering target. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1299,10 +1303,10 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawRect(SDL_Renderer * renderer, /** * Draw some number of rectangles on the current rendering target. * - * \param renderer the rendering context + * \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 + * 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. * @@ -1330,9 +1334,9 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawRects(SDL_Renderer * renderer, * color's alpha value is ignored unless blending is enabled with the * appropriate call to SDL_SetRenderDrawBlendMode(). * - * \param renderer the rendering context + * \param renderer the rendering context. * \param rect the SDL_Rect structure representing the rectangle to fill, or - * NULL for the entire rendering target + * NULL for the entire rendering target. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1356,10 +1360,10 @@ extern DECLSPEC int SDLCALL SDL_RenderFillRect(SDL_Renderer * renderer, * Fill some number of rectangles on the current rendering target with the * drawing color. * - * \param renderer the rendering context + * \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 + * 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. * @@ -1390,12 +1394,13 @@ extern DECLSPEC int SDLCALL SDL_RenderFillRects(SDL_Renderer * renderer, * 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 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 + * given rectangle. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1428,18 +1433,19 @@ extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_Renderer * renderer, * 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 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 + * rendering target. * \param angle an angle in degrees that indicates the rotation that will be - * applied to dstrect, rotating it in a clockwise direction + * 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`) + * around `dstrect.w / 2`, `dstrect.h / 2`). * \param flip a SDL_RendererFlip value stating which flipping actions should - * be performed on the texture + * be performed on the texture. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1465,7 +1471,7 @@ extern DECLSPEC int SDLCALL SDL_RenderCopyEx(SDL_Renderer * renderer, * \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 + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1476,9 +1482,9 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawPointF(SDL_Renderer * renderer, * 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 points The points to draw. + * \param count The number of points to draw. + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1494,7 +1500,7 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawPointsF(SDL_Renderer * renderer, * \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 + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1506,9 +1512,9 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawLineF(SDL_Renderer * renderer, * 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 points The points along the lines. + * \param count The number of points, drawing count-1 lines. + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1522,7 +1528,7 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawLinesF(SDL_Renderer * renderer, * \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 + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1536,7 +1542,7 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawRectF(SDL_Renderer * renderer, * \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 + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1551,7 +1557,7 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawRectsF(SDL_Renderer * renderer, * \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 + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1565,7 +1571,7 @@ extern DECLSPEC int SDLCALL SDL_RenderFillRectF(SDL_Renderer * renderer, * \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 + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1583,7 +1589,7 @@ extern DECLSPEC int SDLCALL SDL_RenderFillRectsF(SDL_Renderer * renderer, * texture. * \param dstrect A pointer to the destination rectangle, or NULL for the * entire rendering target. - * \return 0 on success, or -1 on error + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1603,13 +1609,13 @@ extern DECLSPEC int SDLCALL SDL_RenderCopyF(SDL_Renderer * renderer, * \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 + * 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 + * be performed on the texture. + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1634,7 +1640,7 @@ extern DECLSPEC int SDLCALL SDL_RenderCopyExF(SDL_Renderer * renderer, * array, if NULL all vertices will be rendered in sequential * order. * \param num_indices Number of indices. - * \return 0 on success, or -1 if the operation is not supported + * \return 0 on success, or -1 if the operation is not supported. * * \since This function is available since SDL 2.0.18. * @@ -1653,18 +1659,18 @@ extern DECLSPEC int SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, * * \param renderer The rendering context. * \param texture (optional) The SDL texture to use. - * \param xy Vertex positions - * \param xy_stride Byte size to move from one element to the next element - * \param color Vertex colors (as SDL_Color) - * \param color_stride Byte size to move from one element to the next element - * \param uv Vertex normalized texture coordinates - * \param uv_stride Byte size to move from one element to the next element + * \param xy Vertex positions. + * \param xy_stride Byte size to move from one element to the next element. + * \param color Vertex colors (as SDL_Color). + * \param color_stride Byte size to move from one element to the next element. + * \param uv Vertex normalized texture coordinates. + * \param uv_stride Byte size to move from one element to the next element. * \param num_vertices Number of vertices. * \param indices (optional) An array of indices into the 'vertices' arrays, * if NULL all vertices will be rendered in sequential order. * \param num_indices Number of indices. - * \param size_indices Index size: 1 (byte), 2 (short), 4 (int) - * \return 0 on success, or -1 if the operation is not supported + * \param size_indices Index size: 1 (byte), 2 (short), 4 (int). + * \return 0 on success, or -1 if the operation is not supported. * * \since This function is available since SDL 2.0.18. * @@ -1693,13 +1699,13 @@ extern DECLSPEC int SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer, * but it might contain additional padding (for example, 24bit RGB Windows * Bitmap data pads all rows to multiples of 4 bytes). * - * \param renderer the rendering context + * \param renderer the rendering context. * \param rect an SDL_Rect structure representing the area to read, or NULL - * for the entire render target + * 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 + * 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. * @@ -1729,7 +1735,7 @@ extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Renderer * renderer, * starting each new frame's drawing, even if you plan to overwrite every * pixel. * - * \param renderer the rendering context + * \param renderer the rendering context. * * \threadsafety You may only call this function on the main thread. If this * happens to work on a background thread on any given platform @@ -1738,6 +1744,7 @@ extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Renderer * renderer, * * \since This function is available since SDL 2.0.0. * + * \sa SDL_CreateRenderer * \sa SDL_RenderClear * \sa SDL_RenderDrawLine * \sa SDL_RenderDrawLines @@ -1758,7 +1765,7 @@ extern DECLSPEC void SDLCALL SDL_RenderPresent(SDL_Renderer * renderer); * Passing NULL or an otherwise invalid texture will set the SDL error message * to "Invalid texture". * - * \param texture the texture to destroy + * \param texture the texture to destroy. * * \since This function is available since SDL 2.0.0. * @@ -1773,7 +1780,7 @@ extern DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_Texture * texture); * If `renderer` is NULL, this function will return immediately after setting * the SDL error message to "Invalid renderer". See SDL_GetError(). * - * \param renderer the rendering context + * \param renderer the rendering context. * * \since This function is available since SDL 2.0.0. * @@ -1804,7 +1811,7 @@ extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer * renderer); * and earlier, as earlier versions did not queue rendering commands at all, * instead flushing them to the OS immediately. * - * \param renderer the rendering context + * \param renderer the rendering context. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1835,11 +1842,11 @@ extern DECLSPEC int SDLCALL SDL_RenderFlush(SDL_Renderer * renderer); * 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 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 + * 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 + * 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. * @@ -1855,8 +1862,9 @@ extern DECLSPEC int SDLCALL SDL_GL_BindTexture(SDL_Texture *texture, float *texw * * See SDL_GL_BindTexture() for examples on how to use these functions * - * \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 + * \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. * * \since This function is available since SDL 2.0.0. * @@ -1871,9 +1879,9 @@ extern DECLSPEC int SDLCALL SDL_GL_UnbindTexture(SDL_Texture *texture); * This function returns `void *`, so SDL doesn't have to include Metal's * headers, but it can be safely cast to a `CAMetalLayer *`. * - * \param renderer The renderer to query + * \param renderer The renderer to query. * \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a - * Metal renderer + * Metal renderer. * * \since This function is available since SDL 2.0.8. * @@ -1892,7 +1900,7 @@ extern DECLSPEC void *SDLCALL SDL_RenderGetMetalLayer(SDL_Renderer * renderer); * hidden/minimized/offscreen. This doesn't apply to command encoders for * render targets, just the window's backbuffer. Check your return values! * - * \param renderer The renderer to query + * \param renderer The renderer to query. * \returns an `id<MTLRenderCommandEncoder>` on success, or NULL if the * renderer isn't a Metal renderer or there was an error. * @@ -1905,9 +1913,9 @@ extern DECLSPEC void *SDLCALL SDL_RenderGetMetalCommandEncoder(SDL_Renderer * re /** * Toggle VSync of the given renderer. * - * \param renderer The renderer to toggle - * \param vsync 1 for on, 0 for off. All other values are reserved - * \returns a 0 int on success, or non-zero on failure + * \param renderer The renderer to toggle. + * \param vsync 1 for on, 0 for off. All other values are reserved. + * \returns a 0 int on success, or non-zero on failure. * * \since This function is available since SDL 2.0.18. */ diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_rwops.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_rwops.h @@ -19,11 +19,13 @@ 3. This notice may not be removed or altered from any source distribution. */ +/* WIKI CATEGORY: RWOPS */ + /** - * \file SDL_rwops.h + * # CategoryRWOPS * - * This file provides a general interface for SDL to read and write - * data streams. It can easily be extended to files, memory, etc. + * This file provides a general interface for SDL to read and write data + * streams. It can easily be extended to files, memory, etc. */ #ifndef SDL_rwops_h_ @@ -57,7 +59,7 @@ typedef struct SDL_RWops Sint64 (SDLCALL * size) (struct SDL_RWops * context); /** - * Seek to \c offset relative to \c whence, one of stdio's whence values: + * Seek to `offset` relative to `whence`, one of stdio's whence values: * RW_SEEK_SET, RW_SEEK_CUR, RW_SEEK_END * * \return the final offset in the data stream, or -1 on error. @@ -66,8 +68,8 @@ typedef struct SDL_RWops int whence); /** - * Read up to \c maxnum objects each of size \c size from the data - * stream to the area pointed at by \c ptr. + * Read up to `maxnum` objects each of size `size` from the data + * stream to the area pointed at by `ptr`. * * \return the number of objects read, or 0 at error or end of file. */ @@ -75,8 +77,8 @@ typedef struct SDL_RWops 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 exactly `num` objects each of size `size` from the area + * pointed at by `ptr` to data stream. * * \return the number of objects written, or 0 at error or end of file. */ @@ -186,7 +188,7 @@ typedef struct SDL_RWops * * Closing the SDL_RWops will close the file handle SDL is holding internally. * - * \param file a UTF-8 string representing the filename to open + * \param file a UTF-8 string representing the filename to open. * \param mode an ASCII string representing the mode to be used for opening * the file. * \returns a pointer to the SDL_RWops structure that is created, or NULL on @@ -224,10 +226,10 @@ extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFP(FILE * fp, SDL_bool autoclose); * `FILE*`, depending on what system headers are available to SDL. It is * always intended to be the `FILE*` type from the C runtime's stdio.h. * - * \param fp the `FILE*` that feeds the SDL_RWops stream + * \param fp the `FILE*` that feeds the SDL_RWops stream. * \param autoclose SDL_TRUE to close the `FILE*` when closing the SDL_RWops, * SDL_FALSE to leave the `FILE*` open when the RWops is - * closed + * closed. * \returns a pointer to the SDL_RWops structure that is created, or NULL on * failure; call SDL_GetError() for more information. * @@ -260,8 +262,8 @@ extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFP(void * fp, * If you need to make sure the RWops never writes to the memory buffer, you * should use SDL_RWFromConstMem() with a read-only buffer of memory instead. * - * \param mem a pointer to a buffer to feed an SDL_RWops stream - * \param size the buffer size, in bytes + * \param mem a pointer to a buffer to feed an SDL_RWops stream. + * \param size the buffer size, in bytes. * \returns a pointer to a new SDL_RWops structure, or NULL if it fails; call * SDL_GetError() for more information. * @@ -295,8 +297,8 @@ extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromMem(void *mem, int size); * If you need to write to a memory buffer, you should use SDL_RWFromMem() * with a writable buffer of memory instead. * - * \param mem a pointer to a read-only buffer to feed an SDL_RWops stream - * \param size the buffer size, in bytes + * \param mem a pointer to a read-only buffer to feed an SDL_RWops stream. + * \param size the buffer size, in bytes. * \returns a pointer to a new SDL_RWops structure, or NULL if it fails; call * SDL_GetError() for more information. * @@ -358,7 +360,7 @@ extern DECLSPEC SDL_RWops *SDLCALL SDL_AllocRW(void); * creation of the SDL_RWops is not freed by SDL_FreeRW(); the programmer must * be responsible for managing that memory in their **close** method. * - * \param area the SDL_RWops structure to be freed + * \param area the SDL_RWops structure to be freed. * * \since This function is available since SDL 2.0.0. * @@ -366,6 +368,7 @@ extern DECLSPEC SDL_RWops *SDLCALL SDL_AllocRW(void); */ extern DECLSPEC void SDLCALL SDL_FreeRW(SDL_RWops * area); +/* Possible `whence` values for SDL_RWops seeking... */ #define RW_SEEK_SET 0 /**< Seek from the beginning of data */ #define RW_SEEK_CUR 1 /**< Seek relative to current read point */ #define RW_SEEK_END 2 /**< Seek relative to the end of data */ @@ -375,7 +378,7 @@ extern DECLSPEC void SDLCALL SDL_FreeRW(SDL_RWops * area); * * Prior to SDL 2.0.10, this function was a macro. * - * \param context the SDL_RWops to get the size of the data stream from + * \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. @@ -402,10 +405,10 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWsize(SDL_RWops *context); * * Prior to SDL 2.0.10, this function was a macro. * - * \param context a pointer to an SDL_RWops structure + * \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` + * 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. * * \since This function is available since SDL 2.0.10. @@ -432,7 +435,7 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWseek(SDL_RWops *context, * Prior to SDL 2.0.10, this function was a macro. * * \param context a SDL_RWops data stream object from which to get the current - * offset + * offset. * \returns the current offset in the stream, or -1 if the information can not * be determined. * @@ -462,10 +465,10 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWtell(SDL_RWops *context); * * Prior to SDL 2.0.10, this function was a macro. * - * \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 + * \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. * @@ -496,10 +499,10 @@ extern DECLSPEC size_t SDLCALL SDL_RWread(SDL_RWops *context, * * Prior to SDL 2.0.10, this function was a macro. * - * \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 + * \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. * @@ -530,7 +533,7 @@ extern DECLSPEC size_t SDLCALL SDL_RWwrite(SDL_RWops *context, * * Prior to SDL 2.0.10, this function was a macro. * - * \param context SDL_RWops structure to close + * \param context SDL_RWops structure to close. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -555,9 +558,9 @@ extern DECLSPEC int SDLCALL SDL_RWclose(SDL_RWops *context); * * The data should be freed with SDL_free(). * - * \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 + * \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. * * \since This function is available since SDL 2.0.6. @@ -578,8 +581,8 @@ extern DECLSPEC void *SDLCALL SDL_LoadFile_RW(SDL_RWops *src, * Prior to SDL 2.0.10, this function was a macro wrapping around * SDL_LoadFile_RW. * - * \param file the path to read all available data from - * \param datasize if not NULL, will store the number of bytes read + * \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. * * \since This function is available since SDL 2.0.10. @@ -596,7 +599,7 @@ extern DECLSPEC void *SDLCALL SDL_LoadFile(const char *file, size_t *datasize); /** * Use this function to read a byte from an SDL_RWops. * - * \param src the SDL_RWops to read from + * \param src the SDL_RWops to read from. * \returns the read byte on success or 0 on failure; call SDL_GetError() for * more information. * @@ -613,7 +616,7 @@ extern DECLSPEC Uint8 SDLCALL SDL_ReadU8(SDL_RWops * src); * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * - * \param src the stream from which to read data + * \param src the stream from which to read data. * \returns 16 bits of data in the native byte order of the platform. * * \since This function is available since SDL 2.0.0. @@ -629,7 +632,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_ReadLE16(SDL_RWops * src); * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * - * \param src the stream from which to read data + * \param src the stream from which to read data. * \returns 16 bits of data in the native byte order of the platform. * * \since This function is available since SDL 2.0.0. @@ -645,7 +648,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_ReadBE16(SDL_RWops * src); * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * - * \param src the stream from which to read data + * \param src the stream from which to read data. * \returns 32 bits of data in the native byte order of the platform. * * \since This function is available since SDL 2.0.0. @@ -661,7 +664,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_ReadLE32(SDL_RWops * src); * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * - * \param src the stream from which to read data + * \param src the stream from which to read data. * \returns 32 bits of data in the native byte order of the platform. * * \since This function is available since SDL 2.0.0. @@ -677,7 +680,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_ReadBE32(SDL_RWops * src); * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * - * \param src the stream from which to read data + * \param src the stream from which to read data. * \returns 64 bits of data in the native byte order of the platform. * * \since This function is available since SDL 2.0.0. @@ -693,7 +696,7 @@ extern DECLSPEC Uint64 SDLCALL SDL_ReadLE64(SDL_RWops * src); * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * - * \param src the stream from which to read data + * \param src the stream from which to read data. * \returns 64 bits of data in the native byte order of the platform. * * \since This function is available since SDL 2.0.0. @@ -713,8 +716,8 @@ extern DECLSPEC Uint64 SDLCALL SDL_ReadBE64(SDL_RWops * src); /** * Use this function to write a byte to an SDL_RWops. * - * \param dst the SDL_RWops to write to - * \param value the byte value to write + * \param dst the SDL_RWops to write to. + * \param value the byte value to write. * \returns 1 on success or 0 on failure; call SDL_GetError() for more * information. * @@ -732,8 +735,8 @@ extern DECLSPEC size_t SDLCALL SDL_WriteU8(SDL_RWops * dst, Uint8 value); * specifies native format, and the data written will be in little-endian * format. * - * \param dst the stream to which data will be written - * \param value the data to be written, in native format + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. * \returns 1 on successful write, 0 on error. * * \since This function is available since SDL 2.0.0. @@ -749,8 +752,8 @@ extern DECLSPEC size_t SDLCALL SDL_WriteLE16(SDL_RWops * dst, Uint16 value); * SDL byteswaps the data only if necessary, so the application always * specifies native format, and the data written will be in big-endian format. * - * \param dst the stream to which data will be written - * \param value the data to be written, in native format + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. * \returns 1 on successful write, 0 on error. * * \since This function is available since SDL 2.0.0. @@ -767,8 +770,8 @@ extern DECLSPEC size_t SDLCALL SDL_WriteBE16(SDL_RWops * dst, Uint16 value); * specifies native format, and the data written will be in little-endian * format. * - * \param dst the stream to which data will be written - * \param value the data to be written, in native format + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. * \returns 1 on successful write, 0 on error. * * \since This function is available since SDL 2.0.0. @@ -784,8 +787,8 @@ extern DECLSPEC size_t SDLCALL SDL_WriteLE32(SDL_RWops * dst, Uint32 value); * SDL byteswaps the data only if necessary, so the application always * specifies native format, and the data written will be in big-endian format. * - * \param dst the stream to which data will be written - * \param value the data to be written, in native format + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. * \returns 1 on successful write, 0 on error. * * \since This function is available since SDL 2.0.0. @@ -802,8 +805,8 @@ extern DECLSPEC size_t SDLCALL SDL_WriteBE32(SDL_RWops * dst, Uint32 value); * specifies native format, and the data written will be in little-endian * format. * - * \param dst the stream to which data will be written - * \param value the data to be written, in native format + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. * \returns 1 on successful write, 0 on error. * * \since This function is available since SDL 2.0.0. @@ -819,8 +822,8 @@ extern DECLSPEC size_t SDLCALL SDL_WriteLE64(SDL_RWops * dst, Uint64 value); * SDL byteswaps the data only if necessary, so the application always * specifies native format, and the data written will be in big-endian format. * - * \param dst the stream to which data will be written - * \param value the data to be written, in native format + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. * \returns 1 on successful write, 0 on error. * * \since This function is available since SDL 2.0.0. diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_scancode.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_scancode.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_scancode.h + * # CategoryScancode * - * Defines keyboard scancodes. + * Defines keyboard scancodes. */ #ifndef SDL_scancode_h_ @@ -31,16 +31,16 @@ #include <SDL2/SDL_stdinc.h> /** - * \brief The SDL keyboard scancode representation. + * The SDL keyboard scancode representation. * - * Values of this type are used to represent keyboard keys, among other places - * in the \link SDL_Keysym::scancode key.keysym.scancode \endlink field of the - * SDL_Event structure. + * Values of this type are used to represent keyboard keys, among other places + * in the SDL_Keysym::scancode key.keysym.scancode field of the SDL_Event + * structure. * - * The values in this enumeration are based on the USB usage page standard: - * https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf + * The values in this enumeration are based on the USB usage page standard: + * https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf */ -typedef enum +typedef enum SDL_Scancode { SDL_SCANCODE_UNKNOWN = 0, diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_sensor.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_sensor.h @@ -20,10 +20,9 @@ */ /** - * \file SDL_sensor.h - * - * Include file for SDL sensor event handling + * # CategorySensor * + * Include file for SDL sensor event handling */ #ifndef SDL_sensor_h_ @@ -44,7 +43,7 @@ extern "C" { * \brief SDL_sensor.h * * In order to use these functions, SDL_Init() must have been called - * with the ::SDL_INIT_SENSOR flag. This causes SDL to scan the system + * with the SDL_INIT_SENSOR flag. This causes SDL to scan the system * for sensors, and load appropriate drivers. */ @@ -52,21 +51,67 @@ struct _SDL_Sensor; typedef struct _SDL_Sensor SDL_Sensor; /** - * This is a unique ID for a sensor for the time it is connected to the system, - * and is never reused for the lifetime of the application. + * This is a unique ID for a sensor for the time it is connected to the + * system, and is never reused for the lifetime of the application. * - * The ID value starts at 0 and increments from there. The value -1 is an invalid ID. + * The ID value starts at 0 and increments from there. The value -1 is an + * invalid ID. */ typedef Sint32 SDL_SensorID; -/* The different sensors defined by SDL +/** + * The different sensors defined by SDL. * * Additional sensors may be available, using platform dependent semantics. * - * Hare are the additional Android sensors: + * Here are the additional Android sensors: + * * https://developer.android.com/reference/android/hardware/SensorEvent.html#values + * + * Accelerometer sensor notes: + * + * The accelerometer returns the current acceleration in SI meters per second + * squared. This measurement includes the force of gravity, so a device at + * rest will have an value of SDL_STANDARD_GRAVITY away from the center of the + * earth, which is a positive Y value. + * + * - `values[0]`: Acceleration on the x axis + * - `values[1]`: Acceleration on the y axis + * - `values[2]`: Acceleration on the z axis + * + * For phones and tablets held in natural orientation and game controllers + * held in front of you, the axes are defined as follows: + * + * - -X ... +X : left ... right + * - -Y ... +Y : bottom ... top + * - -Z ... +Z : farther ... closer + * + * The accelerometer axis data is not changed when the device is rotated. + * + * Gyroscope sensor notes: + * + * The gyroscope returns the current rate of rotation in radians per second. + * The rotation is positive in the counter-clockwise direction. That is, an + * observer looking from a positive location on one of the axes would see + * positive rotation on that axis when it appeared to be rotating + * counter-clockwise. + * + * - `values[0]`: Angular speed around the x axis (pitch) + * - `values[1]`: Angular speed around the y axis (yaw) + * - `values[2]`: Angular speed around the z axis (roll) + * + * For phones and tablets held in natural orientation and game controllers + * held in front of you, the axes are defined as follows: + * + * - -X ... +X : left ... right + * - -Y ... +Y : bottom ... top + * - -Z ... +Z : farther ... closer + * + * The gyroscope axis data is not changed when the device is rotated. + * + * \sa SDL_GetDisplayOrientation */ -typedef enum +typedef enum SDL_SensorType { SDL_SENSOR_INVALID = -1, /**< Returned for an invalid sensor */ SDL_SENSOR_UNKNOWN, /**< Unknown sensor type */ @@ -79,52 +124,14 @@ typedef enum } SDL_SensorType; /** - * Accelerometer sensor - * - * The accelerometer returns the current acceleration in SI meters per - * second squared. This measurement includes the force of gravity, so - * a device at rest will have an value of SDL_STANDARD_GRAVITY away - * from the center of the earth, which is a positive Y value. - * - * values[0]: Acceleration on the x axis - * values[1]: Acceleration on the y axis - * values[2]: Acceleration on the z axis - * - * For phones held in portrait mode and game controllers held in front of you, - * the axes are defined as follows: - * -X ... +X : left ... right - * -Y ... +Y : bottom ... top - * -Z ... +Z : farther ... closer - * - * The axis data is not changed when the phone is rotated. - * - * \sa SDL_GetDisplayOrientation() - */ -#define SDL_STANDARD_GRAVITY 9.80665f - -/** - * Gyroscope sensor - * - * The gyroscope returns the current rate of rotation in radians per second. - * The rotation is positive in the counter-clockwise direction. That is, - * an observer looking from a positive location on one of the axes would - * see positive rotation on that axis when it appeared to be rotating - * counter-clockwise. + * A constant to represent standard gravity for accelerometer sensors. * - * values[0]: Angular speed around the x axis (pitch) - * values[1]: Angular speed around the y axis (yaw) - * values[2]: Angular speed around the z axis (roll) - * - * For phones held in portrait mode and game controllers held in front of you, - * the axes are defined as follows: - * -X ... +X : left ... right - * -Y ... +Y : bottom ... top - * -Z ... +Z : farther ... closer - * - * The axis data is not changed when the phone or controller is rotated. - * - * \sa SDL_GetDisplayOrientation() + * The accelerometer returns the current acceleration in SI meters per second + * squared. This measurement includes the force of gravity, so a device at + * rest will have an value of SDL_STANDARD_GRAVITY away from the center of the + * earth, which is a positive Y value. */ +#define SDL_STANDARD_GRAVITY 9.80665f /* Function prototypes */ @@ -155,7 +162,7 @@ extern DECLSPEC int SDLCALL SDL_NumSensors(void); /** * Get the implementation dependent name of a sensor. * - * \param device_index The sensor to obtain name from + * \param device_index The sensor to obtain name from. * \returns the sensor name, or NULL if `device_index` is out of range. * * \since This function is available since SDL 2.0.9. @@ -165,7 +172,7 @@ extern DECLSPEC const char *SDLCALL SDL_SensorGetDeviceName(int device_index); /** * Get the type of a sensor. * - * \param device_index The sensor to get the type from + * \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. * @@ -176,7 +183,7 @@ extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetDeviceType(int device_index) /** * Get the platform dependent type of a sensor. * - * \param device_index The sensor to check + * \param device_index The sensor to check. * \returns the sensor platform dependent type, or -1 if `device_index` is out * of range. * @@ -187,7 +194,7 @@ extern DECLSPEC int SDLCALL SDL_SensorGetDeviceNonPortableType(int device_index) /** * Get the instance ID of a sensor. * - * \param device_index The sensor to get instance id from + * \param device_index The sensor to get instance id from. * \returns the sensor instance ID, or -1 if `device_index` is out of range. * * \since This function is available since SDL 2.0.9. @@ -197,7 +204,7 @@ extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetDeviceInstanceID(int device_in /** * Open a sensor for use. * - * \param device_index The sensor to open + * \param device_index The sensor to open. * \returns an SDL_Sensor sensor object, or NULL if an error occurred. * * \since This function is available since SDL 2.0.9. @@ -207,7 +214,7 @@ 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 + * \param instance_id The sensor from instance id. * \returns an SDL_Sensor object. * * \since This function is available since SDL 2.0.9. @@ -217,7 +224,7 @@ extern DECLSPEC SDL_Sensor *SDLCALL SDL_SensorFromInstanceID(SDL_SensorID instan /** * Get the implementation dependent name of a sensor * - * \param sensor The SDL_Sensor object + * \param sensor The SDL_Sensor object. * \returns the sensor name, or NULL if `sensor` is NULL. * * \since This function is available since SDL 2.0.9. @@ -227,7 +234,7 @@ extern DECLSPEC const char *SDLCALL SDL_SensorGetName(SDL_Sensor *sensor); /** * Get the type of a sensor. * - * \param sensor The SDL_Sensor object to inspect + * \param sensor The SDL_Sensor object to inspect. * \returns the SDL_SensorType type, or `SDL_SENSOR_INVALID` if `sensor` is * NULL. * @@ -238,7 +245,7 @@ extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetType(SDL_Sensor *sensor); /** * Get the platform dependent type of a sensor. * - * \param sensor The SDL_Sensor object to inspect + * \param sensor The SDL_Sensor object to inspect. * \returns the sensor platform dependent type, or -1 if `sensor` is NULL. * * \since This function is available since SDL 2.0.9. @@ -248,7 +255,7 @@ extern DECLSPEC int SDLCALL SDL_SensorGetNonPortableType(SDL_Sensor *sensor); /** * Get the instance ID of a sensor. * - * \param sensor The SDL_Sensor object to inspect + * \param sensor The SDL_Sensor object to inspect. * \returns the sensor instance ID, or -1 if `sensor` is NULL. * * \since This function is available since SDL 2.0.9. @@ -260,9 +267,9 @@ extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetInstanceID(SDL_Sensor *sensor) * * The number of values and interpretation of the data is sensor dependent. * - * \param sensor The 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 + * \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. * * \since This function is available since SDL 2.0.9. @@ -275,11 +282,11 @@ extern DECLSPEC int SDLCALL SDL_SensorGetData(SDL_Sensor *sensor, float *data, i * * The number of values and interpretation of the data is sensor dependent. * - * \param sensor The SDL_Sensor object to query + * \param sensor The SDL_Sensor object to query. * \param timestamp A pointer filled with the timestamp in microseconds of the - * current sensor reading if available, or 0 if not - * \param data A pointer filled with the current sensor state - * \param num_values The number of values to write to data + * current sensor reading if available, or 0 if not. + * \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. * * \since This function is available since SDL 2.26.0. @@ -289,7 +296,7 @@ extern DECLSPEC int SDLCALL SDL_SensorGetDataWithTimestamp(SDL_Sensor *sensor, U /** * Close a sensor previously opened with SDL_SensorOpen(). * - * \param sensor The SDL_Sensor object to close + * \param sensor The SDL_Sensor object to close. * * \since This function is available since SDL 2.0.9. */ diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_shape.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_shape.h @@ -48,18 +48,18 @@ extern "C" { * 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 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. * \param h The height of the window. * \param flags The flags for the window, a mask of SDL_WINDOW_BORDERLESS with - * any of the following: ::SDL_WINDOW_OPENGL, - * ::SDL_WINDOW_INPUT_GRABBED, ::SDL_WINDOW_HIDDEN, - * ::SDL_WINDOW_RESIZABLE, ::SDL_WINDOW_MAXIMIZED, - * ::SDL_WINDOW_MINIMIZED, ::SDL_WINDOW_BORDERLESS is always set, - * and ::SDL_WINDOW_FULLSCREEN is always unset. + * any of the following: SDL_WINDOW_OPENGL, + * SDL_WINDOW_INPUT_GRABBED, SDL_WINDOW_HIDDEN, + * SDL_WINDOW_RESIZABLE, SDL_WINDOW_MAXIMIZED, + * SDL_WINDOW_MINIMIZED, SDL_WINDOW_BORDERLESS is always set, and + * SDL_WINDOW_FULLSCREEN is always unset. * \return the window created, or NULL if window creation failed. * * \since This function is available since SDL 2.0.0. diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_stdinc.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_stdinc.h @@ -19,10 +19,12 @@ 3. This notice may not be removed or altered from any source distribution. */ +/* WIKI CATEGORY: StdInc */ + /** - * \file SDL_stdinc.h + * # CategoryStdInc * - * This is a general header that includes C language support. + * This is a general header that includes C language support. */ #ifndef SDL_stdinc_h_ @@ -129,15 +131,19 @@ void *alloca(size_t); #endif /** - * The number of elements in an array. + * The number of elements in an array. */ #define SDL_arraysize(array) (sizeof(array)/sizeof(array[0])) #define SDL_TABLESIZE(table) SDL_arraysize(table) /** - * Macro useful for building other macros with strings in them + * Macro useful for building other macros with strings in them + * + * e.g: * - * e.g. #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n") + * ```c + * #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n") + * ``` */ #define SDL_STRINGIFY_ARG(arg) #arg @@ -185,54 +191,61 @@ typedef enum #endif /** - * \brief A signed 8-bit integer type. + * A signed 8-bit integer type. */ +typedef int8_t Sint8; #define SDL_MAX_SINT8 ((Sint8)0x7F) /* 127 */ #define SDL_MIN_SINT8 ((Sint8)(~0x7F)) /* -128 */ -typedef int8_t Sint8; + /** - * \brief An unsigned 8-bit integer type. + * An unsigned 8-bit integer type. */ +typedef uint8_t Uint8; #define SDL_MAX_UINT8 ((Uint8)0xFF) /* 255 */ #define SDL_MIN_UINT8 ((Uint8)0x00) /* 0 */ -typedef uint8_t Uint8; + /** - * \brief A signed 16-bit integer type. + * A signed 16-bit integer type. */ +typedef int16_t Sint16; #define SDL_MAX_SINT16 ((Sint16)0x7FFF) /* 32767 */ #define SDL_MIN_SINT16 ((Sint16)(~0x7FFF)) /* -32768 */ -typedef int16_t Sint16; + /** - * \brief An unsigned 16-bit integer type. + * An unsigned 16-bit integer type. */ +typedef uint16_t Uint16; #define SDL_MAX_UINT16 ((Uint16)0xFFFF) /* 65535 */ #define SDL_MIN_UINT16 ((Uint16)0x0000) /* 0 */ -typedef uint16_t Uint16; + /** - * \brief A signed 32-bit integer type. + * A signed 32-bit integer type. */ +typedef int32_t Sint32; #define SDL_MAX_SINT32 ((Sint32)0x7FFFFFFF) /* 2147483647 */ #define SDL_MIN_SINT32 ((Sint32)(~0x7FFFFFFF)) /* -2147483648 */ -typedef int32_t Sint32; + /** - * \brief An unsigned 32-bit integer type. + * An unsigned 32-bit integer type. */ +typedef uint32_t Uint32; #define SDL_MAX_UINT32 ((Uint32)0xFFFFFFFFu) /* 4294967295 */ #define SDL_MIN_UINT32 ((Uint32)0x00000000) /* 0 */ -typedef uint32_t Uint32; /** - * \brief A signed 64-bit integer type. + * A signed 64-bit integer type. */ +typedef int64_t Sint64; #define SDL_MAX_SINT64 ((Sint64)0x7FFFFFFFFFFFFFFFll) /* 9223372036854775807 */ #define SDL_MIN_SINT64 ((Sint64)(~0x7FFFFFFFFFFFFFFFll)) /* -9223372036854775808 */ -typedef int64_t Sint64; + /** - * \brief An unsigned 64-bit integer type. + * An unsigned 64-bit integer type. */ +typedef uint64_t Uint64; #define SDL_MAX_UINT64 ((Uint64)0xFFFFFFFFFFFFFFFFull) /* 18446744073709551615 */ #define SDL_MIN_UINT64 ((Uint64)(0x0000000000000000ull)) /* 0 */ -typedef uint64_t Uint64; + /* @} *//* Basic data types */ @@ -415,8 +428,8 @@ SDL_COMPILE_TIME_ASSERT(sint64, sizeof(Sint64) == 8); /** \cond */ #ifndef DOXYGEN_SHOULD_IGNORE_THIS -#if !defined(__ANDROID__) && !defined(__VITA__) && !defined(__3DS__) - /* TODO: include/SDL_stdinc.h:174: error: size of array 'SDL_dummy_enum' is negative */ +#if !defined(__VITA__) && !defined(__3DS__) +/* TODO: include/SDL_stdinc.h:422: error: size of array 'SDL_dummy_enum' is negative */ typedef enum { DUMMY_ENUM_VALUE @@ -491,8 +504,9 @@ extern DECLSPEC int SDLCALL SDL_GetNumAllocations(void); extern DECLSPEC char *SDLCALL SDL_getenv(const char *name); extern DECLSPEC int SDLCALL SDL_setenv(const char *name, const char *value, int overwrite); -extern DECLSPEC void SDLCALL SDL_qsort(void *base, size_t nmemb, size_t size, int (SDLCALL *compare) (const void *, const void *)); -extern DECLSPEC void * SDLCALL SDL_bsearch(const void *key, const void *base, size_t nmemb, size_t size, int (SDLCALL *compare) (const void *, const void *)); +typedef int (SDLCALL *SDL_CompareCallback)(const void *, const void *); +extern DECLSPEC void SDLCALL SDL_qsort(void *base, size_t nmemb, size_t size, SDL_CompareCallback compare); +extern DECLSPEC void * SDLCALL SDL_bsearch(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback compare); extern DECLSPEC int SDLCALL SDL_abs(int x); @@ -521,6 +535,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_crc32(Uint32 crc, const void *data, size_t le extern DECLSPEC void *SDLCALL SDL_memset(SDL_OUT_BYTECAP(len) void *dst, int c, size_t len); +/* Some safe(r) macros for zero'ing structures... */ #define SDL_zero(x) SDL_memset(&(x), 0, sizeof((x))) #define SDL_zerop(x) SDL_memset((x), 0, sizeof(*(x))) #define SDL_zeroa(x) SDL_memset((x), 0, sizeof((x))) @@ -706,6 +721,8 @@ extern DECLSPEC char *SDLCALL SDL_iconv_string(const char *tocode, const char *fromcode, const char *inbuf, size_t inbytesleft); + +/* Some helper macros for common cases... */ #define SDL_iconv_utf8_locale(S) SDL_iconv_string("", "UTF-8", S, SDL_strlen(S)+1) #define SDL_iconv_utf8_ucs2(S) (Uint16 *)SDL_iconv_string("UCS-2", "UTF-8", S, SDL_strlen(S)+1) #define SDL_iconv_utf8_ucs4(S) (Uint32 *)SDL_iconv_string("UCS-4", "UTF-8", S, SDL_strlen(S)+1) @@ -733,6 +750,9 @@ size_t wcslcpy(wchar_t *dst, const wchar_t *src, size_t size); size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size); #endif +/* strdup is not ANSI but POSIX, and its prototype might be hidden... */ +char *strdup(const char *str); + /* Starting LLVM 16, the analyser errors out if these functions do not have their prototype defined (clang-diagnostic-implicit-function-declaration) */ #include <stdlib.h> @@ -778,8 +798,9 @@ SDL_FORCE_INLINE void *SDL_memcpy4(SDL_OUT_BYTECAP(dwords*4) void *dst, SDL_IN_B } /** - * If a * b would overflow, return -1. Otherwise store a * b via ret - * and return 0. + * If a * b would overflow, return -1. + * + * Otherwise store a * b via ret and return 0. * * \since This function is available since SDL 2.24.0. */ @@ -808,8 +829,9 @@ SDL_FORCE_INLINE int _SDL_size_mul_overflow_builtin (size_t a, #endif /** - * If a + b would overflow, return -1. Otherwise store a + b via ret - * and return 0. + * If a + b would overflow, return -1. + * + * Otherwise store a + b via ret and return 0. * * \since This function is available since SDL 2.24.0. */ diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_surface.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_surface.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_surface.h + * # CategorySurface * - * Header file for ::SDL_Surface definition and management functions. + * Header file for SDL_Surface definition and management functions. */ #ifndef SDL_surface_h_ @@ -43,7 +43,7 @@ extern "C" { /** * \name Surface flags * - * These are the currently supported flags for the ::SDL_Surface. + * These are the currently supported flags for the SDL_Surface. * * \internal * Used internally (read-only). @@ -57,17 +57,17 @@ extern "C" { /* @} *//* Surface flags */ /** - * Evaluates to true if the surface needs to be locked before access. + * Evaluates to true if the surface needs to be locked before access. */ #define SDL_MUSTLOCK(S) (((S)->flags & SDL_RLEACCEL) != 0) typedef struct SDL_BlitMap SDL_BlitMap; /* this is an opaque type. */ /** - * \brief A collection of pixels used in software blitting. + * A collection of pixels used in software blitting. * - * \note This structure should be treated as read-only, except for \c pixels, - * which, if not NULL, contains the raw pixel data for the surface. + * This structure should be treated as read-only, except for `pixels`, which, + * if not NULL, contains the raw pixel data for the surface. */ typedef struct SDL_Surface { @@ -97,15 +97,15 @@ typedef struct SDL_Surface } SDL_Surface; /** - * \brief The type of function used for surface blitting functions. + * The type of function used for surface blitting functions. */ typedef int (SDLCALL *SDL_blit) (struct SDL_Surface * src, SDL_Rect * srcrect, struct SDL_Surface * dst, SDL_Rect * dstrect); /** - * \brief The formula used for converting between YUV and RGB + * The formula used for converting between YUV and RGB */ -typedef enum +typedef enum SDL_YUV_CONVERSION_MODE { SDL_YUV_CONVERSION_JPEG, /**< Full range JPEG */ SDL_YUV_CONVERSION_BT601, /**< BT.601 (the default) */ @@ -140,14 +140,14 @@ typedef enum * 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 + * \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. * @@ -171,10 +171,10 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface * 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 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. @@ -198,15 +198,15 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceWithFormat * 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 + * \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. * @@ -214,6 +214,7 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceWithFormat * * \sa SDL_CreateRGBSurface * \sa SDL_CreateRGBSurfaceWithFormat + * \sa SDL_CreateRGBSurfaceWithFormatFrom * \sa SDL_FreeSurface */ extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels, @@ -239,11 +240,11 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels, * 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 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. @@ -278,8 +279,8 @@ extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface); * * 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 + * \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. * @@ -300,7 +301,7 @@ extern DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface * surface, * 0, then you can read and write to the surface at any time, and the pixel * format of the surface will not change. * - * \param surface the SDL_Surface structure to be locked + * \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. * @@ -314,7 +315,7 @@ extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface); /** * Release a surface after directly accessing the pixels. * - * \param surface the SDL_Surface structure to be unlocked + * \param surface the SDL_Surface structure to be unlocked. * * \since This function is available since SDL 2.0.0. * @@ -329,11 +330,11 @@ extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface); * result in a memory leak. * * src is an open SDL_RWops buffer, typically loaded with SDL_RWFromFile. - * Alternitavely, you might also use the macro SDL_LoadBMP to load a bitmap + * Alternatively, you might also use the macro SDL_LoadBMP to load a bitmap * from a file, convert it to an SDL_Surface and then close the file. * - * \param src the data stream for the surface - * \param freesrc non-zero to close the stream after being read + * \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. * @@ -363,9 +364,9 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src, * surface before they are saved. YUV and paletted 1-bit and 4-bit formats are * not supported. * - * \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 + * \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. * @@ -378,9 +379,9 @@ extern DECLSPEC int SDLCALL SDL_SaveBMP_RW (SDL_Surface * surface, SDL_RWops * dst, int freedst); /** - * Save a surface to a file. + * Save a surface to a file. * - * Convenience macro. + * Convenience macro. */ #define SDL_SaveBMP(surface, file) \ SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1) @@ -391,8 +392,8 @@ extern DECLSPEC int SDLCALL SDL_SaveBMP_RW * If RLE is enabled, color key 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 + * \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. * @@ -410,7 +411,7 @@ extern DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface * surface, * * It is safe to pass a NULL `surface` here; it will return SDL_FALSE. * - * \param surface the SDL_Surface structure to query + * \param surface the SDL_Surface structure to query. * \returns SDL_TRUE if the surface is RLE enabled, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.14. @@ -432,9 +433,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasSurfaceRLE(SDL_Surface * surface); * RLE acceleration can substantially speed up blitting of images with large * horizontal runs of transparent pixels. See SDL_SetSurfaceRLE() for details. * - * \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 + * \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. * @@ -451,7 +452,7 @@ extern DECLSPEC int SDLCALL SDL_SetColorKey(SDL_Surface * surface, * * It is safe to pass a NULL `surface` here; it will return SDL_FALSE. * - * \param surface the SDL_Surface structure to query + * \param surface the SDL_Surface structure to query. * \return SDL_TRUE if the surface has a color key, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.9. @@ -469,8 +470,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasColorKey(SDL_Surface * surface); * * 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 + * \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. * @@ -491,10 +492,10 @@ extern DECLSPEC int SDLCALL SDL_GetColorKey(SDL_Surface * surface, * * `srcC = srcC * (color / 255)` * - * \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 + * \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. * @@ -510,10 +511,10 @@ extern DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface * surface, /** * Get the additional color value multiplied into blit operations. * - * \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 + * \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. * @@ -534,8 +535,8 @@ extern DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface * surface, * * `srcA = srcA * (alpha / 255)` * - * \param surface the SDL_Surface structure to update - * \param alpha the alpha value multiplied into blit operations + * \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. * @@ -550,8 +551,8 @@ extern DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface * surface, /** * Get the additional alpha value used in blit operations. * - * \param surface the SDL_Surface structure 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. * @@ -570,8 +571,8 @@ extern DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface * surface, * existing data, the blendmode of the SOURCE surface should be set to * `SDL_BLENDMODE_NONE`. * - * \param surface the SDL_Surface structure to update - * \param blendMode the SDL_BlendMode to use for blit blending + * \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. * @@ -585,8 +586,8 @@ extern DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface * surface, /** * Get the blend mode used for blit operations. * - * \param surface the SDL_Surface structure to query - * \param blendMode a pointer filled in with the current SDL_BlendMode + * \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. * @@ -606,9 +607,9 @@ extern DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface * surface, * 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 surface the SDL_Surface structure to be clipped. * \param rect the SDL_Rect structure representing the clipping rectangle, or - * NULL to disable clipping + * NULL to disable clipping. * \returns SDL_TRUE if the rectangle intersects the surface, otherwise * SDL_FALSE and blits will be completely clipped. * @@ -627,9 +628,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface, * rectangle is drawn into. * * \param surface the SDL_Surface structure representing the surface to be - * clipped + * clipped. * \param rect an SDL_Rect structure filled in with the clipping rectangle for - * the surface + * the surface. * * \since This function is available since SDL 2.0.0. * @@ -658,11 +659,11 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_DuplicateSurface(SDL_Surface * surface) * 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 src the existing SDL_Surface structure to convert. * \param fmt the SDL_PixelFormat structure that the new surface is optimized - * for + * for. * \param flags the flags are unused and should be set to 0; this is a - * leftover from SDL 1.2's API + * 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. * @@ -683,11 +684,11 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface * 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 src the existing SDL_Surface structure to convert. * \param pixel_format the SDL_PixelFormatEnum that the new surface is - * optimized for + * optimized for. * \param flags the flags are unused and should be set to 0; this is a - * leftover from SDL 1.2's API + * 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. * @@ -703,14 +704,14 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurfaceFormat /** * Copy a block of pixels of one format to another format. * - * \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 source pixels, 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 + * \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 source pixels, 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. * @@ -729,14 +730,14 @@ extern DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height, * * This function is currently only implemented for SDL_PIXELFORMAT_ARGB8888. * - * \param width the width of the block to convert, in pixels - * \param height the height of the block to convert, 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 source pixels, in bytes - * \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format - * \param dst a pointer to be filled in with premultiplied pixel data - * \param dst_pitch the pitch of the destination pixels, in bytes + * \param width the width of the block to convert, in pixels. + * \param height the height of the block to convert, 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 source pixels, in bytes. + * \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format. + * \param dst a pointer to be filled in with premultiplied 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. * @@ -760,10 +761,10 @@ extern DECLSPEC int SDLCALL SDL_PremultiplyAlpha(int width, int height, * 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 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 + * 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. * @@ -786,10 +787,10 @@ extern DECLSPEC int SDLCALL SDL_FillRect * 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 + * \param dst the SDL_Surface structure that is the drawing target. + * \param rects an array of SDL_Rect 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. * @@ -801,62 +802,64 @@ 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. - * - * This assumes that the source and destination rectangles are - * the same size. If either \c srcrect or \c dstrect are NULL, the entire - * surface (\c src or \c dst) is copied. The final blit rectangles are saved - * in \c srcrect and \c dstrect after all clipping is performed. - * - * \returns 0 if the blit is successful, otherwise it returns -1. - * - * The blit function should not be called on a locked surface. - * - * The blit semantics for surfaces with and without blending and colorkey - * are defined as follows: - * \verbatim - RGBA->RGB: - Source surface blend mode set to SDL_BLENDMODE_BLEND: - alpha-blend (using the source alpha-channel and per-surface alpha) - SDL_SRCCOLORKEY ignored. - Source surface blend mode set to SDL_BLENDMODE_NONE: - copy RGB. - if SDL_SRCCOLORKEY set, only copy the pixels matching the - RGB values of the source color key, ignoring alpha in the - comparison. - - RGB->RGBA: - Source surface blend mode set to SDL_BLENDMODE_BLEND: - alpha-blend (using the source per-surface alpha) - Source surface blend mode set to SDL_BLENDMODE_NONE: - copy RGB, set destination alpha to source per-surface alpha value. - both: - if SDL_SRCCOLORKEY set, only copy the pixels matching the - source color key. - - RGBA->RGBA: - Source surface blend mode set to SDL_BLENDMODE_BLEND: - alpha-blend (using the source alpha-channel and per-surface alpha) - SDL_SRCCOLORKEY ignored. - Source surface blend mode set to SDL_BLENDMODE_NONE: - copy all of RGBA to the destination. - if SDL_SRCCOLORKEY set, only copy the pixels matching the - RGB values of the source color key, ignoring alpha in the - comparison. - - RGB->RGB: - Source surface blend mode set to SDL_BLENDMODE_BLEND: - alpha-blend (using the source per-surface alpha) - Source surface blend mode set to SDL_BLENDMODE_NONE: - copy RGB. - both: - if SDL_SRCCOLORKEY set, only copy the pixels matching the - source color key. - \endverbatim - * - * You should call SDL_BlitSurface() unless you know exactly how SDL - * blitting works internally and how to use the other blit functions. + * Performs a fast blit from the source surface to the destination surface. + * + * This assumes that the source and destination rectangles are the same size. + * If either `srcrect` or `dstrect` are NULL, the entire surface (`src` or + * `dst`) is copied. The final blit rectangles are saved in `srcrect` and + * `dstrect` after all clipping is performed. + * + * The blit function should not be called on a locked surface. + * + * The blit semantics for surfaces with and without blending and colorkey are + * defined as follows: + * + * ``` + * RGBA->RGB: + * Source surface blend mode set to SDL_BLENDMODE_BLEND: + * alpha-blend (using the source alpha-channel and per-surface alpha) + * SDL_SRCCOLORKEY ignored. + * Source surface blend mode set to SDL_BLENDMODE_NONE: + * copy RGB. + * if SDL_SRCCOLORKEY set, only copy the pixels matching the + * RGB values of the source color key, ignoring alpha in the + * comparison. + * + * RGB->RGBA: + * Source surface blend mode set to SDL_BLENDMODE_BLEND: + * alpha-blend (using the source per-surface alpha) + * Source surface blend mode set to SDL_BLENDMODE_NONE: + * copy RGB, set destination alpha to source per-surface alpha value. + * both: + * if SDL_SRCCOLORKEY set, only copy the pixels matching the + * source color key. + * + * RGBA->RGBA: + * Source surface blend mode set to SDL_BLENDMODE_BLEND: + * alpha-blend (using the source alpha-channel and per-surface alpha) + * SDL_SRCCOLORKEY ignored. + * Source surface blend mode set to SDL_BLENDMODE_NONE: + * copy all of RGBA to the destination. + * if SDL_SRCCOLORKEY set, only copy the pixels matching the + * RGB values of the source color key, ignoring alpha in the + * comparison. + * + * RGB->RGB: + * Source surface blend mode set to SDL_BLENDMODE_BLEND: + * alpha-blend (using the source per-surface alpha) + * Source surface blend mode set to SDL_BLENDMODE_NONE: + * copy RGB. + * both: + * if SDL_SRCCOLORKEY set, only copy the pixels matching the + * source color key. + * ``` + * + * You should call SDL_BlitSurface() unless you know exactly how SDL blitting + * works internally and how to use the other blit functions. + * + * \returns 0 if the blit is successful, otherwise it returns -1. */ #define SDL_BlitSurface SDL_UpperBlit @@ -883,12 +886,12 @@ extern DECLSPEC int SDLCALL SDL_UpperBlit * 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 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 + * 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 + * copied into. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -925,8 +928,6 @@ extern DECLSPEC int SDLCALL SDL_SoftStretchLinear(SDL_Surface * src, const SDL_Rect * dstrect); -#define SDL_BlitScaled SDL_UpperBlitScaled - /** * Perform a scaled surface copy to a destination surface. * @@ -941,18 +942,21 @@ extern DECLSPEC int SDLCALL SDL_UpperBlitScaled (SDL_Surface * src, const SDL_Rect * srcrect, SDL_Surface * dst, SDL_Rect * dstrect); +#define SDL_BlitScaled SDL_UpperBlitScaled + + /** * 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 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 + * 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 + * copied into. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_system.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_system.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_system.h + * # CategorySystem * - * Include file for platform specific SDL API functions + * Include file for platform specific SDL API functions */ #ifndef SDL_system_h_ @@ -49,7 +49,7 @@ typedef void (SDLCALL * SDL_WindowsMessageHook)(void *userdata, void *hWnd, unsi * 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` + * \param userdata a pointer to pass to every iteration of `callback`. * * \since This function is available since SDL 2.0.4. */ @@ -66,7 +66,7 @@ extern DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook ca * controls on which monitor a full screen application will appear. * * \param displayIndex the display index for which to get the D3D9 adapter - * index + * index. * \returns the D3D9 adapter index on success or a negative error code on * failure; call SDL_GetError() for more information. * @@ -82,7 +82,7 @@ typedef struct IDirect3DDevice9 IDirect3DDevice9; * 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 + * \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. * @@ -98,7 +98,7 @@ typedef struct ID3D11Device ID3D11Device; * 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 + * \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. * @@ -118,7 +118,7 @@ typedef struct ID3D12Device ID3D12Device; * 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 D3D12 device + * \param renderer the renderer from which to get the associated D3D12 device. * \returns the D3D12 device associated with given renderer or NULL if it is * not a D3D12 renderer; call SDL_GetError() for more information. * @@ -140,9 +140,9 @@ extern DECLSPEC ID3D12Device* SDLCALL SDL_RenderGetD3D12Device(SDL_Renderer* ren * 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 + * \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. * @@ -176,7 +176,7 @@ extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriority(Sint64 threadID, int prio * \param threadID The Unix thread ID to change priority of. * \param sdlPriority The new SDL_ThreadPriority value. * \param schedPolicy The new scheduling policy (SCHED_FIFO, SCHED_RR, - * SCHED_OTHER, etc...) + * SCHED_OTHER, etc...). * \returns 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.18. @@ -188,7 +188,7 @@ extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriorityAndPolicy(Sint64 threadID, /* Platform specific functions for iOS */ #ifdef __IPHONEOS__ -#define SDL_iOSSetAnimationCallback(window, interval, callback, callbackParam) SDL_iPhoneSetAnimationCallback(window, interval, callback, callbackParam) +typedef void (SDLCALL *SDL_iOSAnimationCallback)(void*); /** * Use this function to set the animation callback on Apple iOS. @@ -210,9 +210,9 @@ extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriorityAndPolicy(Sint64 threadID, * This functions is also accessible using the macro * SDL_iOSSetAnimationCallback() since SDL 2.0.4. * - * \param window the window for which the animation callback should be set + * \param window the window for which the animation callback should be set. * \param interval the number of frames after which **callback** will be - * called + * called. * \param callback the function to call for every frame. * \param callbackParam a pointer that is passed to `callback`. * \returns 0 on success or a negative error code on failure; call @@ -222,9 +222,10 @@ extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriorityAndPolicy(Sint64 threadID, * * \sa SDL_iPhoneSetEventPump */ -extern DECLSPEC int SDLCALL SDL_iPhoneSetAnimationCallback(SDL_Window * window, int interval, void (SDLCALL *callback)(void*), void *callbackParam); +extern DECLSPEC int SDLCALL SDL_iPhoneSetAnimationCallback(SDL_Window * window, int interval, SDL_iOSAnimationCallback callback, void *callbackParam); + +#define SDL_iOSSetAnimationCallback(window, interval, callback, callbackParam) SDL_iPhoneSetAnimationCallback(window, interval, callback, callbackParam) -#define SDL_iOSSetEventPump(enabled) SDL_iPhoneSetEventPump(enabled) /** * Use this function to enable or disable the SDL event pump on Apple iOS. @@ -234,7 +235,7 @@ extern DECLSPEC int SDLCALL SDL_iPhoneSetAnimationCallback(SDL_Window * window, * This functions is also accessible using the macro SDL_iOSSetEventPump() * since SDL 2.0.4. * - * \param enabled SDL_TRUE to enable the event pump, SDL_FALSE to disable it + * \param enabled SDL_TRUE to enable the event pump, SDL_FALSE to disable it. * * \since This function is available since SDL 2.0.0. * @@ -242,6 +243,9 @@ extern DECLSPEC int SDLCALL SDL_iPhoneSetAnimationCallback(SDL_Window * window, */ extern DECLSPEC void SDLCALL SDL_iPhoneSetEventPump(SDL_bool enabled); +#define SDL_iOSSetEventPump(enabled) SDL_iPhoneSetEventPump(enabled) + +/* end of iOS-specific functions. */ #endif /* __IPHONEOS__ */ @@ -356,9 +360,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IsDeXMode(void); extern DECLSPEC void SDLCALL SDL_AndroidBackButton(void); /** - See the official Android developer guide for more information: - http://developer.android.com/guide/topics/data/data-storage.html -*/ + * See the official Android developer guide for more information: + * http://developer.android.com/guide/topics/data/data-storage.html + */ #define SDL_ANDROID_EXTERNAL_STORAGE_READ 0x01 #define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02 @@ -441,11 +445,11 @@ extern DECLSPEC SDL_bool SDLCALL SDL_AndroidRequestPermission(const char *permis * * https://developer.android.com/reference/android/view/Gravity * - * \param message text message to be shown - * \param duration 0=short, 1=long + * \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 + * \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. * * \since This function is available since SDL 2.0.16. @@ -457,8 +461,8 @@ extern DECLSPEC int SDLCALL SDL_AndroidShowToast(const char* message, int durati * * Override "boolean onUnhandledMessage(Message msg)" to handle the message. * - * \param command user command that must be greater or equal to 0x8000 - * \param param user parameter + * \param command user command that must be greater or equal to 0x8000. + * \param param user parameter. * * \since This function is available since SDL 2.0.22. */ @@ -470,9 +474,9 @@ extern DECLSPEC int SDLCALL SDL_AndroidSendMessage(Uint32 command, int param); #ifdef __WINRT__ /** - * \brief WinRT / Windows Phone path types + * WinRT / Windows Phone path types */ -typedef enum +typedef enum SDL_WinRT_Path { /** \brief The installed app's root directory. Files here are likely to be read-only. */ @@ -494,9 +498,9 @@ typedef enum /** - * \brief WinRT Device Family + * WinRT Device Family */ -typedef enum +typedef enum SDL_WinRT_DeviceFamily { /** \brief Unknown family */ SDL_WINRT_DEVICEFAMILY_UNKNOWN, @@ -524,7 +528,7 @@ typedef enum * * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx * - * \param pathType the type of path to retrieve, one of SDL_WinRT_Path + * \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. @@ -547,7 +551,7 @@ extern DECLSPEC const wchar_t * SDLCALL SDL_WinRTGetFSPathUNICODE(SDL_WinRT_Path * * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx * - * \param pathType the type of path to retrieve, one of SDL_WinRT_Path + * \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. diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_syswm.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_syswm.h @@ -19,10 +19,17 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** - * \file SDL_syswm.h +/* WIKI CATEGORY: SYSWM */ + +/* + * # CategorySYSWM + * + * Include file for SDL custom system window manager hooks. * - * Include file for SDL custom system window manager hooks. + * Your application has access to a special type of event SDL_SYSWMEVENT, + * which contains window-manager specific information and arrives whenever + * an unhandled window event occurs. This event is ignored by default, but + * you can enable it with SDL_EventState(). */ #ifndef SDL_syswm_h_ @@ -33,14 +40,6 @@ #include <SDL2/SDL_video.h> #include <SDL2/SDL_version.h> -/** - * \brief SDL_syswm.h - * - * Your application has access to a special type of event ::SDL_SYSWMEVENT, - * which contains window-manager specific information and arrives whenever - * an unhandled window event occurs. This event is ignored by default, but - * you can enable it with SDL_EventState(). - */ struct SDL_SysWMinfo; #if !defined(SDL_PROTOTYPES_ONLY) @@ -129,10 +128,11 @@ extern "C" { #endif #if !defined(SDL_PROTOTYPES_ONLY) + /** - * These are the various supported windowing subsystems + * These are the various supported windowing subsystems */ -typedef enum +typedef enum SDL_SYSWM_TYPE { SDL_SYSWM_UNKNOWN, SDL_SYSWM_WINDOWS, @@ -152,7 +152,7 @@ typedef enum } SDL_SYSWM_TYPE; /** - * The custom event structure. + * The custom event structure. */ struct SDL_SysWMmsg { @@ -218,10 +218,10 @@ struct SDL_SysWMmsg }; /** - * The custom window manager information structure. + * The custom window manager information structure. * - * When this structure is returned, it holds information about which - * low level system it is using, and will be one of SDL_SYSWM_TYPE. + * When this structure is returned, it holds information about which low level + * system it is using, and will be one of SDL_SYSWM_TYPE. */ struct SDL_SysWMinfo { @@ -363,8 +363,8 @@ typedef struct SDL_SysWMinfo SDL_SysWMinfo; * `SDL_VERSION(&info.version)`, and then this function will fill in the rest * of the structure with information about the given window. * - * \param window the window about which information is being requested - * \param info an SDL_SysWMinfo structure filled in with window information + * \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. diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_thread.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_thread.h @@ -23,9 +23,9 @@ #define SDL_thread_h_ /** - * \file SDL_thread.h + * # CategoryThread * - * Header for the SDL thread management routines. + * Header for the SDL thread management routines. */ #include <SDL2/SDL_stdinc.h> @@ -63,16 +63,18 @@ typedef unsigned long SDL_threadID; typedef unsigned int SDL_TLSID; /** - * The SDL thread priority. + * The SDL thread priority. * - * SDL will make system changes as necessary in order to apply the thread priority. - * Code which attempts to control thread state related to priority should be aware - * that calling SDL_SetThreadPriority may alter such state. - * SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of this behavior. + * SDL will make system changes as necessary in order to apply the thread + * priority. Code which attempts to control thread state related to priority + * should be aware that calling SDL_SetThreadPriority may alter such state. + * SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of this + * behavior. * - * \note On many systems you require special privileges to set high or time critical priority. + * On many systems you require special privileges to set high or time critical + * priority. */ -typedef enum { +typedef enum SDL_ThreadPriority { SDL_THREAD_PRIORITY_LOW, SDL_THREAD_PRIORITY_NORMAL, SDL_THREAD_PRIORITY_HIGH, @@ -82,7 +84,7 @@ typedef enum { /** * The function passed to SDL_CreateThread(). * - * \param data what was passed as `data` 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); @@ -192,9 +194,9 @@ SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn, const char *name, const siz * 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` + * \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. @@ -238,10 +240,10 @@ SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data); * 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 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` + * \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. @@ -261,7 +263,7 @@ SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn, const char *name, const siz * 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 + * \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. * @@ -296,7 +298,7 @@ extern DECLSPEC SDL_threadID SDLCALL SDL_ThreadID(void); * 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 + * \param thread the thread to query. * \returns the ID of the specified thread, or the ID of the current thread if * `thread` is NULL. * @@ -313,7 +315,7 @@ extern DECLSPEC SDL_threadID SDLCALL SDL_GetThreadID(SDL_Thread * thread); * 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 + * \param priority the SDL_ThreadPriority to set. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -344,7 +346,7 @@ extern DECLSPEC int SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority priority); * afterward. * * \param thread the SDL_Thread pointer that was returned from the - * SDL_CreateThread() call that started this thread + * 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. @@ -383,7 +385,7 @@ extern DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread * thread, int *status); * 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 + * SDL_CreateThread() call that started this thread. * * \since This function is available since SDL 2.0.2. * @@ -410,7 +412,7 @@ extern DECLSPEC SDL_TLSID SDLCALL SDL_TLSCreate(void); /** * 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. * @@ -421,6 +423,8 @@ extern DECLSPEC SDL_TLSID SDLCALL SDL_TLSCreate(void); */ extern DECLSPEC void * SDLCALL SDL_TLSGet(SDL_TLSID id); +typedef void (SDLCALL *SDL_TLSDestructorCallback)(void*); + /** * Set the current thread's value associated with a thread local storage ID. * @@ -432,10 +436,10 @@ extern DECLSPEC void * SDLCALL SDL_TLSGet(SDL_TLSID id); * * 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 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 + * value. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -444,7 +448,7 @@ extern DECLSPEC void * SDLCALL SDL_TLSGet(SDL_TLSID id); * \sa SDL_TLSCreate * \sa SDL_TLSGet */ -extern DECLSPEC int SDLCALL SDL_TLSSet(SDL_TLSID id, const void *value, void (SDLCALL *destructor)(void*)); +extern DECLSPEC int SDLCALL SDL_TLSSet(SDL_TLSID id, const void *value, SDL_TLSDestructorCallback destructor); /** * Cleanup all TLS data for this thread. diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_timer.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_timer.h @@ -23,9 +23,9 @@ #define SDL_timer_h_ /** - * \file SDL_timer.h + * # CategoryTimer * - * Header for the SDL time management routines. + * Header for the SDL time management routines. */ #include <SDL2/SDL_stdinc.h> @@ -89,8 +89,8 @@ extern DECLSPEC Uint64 SDLCALL SDL_GetTicks64(void); * days, but should _not_ be used with SDL_GetTicks64(), which does not have * that problem. * - * For example, with SDL_GetTicks(), if you want to wait 100 ms, you could - * do this: + * For example, with SDL_GetTicks(), if you want to wait 100 ms, you could do + * this: * * ```c * const Uint32 timeout = SDL_GetTicks() + 100; @@ -99,9 +99,9 @@ extern DECLSPEC Uint64 SDLCALL SDL_GetTicks64(void); * } * ``` * - * Note that this does not handle tick differences greater - * than 2^31 so take care when using the above kind of code - * with large timeout delays (tens of days). + * Note that this does not handle tick differences greater than 2^31 so take + * care when using the above kind of code with large timeout delays (tens of + * days). */ #define SDL_TICKS_PASSED(A, B) ((Sint32)((B) - (A)) <= 0) @@ -140,7 +140,7 @@ extern DECLSPEC Uint64 SDLCALL SDL_GetPerformanceFrequency(void); * waits at least the specified time, but possibly longer due to OS * scheduling. * - * \param ms the number of milliseconds to delay + * \param ms the number of milliseconds to delay. * * \since This function is available since SDL 2.0.0. */ @@ -149,10 +149,10 @@ extern DECLSPEC void SDLCALL SDL_Delay(Uint32 ms); /** * 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); @@ -182,10 +182,10 @@ typedef int SDL_TimerID; * 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 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` + * `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. * @@ -200,7 +200,7 @@ extern DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval, /** * Remove a timer created with SDL_AddTimer(). * - * \param id the ID of the timer to remove + * \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. * diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_touch.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_touch.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_touch.h + * # CategoryTouch * - * Include file for SDL touch event handling. + * Include file for SDL touch event handling. */ #ifndef SDL_touch_h_ @@ -85,7 +85,7 @@ extern DECLSPEC int SDLCALL SDL_GetNumTouchDevices(void); /** * Get the touch ID with the given index. * - * \param index the touch device 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. * @@ -113,7 +113,7 @@ extern DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_TouchID t /** * Get the number of active fingers for a given touch device. * - * \param touchID the ID of a 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. * @@ -128,8 +128,8 @@ extern DECLSPEC int SDLCALL SDL_GetNumTouchFingers(SDL_TouchID touchID); * * 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 + * \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. * diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_types.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_types.h @@ -19,11 +19,6 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** - * \file SDL_types.h - * - * \deprecated - */ - /* DEPRECATED */ + #include <SDL2/SDL_stdinc.h> diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_version.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_version.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_version.h + * # CategoryVersion * - * This header defines the current SDL version. + * This header defines the current SDL version. */ #ifndef SDL_version_h_ @@ -40,10 +40,9 @@ extern "C" { * 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). + * (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 @@ -58,18 +57,17 @@ typedef struct SDL_version /* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL */ #define SDL_MAJOR_VERSION 2 -#define SDL_MINOR_VERSION 30 -#define SDL_PATCHLEVEL 12 +#define SDL_MINOR_VERSION 32 +#define SDL_PATCHLEVEL 2 /** * 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. * @@ -85,37 +83,40 @@ typedef struct SDL_version /* TODO: Remove this whole block in SDL 3 */ #if SDL_MAJOR_VERSION < 3 + /** - * This macro turns the version numbers into a numeric value: - * \verbatim - (1,2,3) -> (1203) - \endverbatim + * This macro turns the version numbers into a numeric value: + * + * ``` + * (1,2,3) -> (1203) + * ``` + * + * This assumes that there will never be more than 100 patchlevels. * - * This assumes that there will never be more than 100 patchlevels. + * In versions higher than 2.9.0, the minor version overflows into the + * thousands digit: for example, 2.23.0 is encoded as 4300, and 2.255.99 would + * be encoded as 25799. * - * In versions higher than 2.9.0, the minor version overflows into - * the thousands digit: for example, 2.23.0 is encoded as 4300, - * and 2.255.99 would be encoded as 25799. - * This macro will not be available in SDL 3.x. + * This macro will not be available in SDL 3.x. */ #define SDL_VERSIONNUM(X, Y, Z) \ ((X)*1000 + (Y)*100 + (Z)) /** - * This is the version number macro for the current SDL version. + * This is the version number macro for the current SDL version. * - * In versions higher than 2.9.0, the minor version overflows into - * the thousands digit: for example, 2.23.0 is encoded as 4300. - * This macro will not be available in SDL 3.x. + * In versions higher than 2.9.0, the minor version overflows into the + * thousands digit: for example, 2.23.0 is encoded as 4300. This macro will + * not be available in SDL 3.x. * - * Deprecated, use SDL_VERSION_ATLEAST or SDL_VERSION instead. + * Deprecated, use SDL_VERSION_ATLEAST or SDL_VERSION instead. */ #define SDL_COMPILEDVERSION \ SDL_VERSIONNUM(SDL_MAJOR_VERSION, SDL_MINOR_VERSION, SDL_PATCHLEVEL) #endif /* SDL_MAJOR_VERSION < 3 */ /** - * This macro will evaluate to true if compiled with SDL at least X.Y.Z. + * This macro will evaluate to true if compiled with SDL at least X.Y.Z. */ #define SDL_VERSION_ATLEAST(X, Y, Z) \ ((SDL_MAJOR_VERSION >= X) && \ @@ -132,7 +133,7 @@ typedef struct SDL_version * * This function may be called safely at any time, even before SDL_Init(). * - * \param ver the SDL_version structure that contains the version information + * \param ver the SDL_version structure that contains the version information. * * \since This function is available since SDL 2.0.0. * diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_video.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_video.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_video.h + * # CategoryVideo * - * Header file for SDL video functions. + * Header file for SDL video functions. */ #ifndef SDL_video_h_ @@ -40,17 +40,17 @@ extern "C" { #endif /** - * \brief The structure that defines a display mode + * The structure that defines a display mode * - * \sa SDL_GetNumDisplayModes() - * \sa SDL_GetDisplayMode() - * \sa SDL_GetDesktopDisplayMode() - * \sa SDL_GetCurrentDisplayMode() - * \sa SDL_GetClosestDisplayMode() - * \sa SDL_SetWindowDisplayMode() - * \sa SDL_GetWindowDisplayMode() + * \sa SDL_GetNumDisplayModes + * \sa SDL_GetDisplayMode + * \sa SDL_GetDesktopDisplayMode + * \sa SDL_GetCurrentDisplayMode + * \sa SDL_GetClosestDisplayMode + * \sa SDL_SetWindowDisplayMode + * \sa SDL_GetWindowDisplayMode */ -typedef struct +typedef struct SDL_DisplayMode { Uint32 format; /**< pixel format */ int w; /**< width, in screen coordinates */ @@ -60,46 +60,46 @@ typedef struct } SDL_DisplayMode; /** - * \brief The type used to identify a window - * - * \sa SDL_CreateWindow() - * \sa SDL_CreateWindowFrom() - * \sa SDL_DestroyWindow() - * \sa SDL_FlashWindow() - * \sa SDL_GetWindowData() - * \sa SDL_GetWindowFlags() - * \sa SDL_GetWindowGrab() - * \sa SDL_GetWindowKeyboardGrab() - * \sa SDL_GetWindowMouseGrab() - * \sa SDL_GetWindowPosition() - * \sa SDL_GetWindowSize() - * \sa SDL_GetWindowTitle() - * \sa SDL_HideWindow() - * \sa SDL_MaximizeWindow() - * \sa SDL_MinimizeWindow() - * \sa SDL_RaiseWindow() - * \sa SDL_RestoreWindow() - * \sa SDL_SetWindowData() - * \sa SDL_SetWindowFullscreen() - * \sa SDL_SetWindowGrab() - * \sa SDL_SetWindowKeyboardGrab() - * \sa SDL_SetWindowMouseGrab() - * \sa SDL_SetWindowIcon() - * \sa SDL_SetWindowPosition() - * \sa SDL_SetWindowSize() - * \sa SDL_SetWindowBordered() - * \sa SDL_SetWindowResizable() - * \sa SDL_SetWindowTitle() - * \sa SDL_ShowWindow() + * The opaque type used to identify a window. + * + * \sa SDL_CreateWindow + * \sa SDL_CreateWindowFrom + * \sa SDL_DestroyWindow + * \sa SDL_FlashWindow + * \sa SDL_GetWindowData + * \sa SDL_GetWindowFlags + * \sa SDL_GetWindowGrab + * \sa SDL_GetWindowKeyboardGrab + * \sa SDL_GetWindowMouseGrab + * \sa SDL_GetWindowPosition + * \sa SDL_GetWindowSize + * \sa SDL_GetWindowTitle + * \sa SDL_HideWindow + * \sa SDL_MaximizeWindow + * \sa SDL_MinimizeWindow + * \sa SDL_RaiseWindow + * \sa SDL_RestoreWindow + * \sa SDL_SetWindowData + * \sa SDL_SetWindowFullscreen + * \sa SDL_SetWindowGrab + * \sa SDL_SetWindowKeyboardGrab + * \sa SDL_SetWindowMouseGrab + * \sa SDL_SetWindowIcon + * \sa SDL_SetWindowPosition + * \sa SDL_SetWindowSize + * \sa SDL_SetWindowBordered + * \sa SDL_SetWindowResizable + * \sa SDL_SetWindowTitle + * \sa SDL_ShowWindow */ typedef struct SDL_Window SDL_Window; /** - * \brief The flags on a window + * The flags on a window * - * \sa SDL_GetWindowFlags() + * \sa SDL_GetWindowFlags */ -typedef enum +typedef enum SDL_WindowFlags { SDL_WINDOW_FULLSCREEN = 0x00000001, /**< fullscreen window */ SDL_WINDOW_OPENGL = 0x00000002, /**< window usable with OpenGL context */ @@ -131,7 +131,7 @@ typedef enum } SDL_WindowFlags; /** - * \brief Used to indicate that you don't care what the window position is. + * Used to indicate that you don't care what the window position is. */ #define SDL_WINDOWPOS_UNDEFINED_MASK 0x1FFF0000u #define SDL_WINDOWPOS_UNDEFINED_DISPLAY(X) (SDL_WINDOWPOS_UNDEFINED_MASK|(X)) @@ -140,7 +140,7 @@ typedef enum (((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK) /** - * \brief Used to indicate that the window position should be centered. + * Used to indicate that the window position should be centered. */ #define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u #define SDL_WINDOWPOS_CENTERED_DISPLAY(X) (SDL_WINDOWPOS_CENTERED_MASK|(X)) @@ -149,9 +149,9 @@ typedef enum (((X)&0xFFFF0000) == SDL_WINDOWPOS_CENTERED_MASK) /** - * \brief Event subtype for window events + * Event subtype for window events */ -typedef enum +typedef enum SDL_WindowEventID { SDL_WINDOWEVENT_NONE, /**< Never used */ SDL_WINDOWEVENT_SHOWN, /**< Window has been shown */ @@ -180,9 +180,9 @@ typedef enum } SDL_WindowEventID; /** - * \brief Event subtype for display events + * Event subtype for display events */ -typedef enum +typedef enum SDL_DisplayEventID { SDL_DISPLAYEVENT_NONE, /**< Never used */ SDL_DISPLAYEVENT_ORIENTATION, /**< Display orientation has changed to data1 */ @@ -192,9 +192,9 @@ typedef enum } SDL_DisplayEventID; /** - * \brief Display orientation + * Display orientation */ -typedef enum +typedef enum SDL_DisplayOrientation { SDL_ORIENTATION_UNKNOWN, /**< The display orientation can't be determined */ SDL_ORIENTATION_LANDSCAPE, /**< The display is in landscape mode, with the right side up, relative to portrait mode */ @@ -204,9 +204,9 @@ typedef enum } SDL_DisplayOrientation; /** - * \brief Window flash operation + * Window flash operation */ -typedef enum +typedef enum SDL_FlashOperation { SDL_FLASH_CANCEL, /**< Cancel any window flash state */ SDL_FLASH_BRIEFLY, /**< Flash the window briefly to get attention */ @@ -214,53 +214,85 @@ typedef enum } SDL_FlashOperation; /** - * \brief An opaque handle to an OpenGL context. + * An opaque handle to an OpenGL context. + * + * \sa SDL_GL_CreateContext */ typedef void *SDL_GLContext; /** - * \brief OpenGL configuration attributes + * OpenGL configuration attributes. + * + * While you can set most OpenGL attributes normally, the attributes listed + * above must be known before SDL creates the window that will be used with + * the OpenGL context. These attributes are set and read with + * SDL_GL_SetAttribute and SDL_GL_GetAttribute. + * + * In some cases, these attributes are minimum requests; the GL does not + * promise to give you exactly what you asked for. It's possible to ask for a + * 16-bit depth buffer and get a 24-bit one instead, for example, or to ask + * for no stencil buffer and still have one available. Context creation should + * fail if the GL can't provide your requested attributes at a minimum, but + * you should check to see exactly what you got. + * + * + * [Multisample anti-aliasing](http://en.wikipedia.org/wiki/Multisample_anti-aliasing) + * is a type of full screen anti-aliasing. Multipsampling defaults to off but + * can be turned on by setting SDL_GL_MULTISAMPLEBUFFERS to 1 and + * SDL_GL_MULTISAMPLESAMPLES to a value greater than 0. Typical values are 2 + * and 4. + * + * SDL_GL_CONTEXT_PROFILE_MASK determines the type of context created, while + * both SDL_GL_CONTEXT_MAJOR_VERSION and SDL_GL_CONTEXT_MINOR_VERSION + * determine which version. All three attributes must be set prior to creating + * the first window, and in general you can't change the value of + * SDL_GL_CONTEXT_PROFILE_MASK without first destroying all windows created + * with the previous setting. + * + * SDL_GL_CONTEXT_RELEASE_BEHAVIOR can be set to + * SDL_GL_CONTEXT_RELEASE_BEHAVIOR_NONE or + * SDL_GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH. */ -typedef enum +typedef enum SDL_GLattr { - SDL_GL_RED_SIZE, - SDL_GL_GREEN_SIZE, - SDL_GL_BLUE_SIZE, - SDL_GL_ALPHA_SIZE, - SDL_GL_BUFFER_SIZE, - SDL_GL_DOUBLEBUFFER, - SDL_GL_DEPTH_SIZE, - SDL_GL_STENCIL_SIZE, - SDL_GL_ACCUM_RED_SIZE, - SDL_GL_ACCUM_GREEN_SIZE, - SDL_GL_ACCUM_BLUE_SIZE, - SDL_GL_ACCUM_ALPHA_SIZE, - SDL_GL_STEREO, - SDL_GL_MULTISAMPLEBUFFERS, - SDL_GL_MULTISAMPLESAMPLES, - SDL_GL_ACCELERATED_VISUAL, - SDL_GL_RETAINED_BACKING, - SDL_GL_CONTEXT_MAJOR_VERSION, - SDL_GL_CONTEXT_MINOR_VERSION, - SDL_GL_CONTEXT_EGL, - SDL_GL_CONTEXT_FLAGS, - SDL_GL_CONTEXT_PROFILE_MASK, - SDL_GL_SHARE_WITH_CURRENT_CONTEXT, - SDL_GL_FRAMEBUFFER_SRGB_CAPABLE, - SDL_GL_CONTEXT_RELEASE_BEHAVIOR, + SDL_GL_RED_SIZE, /**< the minimum number of bits for the red channel of the color buffer; defaults to 3. */ + SDL_GL_GREEN_SIZE, /**< the minimum number of bits for the green channel of the color buffer; defaults to 3. */ + SDL_GL_BLUE_SIZE, /**< the minimum number of bits for the blue channel of the color buffer; defaults to 2. */ + SDL_GL_ALPHA_SIZE, /**< the minimum number of bits for the alpha channel of the color buffer; defaults to 0. */ + SDL_GL_BUFFER_SIZE, /**< the minimum number of bits for frame buffer size; defaults to 0. */ + SDL_GL_DOUBLEBUFFER, /**< whether the output is single or double buffered; defaults to double buffering on. */ + SDL_GL_DEPTH_SIZE, /**< the minimum number of bits in the depth buffer; defaults to 16. */ + SDL_GL_STENCIL_SIZE, /**< the minimum number of bits in the stencil buffer; defaults to 0. */ + SDL_GL_ACCUM_RED_SIZE, /**< the minimum number of bits for the red channel of the accumulation buffer; defaults to 0. */ + SDL_GL_ACCUM_GREEN_SIZE, /**< the minimum number of bits for the green channel of the accumulation buffer; defaults to 0. */ + SDL_GL_ACCUM_BLUE_SIZE, /**< the minimum number of bits for the blue channel of the accumulation buffer; defaults to 0. */ + SDL_GL_ACCUM_ALPHA_SIZE, /**< the minimum number of bits for the alpha channel of the accumulation buffer; defaults to 0. */ + SDL_GL_STEREO, /**< whether the output is stereo 3D; defaults to off. */ + SDL_GL_MULTISAMPLEBUFFERS, /**< the number of buffers used for multisample anti-aliasing; defaults to 0. */ + SDL_GL_MULTISAMPLESAMPLES, /**< the number of samples used around the current pixel used for multisample anti-aliasing. */ + SDL_GL_ACCELERATED_VISUAL, /**< set to 1 to require hardware acceleration, set to 0 to force software rendering; defaults to allow either. */ + SDL_GL_RETAINED_BACKING, /**< not used (deprecated). */ + SDL_GL_CONTEXT_MAJOR_VERSION, /**< OpenGL context major version. */ + SDL_GL_CONTEXT_MINOR_VERSION, /**< OpenGL context minor version. */ + SDL_GL_CONTEXT_EGL, /**< deprecated: set SDL_GL_CONTEXT_PROFILE_MASK to SDL_GL_CONTEXT_PROFILE_ES to enable instead. */ + SDL_GL_CONTEXT_FLAGS, /**< some combination of 0 or more of elements of the SDL_GLcontextFlag enumeration; defaults to 0. */ + SDL_GL_CONTEXT_PROFILE_MASK, /**< type of GL context (Core, Compatibility, ES). See SDL_GLprofile; default value depends on platform. */ + SDL_GL_SHARE_WITH_CURRENT_CONTEXT, /**< OpenGL context sharing; defaults to 0. */ + SDL_GL_FRAMEBUFFER_SRGB_CAPABLE, /**< requests sRGB capable visual; defaults to 0. (>= SDL 2.0.1) */ + SDL_GL_CONTEXT_RELEASE_BEHAVIOR, /**< sets context the release behavior; defaults to 1. (>= SDL 2.0.4) */ SDL_GL_CONTEXT_RESET_NOTIFICATION, SDL_GL_CONTEXT_NO_ERROR, SDL_GL_FLOATBUFFERS } SDL_GLattr; -typedef enum +typedef enum SDL_GLprofile { SDL_GL_CONTEXT_PROFILE_CORE = 0x0001, SDL_GL_CONTEXT_PROFILE_COMPATIBILITY = 0x0002, SDL_GL_CONTEXT_PROFILE_ES = 0x0004 /**< GLX_CONTEXT_ES2_PROFILE_BIT_EXT */ } SDL_GLprofile; -typedef enum +typedef enum SDL_GLcontextFlag { SDL_GL_CONTEXT_DEBUG_FLAG = 0x0001, SDL_GL_CONTEXT_FORWARD_COMPATIBLE_FLAG = 0x0002, @@ -268,13 +300,13 @@ typedef enum SDL_GL_CONTEXT_RESET_ISOLATION_FLAG = 0x0008 } SDL_GLcontextFlag; -typedef enum +typedef enum SDL_GLcontextReleaseFlag { SDL_GL_CONTEXT_RELEASE_BEHAVIOR_NONE = 0x0000, SDL_GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH = 0x0001 } SDL_GLcontextReleaseFlag; -typedef enum +typedef enum SDL_GLContextResetNotification { SDL_GL_CONTEXT_RESET_NO_NOTIFICATION = 0x0000, SDL_GL_CONTEXT_RESET_LOSE_CONTEXT = 0x0001 @@ -300,7 +332,7 @@ extern DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void); * The video drivers are presented in the order in which they are normally * checked during initialization. * - * \param index the index of a video driver + * \param index the index of a video driver. * \returns the name of the video driver with the given **index**. * * \since This function is available since SDL 2.0.0. @@ -327,7 +359,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetVideoDriver(int index); * specific `driver_name`. * * \param driver_name the name of a video driver to initialize, or NULL for - * the default driver + * the default driver. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -380,7 +412,7 @@ extern DECLSPEC int SDLCALL SDL_GetNumVideoDisplays(void); * Get the name of a display in UTF-8 encoding. * * \param displayIndex the index of display from which the name should be - * queried + * queried. * \returns the name of a display or NULL for an invalid display index or * failure; call SDL_GetError() for more information. * @@ -395,8 +427,8 @@ extern DECLSPEC const char * SDLCALL SDL_GetDisplayName(int displayIndex); * * The primary display (`displayIndex` zero) is always located at 0,0. * - * \param displayIndex the index of the display to query - * \param rect the SDL_Rect structure filled in with the display bounds + * \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. * @@ -425,8 +457,8 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayBounds(int displayIndex, SDL_Rect * re * 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 + * 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. * @@ -456,13 +488,13 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayUsableBounds(int displayIndex, SDL_Rec * more consistent, reliable, and clear. * * \param displayIndex the index of the display from which DPI information - * should be queried + * should be queried. * \param ddpi a pointer filled in with the diagonal DPI of the display; may - * be NULL + * be NULL. * \param hdpi a pointer filled in with the horizontal DPI of the display; may - * be NULL + * be NULL. * \param vdpi a pointer filled in with the vertical DPI of the display; may - * be NULL + * be NULL. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -475,7 +507,7 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayDPI(int displayIndex, float * ddpi, fl /** * Get the orientation of a display. * - * \param displayIndex the index of the display to query + * \param 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. * @@ -491,7 +523,7 @@ extern DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetDisplayOrientation(int dis * The `displayIndex` needs to be in the range from 0 to * SDL_GetNumVideoDisplays() - 1. * - * \param displayIndex the index of the display to query + * \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. * @@ -513,10 +545,10 @@ extern DECLSPEC int SDLCALL SDL_GetNumDisplayModes(int displayIndex); * - 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 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` + * `modeIndex`. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -535,9 +567,9 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayMode(int displayIndex, int modeIndex, * function will return the previous native display mode, and not the current * display mode. * - * \param displayIndex the index of the display to query + * \param displayIndex the index of the display to query. * \param mode an SDL_DisplayMode structure filled in with the current display - * mode + * mode. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -557,9 +589,9 @@ extern DECLSPEC int SDLCALL SDL_GetDesktopDisplayMode(int displayIndex, SDL_Disp * function will return the current display mode, and not the previous native * display mode. * - * \param displayIndex the index of the display to query + * \param displayIndex the index of the display to query. * \param mode an SDL_DisplayMode structure filled in with the current display - * mode + * mode. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -583,11 +615,11 @@ extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(int displayIndex, SDL_Disp * and finally checking the refresh rate. If all the available modes are too * small, then NULL is returned. * - * \param displayIndex the index of the display to query + * \param displayIndex the index of the display to query. * \param mode an SDL_DisplayMode structure containing the desired display - * mode + * mode. * \param closest an SDL_DisplayMode structure filled in with the closest - * match of the available display modes + * 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. * @@ -601,7 +633,7 @@ extern DECLSPEC SDL_DisplayMode * SDLCALL SDL_GetClosestDisplayMode(int displayI /** * Get the index of the display containing a point * - * \param point the point to query + * \param point the point to query. * \returns the index of the display containing the point or a negative error * code on failure; call SDL_GetError() for more information. * @@ -615,7 +647,7 @@ extern DECLSPEC int SDLCALL SDL_GetPointDisplayIndex(const SDL_Point * point); /** * Get the index of the display primarily containing a rect * - * \param rect the rect to query + * \param rect the rect to query. * \returns the index of the display entirely containing the rect or closest * to the center of the rect on success or a negative error code on * failure; call SDL_GetError() for more information. @@ -630,7 +662,7 @@ extern DECLSPEC int SDLCALL SDL_GetRectDisplayIndex(const SDL_Rect * rect); /** * Get the index of the display associated with a window. * - * \param window the window to query + * \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. @@ -649,10 +681,10 @@ extern DECLSPEC int SDLCALL SDL_GetWindowDisplayIndex(SDL_Window * window); * change the window size when the window is not fullscreen, use * SDL_SetWindowSize(). * - * \param window the window to affect + * \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 + * and refresh rate. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -667,9 +699,9 @@ extern DECLSPEC int SDLCALL SDL_SetWindowDisplayMode(SDL_Window * window, /** * Query the display mode to use when a window is visible at fullscreen. * - * \param window the window to query + * \param window the window to query. * \param mode an SDL_DisplayMode structure filled in with the fullscreen - * display mode + * display mode. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -686,8 +718,8 @@ extern DECLSPEC int SDLCALL SDL_GetWindowDisplayMode(SDL_Window * window, * * Data returned should be freed with SDL_free. * - * \param window the window to query - * \param size the size of the ICC profile + * \param window the window to query. + * \param size the size of the ICC profile. * \returns the raw ICC profile data on success or NULL on failure; call * SDL_GetError() for more information. * @@ -698,7 +730,7 @@ extern DECLSPEC void* SDLCALL SDL_GetWindowICCProfile(SDL_Window * window, size_ /** * Get the pixel format associated with the window. * - * \param window the window to query + * \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. @@ -762,15 +794,15 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window * window); * 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 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` + * `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_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 `SDL_Window` that was created or NULL on failure; call * SDL_GetError() for more information. * * \since This function is available since SDL 2.0.0. @@ -790,7 +822,7 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title, * before using SDL_CreateWindowFrom(). * * \param data a pointer to driver-dependent window creation data, typically - * your native window cast to a void* + * your native window cast to a void*. * \returns the window that was created or NULL on failure; call * SDL_GetError() for more information. * @@ -807,7 +839,7 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindowFrom(const void *data); * 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 + * \param window the window to query. * \returns the ID of the window on success or 0 on failure; call * SDL_GetError() for more information. * @@ -823,7 +855,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowID(SDL_Window * window); * 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 + * \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. * @@ -836,8 +868,8 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromID(Uint32 id); /** * Get the window flags. * - * \param window the window to query - * \returns a mask of the SDL_WindowFlags associated with `window` + * \param window the window to query. + * \returns a mask of the SDL_WindowFlags associated with `window`. * * \since This function is available since SDL 2.0.0. * @@ -856,8 +888,8 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowFlags(SDL_Window * window); * * 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 + * \param window the window to change. + * \param title the desired window title in UTF-8 format. * * \since This function is available since SDL 2.0.0. * @@ -869,7 +901,7 @@ extern DECLSPEC void SDLCALL SDL_SetWindowTitle(SDL_Window * window, /** * Get the title of a window. * - * \param window the window to query + * \param window the window to query. * \returns the title of the window in UTF-8 format or "" if there is no * title. * @@ -882,8 +914,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetWindowTitle(SDL_Window * window); /** * Set the icon for a window. * - * \param window the window to change - * \param icon an SDL_Surface structure containing the icon for the window + * \param window the window to change. + * \param icon an SDL_Surface structure containing the icon for the window. * * \since This function is available since SDL 2.0.0. */ @@ -895,9 +927,9 @@ extern DECLSPEC void SDLCALL SDL_SetWindowIcon(SDL_Window * window, * * `name` is case-sensitive. * - * \param window the window to associate with the pointer - * \param name the name of the pointer - * \param userdata the associated pointer + * \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`. * * \since This function is available since SDL 2.0.0. @@ -911,8 +943,8 @@ extern DECLSPEC void* SDLCALL SDL_SetWindowData(SDL_Window * 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`. * * \since This function is available since SDL 2.0.0. @@ -927,11 +959,11 @@ extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_Window * window, * * The window coordinate origin is the upper left of the display. * - * \param window the window to reposition + * \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` + * `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` + * `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED`. * * \since This function is available since SDL 2.0.0. * @@ -946,11 +978,11 @@ extern DECLSPEC void SDLCALL SDL_SetWindowPosition(SDL_Window * window, * If you do not need the value for one of the positions a NULL may be passed * in the `x` or `y` parameter. * - * \param window the window to query + * \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 + * coordinates, may be NULL. * \param y a pointer filled in with the y position of the window, in screen - * coordinates, may be NULL + * coordinates, may be NULL. * * \since This function is available since SDL 2.0.0. * @@ -970,11 +1002,11 @@ extern DECLSPEC void SDLCALL SDL_GetWindowPosition(SDL_Window * window, * Fullscreen windows automatically match the size of the display mode, and * you should use SDL_SetWindowDisplayMode() to change their size. * - * \param window the window to change + * \param window the window to change. * \param w the width of the window in pixels, in screen coordinates, must be - * > 0 + * > 0. * \param h the height of the window in pixels, in screen coordinates, must be - * > 0 + * > 0. * * \since This function is available since SDL 2.0.0. * @@ -996,11 +1028,11 @@ extern DECLSPEC void SDLCALL SDL_SetWindowSize(SDL_Window * window, int w, * SDL_Vulkan_GetDrawableSize(), or SDL_GetRendererOutputSize() to get the * real client area size in pixels. * - * \param window the window to query the width and height from + * \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 + * coordinates, may be NULL. * \param h a pointer filled in with the height of the window, in screen - * coordinates, may be NULL + * coordinates, may be NULL. * * \since This function is available since SDL 2.0.0. * @@ -1027,15 +1059,15 @@ extern DECLSPEC void SDLCALL SDL_GetWindowSize(SDL_Window * window, int *w, * This function also returns -1 if getting the information is not supported. * * \param window the window to query the size values of the border - * (decorations) from + * (decorations) from. * \param top pointer to variable for storing the size of the top border; NULL - * is permitted + * is permitted. * \param left pointer to variable for storing the size of the left border; - * NULL is permitted + * NULL is permitted. * \param bottom pointer to variable for storing the size of the bottom - * border; NULL is permitted + * border; NULL is permitted. * \param right pointer to variable for storing the size of the right border; - * NULL is permitted + * NULL is permitted. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1055,10 +1087,11 @@ extern DECLSPEC int SDLCALL SDL_GetWindowBordersSize(SDL_Window * window, * platform with high-DPI support (Apple calls this "Retina"), and not * disabled by the `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint. * - * \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 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 + * NULL. * * \since This function is available since SDL 2.26.0. * @@ -1071,9 +1104,9 @@ extern DECLSPEC void SDLCALL SDL_GetWindowSizeInPixels(SDL_Window * window, /** * Set the minimum size of a window's client area. * - * \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 + * \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. * * \since This function is available since SDL 2.0.0. * @@ -1086,11 +1119,11 @@ extern DECLSPEC void SDLCALL SDL_SetWindowMinimumSize(SDL_Window * window, /** * Get the minimum size of a window's client area. * - * \param window the window to query + * \param window the window to query. * \param w a pointer filled in with the minimum width of the window, may be - * NULL + * NULL. * \param h a pointer filled in with the minimum height of the window, may be - * NULL + * NULL. * * \since This function is available since SDL 2.0.0. * @@ -1103,9 +1136,9 @@ extern DECLSPEC void SDLCALL SDL_GetWindowMinimumSize(SDL_Window * window, /** * Set the maximum size of a window's client area. * - * \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 + * \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. * * \since This function is available since SDL 2.0.0. * @@ -1118,11 +1151,11 @@ extern DECLSPEC void SDLCALL SDL_SetWindowMaximumSize(SDL_Window * window, /** * Get the maximum size of a window's client area. * - * \param window the window to query + * \param window the window to query. * \param w a pointer filled in with the maximum width of the window, may be - * NULL + * NULL. * \param h a pointer filled in with the maximum height of the window, may be - * NULL + * NULL. * * \since This function is available since SDL 2.0.0. * @@ -1141,8 +1174,8 @@ extern DECLSPEC void SDLCALL SDL_GetWindowMaximumSize(SDL_Window * window, * * 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 + * \param window the window of which to change the border state. + * \param bordered SDL_FALSE to remove border, SDL_TRUE to add border. * * \since This function is available since SDL 2.0.0. * @@ -1160,8 +1193,8 @@ extern DECLSPEC void SDLCALL SDL_SetWindowBordered(SDL_Window * window, * * 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 + * \param window the window of which to change the resizable state. + * \param resizable SDL_TRUE to allow resizing, SDL_FALSE to disallow. * * \since This function is available since SDL 2.0.5. * @@ -1176,9 +1209,9 @@ extern DECLSPEC void SDLCALL SDL_SetWindowResizable(SDL_Window * window, * This will add or remove the window's `SDL_WINDOW_ALWAYS_ON_TOP` flag. This * will bring the window to the front and keep the window above the rest. * - * \param window The window of which to change the always on top state + * \param window The window of which to change the always on top state. * \param on_top SDL_TRUE to set the window always on top, SDL_FALSE to - * disable + * disable. * * \since This function is available since SDL 2.0.16. * @@ -1190,7 +1223,7 @@ extern DECLSPEC void SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window * window, /** * Show a window. * - * \param window the window to show + * \param window the window to show. * * \since This function is available since SDL 2.0.0. * @@ -1202,7 +1235,7 @@ extern DECLSPEC void SDLCALL SDL_ShowWindow(SDL_Window * window); /** * Hide a window. * - * \param window the window to hide + * \param window the window to hide. * * \since This function is available since SDL 2.0.0. * @@ -1213,7 +1246,7 @@ extern DECLSPEC void SDLCALL SDL_HideWindow(SDL_Window * window); /** * Raise a window above other windows and set the input focus. * - * \param window the window to raise + * \param window the window to raise. * * \since This function is available since SDL 2.0.0. */ @@ -1222,7 +1255,7 @@ extern DECLSPEC void SDLCALL SDL_RaiseWindow(SDL_Window * window); /** * Make a window as large as possible. * - * \param window the window to maximize + * \param window the window to maximize. * * \since This function is available since SDL 2.0.0. * @@ -1234,7 +1267,7 @@ extern DECLSPEC void SDLCALL SDL_MaximizeWindow(SDL_Window * window); /** * Minimize a window to an iconic representation. * - * \param window the window to minimize + * \param window the window to minimize. * * \since This function is available since SDL 2.0.0. * @@ -1246,7 +1279,7 @@ extern DECLSPEC void SDLCALL SDL_MinimizeWindow(SDL_Window * window); /** * Restore the size and position of a minimized or maximized window. * - * \param window the window to restore + * \param window the window to restore. * * \since This function is available since SDL 2.0.0. * @@ -1262,8 +1295,12 @@ extern DECLSPEC void SDLCALL SDL_RestoreWindow(SDL_Window * window); * videomode change; `SDL_WINDOW_FULLSCREEN_DESKTOP` for "fake" fullscreen * that takes the size of the desktop; and 0 for windowed mode. * - * \param window the window to change - * \param flags `SDL_WINDOW_FULLSCREEN`, `SDL_WINDOW_FULLSCREEN_DESKTOP` or 0 + * Note that for some renderers, this function may trigger an + * SDL_RENDER_TARGETS_RESET event. Your application should be prepared to + * handle this event by reuploading textures! + * + * \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. * @@ -1297,11 +1334,15 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasWindowSurface(SDL_Window *window); * 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 that on some platforms the pixels pointer of the surface may be + * modified after each call to SDL_UpdateWindowSurface(), so that the platform + * code can implement efficient double or triple buffering. + * * You may not combine this with 3D or the rendering API on this window. * * This function is affected by `SDL_HINT_FRAMEBUFFER_ACCELERATION`. * - * \param window the window to query + * \param window the window to query. * \returns the surface associated with the window, or NULL on failure; call * SDL_GetError() for more information. * @@ -1322,7 +1363,7 @@ extern DECLSPEC SDL_Surface * SDLCALL SDL_GetWindowSurface(SDL_Window * window); * * This function is equivalent to the SDL 1.2 API SDL_Flip(). * - * \param window the window to update + * \param window the window to update. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1343,13 +1384,13 @@ extern DECLSPEC int SDLCALL SDL_UpdateWindowSurface(SDL_Window * window); * * Note that this function will update _at least_ the rectangles specified, * but this is only intended as an optimization; in practice, this might - * update more of the screen (or all of the screen!), depending on what - * method SDL uses to send pixels to the system. + * update more of the screen (or all of the screen!), depending on what method + * SDL uses to send pixels to the system. * - * \param window the window to update + * \param window the window to update. * \param rects an array of SDL_Rect structures representing areas of the - * surface to copy, in pixels - * \param numrects the number of rectangles + * surface to copy, in pixels. + * \param numrects the number of rectangles. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1365,7 +1406,7 @@ extern DECLSPEC int SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window * window, /** * Destroy the surface associated with the window. * - * \param window the window to update + * \param window the window to update. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1386,8 +1427,8 @@ extern DECLSPEC int SDLCALL SDL_DestroyWindowSurface(SDL_Window *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 input grab mode should be set - * \param grabbed SDL_TRUE to grab input or SDL_FALSE to release 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. * * \since This function is available since SDL 2.0.0. * @@ -1448,7 +1489,7 @@ extern DECLSPEC void SDLCALL SDL_SetWindowMouseGrab(SDL_Window * window, /** * Get a window's input grab mode. * - * \param window the window to query + * \param window the window to query. * \returns SDL_TRUE if input is grabbed, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.0. @@ -1460,7 +1501,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowGrab(SDL_Window * window); /** * Get a window's keyboard grab mode. * - * \param window the window to query + * \param window the window to query. * \returns SDL_TRUE if keyboard is grabbed, and SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.16. @@ -1473,7 +1514,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window * window); /** * Get a window's mouse grab mode. * - * \param window the window to query + * \param window the window to query. * \returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.16. @@ -1517,7 +1558,7 @@ extern DECLSPEC int SDLCALL SDL_SetWindowMouseRect(SDL_Window * window, const SD /** * Get the mouse confinement rectangle of a window. * - * \param window The window to query + * \param window The window to query. * \returns A pointer to the mouse confinement rectangle of a window, or NULL * if there isn't one. * @@ -1542,9 +1583,9 @@ extern DECLSPEC const SDL_Rect * SDLCALL SDL_GetWindowMouseRect(SDL_Window * win * something similar. * * \param window the window used to select the display whose brightness will - * be changed + * be changed. * \param brightness the brightness (gamma multiplier) value to set where 0.0 - * is completely dark and 1.0 is normal brightness + * 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. * @@ -1564,7 +1605,7 @@ extern DECLSPEC int SDLCALL SDL_SetWindowBrightness(SDL_Window * window, float b * this display can be retrieved using SDL_GetWindowDisplayIndex().) * * \param window the window used to select the display whose brightness will - * be queried + * be queried. * \returns the brightness for the display where 0.0 is completely dark and * 1.0 is normal brightness. * @@ -1582,8 +1623,8 @@ extern DECLSPEC float SDLCALL SDL_GetWindowBrightness(SDL_Window * window); * * This function also returns -1 if setting the opacity isn't supported. * - * \param window the window which will be made transparent or opaque - * \param opacity the opacity value (0.0f - transparent, 1.0f - opaque) + * \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. * @@ -1603,8 +1644,8 @@ extern DECLSPEC int SDLCALL SDL_SetWindowOpacity(SDL_Window * window, float opac * * This function also returns -1 if an invalid window was provided. * - * \param window the window to get the current opacity value from - * \param out_opacity the float filled in (0.0f - transparent, 1.0f - opaque) + * \param window the window to get the current opacity value from. + * \param out_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. * @@ -1617,8 +1658,8 @@ extern DECLSPEC int SDLCALL SDL_GetWindowOpacity(SDL_Window * window, float * ou /** * Set the window as a modal for another window. * - * \param modal_window the window that should be set modal - * \param parent_window the parent window for the modal 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. * @@ -1633,7 +1674,7 @@ extern DECLSPEC int SDLCALL SDL_SetWindowModalFor(SDL_Window * modal_window, SDL * 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. * @@ -1659,13 +1700,13 @@ extern DECLSPEC int SDLCALL SDL_SetWindowInputFocus(SDL_Window * window); * ramp set will not follow the window if it is moved to another display. * * \param window the window used to select the display whose gamma ramp will - * be changed + * be changed. * \param red a 256 element array of 16-bit quantities representing the - * translation table for the red channel, or NULL + * 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 + * 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 + * 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. * @@ -1687,13 +1728,13 @@ extern DECLSPEC int SDLCALL SDL_SetWindowGammaRamp(SDL_Window * window, * this display can be retrieved using SDL_GetWindowDisplayIndex().) * * \param window the window used to select the display whose gamma ramp will - * be queried + * be queried. * \param red a 256 element array of 16-bit quantities filled in with the - * translation table for the red channel, or NULL + * 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 + * 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 + * 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. * @@ -1711,7 +1752,7 @@ extern DECLSPEC int SDLCALL SDL_GetWindowGammaRamp(SDL_Window * window, * * \sa SDL_HitTest */ -typedef enum +typedef enum SDL_HitTestResult { SDL_HITTEST_NORMAL, /**< Region is normal. No special properties. */ SDL_HITTEST_DRAGGABLE, /**< Region can drag entire window. */ @@ -1728,9 +1769,9 @@ typedef enum /** * Callback used for hit-testing. * - * \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() + * \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 @@ -1771,9 +1812,9 @@ typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win, * 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 function to call when doing a hit-test - * \param callback_data an app-defined void pointer passed to **callback** + * \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. * @@ -1786,8 +1827,8 @@ extern DECLSPEC int SDLCALL SDL_SetWindowHitTest(SDL_Window * window, /** * Request a window to demand attention from the user. * - * \param window the window to be flashed - * \param operation the flash operation + * \param window the window to be flashed. + * \param operation the flash operation. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1801,7 +1842,7 @@ extern DECLSPEC int SDLCALL SDL_FlashWindow(SDL_Window * window, SDL_FlashOperat * 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 + * \param window the window to destroy. * * \since This function is available since SDL 2.0.0. * @@ -1872,7 +1913,7 @@ extern DECLSPEC void SDLCALL SDL_DisableScreenSaver(void); * program from the dynamic library using SDL_GL_GetProcAddress(). * * \param path the platform dependent OpenGL library name, or NULL to open the - * default OpenGL library + * default OpenGL library. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1924,7 +1965,7 @@ extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path); * 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 + * \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. * @@ -1959,7 +2000,7 @@ extern DECLSPEC void SDLCALL SDL_GL_UnloadLibrary(void); * 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 + * \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. @@ -1985,8 +2026,9 @@ extern DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void); * 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 + * \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. * @@ -2000,8 +2042,9 @@ extern DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value); /** * Get the actual value for an attribute from the current context. * - * \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` + * \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. * @@ -2023,7 +2066,7 @@ extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value); * * SDL_GLContext is an alias for `void *`. It's opaque to the application. * - * \param window the window to associate with the context + * \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. * @@ -2040,8 +2083,8 @@ extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_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 + * \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. * @@ -2084,10 +2127,11 @@ extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_GetCurrentContext(void); * platform with high-DPI support (Apple calls this "Retina"), and not * disabled by the `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint. * - * \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 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 + * NULL. * * \since This function is available since SDL 2.0.1. * @@ -2116,7 +2160,7 @@ extern DECLSPEC void SDLCALL SDL_GL_GetDrawableSize(SDL_Window * window, int *w, * 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 + * 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. * @@ -2153,7 +2197,7 @@ extern DECLSPEC int SDLCALL SDL_GL_GetSwapInterval(void); * glBindFramebuffer(), this is the default and you won't have to do anything * extra. * - * \param window the window to change + * \param window the window to change. * * \since This function is available since SDL 2.0.0. */ @@ -2162,7 +2206,7 @@ extern DECLSPEC void SDLCALL SDL_GL_SwapWindow(SDL_Window * window); /** * Delete an OpenGL context. * - * \param context the OpenGL context to be deleted + * \param context the OpenGL context to be deleted. * * \since This function is available since SDL 2.0.0. * diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_vulkan.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/SDL_vulkan.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_vulkan.h + * # CategoryVulkan * - * Header file for functions to creating Vulkan surfaces on SDL windows. + * Header file for functions to creating Vulkan surfaces on SDL windows. */ #ifndef SDL_vulkan_h_ @@ -101,13 +101,13 @@ typedef VkSurfaceKHR SDL_vulkanSurface; /* for compatibility with Tizen */ * supported. Either do not link to the Vulkan loader or link to a dynamic * library version. * - * \param path The platform dependent Vulkan loader library name or NULL + * \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. * * \since This function is available since SDL 2.0.6. * - * \sa SDL_Vulkan_GetVkInstanceProcAddr + * \sa SDL_Vulkan_GetVkGetInstanceProcAddr * \sa SDL_Vulkan_UnloadLibrary */ extern DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path); @@ -150,11 +150,11 @@ extern DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void); * however, this parameter will likely be removed in future releases * * \param window A window for which the required Vulkan instance extensions - * should be retrieved (will be deprecated in a future release) + * 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 + * extensions to be returned. * \param pNames NULL or a pointer to an array to be filled with required - * Vulkan instance extensions + * Vulkan instance extensions. * \returns SDL_TRUE on success, SDL_FALSE on error. * * \since This function is available since SDL 2.0.6. @@ -172,10 +172,10 @@ extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_GetInstanceExtensions(SDL_Window *wi * `instance` must have been created with extensions returned by * SDL_Vulkan_GetInstanceExtensions() enabled. * - * \param window The window to which to attach the Vulkan surface - * \param instance The Vulkan instance handle + * \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 + * created surface. * \returns SDL_TRUE on success, SDL_FALSE on error. * * \since This function is available since SDL 2.0.6. @@ -195,9 +195,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window, * platform with high-DPI support (Apple calls this "Retina"), and not * disabled by the `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint. * - * \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 + * \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. * * \since This function is available since SDL 2.0.6. * diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/begin_code.h b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Headers/begin_code.h @@ -19,12 +19,12 @@ 3. This notice may not be removed or altered from any source distribution. */ +/* WIKI CATEGORY: BeginCode */ + /** - * \file begin_code.h - * - * This file sets things up for C dynamic library function definitions, - * static inlined functions, and structures aligned at 4-byte alignment. - * If you don't like ugly C preprocessor code, don't look at this file. :) + * begin_code.h sets things up for C dynamic library function definitions, + * static inlined functions, and structures aligned at 4-byte alignment. + * If you don't like ugly C preprocessor code, don't look at this file. :) */ /* This shouldn't be nested -- included it around code only. */ @@ -172,7 +172,7 @@ (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 202000L) #define SDL_FALLTHROUGH [[fallthrough]] #else -#if defined(__has_attribute) +#if defined(__has_attribute) && !defined(__SUNPRO_C) && !defined(__SUNPRO_CC) #define SDL_HAS_FALLTHROUGH __has_attribute(__fallthrough__) #else #define SDL_HAS_FALLTHROUGH 0 diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Resources/Info.plist b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/Resources/Info.plist @@ -19,7 +19,7 @@ <key>CFBundlePackageType</key> <string>FMWK</string> <key>CFBundleShortVersionString</key> - <string>2.30.12</string> + <string>2.32.2</string> <key>CFBundleSignature</key> <string>SDLX</string> <key>CFBundleSupportedPlatforms</key> @@ -27,7 +27,7 @@ <string>MacOSX</string> </array> <key>CFBundleVersion</key> - <string>2.30.12</string> + <string>2.32.2</string> <key>DTCompiler</key> <string>com.apple.compilers.llvm.clang.1_0</string> <key>DTPlatformBuild</key> diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/SDL2 b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/SDL2 Binary files differ. diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/_CodeSignature/CodeResources b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/A/_CodeSignature/CodeResources @@ -14,7 +14,7 @@ </data> <key>Resources/Info.plist</key> <data> - jESzPNfAE68YVYa1JqAGzzZlVgk= + Dy9w1XfagXeZ0e81ZSWsFJg+azY= </data> <key>Resources/License.txt</key> <data> @@ -35,88 +35,88 @@ <dict> <key>hash</key> <data> - szoTZ+UW6M4zlTQFrRMblKZbAy0= + kXZkl2ZSSQyVrmrJOXBRaAtXY0I= </data> <key>hash2</key> <data> - bW2HEtw13tGn38QlBSvwA6gqlSHRuiD+dJmGvPkelmU= + xDumk5UiAj/35enjtwvoNz9i9FWhFvojHs4+59cpnbI= </data> </dict> <key>Headers/SDL_assert.h</key> <dict> <key>hash</key> <data> - rIyJvCWybknhk6vSENqN18jIXXA= + lr3sQSBPznWi8vveV34dIyAW8BM= </data> <key>hash2</key> <data> - 2g8v9qkDCkSpBiAmIM4CuT20SJU21cGGNdPzoxI7XZY= + BGNHXTS5rBD3wuyUkKhgbl50o8FUh12u96oFkrA4KFo= </data> </dict> <key>Headers/SDL_atomic.h</key> <dict> <key>hash</key> <data> - n7wOXwjIdrZYkzJyuv/Y+Iz+wkg= + R5vrwDefFJeaJsnGkly4WqJ7UPw= </data> <key>hash2</key> <data> - qmxBKFsgCFIVc8om5S815bks2PaEknnPcjSIamG4edk= + DgHR+hJ6x1M3+NB4wUNI4S8Xj2awpMe4dWD1hJ6C+Ak= </data> </dict> <key>Headers/SDL_audio.h</key> <dict> <key>hash</key> <data> - poAS7VnlUFhxdrBEKFP4EvukNUU= + vD35LoraUn0dXRtYXURSOA2fmzo= </data> <key>hash2</key> <data> - Tsdxv5wWcs2R359gukhwdjDEUXCs80rfKHUudM9L/NY= + 7GEn/t1dKLeDAz+dClqETucnBCg0JQiRgVOxmOn7JFM= </data> </dict> <key>Headers/SDL_bits.h</key> <dict> <key>hash</key> <data> - ZIGoNNpWlYXPn4pUApnxGg2zXSs= + m/yLRLFvcyhpnaReaUyzn+DrKjY= </data> <key>hash2</key> <data> - 5oKpBJOEvM17BJXzxC/YQhhCoW2RD6ZZe22I0cPz7lc= + o2NLdv2ji2kQE1gvsKNW/xcd1txMxhXGRX6D9LXZpA0= </data> </dict> <key>Headers/SDL_blendmode.h</key> <dict> <key>hash</key> <data> - VM6EnTGffUqd6Nqmue+3NLj8Wq0= + ZhDDvn1XJCv+eMyWGDNz26CFI58= </data> <key>hash2</key> <data> - xkHYVT2V/aQU64IgEtGDbEbqaBVlScaGPY4h29/ZGU8= + bQjeL6hATkceL0ngnlzrYY2Zp7jNdLW26Cr3Mt7eM6o= </data> </dict> <key>Headers/SDL_clipboard.h</key> <dict> <key>hash</key> <data> - U8R4Lp+xppbP1QXWGc+NQPKcTKQ= + uq20kABjWOFzXdejk/Q8rC8a5AM= </data> <key>hash2</key> <data> - rpwSMt3xs+tfmYr5oSYxJYE/Airao0Merl7SdMQBz0w= + u9qUforELEcJfq+QEHCgZ3wd8g5tPW9JI1+zj4xEm5E= </data> </dict> <key>Headers/SDL_config.h</key> <dict> <key>hash</key> <data> - DsoHCm+xZ9YPKm8rb+A0i3/aRyM= + hI+pWoBtzhWnuh9kOELW4J4hs8o= </data> <key>hash2</key> <data> - 5mMRwuIB32Sk1g4B7rFzZRn7FG6U+iHS6khOAucoLFM= + s/hYepaQobM/ewrw1MULpg/LKbyWnIHEVZQ4sbSY7ws= </data> </dict> <key>Headers/SDL_config_macosx.h</key> @@ -145,253 +145,253 @@ <dict> <key>hash</key> <data> - cHwIsNWoaM5oT9ErxuvCSDDXLHA= + C0H58cl/xghA4cpTvltFa5zADSc= </data> <key>hash2</key> <data> - hKt0HxrpiGrTEB12/thJmpdlbDQ2JtZdcnC/hH0TT5w= + JpncPWHkqqQ39WvjWBFvdMLGOAhlGvwtEdtEflUSwwQ= </data> </dict> <key>Headers/SDL_endian.h</key> <dict> <key>hash</key> <data> - 90rCMZNthI+iguNWrit8fVSPjsM= + Oo+H5bGafn8oIzZ5A2DI+6yJsNI= </data> <key>hash2</key> <data> - YSBWifRu40lnlyJekPyT1ideEfog865npUsdSLtRh/A= + ejsqpRB8uahMk/Zo2KMVUes2H9nWrrSMDXtypIMmAUE= </data> </dict> <key>Headers/SDL_error.h</key> <dict> <key>hash</key> <data> - h6fXKviOtmcCQIkqzwjMAtC7I7w= + ZxWtU4QHHrwxJbxAg+0wA/BX2OA= </data> <key>hash2</key> <data> - p4CBIXT/A+jDRwtHaUH3xB0bwNV0aJ/e9jqSexmtG2c= + SsWIV+Yerb7smmRk25OcD33qX1UCM94jrw0iu38zQco= </data> </dict> <key>Headers/SDL_events.h</key> <dict> <key>hash</key> <data> - OCy3CH+HASANGBaV5Nu/qet8ML8= + 34TF6C56a/HKmGg7hzyO88NJle4= </data> <key>hash2</key> <data> - bNPw20oLa45oKb93b7PaRFgBXrnx93opB0J8KktsYIE= + 2Po+gCuGCGxgmR6DdLPrWu2deTHFLhWAFPZUCkap8Mo= </data> </dict> <key>Headers/SDL_filesystem.h</key> <dict> <key>hash</key> <data> - qfFFwMlK9JJLK43hGykgojoAsik= + 5OC/DWaJoiaHRxExqCHZ1QPRP4Y= </data> <key>hash2</key> <data> - Mo+N4byz35KXr7OpoEXNnIlHUFbhUPrp7mcJOUH0yvw= + tZpKt7pLk5yKvjAiPMqdoeFsNWGZlwY390pZAzyeCLM= </data> </dict> <key>Headers/SDL_gamecontroller.h</key> <dict> <key>hash</key> <data> - hc3zeQXp9ZWClvAWbSFLPfxaYZg= + I/FIRlgGO0GQxPa7tmoA9QbfT8s= </data> <key>hash2</key> <data> - tApp2V4YNcSI1EKEXWbNgVkXEqrCfpXOP76ympkShlg= + kcdn3wsLxbvOYUIfT6RjZ6PVwEJyiP19UHCVZ1SK0Xg= </data> </dict> <key>Headers/SDL_gesture.h</key> <dict> <key>hash</key> <data> - uzP8E0LPqR5s3nir8tN5uIvPB14= + clELTT6eZHcdLgYclKLVVihe3vU= </data> <key>hash2</key> <data> - LqlvJygqx6CgQ/7V4j3X8I9oBzD6upSqiNQc4chNQs4= + jcGQi63lLK6d0mKPptalC8oIPHIYkJXVFmB+Ph03FIc= </data> </dict> <key>Headers/SDL_guid.h</key> <dict> <key>hash</key> <data> - hmhZ70ul+daU2/X6QcLpFsZWcNE= + dgThPofjZztWJ48hlLrifr+7Dtc= </data> <key>hash2</key> <data> - 0ak+kH41rPl6mJ7/e4DxbksZ0mo0FkC1l1gQBU5sVzQ= + +2lkD4yu0yhf1fO7Cbd91+Zw7rsW1R7oVeT9Z6YOwZU= </data> </dict> <key>Headers/SDL_haptic.h</key> <dict> <key>hash</key> <data> - 2SW7LfyRaUAv3iO6Gg8x82UQPnk= + yhzVxf1Kdqq1Xr2Sg+pJbTqkwQ0= </data> <key>hash2</key> <data> - VSTYzwTdPnxWbeRwnam7P6hXOkkuGsjxEtv34lksIfM= + q4GVfzAB4sSEDj+jIPWp9Xw2B3HauyTHo/o060eaygQ= </data> </dict> <key>Headers/SDL_hidapi.h</key> <dict> <key>hash</key> <data> - wys7GscP2S3hOuBJaX7Zs1rdABY= + z+fSffaSHzN3Y/+Fvx/Q3ZxzlvM= </data> <key>hash2</key> <data> - EFTAY5N/RDQ/l28iXt6YU82o4wQfksEvg9NHCe87wiQ= + CBbGekbczUMw0zOsfPZwjkntaN1nlc4fho8S5LTQbTc= </data> </dict> <key>Headers/SDL_hints.h</key> <dict> <key>hash</key> <data> - 8grraRkgHQCHCeiTiFmmdVxOnyA= + x8pHmxmobsfIdGQ3U8T/wVTr4pc= </data> <key>hash2</key> <data> - AvgwtPXKim1Z0DtKiaBF5gErJem9LXMXEQ0mXFTD29Y= + 6tHFNKbAt52Tfvnd9I5945Lgf9zMlRYqeRuWrPW2wfo= </data> </dict> <key>Headers/SDL_joystick.h</key> <dict> <key>hash</key> <data> - TpEuc3Jj0ZNykIfsJzn5u+eDRKc= + 6XHQGqWAhtUqF+5nJXvM5qTYwRE= </data> <key>hash2</key> <data> - RCaBlGhjqJhVypyXq7qibu9CY0LVoabsd3EHwkETjbU= + uKjhvX3KIhPTT/lpAu1Y3q/KMqIQXVfi2H+VFfmb4mg= </data> </dict> <key>Headers/SDL_keyboard.h</key> <dict> <key>hash</key> <data> - g+MPSprjm7vcMsMd/wLkdd9NrU4= + Ml+MLe134SMquN/d5bx948jSG2k= </data> <key>hash2</key> <data> - 90sol8kJnKmwp1A7cSjHjF97xEjGliZgL4XRAVwRp2I= + SO9J+my4T35L6w60ZTEC98mabEy2W14U3bXg8ZMSodQ= </data> </dict> <key>Headers/SDL_keycode.h</key> <dict> <key>hash</key> <data> - K1YmjsaJPtnAbzM0NtV+49y5ij4= + m7xeznNONTBfKkVWp/d041JqNxc= </data> <key>hash2</key> <data> - ejuRyCNpmBcZPDN7TVguQ9bnjKrixfZBAnHuu27+2hU= + wl5XcoxPLKXuZfRaVMHaN5CjnygVgrSNowFRESevpd8= </data> </dict> <key>Headers/SDL_loadso.h</key> <dict> <key>hash</key> <data> - CMc5En/AnoWgyx3aLIoSGCFh/jA= + 5L842bJf5iUWjoTpu+UQFgKa09I= </data> <key>hash2</key> <data> - 6FlCQsL/t9rotWnnRwIp0W9T4Nx6bY+Y3Slfn54kWWU= + zryjqdnh9zWQRgbBLaH8ZzFYHxS0/wEeBXqq9KW8wds= </data> </dict> <key>Headers/SDL_locale.h</key> <dict> <key>hash</key> <data> - Ns0HLxFujODEB/R96m+GovJ26C4= + PIHUy1X2+y0z6c3pxt/ge6pBcvo= </data> <key>hash2</key> <data> - qYrdic2N30C0i6VaXgTjOAUK96ZppaLI/D2X37s1WFI= + /rfGMxdMoHftVV0QUdzzyMCV5DNBVAJ2t2fDfmXGEo0= </data> </dict> <key>Headers/SDL_log.h</key> <dict> <key>hash</key> <data> - 6kYjboxWHr/OWH2wjc9kOyMN5Q0= + +/4vJepf9ntrZJr5bivvVp/QUio= </data> <key>hash2</key> <data> - 1qRi5NQkl7LG3RiMF7Hma9NdikGlSK+U/wrtVz0r0BE= + CIY407VUnS9pLPMOxgjJpAGcv3zny3Ls+Y7yhVO0qqE= </data> </dict> <key>Headers/SDL_main.h</key> <dict> <key>hash</key> <data> - fcGrpNPxH380Jq7ZnPzdwa1KbWE= + E0g/VXfi2wtzpgsPenS2Si+WzoU= </data> <key>hash2</key> <data> - dpFEnHvFCDQ0zn8PLGsZJ9raacYsCVeV0EESDv4jdjg= + t7yYbM3kL+w4Cjbt6cIcyLJ59lDFO7YwlCxbNXPf7/8= </data> </dict> <key>Headers/SDL_messagebox.h</key> <dict> <key>hash</key> <data> - PncaWDlEQvYS9yr8gAOrW1E5C7U= + S/UqHw1xzOq/G5whAbsqqR83zFE= </data> <key>hash2</key> <data> - 75/uf2pgUcYzuu9q/wH/0Lrw28eFAXKk4EJSARuaPlc= + 9aB/qv/nBBV7BOwuqIY4MXSD6bpDrkA4afejIwfNBp8= </data> </dict> <key>Headers/SDL_metal.h</key> <dict> <key>hash</key> <data> - A6LJSU5rn6dAFNKKfx+k2KETKZw= + fmU5Aftuv130e3jkyJpHaPg3eqM= </data> <key>hash2</key> <data> - UOhX5Cr2WkRCSjrQ//B0XfYajA9m70rRlVMdIVSS8Ug= + hwRNMv854qroz8h1X0Aaab5nt3a6JLY0GSILyvaBvCk= </data> </dict> <key>Headers/SDL_misc.h</key> <dict> <key>hash</key> <data> - sXjqdYBIrnK8e/od5QQ6xwxgOkw= + R+Xst5koKUN3c8Q7ABjNFogS7S4= </data> <key>hash2</key> <data> - ltOY0ilt30GRNyuE7T2AW94K97CAE6s4wLZdpLDVIls= + lczD5q4vVNJ0MwkE9oLIYaZsWesbVlAu1cLQ1Dg+nmM= </data> </dict> <key>Headers/SDL_mouse.h</key> <dict> <key>hash</key> <data> - MmWu0BJarAuo75epPR/XXrVP2Ic= + n11vFqL98fGtKLlIjg5mmNQIL68= </data> <key>hash2</key> <data> - bF5OAcFh2FLZAWCOxbcAyHd1VcTgaUUE/Ekg566Q+IA= + MDPaWpoGwlvOF7QxkDl0rh6bjsPhvf4oRwDOdTzWjTA= </data> </dict> <key>Headers/SDL_mutex.h</key> <dict> <key>hash</key> <data> - gCz3Nv9EzRbH6H8P1AwUlu/OIZ8= + +P42iYJpHbiwGZ7bBhCJFWSQgos= </data> <key>hash2</key> <data> - g4nhEgVsnXaaodfdhR0GJly8Xq82AlVx/8andTSlS4U= + EcYUNrtTCWC+fr7AUjZLpWNxq0TH0NmEZ3LkjVV9/TE= </data> </dict> <key>Headers/SDL_name.h</key> @@ -409,11 +409,11 @@ <dict> <key>hash</key> <data> - Q90bBafFHszLeE8yBNeHm12QdlQ= + 3leUh6Gq18sJB4BEcKQy+iQolc0= </data> <key>hash2</key> <data> - BPd3egmtGYAVuwj0YHngqICGDqQy3Nzh/8NTTHD0yAY= + k8R1LV5eKvkCsaMBHfJ1lNNI7I/dqmIbqr+qjbsRn64= </data> </dict> <key>Headers/SDL_opengl_glext.h</key> @@ -431,22 +431,22 @@ <dict> <key>hash</key> <data> - n4pNuXLYivjIgXTeEtm8ZQ6qKnk= + P5Pj7wk9Nf1ixGBxO3GiEwSI0TU= </data> <key>hash2</key> <data> - e/2z/uWUAJUOn6BiAvYcFJzzuPANQw+V1f+PlKxOu1U= + 7UPklt2GVWwjaLS9BScuAQJ1VnJfzyOWQ7XffOUgKF4= </data> </dict> <key>Headers/SDL_opengles2.h</key> <dict> <key>hash</key> <data> - z4dMiAEn9NQnUdUMteX76RJ6N5M= + iaFWK+305+CdfRcsenhRwwxW348= </data> <key>hash2</key> <data> - /y6K6JOn+tGufX9VQj1HRct0mtVv1OsrLB/V60KuRwM= + p6YaZQLVlsW+Xtmwq2apbUUN0V5PQBqbL+Kb50ty874= </data> </dict> <key>Headers/SDL_opengles2_gl2.h</key> @@ -497,66 +497,66 @@ <dict> <key>hash</key> <data> - 1fIwoEe2ktQb6D5A7PQ7mi2Oqec= + HOeOsR1S852BPw+GyoQxCu8dnrk= </data> <key>hash2</key> <data> - 7geaawuRwA91yelwtNBEl0b/VR+r/CSr84vVYa1YIM4= + DMnCgERmRqNhjIu8bEnce3WOlhLueJ7/2VQlkld0cqM= </data> </dict> <key>Headers/SDL_platform.h</key> <dict> <key>hash</key> <data> - F8OSz+awKv1XDtEakTW8vo55/Vs= + 2EuaPqxxPCCnhQT8TgXVlAGPVd0= </data> <key>hash2</key> <data> - SNI/VCAQ35ReFL9qF5xj8Lhu4a/Prm53nTK7tRA1jhg= + /UdCUiELMW5LpnyQtiRIrltB0fmsOUuo5PcJfihUSP4= </data> </dict> <key>Headers/SDL_power.h</key> <dict> <key>hash</key> <data> - +yLHw43h1fJujEDgyY7jpN1txU0= + OcflGeCM0fbVTFzZKWdM1eKVKlg= </data> <key>hash2</key> <data> - IjPm5fw8G4fGmIEDbiQukZxBn9rYKt8OSIutX9QfZuA= + u80xdoA8Qm6LjBYuxop4mIHrpcCya4BL5oxrH9I+DaM= </data> </dict> <key>Headers/SDL_quit.h</key> <dict> <key>hash</key> <data> - qT1qlKVJIRMfIje3cQSmKU9SjAo= + UesdW/A6uv3gPVlX0rttt2qUYY8= </data> <key>hash2</key> <data> - EysJnWaW2IwfC6s/E8x2vKwbbwbfiW8j7/OjKcfrPp8= + 1orkEGymBZUzW8+XfZkjeGEbgKcXPxZkwleDgdTXWFU= </data> </dict> <key>Headers/SDL_rect.h</key> <dict> <key>hash</key> <data> - AyXLTBMooPXNWI9syN7FLtZ8EGQ= + 0tzoAGRmXs2qe4YGcW7xEB44mgI= </data> <key>hash2</key> <data> - s8YsZal0Dzfp45WhQh2Sop4hJ/lPGeHUwTHZS4M8+Pc= + 4a+aTUFeNyT8FcphJmUM2TJsOqpZr5pDXXmKjQWfwLA= </data> </dict> <key>Headers/SDL_render.h</key> <dict> <key>hash</key> <data> - aWAMDKmt93Ao4AU5feyBSJnbpyg= + ixhZ1LVMllogghoxkbkrnjkmfm0= </data> <key>hash2</key> <data> - 0syhQHuuYccT9K/0c1YSSs7AIFZdWaj1XpbK6XTjIvg= + YKCPJJ9GkJ8hiZ95O876mXtZ5SvBv5ViiUsgYkuykPs= </data> </dict> <key>Headers/SDL_revision.h</key> @@ -574,176 +574,176 @@ <dict> <key>hash</key> <data> - Ki47XgLI9PP9BsgCOocGnLd8YJk= + RoEkA5bj0f8XwVQyVcYHxlRLH+M= </data> <key>hash2</key> <data> - nLeSv+IRZOlqDFrK+Kq/oTCotwGs/McKAHZPlhMm0k0= + x/9RNtJfolHcK7DxJwPH3corQGd2BbzC8PgvzzHSxX8= </data> </dict> <key>Headers/SDL_scancode.h</key> <dict> <key>hash</key> <data> - MagJ1t5D9cUUdjfJxO4SSxKn/s0= + uT6v61MI9lFx99szDhZfL4N/rGc= </data> <key>hash2</key> <data> - v84LnU16TV6RKwAcwhP0j+ypcZ8tYazJ5x41L8WXH9E= + MzwGUSgeP0Cmj7z20owSg5EsfpwV9yfG7bIFUqgzric= </data> </dict> <key>Headers/SDL_sensor.h</key> <dict> <key>hash</key> <data> - ekOOqi8kKKNwFU1pgFpq1V+YR4w= + 5r6P94IS5vfiIJMZhrMZNpabid0= </data> <key>hash2</key> <data> - lR1mKNtje2LhTqfwh06Adf1aF8XPb7ZSQnwLlDND9F4= + gAFmGVEIFr3q+SQiXmHBctnS1qMa9guogUbp2JDeDdk= </data> </dict> <key>Headers/SDL_shape.h</key> <dict> <key>hash</key> <data> - +IzMhEcjMEVIuOFt1uwMqmL6v7E= + jmzKazW1l/+89mfDEsa68yfO+M0= </data> <key>hash2</key> <data> - 7M4n2rfnvCfTE5+nS/tJp6iA35L6czERKuv9iQlC/n0= + zrlHT6aGBYNFY5OOhnuPp6/HUIq32NzHq7RcHEnY4ww= </data> </dict> <key>Headers/SDL_stdinc.h</key> <dict> <key>hash</key> <data> - 8QMuXJYqaxRMPcv5u+iv7E67LBs= + ghpA/MCplmhdO4hJb25EXKh4+s4= </data> <key>hash2</key> <data> - EdsumpR5mB5VaJVsyvZgYGJ0BLa9jA5lm66/V+hOo+o= + cSrXM8EyC4v/PujaxFfax4TvFm2zt24dFebf53otApM= </data> </dict> <key>Headers/SDL_surface.h</key> <dict> <key>hash</key> <data> - hcQ0Xf+oe5CIPdK/p0s3EYvn1Jw= + 4Ep9Q21aB+MvJ4ohfIaIobCiERU= </data> <key>hash2</key> <data> - L4fQk7WiPrvRH2KN1BAREdwHFF/iFV0vbhi+Yfk2ck0= + HBm9M4a5z2TAO7jYrEREEBPmFIZ10He+SyiAhJ90C6M= </data> </dict> <key>Headers/SDL_system.h</key> <dict> <key>hash</key> <data> - 4BQqRt25rE6gz3HZIqrWc0sVChs= + kBnA4mSoS+aU91if04kxha03KHY= </data> <key>hash2</key> <data> - mt+VVfR8xWZ6HFwR2IPTsVioxlle1/l7BM8/QlhlhNs= + EV4kDREc7p2kR4LtHoOuY6J2Rsm+KX65ZQv58y+QVz8= </data> </dict> <key>Headers/SDL_syswm.h</key> <dict> <key>hash</key> <data> - eGil06WtbiBMBrBlfGTfU59ilGI= + yIC4ZT4qln13hliROuzUyx3FhyY= </data> <key>hash2</key> <data> - cExBYrufNgnE2h2D/+g4e9P78tw78U6lwPt/6SAh99o= + rXp/rtBhEjRJoZnGV9F6IrAIdoE5WJdtUtwNypSUF7E= </data> </dict> <key>Headers/SDL_thread.h</key> <dict> <key>hash</key> <data> - nhxs2YXZEAAABhCCly6FBwJyIVw= + OFKWGOtypbrEI7UTrkw42voWf20= </data> <key>hash2</key> <data> - jProCOb6lntIte2C8xsnYMedNUYCaMgCk4kzf1JkRhY= + 7qn2qV503yS1JbYFUB2HvCHoN1AzetzjrmZWZIIf3qo= </data> </dict> <key>Headers/SDL_timer.h</key> <dict> <key>hash</key> <data> - F4SP5Obcx3huEZ4MP3zlMh+gVdw= + GIT08iK8cG99/tVgSH4+ACwG9mU= </data> <key>hash2</key> <data> - jzrSTcXaNBjpj1IKY/ADhiiuudJe7gZw9ND2Oa0FyW4= + Q8Bv8+1i2eKfGySzfRXZT03Clzce9l8uP9QDjGTzzVc= </data> </dict> <key>Headers/SDL_touch.h</key> <dict> <key>hash</key> <data> - 6vhIvHe/ZmQnHrZDIOngBL+KLVU= + QmkTEEIiL2jICJu6ecf2wLwyhAU= </data> <key>hash2</key> <data> - /Q/C0mRXFy4EXe69A+ygrV60pojHzI+UEh1hpw7a5Uw= + MOw1u2X8Zk9fljCdbfSRRyEXEbgT+caV26N+T0NjF0s= </data> </dict> <key>Headers/SDL_types.h</key> <dict> <key>hash</key> <data> - +ft8hvbcKHar7v/aTUNeVxAyw0Y= + Uh90u3TkJONniC7ql41abwXUPa4= </data> <key>hash2</key> <data> - qmvIcFXNA1r8zfJC5XZYLn3FCLq9YWQVZ2CmTxPRKw4= + jrJoMRTqqOrdJC6jL9UHPmZHjACvE7fU8poxxLLjKd8= </data> </dict> <key>Headers/SDL_version.h</key> <dict> <key>hash</key> <data> - I/lyzuAeveDmThBIuOC4DUgKMic= + 0p5YxpDU0ZKVW3O7oaiUEbQvQgM= </data> <key>hash2</key> <data> - EBYxbRDZpHP9GSqf6WgKA0v/IKaOgflKPE2VV6/fRxY= + EtiQXi0LseubTFgUWQb2VmPg9hMBLtbyUYL/q744sqo= </data> </dict> <key>Headers/SDL_video.h</key> <dict> <key>hash</key> <data> - UlQTZYCQoY31S36HghsdeKBfe1I= + pbav/kF15VNS1e5QTP2fYMa9u+E= </data> <key>hash2</key> <data> - eCHeiPp27E6Uuy+yVWhAnMv90n9T18stOMqH8xRtw1Q= + XyZkUty0lOswE4c3LokQs92335pjv6Mdqu/eFkB0XNo= </data> </dict> <key>Headers/SDL_vulkan.h</key> <dict> <key>hash</key> <data> - bsq9F6bHSfRUZWqi6pyhcJfFdv8= + gLQPn/TnSR9Mw0SzIieM7cyPPQY= </data> <key>hash2</key> <data> - orVndhc5fB+XucpAcaS8hFxijBDU2oR4F1jhbc7Ju1k= + gqb0mAn18Ax0d7+3MwoDmO2kMJ2wXR900U/Kxs7QP8A= </data> </dict> <key>Headers/begin_code.h</key> <dict> <key>hash</key> <data> - 7za3SOa60MgSMnFyUMAE51KiJVU= + F5WwG4LxINu6xsjkDri880RDPAQ= </data> <key>hash2</key> <data> - C2GhWOTumDTaCzX+9soBe5KEB8QOvC++hIQQc4whBbE= + mAPasp+0UizjUAq3iSYOliLfYwfOkPkq0gwYCOGcTns= </data> </dict> <key>Headers/close_code.h</key> @@ -783,11 +783,11 @@ <dict> <key>hash</key> <data> - jESzPNfAE68YVYa1JqAGzzZlVgk= + Dy9w1XfagXeZ0e81ZSWsFJg+azY= </data> <key>hash2</key> <data> - qm21JRCtQ5em6iywJ3ZXyBn3vKdbwBOfTmIOo+GAAH8= + BAddkaN2r4dEHPxmdAwZ33wKCEuHqn1y3xUe9sQ/wtY= </data> </dict> <key>Resources/License.txt</key> diff --git a/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/Current b/release/macos/ft2-clone-macos.app/Contents/Frameworks/SDL2.framework/Versions/Current Binary files differ. diff --git a/release/win32/SDL2.dll b/release/win32/SDL2.dll Binary files differ. diff --git a/release/win64/SDL2.dll b/release/win64/SDL2.dll Binary files differ. diff --git a/vs2019_project/ft2-clone/SDL2.dll b/vs2019_project/ft2-clone/SDL2.dll Binary files differ. diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL.h @@ -25,7 +25,6 @@ * Main include header for the SDL library */ - #ifndef SDL_h_ #define SDL_h_ @@ -70,6 +69,8 @@ extern "C" { #endif +/* WIKI CATEGORY: Init */ + /* As of version 0.5, SDL is loaded dynamically into the application */ /** @@ -130,7 +131,7 @@ extern "C" { * 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 + * \param flags subsystem initialization flags. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_assert.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_assert.h @@ -61,6 +61,8 @@ assert can have unique static variables associated with it. #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "brk #22\n\t" ) #elif defined(__APPLE__) && defined(__arm__) #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "bkpt #22\n\t" ) +#elif defined(_WIN32) && ((defined(__GNUC__) || defined(__clang__)) && (defined(__arm64__) || defined(__aarch64__)) ) + #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "brk #0xF000\n\t" ) #elif defined(__386__) && defined(__WATCOMC__) #define SDL_TriggerBreakpoint() { _asm { int 0x03 } } #elif defined(HAVE_SIGNAL_H) && !defined(__WATCOMC__) @@ -191,8 +193,8 @@ extern DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *, * A callback that fires when an SDL assertion fails. * * \param data a pointer to the SDL_AssertData structure corresponding to the - * current assertion - * \param userdata what was passed as `userdata` to SDL_SetAssertionHandler() + * current assertion. + * \param userdata what was passed as `userdata` to SDL_SetAssertionHandler(). * \returns an SDL_AssertState value indicating how to handle the failure. */ typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)( @@ -212,8 +214,8 @@ typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)( * This callback is NOT reset to SDL's internal handler upon SDL_Quit()! * * \param handler the SDL_AssertionHandler function to call when an assertion - * fails or NULL for the default handler - * \param userdata a pointer that is passed to `handler` + * fails or NULL for the default handler. + * \param userdata a pointer that is passed to `handler`. * * \since This function is available since SDL 2.0.0. * @@ -254,7 +256,7 @@ extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetDefaultAssertionHandler(void * 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() + * 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. diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_atomic.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_atomic.h @@ -20,38 +20,29 @@ */ /** - * \file SDL_atomic.h + * # CategoryAtomic * * Atomic operations. * - * IMPORTANT: - * If you are not an expert in concurrent lockless programming, you should - * only be using the atomic lock and reference counting functions in this - * file. In all other cases you should be protecting your data structures - * with full mutexes. + * IMPORTANT: If you are not an expert in concurrent lockless programming, you + * should not be using any functions in this file. You should be protecting + * your data structures with full mutexes instead. * - * The list of "safe" functions to use are: - * SDL_AtomicLock() - * SDL_AtomicUnlock() - * SDL_AtomicIncRef() - * SDL_AtomicDecRef() + * ***Seriously, here be dragons!*** * - * Seriously, here be dragons! - * ^^^^^^^^^^^^^^^^^^^^^^^^^^^ - * - * You can find out a little more about lockless programming and the - * subtle issues that can arise here: - * http://msdn.microsoft.com/en-us/library/ee418650%28v=vs.85%29.aspx + * You can find out a little more about lockless programming and the subtle + * issues that can arise here: + * https://learn.microsoft.com/en-us/windows/win32/dxtecharts/lockless-programming * * There's also lots of good information here: - * http://www.1024cores.net/home/lock-free-algorithms - * http://preshing.com/ * - * These operations may or may not actually be implemented using - * processor specific atomic operations. When possible they are - * implemented as true processor specific atomic operations. When that - * is not possible the are implemented using locks that *do* use the - * available atomic operations. + * - https://www.1024cores.net/home/lock-free-algorithms + * - https://preshing.com/ + * + * These operations may or may not actually be implemented using processor + * specific atomic operations. When possible they are implemented as true + * processor specific atomic operations. When that is not possible the are + * implemented using locks that *do* use the available atomic operations. * * All of the atomic operations that modify memory are full memory barriers. */ @@ -94,7 +85,7 @@ typedef int SDL_SpinLock; * ***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 + * \param lock a pointer to a lock variable. * \returns SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already * held. * @@ -111,7 +102,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTryLock(SDL_SpinLock *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 + * \param lock a pointer to a lock variable. * * \since This function is available since SDL 2.0.0. * @@ -128,7 +119,7 @@ extern DECLSPEC void SDLCALL SDL_AtomicLock(SDL_SpinLock *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 + * \param lock a pointer to a lock variable. * * \since This function is available since SDL 2.0.0. * @@ -257,10 +248,13 @@ typedef void (*SDL_KernelMemoryBarrierFunc)(); /** - * \brief A type representing an atomic integer value. It is a struct - * so people don't accidentally use numeric operations on it. + * A type representing an atomic integer value. + * + * It is a struct so people don't accidentally use numeric operations on it. */ -typedef struct { int value; } SDL_atomic_t; +typedef struct SDL_atomic_t { + int value; +} SDL_atomic_t; /** * Set an atomic variable to a new value if it is currently an old value. @@ -268,9 +262,9 @@ typedef struct { int value; } SDL_atomic_t; * ***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 + * \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. @@ -289,8 +283,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCAS(SDL_atomic_t *a, int oldval, int * ***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 + * \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. * * \since This function is available since SDL 2.0.2. @@ -305,7 +299,7 @@ extern DECLSPEC int SDLCALL SDL_AtomicSet(SDL_atomic_t *a, int v); * ***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 + * \param a a pointer to an SDL_atomic_t variable. * \returns the current value of an atomic variable. * * \since This function is available since SDL 2.0.2. @@ -322,8 +316,8 @@ extern DECLSPEC int SDLCALL SDL_AtomicGet(SDL_atomic_t *a); * ***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 + * \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. * * \since This function is available since SDL 2.0.2. @@ -356,9 +350,9 @@ extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_atomic_t *a, int v); * ***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 + * \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. @@ -375,8 +369,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCASPtr(void **a, void *oldval, void * * ***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 + * \param a a pointer to a pointer. + * \param v the desired pointer value. * \returns the previous value of the pointer. * * \since This function is available since SDL 2.0.2. @@ -392,7 +386,7 @@ extern DECLSPEC void* SDLCALL SDL_AtomicSetPtr(void **a, void* v); * ***Note: If you don't know what this function is for, you shouldn't use * it!*** * - * \param a a pointer to a pointer + * \param a a pointer to a pointer. * \returns the current value of a pointer. * * \since This function is available since SDL 2.0.2. diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_audio.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_audio.h @@ -22,9 +22,9 @@ /* !!! FIXME: several functions in here need Doxygen comments. */ /** - * \file SDL_audio.h + * # CategoryAudio * - * Access to the raw audio mixing buffer for the SDL library. + * Access to the raw audio mixing buffer for the SDL library. */ #ifndef SDL_audio_h_ @@ -44,24 +44,24 @@ extern "C" { #endif /** - * \brief Audio format flags. - * - * These are what the 16 bits in SDL_AudioFormat currently mean... - * (Unspecified bits are always zero). - * - * \verbatim - ++-----------------------sample is signed if set - || - || ++-----------sample is bigendian if set - || || - || || ++---sample is float if set - || || || - || || || +---sample bit size---+ - || || || | | - 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00 - \endverbatim - * - * There are macros in SDL 2.0 and later to query these bits. + * Audio format flags. + * + * These are what the 16 bits in SDL_AudioFormat currently mean... + * (Unspecified bits are always zero). + * + * ``` + * ++-----------------------sample is signed if set + * || + * || ++-----------sample is bigendian if set + * || || + * || || ++---sample is float if set + * || || || + * || || || +---sample bit size---+ + * || || || | | + * 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00 + * ``` + * + * There are macros in SDL 2.0 and later to query these bits. */ typedef Uint16 SDL_AudioFormat; @@ -149,33 +149,30 @@ typedef Uint16 SDL_AudioFormat; /* @} *//* Audio flags */ /** - * This function is called when the audio device needs more data. - * - * \param userdata An application-specific parameter saved in - * the SDL_AudioSpec structure - * \param stream A pointer to the audio data buffer. - * \param len The length of that buffer in bytes. - * - * Once the callback returns, the buffer will no longer be valid. - * Stereo samples are stored in a LRLRLR ordering. + * This function is called when the audio device needs more data. * - * You can choose to avoid callbacks and use SDL_QueueAudio() instead, if - * you like. Just open your audio device with a NULL callback. + * \param userdata An application-specific parameter saved in the + * SDL_AudioSpec structure. + * \param stream A pointer to the audio data buffer. + * \param len Length of **stream** in bytes. */ typedef void (SDLCALL * SDL_AudioCallback) (void *userdata, Uint8 * stream, int len); /** - * The calculated values in this structure are calculated by SDL_OpenAudio(). - * - * For multi-channel audio, the default SDL channel mapping is: - * 2: FL FR (stereo) - * 3: FL FR LFE (2.1 surround) - * 4: FL FR BL BR (quad) - * 5: FL FR LFE BL BR (4.1 surround) - * 6: FL FR FC LFE SL SR (5.1 surround - last two can also be BL BR) - * 7: FL FR FC LFE BC SL SR (6.1 surround) - * 8: FL FR FC LFE BL BR SL SR (7.1 surround) + * The calculated values in this structure are calculated by SDL_OpenAudio(). + * + * For multi-channel audio, the default SDL channel mapping is: + * + * ``` + * 2: FL FR (stereo) + * 3: FL FR LFE (2.1 surround) + * 4: FL FR BL BR (quad) + * 5: FL FR LFE BL BR (4.1 surround) + * 6: FL FR FC LFE SL SR (5.1 surround - last two can also be BL BR) + * 7: FL FR FC LFE BC SL SR (6.1 surround) + * 8: FL FR FC LFE BL BR SL SR (7.1 surround) + * ``` */ typedef struct SDL_AudioSpec { @@ -196,11 +193,11 @@ typedef void (SDLCALL * SDL_AudioFilter) (struct SDL_AudioCVT * cvt, SDL_AudioFormat format); /** - * \brief Upper limit of filters in SDL_AudioCVT + * Upper limit of filters in SDL_AudioCVT * - * The maximum number of SDL_AudioFilter functions in SDL_AudioCVT is - * currently limited to 9. The SDL_AudioCVT.filters array has 10 pointers, - * one of which is the terminating NULL pointer. + * The maximum number of SDL_AudioFilter functions in SDL_AudioCVT is + * currently limited to 9. The SDL_AudioCVT.filters array has 10 pointers, one + * of which is the terminating NULL pointer. */ #define SDL_AUDIOCVT_MAX_FILTERS 9 @@ -287,7 +284,7 @@ extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void); * meant to be proper names. * * \param index the index of the audio driver; the value ranges from 0 to - * SDL_GetNumAudioDrivers() - 1 + * SDL_GetNumAudioDrivers() - 1. * \returns the name of the audio driver at the requested index, or NULL if an * invalid index was specified. * @@ -314,7 +311,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index); * specific need to designate the audio driver you want to use. You should * normally use SDL_Init() or SDL_InitSubSystem(). * - * \param driver_name the name of the desired audio driver + * \param driver_name the name of the desired audio driver. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -408,13 +405,13 @@ extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired, SDL_AudioSpec * obtained); /** - * SDL Audio Device IDs. + * SDL Audio Device IDs. * - * A successful call to SDL_OpenAudio() is always device id 1, and legacy - * SDL audio APIs assume you want this device ID. SDL_OpenAudioDevice() calls - * always returns devices >= 2 on success. The legacy calls are good both - * for backwards compatibility and when you don't care about multiple, - * specific, or capture devices. + * A successful call to SDL_OpenAudio() is always device id 1, and legacy SDL + * audio APIs assume you want this device ID. SDL_OpenAudioDevice() calls + * always returns devices >= 2 on success. The legacy calls are good both for + * backwards compatibility and when you don't care about multiple, specific, + * or capture devices. */ typedef Uint32 SDL_AudioDeviceID; @@ -452,7 +449,7 @@ typedef Uint32 SDL_AudioDeviceID; * ``` * * \param iscapture zero to request playback devices, non-zero to request - * recording devices + * 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. @@ -478,7 +475,7 @@ extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture); * 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 + * 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 @@ -504,11 +501,11 @@ extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index, * count. * * \param index the index of the audio device; valid values range from 0 to - * SDL_GetNumAudioDevices() - 1 + * 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 + * \returns 0 on success, nonzero on error. * * \since This function is available since SDL 2.0.16. * @@ -542,7 +539,7 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index, * \param spec The SDL_AudioSpec to be initialized by this function. * \param iscapture non-zero to query the default recording device, zero to * query the default output device. - * \returns 0 on success, nonzero on error + * \returns 0 on success, nonzero on error. * * \since This function is available since SDL 2.24.0. * @@ -645,12 +642,12 @@ extern DECLSPEC int SDLCALL SDL_GetDefaultAudioInfo(char **name, * 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 + * recording, not playback. * \param desired an SDL_AudioSpec structure representing the desired output - * format; see SDL_OpenAudio() for more information + * 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 + * 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. * @@ -712,7 +709,7 @@ extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void); * Use this function to get the current audio state of an audio device. * * \param dev the ID of an audio device previously opened with - * SDL_OpenAudioDevice() + * SDL_OpenAudioDevice(). * \returns the SDL_AudioStatus of the specified audio device. * * \since This function is available since SDL 2.0.0. @@ -745,7 +742,7 @@ extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioDeviceStatus(SDL_AudioDevice * * ...and is only useful if you used the legacy SDL_OpenAudio() function. * - * \param pause_on non-zero to pause, 0 to unpause + * \param pause_on non-zero to pause, 0 to unpause. * * \since This function is available since SDL 2.0.0. * @@ -775,8 +772,8 @@ extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on); * callback, you shouldn't pause the audio device, as it will lead to dropouts * in the audio playback. Instead, you should use SDL_LockAudioDevice(). * - * \param dev a device opened by SDL_OpenAudioDevice() - * \param pause_on non-zero to pause, 0 to unpause + * \param dev a device opened by SDL_OpenAudioDevice(). + * \param pause_on non-zero to pause, 0 to unpause. * * \since This function is available since SDL 2.0.0. * @@ -841,14 +838,14 @@ extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev, * 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 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 + * 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 + * 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 @@ -874,8 +871,9 @@ extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src, Uint32 * audio_len); /** - * Loads a WAV from a file. - * Compatibility convenience function. + * Loads a WAV from a file. + * + * Compatibility convenience function. */ #define SDL_LoadWAV(file, spec, audio_buf, audio_len) \ SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len) @@ -888,7 +886,7 @@ extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src, * this function with a NULL pointer. * * \param audio_buf a pointer to the buffer created by SDL_LoadWAV() or - * SDL_LoadWAV_RW() + * SDL_LoadWAV_RW(). * * \since This function is available since SDL 2.0.0. * @@ -912,15 +910,16 @@ extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf); * and then can call SDL_ConvertAudio() to complete the conversion. * * \param cvt an SDL_AudioCVT structure filled in with audio conversion - * information + * 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 + * 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 + * 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. @@ -991,12 +990,12 @@ typedef struct _SDL_AudioStream SDL_AudioStream; /** * 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 - * \param src_rate The sampling rate of the source audio - * \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 + * \param src_format The format of the source audio. + * \param src_channels The number of channels of the source audio. + * \param src_rate The sampling rate of the source audio. + * \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. * \returns 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.7. @@ -1018,9 +1017,9 @@ extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioForm /** * 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 + * \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. * \returns 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.7. @@ -1037,10 +1036,10 @@ extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const vo /** * Get converted/resampled data from the stream * - * \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 - * \returns the number of bytes read from the stream, or -1 on error + * \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. + * \returns the number of bytes read from the stream, or -1 on error. * * \since This function is available since SDL 2.0.7. * @@ -1118,6 +1117,9 @@ extern DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream); */ extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream); +/** + * Maximum volume allowed in calls to SDL_MixAudio and SDL_MixAudioFormat. + */ #define SDL_MIX_MAXVOLUME 128 /** @@ -1132,11 +1134,11 @@ extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream); * ...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 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 + * for full audio volume. * * \since This function is available since SDL 2.0.0. * @@ -1165,13 +1167,13 @@ extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src, * 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 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 + * 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 + * for full audio volume. * * \since This function is available since SDL 2.0.0. */ @@ -1215,9 +1217,9 @@ extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst, * from planar audio formats into a non-planar one (see SDL_AudioFormat) * before queuing audio. * - * \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 + * \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. * @@ -1263,9 +1265,9 @@ extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *da * 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 + * \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 the number of bytes dequeued, which could be less than requested; * call SDL_GetError() for more information. * @@ -1299,7 +1301,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *dat * You should not call SDL_LockAudio() on the device before querying; SDL * handles locking internally for this function. * - * \param dev the device ID of which we will query queued audio size + * \param dev the device ID of which we will query queued audio size. * \returns the number of bytes (not samples!) of queued audio. * * \since This function is available since SDL 2.0.4. @@ -1334,7 +1336,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev); * * This function always succeeds and thus returns void. * - * \param dev the device ID of which to clear the audio queue + * \param dev the device ID of which to clear the audio queue. * * \since This function is available since SDL 2.0.4. * @@ -1406,7 +1408,7 @@ extern DECLSPEC void SDLCALL SDL_LockAudio(void); * at once, not only will you block the audio callback, you'll block the other * thread. * - * \param dev the ID of the device to be locked + * \param dev the ID of the device to be locked. * * \since This function is available since SDL 2.0.0. * @@ -1439,7 +1441,7 @@ extern DECLSPEC void SDLCALL SDL_UnlockAudio(void); * * This function should be paired with a previous SDL_LockAudioDevice() call. * - * \param dev the ID of the device to be unlocked + * \param dev the ID of the device to be unlocked. * * \since This function is available since SDL 2.0.0. * @@ -1481,7 +1483,7 @@ extern DECLSPEC void SDLCALL SDL_CloseAudio(void); * The device ID is invalid as soon as the device is closed, and is eligible * for reuse in a new SDL_OpenAudioDevice() call immediately. * - * \param dev an audio device previously opened with SDL_OpenAudioDevice() + * \param dev an audio device previously opened with SDL_OpenAudioDevice(). * * \since This function is available since SDL 2.0.0. * diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_bits.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_bits.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_bits.h + * # CategoryBits * - * Functions for fiddling with bits and bitmasks. + * Functions for fiddling with bits and bitmasks. */ #ifndef SDL_bits_h_ @@ -56,6 +56,12 @@ extern __inline int _SDL_bsr_watcom(Uint32); modify exact [eax] nomemory; #endif +/** + * Use this function to get the index of the most significant (set) bit in a + * + * \param x the number to find the MSB of. + * \returns the index of the most significant bit of x, or -1 if x is 0. + */ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) { diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_blendmode.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_blendmode.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_blendmode.h + * # CategoryBlendmode * - * Header file declaring the SDL_BlendMode enumeration + * Header file declaring the SDL_BlendMode enumeration */ #ifndef SDL_blendmode_h_ @@ -35,9 +35,9 @@ extern "C" { #endif /** - * \brief The blend mode used in SDL_RenderCopy() and drawing operations. + * The blend mode used in SDL_RenderCopy() and drawing operations. */ -typedef enum +typedef enum SDL_BlendMode { SDL_BLENDMODE_NONE = 0x00000000, /**< no blending dstRGBA = srcRGBA */ @@ -60,9 +60,10 @@ typedef enum } SDL_BlendMode; /** - * \brief The blend operation used when combining source and destination pixel components + * The blend operation used when combining source and destination pixel + * components */ -typedef enum +typedef enum SDL_BlendOperation { SDL_BLENDOPERATION_ADD = 0x1, /**< dst + src: supported by all renderers */ SDL_BLENDOPERATION_SUBTRACT = 0x2, /**< src - dst : supported by D3D9, D3D11, OpenGL, OpenGLES */ @@ -72,9 +73,9 @@ typedef enum } SDL_BlendOperation; /** - * \brief The normalized factor used to multiply pixel components + * The normalized factor used to multiply pixel components */ -typedef enum +typedef enum SDL_BlendFactor { SDL_BLENDFACTOR_ZERO = 0x1, /**< 0, 0, 0, 0 */ SDL_BLENDFACTOR_ONE = 0x2, /**< 1, 1, 1, 1 */ @@ -158,18 +159,18 @@ typedef enum * case. * * \param srcColorFactor the SDL_BlendFactor applied to the red, green, and - * blue components of the source pixels + * blue components of the source pixels. * \param dstColorFactor the SDL_BlendFactor applied to the red, green, and - * blue components of the destination pixels + * 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 + * destination pixels. * \param srcAlphaFactor the SDL_BlendFactor applied to the alpha component of - * the source pixels + * the source pixels. * \param dstAlphaFactor the SDL_BlendFactor applied to the alpha component of - * the destination pixels + * the destination pixels. * \param alphaOperation the SDL_BlendOperation used to combine the alpha - * component of the source and destination pixels + * component of the source and destination pixels. * \returns an SDL_BlendMode that represents the chosen factors and * operations. * diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_clipboard.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_clipboard.h @@ -20,7 +20,7 @@ */ /** - * \file SDL_clipboard.h + * # CategoryClipboard * * Include file for SDL clipboard handling */ @@ -41,7 +41,7 @@ extern "C" { /** * Put UTF-8 text into the clipboard. * - * \param text the text to store in the clipboard + * \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. * @@ -85,7 +85,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasClipboardText(void); /** * Put UTF-8 text into the primary selection. * - * \param text the text to store in the primary selection + * \param text the text to store in the primary selection. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_config.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_config.h @@ -24,9 +24,7 @@ #include "SDL_platform.h" -/** - * \file SDL_config.h - */ +/* WIKI CATEGORY: - */ /* Add any platform that doesn't build using the configure system. */ #if defined(__WIN32__) diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_cpuinfo.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_cpuinfo.h @@ -19,10 +19,16 @@ 3. This notice may not be removed or altered from any source distribution. */ +/* WIKI CATEGORY: CPUInfo */ + /** - * \file SDL_cpuinfo.h + * # CategoryCPUInfo + * + * CPU feature detection for SDL. * - * CPU feature detection for SDL. + * These functions are largely concerned with reporting if the system has + * access to various SIMD instruction sets, but also has other important info + * to share, such as number of logical CPU cores. */ #ifndef SDL_cpuinfo_h_ diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_egl.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_egl.h @@ -19,11 +19,10 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** - * \file SDL_egl.h - * - * This is a simple file to encapsulate the EGL API headers. +/* + * This is a simple file to encapsulate the EGL API headers. */ + #if !defined(_MSC_VER) && !defined(__ANDROID__) && !defined(SDL_USE_BUILTIN_OPENGL_DEFINITIONS) #if defined(__vita__) || defined(__psp2__) diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_endian.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_endian.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_endian.h + * # CategoryEndian * - * Functions for reading and writing endian-specific values + * Functions for reading and writing endian-specific values */ #ifndef SDL_endian_h_ @@ -59,6 +59,15 @@ _m_prefetch(void *__P) #ifdef __linux__ #include <endian.h> #define SDL_BYTEORDER __BYTE_ORDER +#elif defined(__sun) && defined(__SVR4) /* Solaris */ +#include <sys/byteorder.h> +#if defined(_LITTLE_ENDIAN) +#define SDL_BYTEORDER SDL_LIL_ENDIAN +#elif defined(_BIG_ENDIAN) +#define SDL_BYTEORDER SDL_BIG_ENDIAN +#else +#error Unsupported endianness +#endif #elif defined(__OpenBSD__) || defined(__DragonFly__) #include <endian.h> #define SDL_BYTEORDER BYTE_ORDER @@ -79,7 +88,7 @@ _m_prefetch(void *__P) defined(__m68k__) || defined(mc68000) || defined(_M_M68K) || \ (defined(__MIPS__) && defined(__MIPSEB__)) || \ defined(__ppc__) || defined(__POWERPC__) || defined(__powerpc__) || defined(__PPC__) || \ - defined(__sparc__) + defined(__sparc__) || defined(__sparc) #define SDL_BYTEORDER SDL_BIG_ENDIAN #else #define SDL_BYTEORDER SDL_LIL_ENDIAN @@ -180,6 +189,16 @@ extern __inline Uint16 SDL_Swap16(Uint16); parm [ax] \ modify [ax]; #else + +/** + * Use this function to swap the byte order of a 16-bit value. + * + * \param x the value to be swapped. + * \returns the swapped value. + * + * \sa SDL_SwapBE16 + * \sa SDL_SwapLE16 + */ SDL_FORCE_INLINE Uint16 SDL_Swap16(Uint16 x) { @@ -231,6 +250,16 @@ extern __inline Uint32 SDL_Swap32(Uint32); parm [eax] \ modify [eax]; #else + +/** + * Use this function to swap the byte order of a 32-bit value. + * + * \param x the value to be swapped. + * \returns the swapped value. + * + * \sa SDL_SwapBE32 + * \sa SDL_SwapLE32 + */ SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) { @@ -276,6 +305,16 @@ extern __inline Uint64 SDL_Swap64(Uint64); parm [eax edx] \ modify [eax edx]; #else + +/** + * Use this function to swap the byte order of a 64-bit value. + * + * \param x the value to be swapped. + * \returns the swapped value. + * + * \sa SDL_SwapBE64 + * \sa SDL_SwapLE64 + */ SDL_FORCE_INLINE Uint64 SDL_Swap64(Uint64 x) { @@ -293,6 +332,15 @@ SDL_Swap64(Uint64 x) #endif +/** + * Use this function to swap the byte order of a floating point value. + * + * \param x the value to be swapped. + * \returns the swapped value. + * + * \sa SDL_SwapFloatBE + * \sa SDL_SwapFloatLE + */ SDL_FORCE_INLINE float SDL_SwapFloat(float x) { diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_error.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_error.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_error.h + * # CategoryError * - * Simple error message routines for SDL. + * Simple error message routines for SDL. */ #ifndef SDL_error_h_ @@ -53,9 +53,9 @@ extern "C" { * } * ``` * - * \param fmt a printf()-style message format string + * \param fmt a printf()-style message format string. * \param ... additional parameters matching % tokens in the `fmt` string, if - * any + * any. * \returns always -1. * * \since This function is available since SDL 2.0.0. @@ -109,8 +109,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetError(void); * 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 + * the current thread. + * \param maxlen The size of the buffer pointed to by the errstr parameter. * \returns the pointer passed in as the `errstr` parameter. * * \since This function is available since SDL 2.0.14. diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_events.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_events.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_events.h + * # CategoryEvents * - * Include file for SDL event handling. + * Include file for SDL event handling. */ #ifndef SDL_events_h_ @@ -52,7 +52,7 @@ extern "C" { /** * The types of events that can be delivered. */ -typedef enum +typedef enum SDL_EventType { SDL_FIRSTEVENT = 0, /**< Unused (do not remove) */ @@ -167,7 +167,7 @@ typedef enum /* Internal events */ SDL_POLLSENTINEL = 0x7F00, /**< Signals the end of an event poll cycle */ - /** Events ::SDL_USEREVENT through ::SDL_LASTEVENT are for your use, + /** Events SDL_USEREVENT through SDL_LASTEVENT are for your use, * and should be allocated with SDL_RegisterEvents() */ SDL_USEREVENT = 0x8000, @@ -179,7 +179,7 @@ typedef enum } SDL_EventType; /** - * \brief Fields shared by every event + * Fields shared by every event */ typedef struct SDL_CommonEvent { @@ -188,14 +188,14 @@ typedef struct SDL_CommonEvent } SDL_CommonEvent; /** - * \brief Display state change event data (event.display.*) + * Display state change event data (event.display.*) */ typedef struct SDL_DisplayEvent { - Uint32 type; /**< ::SDL_DISPLAYEVENT */ + Uint32 type; /**< SDL_DISPLAYEVENT */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 display; /**< The associated display index */ - Uint8 event; /**< ::SDL_DisplayEventID */ + Uint8 event; /**< SDL_DisplayEventID */ Uint8 padding1; Uint8 padding2; Uint8 padding3; @@ -203,14 +203,14 @@ typedef struct SDL_DisplayEvent } SDL_DisplayEvent; /** - * \brief Window state change event data (event.window.*) + * Window state change event data (event.window.*) */ typedef struct SDL_WindowEvent { - Uint32 type; /**< ::SDL_WINDOWEVENT */ + Uint32 type; /**< SDL_WINDOWEVENT */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 windowID; /**< The associated window */ - Uint8 event; /**< ::SDL_WindowEventID */ + Uint8 event; /**< SDL_WindowEventID */ Uint8 padding1; Uint8 padding2; Uint8 padding3; @@ -219,14 +219,14 @@ typedef struct SDL_WindowEvent } SDL_WindowEvent; /** - * \brief Keyboard button event structure (event.key.*) + * Keyboard button event structure (event.key.*) */ typedef struct SDL_KeyboardEvent { - Uint32 type; /**< ::SDL_KEYDOWN or ::SDL_KEYUP */ + Uint32 type; /**< SDL_KEYDOWN or SDL_KEYUP */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 windowID; /**< The window with keyboard focus, if any */ - Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */ + Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ Uint8 repeat; /**< Non-zero if this is a key repeat */ Uint8 padding2; Uint8 padding3; @@ -234,12 +234,13 @@ typedef struct SDL_KeyboardEvent } SDL_KeyboardEvent; #define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32) + /** - * \brief Keyboard text editing event structure (event.edit.*) + * Keyboard text editing event structure (event.edit.*) */ typedef struct SDL_TextEditingEvent { - Uint32 type; /**< ::SDL_TEXTEDITING */ + Uint32 type; /**< SDL_TEXTEDITING */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 windowID; /**< The window with keyboard focus, if any */ char text[SDL_TEXTEDITINGEVENT_TEXT_SIZE]; /**< The editing text */ @@ -248,12 +249,12 @@ typedef struct SDL_TextEditingEvent } SDL_TextEditingEvent; /** - * \brief Extended keyboard text editing event structure (event.editExt.*) when text would be - * truncated if stored in the text buffer SDL_TextEditingEvent + * Extended keyboard text editing event structure (event.editExt.*) when text + * would be truncated if stored in the text buffer SDL_TextEditingEvent */ typedef struct SDL_TextEditingExtEvent { - Uint32 type; /**< ::SDL_TEXTEDITING_EXT */ + Uint32 type; /**< SDL_TEXTEDITING_EXT */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 windowID; /**< The window with keyboard focus, if any */ char* text; /**< The editing text, which should be freed with SDL_free(), and will not be NULL */ @@ -261,24 +262,43 @@ typedef struct SDL_TextEditingExtEvent Sint32 length; /**< The length of selected editing text */ } SDL_TextEditingExtEvent; +/** + * The maximum bytes of text that can be supplied in an SDL_TextInputEvent. + */ #define SDL_TEXTINPUTEVENT_TEXT_SIZE (32) + /** - * \brief Keyboard text input event structure (event.text.*) + * Keyboard text input event structure (event.text.*) + * + * `text` is limited to SDL_TEXTINPUTEVENT_TEXT_SIZE bytes. If the incoming + * string is larger than this, SDL will split it and send it in pieces, across + * multiple events. The string is in UTF-8 format, and if split, SDL + * guarantees that it will not split in the middle of a UTF-8 sequence, so any + * event will only contain complete codepoints. However, if there are several + * codepoints that go together into a single glyph (like an emoji "thumbs up" + * followed by a skin color), they may be split between events. + * + * This event will never be delivered unless text input is enabled by calling + * SDL_StartTextInput(). Text input is enabled by default on desktop + * platforms, and disabled by default on mobile platforms! + * + * \sa SDL_StartTextInput + * \sa SDL_StopTextInput */ typedef struct SDL_TextInputEvent { - Uint32 type; /**< ::SDL_TEXTINPUT */ + Uint32 type; /**< SDL_TEXTINPUT */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 windowID; /**< The window with keyboard focus, if any */ - char text[SDL_TEXTINPUTEVENT_TEXT_SIZE]; /**< The input text */ + char text[SDL_TEXTINPUTEVENT_TEXT_SIZE]; /**< The input text; UTF-8 encoded. */ } SDL_TextInputEvent; /** - * \brief Mouse motion event structure (event.motion.*) + * Mouse motion event structure (event.motion.*) */ typedef struct SDL_MouseMotionEvent { - Uint32 type; /**< ::SDL_MOUSEMOTION */ + Uint32 type; /**< SDL_MOUSEMOTION */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 windowID; /**< The window with mouse focus, if any */ Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */ @@ -290,16 +310,16 @@ typedef struct SDL_MouseMotionEvent } SDL_MouseMotionEvent; /** - * \brief Mouse button event structure (event.button.*) + * Mouse button event structure (event.button.*) */ typedef struct SDL_MouseButtonEvent { - Uint32 type; /**< ::SDL_MOUSEBUTTONDOWN or ::SDL_MOUSEBUTTONUP */ + Uint32 type; /**< SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 windowID; /**< The window with mouse focus, if any */ Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */ Uint8 button; /**< The mouse button index */ - Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */ + Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ Uint8 clicks; /**< 1 for single-click, 2 for double-click, etc. */ Uint8 padding1; Sint32 x; /**< X coordinate, relative to window */ @@ -307,11 +327,11 @@ typedef struct SDL_MouseButtonEvent } SDL_MouseButtonEvent; /** - * \brief Mouse wheel event structure (event.wheel.*) + * Mouse wheel event structure (event.wheel.*) */ typedef struct SDL_MouseWheelEvent { - Uint32 type; /**< ::SDL_MOUSEWHEEL */ + Uint32 type; /**< SDL_MOUSEWHEEL */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 windowID; /**< The window with mouse focus, if any */ Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */ @@ -325,11 +345,11 @@ typedef struct SDL_MouseWheelEvent } SDL_MouseWheelEvent; /** - * \brief Joystick axis motion event structure (event.jaxis.*) + * Joystick axis motion event structure (event.jaxis.*) */ typedef struct SDL_JoyAxisEvent { - Uint32 type; /**< ::SDL_JOYAXISMOTION */ + Uint32 type; /**< SDL_JOYAXISMOTION */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_JoystickID which; /**< The joystick instance id */ Uint8 axis; /**< The joystick axis index */ @@ -341,11 +361,11 @@ typedef struct SDL_JoyAxisEvent } SDL_JoyAxisEvent; /** - * \brief Joystick trackball motion event structure (event.jball.*) + * Joystick trackball motion event structure (event.jball.*) */ typedef struct SDL_JoyBallEvent { - Uint32 type; /**< ::SDL_JOYBALLMOTION */ + Uint32 type; /**< SDL_JOYBALLMOTION */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_JoystickID which; /**< The joystick instance id */ Uint8 ball; /**< The joystick trackball index */ @@ -357,18 +377,18 @@ typedef struct SDL_JoyBallEvent } SDL_JoyBallEvent; /** - * \brief Joystick hat position change event structure (event.jhat.*) + * Joystick hat position change event structure (event.jhat.*) */ typedef struct SDL_JoyHatEvent { - Uint32 type; /**< ::SDL_JOYHATMOTION */ + Uint32 type; /**< SDL_JOYHATMOTION */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_JoystickID which; /**< The joystick instance id */ Uint8 hat; /**< The joystick hat index */ Uint8 value; /**< The hat position value. - * \sa ::SDL_HAT_LEFTUP ::SDL_HAT_UP ::SDL_HAT_RIGHTUP - * \sa ::SDL_HAT_LEFT ::SDL_HAT_CENTERED ::SDL_HAT_RIGHT - * \sa ::SDL_HAT_LEFTDOWN ::SDL_HAT_DOWN ::SDL_HAT_RIGHTDOWN + * \sa SDL_HAT_LEFTUP SDL_HAT_UP SDL_HAT_RIGHTUP + * \sa SDL_HAT_LEFT SDL_HAT_CENTERED SDL_HAT_RIGHT + * \sa SDL_HAT_LEFTDOWN SDL_HAT_DOWN SDL_HAT_RIGHTDOWN * * Note that zero means the POV is centered. */ @@ -377,46 +397,51 @@ typedef struct SDL_JoyHatEvent } SDL_JoyHatEvent; /** - * \brief Joystick button event structure (event.jbutton.*) + * Joystick button event structure (event.jbutton.*) */ typedef struct SDL_JoyButtonEvent { - Uint32 type; /**< ::SDL_JOYBUTTONDOWN or ::SDL_JOYBUTTONUP */ + Uint32 type; /**< SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_JoystickID which; /**< The joystick instance id */ Uint8 button; /**< The joystick button index */ - Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */ + Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ Uint8 padding1; Uint8 padding2; } SDL_JoyButtonEvent; /** - * \brief Joystick device event structure (event.jdevice.*) + * Joystick device event structure (event.jdevice.*) + * + * SDL will send JOYSTICK_ADDED events for devices that are already plugged in + * during SDL_Init. + * + * \sa SDL_ControllerDeviceEvent */ typedef struct SDL_JoyDeviceEvent { - Uint32 type; /**< ::SDL_JOYDEVICEADDED or ::SDL_JOYDEVICEREMOVED */ + Uint32 type; /**< SDL_JOYDEVICEADDED or SDL_JOYDEVICEREMOVED */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Sint32 which; /**< The joystick device index for the ADDED event, instance id for the REMOVED event */ } SDL_JoyDeviceEvent; /** - * \brief Joysick battery level change event structure (event.jbattery.*) + * Joysick battery level change event structure (event.jbattery.*) */ typedef struct SDL_JoyBatteryEvent { - Uint32 type; /**< ::SDL_JOYBATTERYUPDATED */ + Uint32 type; /**< SDL_JOYBATTERYUPDATED */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_JoystickID which; /**< The joystick instance id */ SDL_JoystickPowerLevel level; /**< The joystick battery level */ } SDL_JoyBatteryEvent; /** - * \brief Game controller axis motion event structure (event.caxis.*) + * Game controller axis motion event structure (event.caxis.*) */ typedef struct SDL_ControllerAxisEvent { - Uint32 type; /**< ::SDL_CONTROLLERAXISMOTION */ + Uint32 type; /**< SDL_CONTROLLERAXISMOTION */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_JoystickID which; /**< The joystick instance id */ Uint8 axis; /**< The controller axis (SDL_GameControllerAxis) */ @@ -429,36 +454,42 @@ typedef struct SDL_ControllerAxisEvent /** - * \brief Game controller button event structure (event.cbutton.*) + * Game controller button event structure (event.cbutton.*) */ typedef struct SDL_ControllerButtonEvent { - Uint32 type; /**< ::SDL_CONTROLLERBUTTONDOWN or ::SDL_CONTROLLERBUTTONUP */ + Uint32 type; /**< SDL_CONTROLLERBUTTONDOWN or SDL_CONTROLLERBUTTONUP */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_JoystickID which; /**< The joystick instance id */ Uint8 button; /**< The controller button (SDL_GameControllerButton) */ - Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */ + Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ Uint8 padding1; Uint8 padding2; } SDL_ControllerButtonEvent; /** - * \brief Controller device event structure (event.cdevice.*) + * Controller device event structure (event.cdevice.*) + * + * Joysticks that are supported game controllers receive both an + * SDL_JoyDeviceEvent and an SDL_ControllerDeviceEvent. + * + * SDL will send CONTROLLERDEVICEADDED events for joysticks that are already + * plugged in during SDL_Init() and are recognized as game controllers. */ typedef struct SDL_ControllerDeviceEvent { - Uint32 type; /**< ::SDL_CONTROLLERDEVICEADDED, ::SDL_CONTROLLERDEVICEREMOVED, ::SDL_CONTROLLERDEVICEREMAPPED, or ::SDL_CONTROLLERSTEAMHANDLEUPDATED */ + Uint32 type; /**< SDL_CONTROLLERDEVICEADDED, SDL_CONTROLLERDEVICEREMOVED, SDL_CONTROLLERDEVICEREMAPPED, or SDL_CONTROLLERSTEAMHANDLEUPDATED */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Sint32 which; /**< The joystick device index for the ADDED event, instance id for the REMOVED or REMAPPED event */ } SDL_ControllerDeviceEvent; /** - * \brief Game controller touchpad event structure (event.ctouchpad.*) + * Game controller touchpad event structure (event.ctouchpad.*) */ typedef struct SDL_ControllerTouchpadEvent { - Uint32 type; /**< ::SDL_CONTROLLERTOUCHPADDOWN or ::SDL_CONTROLLERTOUCHPADMOTION or ::SDL_CONTROLLERTOUCHPADUP */ + Uint32 type; /**< SDL_CONTROLLERTOUCHPADDOWN or SDL_CONTROLLERTOUCHPADMOTION or SDL_CONTROLLERTOUCHPADUP */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_JoystickID which; /**< The joystick instance id */ Sint32 touchpad; /**< The index of the touchpad */ @@ -469,24 +500,24 @@ typedef struct SDL_ControllerTouchpadEvent } SDL_ControllerTouchpadEvent; /** - * \brief Game controller sensor event structure (event.csensor.*) + * Game controller sensor event structure (event.csensor.*) */ typedef struct SDL_ControllerSensorEvent { - Uint32 type; /**< ::SDL_CONTROLLERSENSORUPDATE */ + Uint32 type; /**< SDL_CONTROLLERSENSORUPDATE */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_JoystickID which; /**< The joystick instance id */ - Sint32 sensor; /**< The type of the sensor, one of the values of ::SDL_SensorType */ + Sint32 sensor; /**< The type of the sensor, one of the values of SDL_SensorType */ float data[3]; /**< Up to 3 values from the sensor, as defined in SDL_sensor.h */ Uint64 timestamp_us; /**< The timestamp of the sensor reading in microseconds, if the hardware provides this information. */ } SDL_ControllerSensorEvent; /** - * \brief Audio device event structure (event.adevice.*) + * Audio device event structure (event.adevice.*) */ typedef struct SDL_AudioDeviceEvent { - Uint32 type; /**< ::SDL_AUDIODEVICEADDED, or ::SDL_AUDIODEVICEREMOVED */ + Uint32 type; /**< SDL_AUDIODEVICEADDED, or SDL_AUDIODEVICEREMOVED */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 which; /**< The audio device index for the ADDED event (valid until next SDL_GetNumAudioDevices() call), SDL_AudioDeviceID for the REMOVED event */ Uint8 iscapture; /**< zero if an output device, non-zero if a capture device. */ @@ -497,11 +528,11 @@ typedef struct SDL_AudioDeviceEvent /** - * \brief Touch finger event structure (event.tfinger.*) + * Touch finger event structure (event.tfinger.*) */ typedef struct SDL_TouchFingerEvent { - Uint32 type; /**< ::SDL_FINGERMOTION or ::SDL_FINGERDOWN or ::SDL_FINGERUP */ + Uint32 type; /**< SDL_FINGERMOTION or SDL_FINGERDOWN or SDL_FINGERUP */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_TouchID touchId; /**< The touch device id */ SDL_FingerID fingerId; @@ -515,11 +546,11 @@ typedef struct SDL_TouchFingerEvent /** - * \brief Multiple Finger Gesture Event (event.mgesture.*) + * Multiple Finger Gesture Event (event.mgesture.*) */ typedef struct SDL_MultiGestureEvent { - Uint32 type; /**< ::SDL_MULTIGESTURE */ + Uint32 type; /**< SDL_MULTIGESTURE */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_TouchID touchId; /**< The touch device id */ float dTheta; @@ -532,11 +563,11 @@ typedef struct SDL_MultiGestureEvent /** - * \brief Dollar Gesture Event (event.dgesture.*) + * Dollar Gesture Event (event.dgesture.*) */ typedef struct SDL_DollarGestureEvent { - Uint32 type; /**< ::SDL_DOLLARGESTURE or ::SDL_DOLLARRECORD */ + Uint32 type; /**< SDL_DOLLARGESTURE or SDL_DOLLARRECORD */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_TouchID touchId; /**< The touch device id */ SDL_GestureID gestureId; @@ -548,13 +579,15 @@ typedef struct SDL_DollarGestureEvent /** - * \brief An event used to request a file open by the system (event.drop.*) - * This event is enabled by default, you can disable it with SDL_EventState(). - * \note If this event is enabled, you must free the filename in the event. + * An event used to request a file open by the system (event.drop.*) + * + * This event is enabled by default, you can disable it with SDL_EventState(). + * + * If this event is enabled, you must free the filename in the event. */ typedef struct SDL_DropEvent { - Uint32 type; /**< ::SDL_DROPBEGIN or ::SDL_DROPFILE or ::SDL_DROPTEXT or ::SDL_DROPCOMPLETE */ + Uint32 type; /**< SDL_DROPBEGIN or SDL_DROPFILE or SDL_DROPTEXT or SDL_DROPCOMPLETE */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ char *file; /**< The file name, which should be freed with SDL_free(), is NULL on begin/complete */ Uint32 windowID; /**< The window that was dropped on, if any */ @@ -562,11 +595,11 @@ typedef struct SDL_DropEvent /** - * \brief Sensor event structure (event.sensor.*) + * Sensor event structure (event.sensor.*) */ typedef struct SDL_SensorEvent { - Uint32 type; /**< ::SDL_SENSORUPDATE */ + Uint32 type; /**< SDL_SENSORUPDATE */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Sint32 which; /**< The instance ID of the sensor */ float data[6]; /**< Up to 6 values from the sensor - additional values can be queried using SDL_SensorGetData() */ @@ -574,20 +607,20 @@ typedef struct SDL_SensorEvent } SDL_SensorEvent; /** - * \brief The "quit requested" event + * The "quit requested" event */ typedef struct SDL_QuitEvent { - Uint32 type; /**< ::SDL_QUIT */ + Uint32 type; /**< SDL_QUIT */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ } SDL_QuitEvent; /** - * \brief A user-defined event type (event.user.*) + * A user-defined event type (event.user.*) */ typedef struct SDL_UserEvent { - Uint32 type; /**< ::SDL_USEREVENT through ::SDL_LASTEVENT-1 */ + Uint32 type; /**< SDL_USEREVENT through SDL_LASTEVENT-1 */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 windowID; /**< The associated window if any */ Sint32 code; /**< User defined event code */ @@ -600,20 +633,24 @@ struct SDL_SysWMmsg; typedef struct SDL_SysWMmsg SDL_SysWMmsg; /** - * \brief A video driver dependent system event (event.syswm.*) - * This event is disabled by default, you can enable it with SDL_EventState() + * A video driver dependent system event (event.syswm.*) + * + * This event is disabled by default, you can enable it with SDL_EventState() * - * \note If you want to use this event, you should include SDL_syswm.h. + * If you want to use this event, you should include SDL_syswm.h. */ typedef struct SDL_SysWMEvent { - Uint32 type; /**< ::SDL_SYSWMEVENT */ + Uint32 type; /**< SDL_SYSWMEVENT */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ SDL_SysWMmsg *msg; /**< driver dependent data, defined in SDL_syswm.h */ } SDL_SysWMEvent; /** - * \brief General event structure + * General event structure + * + * The SDL_Event structure is the core of all event handling in SDL. SDL_Event + * is a union of all event structures used in SDL. */ typedef union SDL_Event { @@ -696,7 +733,7 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL extern DECLSPEC void SDLCALL SDL_PumpEvents(void); /* @{ */ -typedef enum +typedef enum SDL_eventaction { SDL_ADDEVENT, SDL_PEEKEVENT, @@ -723,15 +760,15 @@ typedef enum * * This function is thread-safe. * - * \param events destination buffer for the retrieved events + * \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 + * 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 + * SDL_FIRSTEVENT is a safe choice. * \param maxType maximum value of the event type to be considered; - * SDL_LASTEVENT is a safe choice + * 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. * @@ -752,7 +789,7 @@ extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents, * 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 + * \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. * @@ -769,9 +806,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type); * 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 + * SDL_EventType for details. * \param maxType the high end of event type to be queried, inclusive; see - * SDL_EventType for details + * SDL_EventType for details. * \returns SDL_TRUE if events with type >= `minType` and <= `maxType` are * present, or SDL_FALSE if not. * @@ -795,7 +832,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType); * 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 + * \param type the type of event to be cleared; see SDL_EventType for details. * * \since This function is available since SDL 2.0.0. * @@ -818,9 +855,9 @@ extern DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type); * 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 + * SDL_EventType for details. * \param maxType the high end of event type to be cleared, inclusive; see - * SDL_EventType for details + * SDL_EventType for details. * * \since This function is available since SDL 2.0.0. * @@ -861,7 +898,7 @@ extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType); * ``` * * \param event the SDL_Event structure to be filled with the next event from - * the queue, or NULL + * the queue, or NULL. * \returns 1 if there is a pending event or 0 if there are none available. * * \since This function is available since SDL 2.0.0. @@ -885,7 +922,7 @@ extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event); * 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 + * 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. * @@ -908,9 +945,9 @@ extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event); * 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 + * from the queue, or NULL. * \param timeout the maximum number of milliseconds to wait for the next - * available event + * 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. @@ -945,7 +982,7 @@ extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event, * 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 + * \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. @@ -961,11 +998,11 @@ 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 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. + * \param userdata what was passed as `userdata` to SDL_SetEventFilter() or + * SDL_AddEventWatch, etc. + * \param event the event that triggered the callback. + * \returns 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 @@ -988,7 +1025,7 @@ typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event); * 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 + * 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. @@ -1003,8 +1040,8 @@ typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event); * 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` + * \param filter An SDL_EventFilter function to call when an event happens. + * \param userdata a pointer that is passed to `filter`. * * \since This function is available since SDL 2.0.0. * @@ -1023,9 +1060,9 @@ extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter 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 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 + * be stored here. * \returns SDL_TRUE on success or SDL_FALSE if there is no event filter set. * * \since This function is available since SDL 2.0.0. @@ -1054,7 +1091,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter, * through SDL_PeepEvents(). * * \param filter an SDL_EventFilter function to call when an event happens. - * \param userdata a pointer that is passed to `filter` + * \param userdata a pointer that is passed to `filter`. * * \since This function is available since SDL 2.0.0. * @@ -1070,8 +1107,8 @@ extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, * 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() + * \param filter the function originally passed to SDL_AddEventWatch(). + * \param userdata the pointer originally passed to SDL_AddEventWatch(). * * \since This function is available since SDL 2.0.0. * @@ -1088,8 +1125,8 @@ extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter, * 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` + * \param filter the SDL_EventFilter function to call when an event happens. + * \param userdata a pointer that is passed to `filter`. * * \since This function is available since SDL 2.0.0. * @@ -1115,8 +1152,8 @@ extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter, * 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 + * \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. * @@ -1138,7 +1175,7 @@ extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state); * 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 + * \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. * diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_filesystem.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_filesystem.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_filesystem.h + * # CategoryFilesystem * - * \brief Include file for filesystem SDL API functions + * Include file for filesystem SDL API functions */ #ifndef SDL_filesystem_h_ @@ -126,8 +126,8 @@ extern DECLSPEC char *SDLCALL SDL_GetBasePath(void); * 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 + * \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.). diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_gamecontroller.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_gamecontroller.h @@ -19,10 +19,12 @@ 3. This notice may not be removed or altered from any source distribution. */ +/* WIKI CATEGORY: GameController */ + /** - * \file SDL_gamecontroller.h + * # CategoryGameController * - * Include file for SDL game controller event handling + * Include file for SDL game controller event handling */ #ifndef SDL_gamecontroller_h_ @@ -44,7 +46,7 @@ extern "C" { * \file SDL_gamecontroller.h * * In order to use these functions, SDL_Init() must have been called - * with the ::SDL_INIT_GAMECONTROLLER flag. This causes SDL to scan the system + * with the SDL_INIT_GAMECONTROLLER flag. This causes SDL to scan the system * for game controllers, and load appropriate drivers. * * If you would like to receive controller updates while the application @@ -58,7 +60,7 @@ extern "C" { struct _SDL_GameController; typedef struct _SDL_GameController SDL_GameController; -typedef enum +typedef enum SDL_GameControllerType { SDL_CONTROLLER_TYPE_UNKNOWN = 0, SDL_CONTROLLER_TYPE_XBOX360, @@ -77,7 +79,7 @@ typedef enum SDL_CONTROLLER_TYPE_MAX } SDL_GameControllerType; -typedef enum +typedef enum SDL_GameControllerBindType { SDL_CONTROLLER_BINDTYPE_NONE = 0, SDL_CONTROLLER_BINDTYPE_BUTTON, @@ -86,7 +88,7 @@ typedef enum } SDL_GameControllerBindType; /** - * Get the SDL joystick layer binding for this controller button/axis mapping + * Get the SDL joystick layer binding for this controller button/axis mapping */ typedef struct SDL_GameControllerButtonBind { @@ -144,6 +146,10 @@ typedef struct SDL_GameControllerButtonBind * If a new mapping is loaded for an already known controller GUID, the later * version will overwrite the one currently loaded. * + * If this function is called before SDL_Init, SDL will generate an + * SDL_CONTROLLERDEVICEADDED event for matching controllers that are plugged + * in at the time that SDL_Init is called. + * * 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). @@ -152,8 +158,8 @@ typedef struct SDL_GameControllerButtonBind * 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 + * \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. * @@ -162,13 +168,15 @@ typedef struct SDL_GameControllerButtonBind * \sa SDL_GameControllerAddMapping * \sa SDL_GameControllerAddMappingsFromFile * \sa SDL_GameControllerMappingForGUID + * \sa SDL_CONTROLLERDEVICEADDED */ extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw, int freerw); /** - * Load a set of mappings from a file, filtered by the current SDL_GetPlatform() + * Load a set of mappings from a file, filtered by the current + * SDL_GetPlatform() * - * Convenience macro. + * Convenience macro. */ #define SDL_GameControllerAddMappingsFromFile(file) SDL_GameControllerAddMappingsFromRW(SDL_RWFromFile(file, "rb"), 1) @@ -190,7 +198,11 @@ extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw, * "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 + * If this function is called before SDL_Init, SDL will generate an + * SDL_CONTROLLERDEVICEADDED event for matching controllers that are plugged + * in at the time that SDL_Init is called. + * + * \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. * @@ -198,6 +210,7 @@ extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw, * * \sa SDL_GameControllerMapping * \sa SDL_GameControllerMappingForGUID + * \sa SDL_CONTROLLERDEVICEADDED */ extern DECLSPEC int SDLCALL SDL_GameControllerAddMapping(const char* mappingString); @@ -225,7 +238,7 @@ extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForIndex(int mapping_ind * * The returned string must be freed with SDL_free(). * - * \param guid a structure containing the GUID for which a mapping is desired + * \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. * @@ -244,7 +257,7 @@ extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForGUID(SDL_JoystickGUID * Details about mappings are discussed with SDL_GameControllerAddMapping(). * * \param gamecontroller the game controller you want to get the current - * mapping for + * mapping for. * \returns a string that has the controller's mapping or NULL if no mapping * is available; call SDL_GetError() for more information. * @@ -262,7 +275,7 @@ extern DECLSPEC char * SDLCALL SDL_GameControllerMapping(SDL_GameController *gam * SDL_JoystickOpen(). * * \param joystick_index the device_index of a device, up to - * SDL_NumJoysticks() + * 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. * @@ -282,7 +295,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IsGameController(int joystick_index); * SDL_JoystickOpen(). * * \param joystick_index the device_index of a device, from zero to - * SDL_NumJoysticks()-1 + * SDL_NumJoysticks()-1. * \returns the implementation-dependent name for the game controller, or NULL * if there is no name or the index is invalid. * @@ -303,7 +316,7 @@ extern DECLSPEC const char *SDLCALL SDL_GameControllerNameForIndex(int joystick_ * SDL_JoystickOpen(). * * \param joystick_index the device_index of a device, from zero to - * SDL_NumJoysticks()-1 + * SDL_NumJoysticks()-1. * \returns the implementation-dependent path for the game controller, or NULL * if there is no path or the index is invalid. * @@ -319,7 +332,7 @@ extern DECLSPEC const char *SDLCALL SDL_GameControllerPathForIndex(int joystick_ * This can be called before any controllers are opened. * * \param joystick_index the device_index of a device, from zero to - * SDL_NumJoysticks()-1 + * SDL_NumJoysticks()-1. * \returns the controller type. * * \since This function is available since SDL 2.0.12. @@ -332,7 +345,7 @@ extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerTypeForIndex(in * This can be called before any controllers are opened. * * \param joystick_index the device_index of a device, from zero to - * SDL_NumJoysticks()-1 + * SDL_NumJoysticks()-1. * \returns the mapping string. Must be freed with SDL_free(). Returns NULL if * no mapping is available. * @@ -352,7 +365,7 @@ extern DECLSPEC char *SDLCALL SDL_GameControllerMappingForDeviceIndex(int joysti * be used there instead. * * \param joystick_index the device_index of a device, up to - * SDL_NumJoysticks() + * SDL_NumJoysticks(). * \returns a gamecontroller identifier or NULL if an error occurred; call * SDL_GetError() for more information. * @@ -367,7 +380,7 @@ extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerOpen(int joystick_ /** * Get the SDL_GameController associated with an instance id. * - * \param joyid the instance id to get the SDL_GameController for + * \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. * @@ -399,7 +412,7 @@ extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromPlayerIndex(in * it takes a controller identifier instead of the (unstable) device index. * * \param gamecontroller a game controller identifier previously returned by - * SDL_GameControllerOpen() + * SDL_GameControllerOpen(). * \returns the implementation dependent name for the game controller, or NULL * if there is no name or the identifier passed is invalid. * @@ -417,7 +430,7 @@ extern DECLSPEC const char *SDLCALL SDL_GameControllerName(SDL_GameController *g * it takes a controller identifier instead of the (unstable) device index. * * \param gamecontroller a game controller identifier previously returned by - * SDL_GameControllerOpen() + * SDL_GameControllerOpen(). * \returns the implementation dependent path for the game controller, or NULL * if there is no path or the identifier passed is invalid. * @@ -527,8 +540,8 @@ extern DECLSPEC const char * SDLCALL SDL_GameControllerGetSerial(SDL_GameControl /** * Get the Steam Input handle of an opened controller, if available. * - * Returns an InputHandle_t for the controller that can be used with Steam Input API: - * https://partner.steamgames.com/doc/api/ISteamInput + * Returns an InputHandle_t for the controller that can be used with Steam + * Input API: https://partner.steamgames.com/doc/api/ISteamInput * * \param gamecontroller the game controller object to query. * \returns the gamepad handle, or 0 if unavailable. @@ -542,7 +555,7 @@ extern DECLSPEC Uint64 SDLCALL SDL_GameControllerGetSteamHandle(SDL_GameControll * Check if a controller has been opened and is currently connected. * * \param gamecontroller a game controller identifier previously returned by - * SDL_GameControllerOpen() + * SDL_GameControllerOpen(). * \returns SDL_TRUE if the controller has been opened and is currently * connected, or SDL_FALSE if not. * @@ -567,7 +580,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerGetAttached(SDL_GameControlle * cause SDL to crash. * * \param gamecontroller the game controller object that you want to get a - * joystick from + * joystick from. * \returns a SDL_Joystick object; call SDL_GetError() for more information. * * \since This function is available since SDL 2.0.0. @@ -584,7 +597,7 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_GameControllerGetJoystick(SDL_GameCont * 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` + * \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. * @@ -607,17 +620,19 @@ extern DECLSPEC void SDLCALL SDL_GameControllerUpdate(void); /** - * The list of axes available from a controller + * The list of axes available from a controller * - * Thumbstick axis values range from SDL_JOYSTICK_AXIS_MIN to SDL_JOYSTICK_AXIS_MAX, - * and are centered within ~8000 of zero, though advanced UI will allow users to set - * or autodetect the dead zone, which varies between controllers. + * Thumbstick axis values range from SDL_JOYSTICK_AXIS_MIN to + * SDL_JOYSTICK_AXIS_MAX, and are centered within ~8000 of zero, though + * advanced UI will allow users to set or autodetect the dead zone, which + * varies between controllers. * - * Trigger axis values range from 0 (released) to SDL_JOYSTICK_AXIS_MAX - * (fully pressed) when reported by SDL_GameControllerGetAxis(). Note that this is not the - * same range that will be reported by the lower-level SDL_GetJoystickAxis(). + * Trigger axis values range from 0 (released) to SDL_JOYSTICK_AXIS_MAX (fully + * pressed) when reported by SDL_GameControllerGetAxis(). Note that this is + * not the same range that will be reported by the lower-level + * SDL_GetJoystickAxis(). */ -typedef enum +typedef enum SDL_GameControllerAxis { SDL_CONTROLLER_AXIS_INVALID = -1, SDL_CONTROLLER_AXIS_LEFTX, @@ -641,7 +656,7 @@ typedef enum * `SDL_CONTROLLER_AXIS_TRIGGERRIGHT` and `SDL_CONTROLLER_AXIS_TRIGGERLEFT`, * respectively. * - * \param str string representing a SDL_GameController axis + * \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. * @@ -656,7 +671,7 @@ extern DECLSPEC SDL_GameControllerAxis SDLCALL SDL_GameControllerGetAxisFromStri * * The caller should not SDL_free() the returned string. * - * \param axis an enum value for a given SDL_GameControllerAxis + * \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. @@ -670,8 +685,8 @@ extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForAxis(SDL_GameC /** * 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) + * \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`. @@ -690,8 +705,8 @@ SDL_GameControllerGetBindForAxis(SDL_GameController *gamecontroller, * 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) + * \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. * * \since This function is available since SDL 2.0.14. @@ -704,16 +719,15 @@ SDL_GameControllerHasAxis(SDL_GameController *gamecontroller, SDL_GameController * * The axis indices start at index 0. * - * For thumbsticks, the state is a value ranging from -32768 (up/left) - * to 32767 (down/right). + * For thumbsticks, the state is a value ranging from -32768 (up/left) to + * 32767 (down/right). * - * Triggers range from 0 when released to 32767 when fully pressed, and - * never return a negative value. Note that this differs from the value - * reported by the lower-level SDL_GetJoystickAxis(), which normally uses - * the full range. + * Triggers range from 0 when released to 32767 when fully pressed, and never + * return a negative value. Note that this differs from the value reported by + * the lower-level SDL_JoystickGetAxis(), which normally uses the full range. * - * \param gamecontroller a game controller - * \param axis an axis index (one of the SDL_GameControllerAxis values) + * \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. * @@ -725,9 +739,9 @@ extern DECLSPEC Sint16 SDLCALL SDL_GameControllerGetAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis); /** - * The list of buttons available from a controller + * The list of buttons available from a controller */ -typedef enum +typedef enum SDL_GameControllerButton { SDL_CONTROLLER_BUTTON_INVALID = -1, SDL_CONTROLLER_BUTTON_A, @@ -762,7 +776,7 @@ typedef enum * 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 + * \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. * @@ -775,7 +789,7 @@ extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFrom * * The caller should not SDL_free() the returned string. * - * \param button an enum value for a given SDL_GameControllerButton + * \param button an enum value for a given SDL_GameControllerButton. * \returns a string for the given button, or NULL if an invalid button is * specified. The string returned is of the format used by * SDL_GameController mapping strings. @@ -789,8 +803,8 @@ extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForButton(SDL_Gam /** * 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) + * \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`. @@ -809,8 +823,8 @@ SDL_GameControllerGetBindForButton(SDL_GameController *gamecontroller, * 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) + * \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. * * \since This function is available since SDL 2.0.14. @@ -821,8 +835,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasButton(SDL_GameController /** * Get the current state of a button on a game controller. * - * \param gamecontroller a game controller - * \param button a button index (one of the SDL_GameControllerButton values) + * \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. * @@ -858,8 +872,8 @@ extern DECLSPEC int SDLCALL SDL_GameControllerGetTouchpadFinger(SDL_GameControll /** * 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. * \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.14. @@ -869,9 +883,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasSensor(SDL_GameController /** * 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. * \returns 0 or -1 if an error occurred. * * \since This function is available since SDL 2.0.14. @@ -881,8 +895,8 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSetSensorEnabled(SDL_GameControlle /** * 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. * \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.14. @@ -893,8 +907,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerIsSensorEnabled(SDL_GameContr * Get the data rate (number of events per second) of a game controller * 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 the data rate, or 0.0f if the data rate is not available. * * \since This function is available since SDL 2.0.16. @@ -907,10 +921,10 @@ extern DECLSPEC float SDLCALL SDL_GameControllerGetSensorDataRate(SDL_GameContro * 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 + * \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. * * \since This function is available since SDL 2.0.14. @@ -924,12 +938,12 @@ extern DECLSPEC int SDLCALL SDL_GameControllerGetSensorData(SDL_GameController * * 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 gamecontroller The controller to query. + * \param type The type of sensor to query. * \param timestamp A pointer filled with the timestamp in microseconds of the - * current sensor reading if available, or 0 if not - * \param data A pointer filled with the current sensor state - * \param num_values The number of values to write to data + * current sensor reading if available, or 0 if not. + * \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. * * \since This function is available since SDL 2.26.0. @@ -942,13 +956,13 @@ extern DECLSPEC int SDLCALL SDL_GameControllerGetSensorDataWithTimestamp(SDL_Gam * Each call to this function cancels any previous rumble effect, and calling * it with 0 intensity stops any rumbling. * - * \param gamecontroller The controller to vibrate + * \param gamecontroller The controller to vibrate. * \param low_frequency_rumble The intensity of the low frequency (left) - * rumble motor, from 0 to 0xFFFF + * 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 + * 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. * * \since This function is available since SDL 2.0.9. * @@ -967,13 +981,13 @@ extern DECLSPEC int SDLCALL SDL_GameControllerRumble(SDL_GameController *gamecon * want the (more common) whole-controller rumble, use * SDL_GameControllerRumble() instead. * - * \param gamecontroller The controller to vibrate + * \param gamecontroller The controller to vibrate. * \param left_rumble The intensity of the left trigger rumble motor, from 0 - * to 0xFFFF + * 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 + * 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. * * \since This function is available since SDL 2.0.14. * @@ -984,9 +998,9 @@ extern DECLSPEC int SDLCALL SDL_GameControllerRumbleTriggers(SDL_GameController /** * Query whether a game controller has an LED. * - * \param gamecontroller The controller to query + * \param gamecontroller The controller to query. * \returns SDL_TRUE, or SDL_FALSE if this controller does not have a - * modifiable LED + * modifiable LED. * * \since This function is available since SDL 2.0.14. */ @@ -995,9 +1009,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasLED(SDL_GameController *ga /** * Query whether a game controller has rumble support. * - * \param gamecontroller The controller to query + * \param gamecontroller The controller to query. * \returns SDL_TRUE, or SDL_FALSE if this controller does not have rumble - * support + * support. * * \since This function is available since SDL 2.0.18. * @@ -1008,9 +1022,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasRumble(SDL_GameController /** * Query whether a game controller has rumble support on triggers. * - * \param gamecontroller The controller to query + * \param gamecontroller The controller to query. * \returns SDL_TRUE, or SDL_FALSE if this controller does not have trigger - * rumble support + * rumble support. * * \since This function is available since SDL 2.0.18. * @@ -1021,11 +1035,11 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasRumbleTriggers(SDL_GameCon /** * 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 - * \returns 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. * * \since This function is available since SDL 2.0.14. */ @@ -1034,11 +1048,11 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSetLED(SDL_GameController *gamecon /** * Send a controller specific effect packet * - * \param gamecontroller The controller to affect - * \param data The data to send to the controller - * \param size The size of the data to send to the controller + * \param gamecontroller The controller to affect. + * \param data The data to send to the controller. + * \param size The size of the data to send to the controller. * \returns 0, or -1 if this controller or driver doesn't support effect - * packets + * packets. * * \since This function is available since SDL 2.0.16. */ @@ -1048,7 +1062,7 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSendEffect(SDL_GameController *gam * Close a game controller previously opened with SDL_GameControllerOpen(). * * \param gamecontroller a game controller identifier previously returned by - * SDL_GameControllerOpen() + * SDL_GameControllerOpen(). * * \since This function is available since SDL 2.0.0. * @@ -1060,9 +1074,9 @@ extern DECLSPEC void SDLCALL SDL_GameControllerClose(SDL_GameController *gamecon * Return the sfSymbolsName for a given button on a game controller on Apple * platforms. * - * \param gamecontroller the controller to query - * \param button a button on the game controller - * \returns the sfSymbolsName or NULL if the name can't be found + * \param gamecontroller the controller to query. + * \param button a button on the game controller. + * \returns the sfSymbolsName or NULL if the name can't be found. * * \since This function is available since SDL 2.0.18. * @@ -1074,9 +1088,9 @@ extern DECLSPEC const char* SDLCALL SDL_GameControllerGetAppleSFSymbolsNameForBu * Return the sfSymbolsName for a given axis on a game controller on Apple * platforms. * - * \param gamecontroller the controller to query - * \param axis an axis on the game controller - * \returns the sfSymbolsName or NULL if the name can't be found + * \param gamecontroller the controller to query. + * \param axis an axis on the game controller. + * \returns the sfSymbolsName or NULL if the name can't be found. * * \since This function is available since SDL 2.0.18. * diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_gesture.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_gesture.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_gesture.h + * # CategoryGesture * - * Include file for SDL gesture event handling. + * Include file for SDL gesture event handling. */ #ifndef SDL_gesture_h_ @@ -51,7 +51,7 @@ typedef Sint64 SDL_GestureID; * 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 + * \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. @@ -64,7 +64,7 @@ extern DECLSPEC int SDLCALL SDL_RecordGesture(SDL_TouchID touchId); /** * Save all currently loaded Dollar Gesture templates. * - * \param dst a SDL_RWops to save to + * \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. * @@ -78,8 +78,8 @@ extern DECLSPEC int SDLCALL SDL_SaveAllDollarTemplates(SDL_RWops *dst); /** * Save a currently loaded Dollar Gesture template. * - * \param gestureId a gesture id - * \param dst a SDL_RWops to save to + * \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. * @@ -94,8 +94,8 @@ extern DECLSPEC int SDLCALL SDL_SaveDollarTemplate(SDL_GestureID gestureId,SDL_R /** * Load Dollar Gesture templates from a file. * - * \param touchId a touch id - * \param src a SDL_RWops to load from + * \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. * diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_guid.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_guid.h @@ -19,10 +19,13 @@ 3. This notice may not be removed or altered from any source distribution. */ +/* WIKI CATEGORY: GUID */ + /** - * \file SDL_guid.h + * # CategoryGUID * - * Include file for handling ::SDL_GUID values. + * A GUID is a 128-bit value that represents something that is uniquely + * identifiable by this value: "globally unique." */ #ifndef SDL_guid_h_ @@ -38,34 +41,38 @@ extern "C" { #endif /** - * An SDL_GUID is a 128-bit identifier for an input device that - * identifies that device across runs of SDL programs on the same - * platform. If the device is detached and then re-attached to a - * different port, or if the base system is rebooted, the device - * should still report the same GUID. + * An SDL_GUID is a 128-bit identifier. + * + * This is an acronym for "Globally Unique ID." + * + * While a GUID can be used to assign a unique value to almost anything, in + * SDL these are largely used to identify input devices across runs of SDL + * programs on the same platform.If the device is detached and then + * re-attached to a different port, or if the base system is rebooted, the + * device should still report the same GUID. * - * GUIDs are as precise as possible but are not guaranteed to - * distinguish physically distinct but equivalent devices. For - * example, two game controllers from the same vendor with the same - * product ID and revision may have the same GUID. + * GUIDs are as precise as possible but are not guaranteed to distinguish + * physically distinct but equivalent devices. For example, two game + * controllers from the same vendor with the same product ID and revision may + * have the same GUID. * - * GUIDs may be platform-dependent (i.e., the same device may report - * different GUIDs on different operating systems). + * GUIDs may be platform-dependent (i.e., the same device may report different + * GUIDs on different operating systems). */ -typedef struct { +typedef struct SDL_GUID { Uint8 data[16]; } SDL_GUID; /* Function prototypes */ /** - * Get an ASCII string representation for a given ::SDL_GUID. + * Get an ASCII string representation for a given SDL_GUID. * * You should supply at least 33 bytes for pszGUID. * - * \param guid the ::SDL_GUID you wish to convert to string - * \param pszGUID buffer in which to write the ASCII string - * \param cbGUID the size of pszGUID + * \param guid the SDL_GUID you wish to convert to string. + * \param pszGUID buffer in which to write the ASCII string. + * \param cbGUID the size of pszGUID. * * \since This function is available since SDL 2.24.0. * @@ -74,14 +81,14 @@ typedef struct { extern DECLSPEC void SDLCALL SDL_GUIDToString(SDL_GUID guid, char *pszGUID, int cbGUID); /** - * Convert a GUID string into a ::SDL_GUID structure. + * Convert a GUID string into a SDL_GUID 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_GUID structure. + * \param pchGUID string containing an ASCII representation of a GUID. + * \returns a SDL_GUID structure. * * \since This function is available since SDL 2.24.0. * diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_haptic.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_haptic.h @@ -20,24 +20,25 @@ */ /** - * \file SDL_haptic.h - * - * \brief The SDL haptic subsystem allows you to control haptic (force feedback) - * devices. - * - * The basic usage is as follows: - * - Initialize the subsystem (::SDL_INIT_HAPTIC). - * - Open a haptic device. - * - SDL_HapticOpen() to open from index. - * - SDL_HapticOpenFromJoystick() to open from an existing joystick. - * - Create an effect (::SDL_HapticEffect). - * - Upload the effect with SDL_HapticNewEffect(). - * - Run the effect with SDL_HapticRunEffect(). - * - (optional) Free the effect with SDL_HapticDestroyEffect(). - * - Close the haptic device with SDL_HapticClose(). - * - * \par Simple rumble example: - * \code + * # CategoryHaptic + * + * SDL haptic subsystem allows you to control haptic (force feedback) devices. + * + * The basic usage is as follows: + * + * - Initialize the subsystem (SDL_INIT_HAPTIC). + * - Open a haptic device. + * - SDL_HapticOpen() to open from index. + * - SDL_HapticOpenFromJoystick() to open from an existing joystick. + * - Create an effect (SDL_HapticEffect). + * - Upload the effect with SDL_HapticNewEffect(). + * - Run the effect with SDL_HapticRunEffect(). + * - (optional) Free the effect with SDL_HapticDestroyEffect(). + * - Close the haptic device with SDL_HapticClose(). + * + * Simple rumble example: + * + * ```c * SDL_Haptic *haptic; * * // Open the device @@ -56,10 +57,11 @@ * * // Clean up * SDL_HapticClose( haptic ); - * \endcode + * ``` + * + * Complete example: * - * \par Complete example: - * \code + * ```c * int test_haptic( SDL_Joystick * joystick ) { * SDL_Haptic *haptic; * SDL_HapticEffect effect; @@ -101,7 +103,7 @@ * * return 0; // Success * } - * \endcode + * ``` */ #ifndef SDL_haptic_h_ @@ -154,31 +156,29 @@ typedef struct _SDL_Haptic SDL_Haptic; /* @{ */ /** - * \brief Constant effect supported. + * Constant effect supported. * - * Constant haptic effect. + * Constant haptic effect. * - * \sa SDL_HapticCondition + * \sa SDL_HapticCondition */ #define SDL_HAPTIC_CONSTANT (1u<<0) /** - * \brief Sine wave effect supported. + * Sine wave effect supported. * - * Periodic haptic effect that simulates sine waves. + * Periodic haptic effect that simulates sine waves. * - * \sa SDL_HapticPeriodic + * \sa SDL_HapticPeriodic */ #define SDL_HAPTIC_SINE (1u<<1) /** - * \brief Left/Right effect supported. + * Left/Right effect supported. * - * Haptic effect for direct control over high/low frequency motors. + * Haptic effect for direct control over high/low frequency motors. * - * \sa SDL_HapticLeftRight - * \warning this value was SDL_HAPTIC_SQUARE right before 2.0.0 shipped. Sorry, - * we ran out of bits, and this is important for XInput devices. + * \sa SDL_HapticLeftRight */ #define SDL_HAPTIC_LEFTRIGHT (1u<<2) @@ -186,85 +186,85 @@ typedef struct _SDL_Haptic SDL_Haptic; /* #define SDL_HAPTIC_SQUARE (1<<2) */ /** - * \brief Triangle wave effect supported. + * Triangle wave effect supported. * - * Periodic haptic effect that simulates triangular waves. + * Periodic haptic effect that simulates triangular waves. * - * \sa SDL_HapticPeriodic + * \sa SDL_HapticPeriodic */ #define SDL_HAPTIC_TRIANGLE (1u<<3) /** - * \brief Sawtoothup wave effect supported. + * Sawtoothup wave effect supported. * - * Periodic haptic effect that simulates saw tooth up waves. + * Periodic haptic effect that simulates saw tooth up waves. * - * \sa SDL_HapticPeriodic + * \sa SDL_HapticPeriodic */ #define SDL_HAPTIC_SAWTOOTHUP (1u<<4) /** - * \brief Sawtoothdown wave effect supported. + * Sawtoothdown wave effect supported. * - * Periodic haptic effect that simulates saw tooth down waves. + * Periodic haptic effect that simulates saw tooth down waves. * - * \sa SDL_HapticPeriodic + * \sa SDL_HapticPeriodic */ #define SDL_HAPTIC_SAWTOOTHDOWN (1u<<5) /** - * \brief Ramp effect supported. + * Ramp effect supported. * - * Ramp haptic effect. + * Ramp haptic effect. * - * \sa SDL_HapticRamp + * \sa SDL_HapticRamp */ #define SDL_HAPTIC_RAMP (1u<<6) /** - * \brief Spring effect supported - uses axes position. + * Spring effect supported - uses axes position. * - * Condition haptic effect that simulates a spring. Effect is based on the - * axes position. + * Condition haptic effect that simulates a spring. Effect is based on the + * axes position. * - * \sa SDL_HapticCondition + * \sa SDL_HapticCondition */ #define SDL_HAPTIC_SPRING (1u<<7) /** - * \brief Damper effect supported - uses axes velocity. + * Damper effect supported - uses axes velocity. * - * Condition haptic effect that simulates dampening. Effect is based on the - * axes velocity. + * Condition haptic effect that simulates dampening. Effect is based on the + * axes velocity. * - * \sa SDL_HapticCondition + * \sa SDL_HapticCondition */ #define SDL_HAPTIC_DAMPER (1u<<8) /** - * \brief Inertia effect supported - uses axes acceleration. + * Inertia effect supported - uses axes acceleration. * - * Condition haptic effect that simulates inertia. Effect is based on the axes - * acceleration. + * Condition haptic effect that simulates inertia. Effect is based on the axes + * acceleration. * - * \sa SDL_HapticCondition + * \sa SDL_HapticCondition */ #define SDL_HAPTIC_INERTIA (1u<<9) /** - * \brief Friction effect supported - uses axes movement. + * Friction effect supported - uses axes movement. * - * Condition haptic effect that simulates friction. Effect is based on the - * axes movement. + * Condition haptic effect that simulates friction. Effect is based on the + * axes movement. * - * \sa SDL_HapticCondition + * \sa SDL_HapticCondition */ #define SDL_HAPTIC_FRICTION (1u<<10) /** - * \brief Custom effect is supported. + * Custom effect is supported. * - * User defined custom haptic effect. + * User defined custom haptic effect. */ #define SDL_HAPTIC_CUSTOM (1u<<11) @@ -273,39 +273,39 @@ typedef struct _SDL_Haptic SDL_Haptic; /* These last few are features the device has, not effects */ /** - * \brief Device can set global gain. + * Device can set global gain. * - * Device supports setting the global gain. + * Device supports setting the global gain. * - * \sa SDL_HapticSetGain + * \sa SDL_HapticSetGain */ #define SDL_HAPTIC_GAIN (1u<<12) /** - * \brief Device can set autocenter. + * Device can set autocenter. * - * Device supports setting autocenter. + * Device supports setting autocenter. * - * \sa SDL_HapticSetAutocenter + * \sa SDL_HapticSetAutocenter */ #define SDL_HAPTIC_AUTOCENTER (1u<<13) /** - * \brief Device can be queried for effect status. + * Device can be queried for effect status. * - * Device supports querying effect status. + * Device supports querying effect status. * - * \sa SDL_HapticGetEffectStatus + * \sa SDL_HapticGetEffectStatus */ #define SDL_HAPTIC_STATUS (1u<<14) /** - * \brief Device can be paused. + * Device can be paused. * - * Devices supports being paused. + * Devices supports being paused. * - * \sa SDL_HapticPause - * \sa SDL_HapticUnpause + * \sa SDL_HapticPause + * \sa SDL_HapticUnpause */ #define SDL_HAPTIC_PAUSE (1u<<15) @@ -316,31 +316,33 @@ typedef struct _SDL_Haptic SDL_Haptic; /* @{ */ /** - * \brief Uses polar coordinates for the direction. + * Uses polar coordinates for the direction. * - * \sa SDL_HapticDirection + * \sa SDL_HapticDirection */ #define SDL_HAPTIC_POLAR 0 /** - * \brief Uses cartesian coordinates for the direction. + * Uses cartesian coordinates for the direction. * - * \sa SDL_HapticDirection + * \sa SDL_HapticDirection */ #define SDL_HAPTIC_CARTESIAN 1 /** - * \brief Uses spherical coordinates for the direction. + * Uses spherical coordinates for the direction. * - * \sa SDL_HapticDirection + * \sa SDL_HapticDirection */ #define SDL_HAPTIC_SPHERICAL 2 /** - * \brief Use this value to play an effect on the steering wheel axis. This - * provides better compatibility across platforms and devices as SDL will guess - * the correct axis. - * \sa SDL_HapticDirection + * Use this value to play an effect on the steering wheel axis. + * + * This provides better compatibility across platforms and devices as SDL will + * guess the correct axis. + * + * \sa SDL_HapticDirection */ #define SDL_HAPTIC_STEERING_AXIS 3 @@ -353,7 +355,7 @@ typedef struct _SDL_Haptic SDL_Haptic; */ /** - * \brief Used to play a device an infinite number of times. + * Used to play a device an infinite number of times. * * \sa SDL_HapticRunEffect */ @@ -361,77 +363,82 @@ typedef struct _SDL_Haptic SDL_Haptic; /** - * \brief Structure that represents a haptic direction. - * - * This is the direction where the force comes from, - * instead of the direction in which the force is exerted. - * - * Directions can be specified by: - * - ::SDL_HAPTIC_POLAR : Specified by polar coordinates. - * - ::SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates. - * - ::SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates. - * - * Cardinal directions of the haptic device are relative to the positioning - * of the device. North is considered to be away from the user. - * - * The following diagram represents the cardinal directions: - * \verbatim - .--. - |__| .-------. - |=.| |.-----.| - |--| || || - | | |'-----'| - |__|~')_____(' - [ COMPUTER ] - - - North (0,-1) - ^ - | - | - (-1,0) West <----[ HAPTIC ]----> East (1,0) - | - | - v - South (0,1) - - - [ USER ] - \|||/ - (o o) - ---ooO-(_)-Ooo--- - \endverbatim - * - * If type is ::SDL_HAPTIC_POLAR, direction is encoded by hundredths of a - * degree starting north and turning clockwise. ::SDL_HAPTIC_POLAR only uses - * the first \c dir parameter. The cardinal directions would be: - * - North: 0 (0 degrees) - * - East: 9000 (90 degrees) - * - South: 18000 (180 degrees) - * - West: 27000 (270 degrees) - * - * If type is ::SDL_HAPTIC_CARTESIAN, direction is encoded by three positions - * (X axis, Y axis and Z axis (with 3 axes)). ::SDL_HAPTIC_CARTESIAN uses - * the first three \c dir parameters. The cardinal directions would be: - * - North: 0,-1, 0 - * - East: 1, 0, 0 - * - South: 0, 1, 0 - * - West: -1, 0, 0 - * - * The Z axis represents the height of the effect if supported, otherwise - * it's unused. In cartesian encoding (1, 2) would be the same as (2, 4), you - * can use any multiple you want, only the direction matters. - * - * If type is ::SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations. - * The first two \c dir parameters are used. The \c dir parameters are as - * follows (all values are in hundredths of degrees): - * - Degrees from (1, 0) rotated towards (0, 1). - * - Degrees towards (0, 0, 1) (device needs at least 3 axes). - * - * - * Example of force coming from the south with all encodings (force coming - * from the south means the user will have to pull the stick to counteract): - * \code + * Structure that represents a haptic direction. + * + * This is the direction where the force comes from, instead of the direction + * in which the force is exerted. + * + * Directions can be specified by: + * + * - SDL_HAPTIC_POLAR : Specified by polar coordinates. + * - SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates. + * - SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates. + * + * Cardinal directions of the haptic device are relative to the positioning of + * the device. North is considered to be away from the user. + * + * The following diagram represents the cardinal directions: + * + * ``` + * .--. + * |__| .-------. + * |=.| |.-----.| + * |--| || || + * | | |'-----'| + * |__|~')_____(' + * [ COMPUTER ] + * + * + * North (0,-1) + * ^ + * | + * | + * (-1,0) West <----[ HAPTIC ]----> East (1,0) + * | + * | + * v + * South (0,1) + * + * + * [ USER ] + * \|||/ + * (o o) + * ---ooO-(_)-Ooo--- + * ``` + * + * If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a degree + * starting north and turning clockwise. SDL_HAPTIC_POLAR only uses the first + * `dir` parameter. The cardinal directions would be: + * + * - North: 0 (0 degrees) + * - East: 9000 (90 degrees) + * - South: 18000 (180 degrees) + * - West: 27000 (270 degrees) + * + * If type is SDL_HAPTIC_CARTESIAN, direction is encoded by three positions (X + * axis, Y axis and Z axis (with 3 axes)). SDL_HAPTIC_CARTESIAN uses the first + * three `dir` parameters. The cardinal directions would be: + * + * - North: 0,-1, 0 + * - East: 1, 0, 0 + * - South: 0, 1, 0 + * - West: -1, 0, 0 + * + * The Z axis represents the height of the effect if supported, otherwise it's + * unused. In cartesian encoding (1, 2) would be the same as (2, 4), you can + * use any multiple you want, only the direction matters. + * + * If type is SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations. The + * first two `dir` parameters are used. The `dir` parameters are as follows + * (all values are in hundredths of degrees): + * + * - Degrees from (1, 0) rotated towards (0, 1). + * - Degrees towards (0, 0, 1) (device needs at least 3 axes). + * + * Example of force coming from the south with all encodings (force coming + * from the south means the user will have to pull the stick to counteract): + * + * ```c * SDL_HapticDirection direction; * * // Cartesian directions @@ -447,14 +454,14 @@ typedef struct _SDL_Haptic SDL_Haptic; * // Spherical coordinates * direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding * direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters. - * \endcode + * ``` * - * \sa SDL_HAPTIC_POLAR - * \sa SDL_HAPTIC_CARTESIAN - * \sa SDL_HAPTIC_SPHERICAL - * \sa SDL_HAPTIC_STEERING_AXIS - * \sa SDL_HapticEffect - * \sa SDL_HapticNumAxes + * \sa SDL_HAPTIC_POLAR + * \sa SDL_HAPTIC_CARTESIAN + * \sa SDL_HAPTIC_SPHERICAL + * \sa SDL_HAPTIC_STEERING_AXIS + * \sa SDL_HapticEffect + * \sa SDL_HapticNumAxes */ typedef struct SDL_HapticDirection { @@ -464,20 +471,20 @@ typedef struct SDL_HapticDirection /** - * \brief A structure containing a template for a Constant effect. + * A structure containing a template for a Constant effect. * - * This struct is exclusively for the ::SDL_HAPTIC_CONSTANT effect. + * This struct is exclusively for the SDL_HAPTIC_CONSTANT effect. * - * A constant effect applies a constant force in the specified direction - * to the joystick. + * A constant effect applies a constant force in the specified direction to + * the joystick. * - * \sa SDL_HAPTIC_CONSTANT - * \sa SDL_HapticEffect + * \sa SDL_HAPTIC_CONSTANT + * \sa SDL_HapticEffect */ typedef struct SDL_HapticConstant { /* Header */ - Uint16 type; /**< ::SDL_HAPTIC_CONSTANT */ + Uint16 type; /**< SDL_HAPTIC_CONSTANT */ SDL_HapticDirection direction; /**< Direction of the effect. */ /* Replay */ @@ -499,68 +506,71 @@ typedef struct SDL_HapticConstant } SDL_HapticConstant; /** - * \brief A structure containing a template for a Periodic effect. - * - * The struct handles the following effects: - * - ::SDL_HAPTIC_SINE - * - ::SDL_HAPTIC_LEFTRIGHT - * - ::SDL_HAPTIC_TRIANGLE - * - ::SDL_HAPTIC_SAWTOOTHUP - * - ::SDL_HAPTIC_SAWTOOTHDOWN - * - * A periodic effect consists in a wave-shaped effect that repeats itself - * over time. The type determines the shape of the wave and the parameters - * determine the dimensions of the wave. - * - * Phase is given by hundredth of a degree meaning that giving the phase a value - * of 9000 will displace it 25% of its period. Here are sample values: - * - 0: No phase displacement. - * - 9000: Displaced 25% of its period. - * - 18000: Displaced 50% of its period. - * - 27000: Displaced 75% of its period. - * - 36000: Displaced 100% of its period, same as 0, but 0 is preferred. - * - * Examples: - * \verbatim - SDL_HAPTIC_SINE - __ __ __ __ - / \ / \ / \ / - / \__/ \__/ \__/ - - SDL_HAPTIC_SQUARE - __ __ __ __ __ - | | | | | | | | | | - | |__| |__| |__| |__| | - - SDL_HAPTIC_TRIANGLE - /\ /\ /\ /\ /\ - / \ / \ / \ / \ / - / \/ \/ \/ \/ - - SDL_HAPTIC_SAWTOOTHUP - /| /| /| /| /| /| /| - / | / | / | / | / | / | / | - / |/ |/ |/ |/ |/ |/ | - - SDL_HAPTIC_SAWTOOTHDOWN - \ |\ |\ |\ |\ |\ |\ | - \ | \ | \ | \ | \ | \ | \ | - \| \| \| \| \| \| \| - \endverbatim - * - * \sa SDL_HAPTIC_SINE - * \sa SDL_HAPTIC_LEFTRIGHT - * \sa SDL_HAPTIC_TRIANGLE - * \sa SDL_HAPTIC_SAWTOOTHUP - * \sa SDL_HAPTIC_SAWTOOTHDOWN - * \sa SDL_HapticEffect + * A structure containing a template for a Periodic effect. + * + * The struct handles the following effects: + * + * - SDL_HAPTIC_SINE + * - SDL_HAPTIC_SQUARE + * - SDL_HAPTIC_TRIANGLE + * - SDL_HAPTIC_SAWTOOTHUP + * - SDL_HAPTIC_SAWTOOTHDOWN + * + * A periodic effect consists in a wave-shaped effect that repeats itself over + * time. The type determines the shape of the wave and the parameters + * determine the dimensions of the wave. + * + * Phase is given by hundredth of a degree meaning that giving the phase a + * value of 9000 will displace it 25% of its period. Here are sample values: + * + * - 0: No phase displacement. + * - 9000: Displaced 25% of its period. + * - 18000: Displaced 50% of its period. + * - 27000: Displaced 75% of its period. + * - 36000: Displaced 100% of its period, same as 0, but 0 is preferred. + * + * Examples: + * + * ``` + * SDL_HAPTIC_SINE + * __ __ __ __ + * / \ / \ / \ / + * / \__/ \__/ \__/ + * + * SDL_HAPTIC_SQUARE + * __ __ __ __ __ + * | | | | | | | | | | + * | |__| |__| |__| |__| | + * + * SDL_HAPTIC_TRIANGLE + * /\ /\ /\ /\ /\ + * / \ / \ / \ / \ / + * / \/ \/ \/ \/ + * + * SDL_HAPTIC_SAWTOOTHUP + * /| /| /| /| /| /| /| + * / | / | / | / | / | / | / | + * / |/ |/ |/ |/ |/ |/ | + * + * SDL_HAPTIC_SAWTOOTHDOWN + * \ |\ |\ |\ |\ |\ |\ | + * \ | \ | \ | \ | \ | \ | \ | + * \| \| \| \| \| \| \| + * ``` + * + * \sa SDL_HAPTIC_SINE + * \sa SDL_HAPTIC_LEFTRIGHT + * \sa SDL_HAPTIC_TRIANGLE + * \sa SDL_HAPTIC_SAWTOOTHUP + * \sa SDL_HAPTIC_SAWTOOTHDOWN + * \sa SDL_HapticEffect */ typedef struct SDL_HapticPeriodic { /* Header */ - Uint16 type; /**< ::SDL_HAPTIC_SINE, ::SDL_HAPTIC_LEFTRIGHT, - ::SDL_HAPTIC_TRIANGLE, ::SDL_HAPTIC_SAWTOOTHUP or - ::SDL_HAPTIC_SAWTOOTHDOWN */ + Uint16 type; /**< SDL_HAPTIC_SINE, SDL_HAPTIC_LEFTRIGHT, + SDL_HAPTIC_TRIANGLE, SDL_HAPTIC_SAWTOOTHUP or + SDL_HAPTIC_SAWTOOTHDOWN */ SDL_HapticDirection direction; /**< Direction of the effect. */ /* Replay */ @@ -585,35 +595,36 @@ typedef struct SDL_HapticPeriodic } SDL_HapticPeriodic; /** - * \brief A structure containing a template for a Condition effect. + * A structure containing a template for a Condition effect. * - * The struct handles the following effects: - * - ::SDL_HAPTIC_SPRING: Effect based on axes position. - * - ::SDL_HAPTIC_DAMPER: Effect based on axes velocity. - * - ::SDL_HAPTIC_INERTIA: Effect based on axes acceleration. - * - ::SDL_HAPTIC_FRICTION: Effect based on axes movement. + * The struct handles the following effects: * - * Direction is handled by condition internals instead of a direction member. - * The condition effect specific members have three parameters. The first - * refers to the X axis, the second refers to the Y axis and the third - * refers to the Z axis. The right terms refer to the positive side of the - * axis and the left terms refer to the negative side of the axis. Please - * refer to the ::SDL_HapticDirection diagram for which side is positive and - * which is negative. + * - SDL_HAPTIC_SPRING: Effect based on axes position. + * - SDL_HAPTIC_DAMPER: Effect based on axes velocity. + * - SDL_HAPTIC_INERTIA: Effect based on axes acceleration. + * - SDL_HAPTIC_FRICTION: Effect based on axes movement. * - * \sa SDL_HapticDirection - * \sa SDL_HAPTIC_SPRING - * \sa SDL_HAPTIC_DAMPER - * \sa SDL_HAPTIC_INERTIA - * \sa SDL_HAPTIC_FRICTION - * \sa SDL_HapticEffect + * Direction is handled by condition internals instead of a direction member. + * The condition effect specific members have three parameters. The first + * refers to the X axis, the second refers to the Y axis and the third refers + * to the Z axis. The right terms refer to the positive side of the axis and + * the left terms refer to the negative side of the axis. Please refer to the + * SDL_HapticDirection diagram for which side is positive and which is + * negative. + * + * \sa SDL_HapticDirection + * \sa SDL_HAPTIC_SPRING + * \sa SDL_HAPTIC_DAMPER + * \sa SDL_HAPTIC_INERTIA + * \sa SDL_HAPTIC_FRICTION + * \sa SDL_HapticEffect */ typedef struct SDL_HapticCondition { /* Header */ - Uint16 type; /**< ::SDL_HAPTIC_SPRING, ::SDL_HAPTIC_DAMPER, - ::SDL_HAPTIC_INERTIA or ::SDL_HAPTIC_FRICTION */ - SDL_HapticDirection direction; /**< Direction of the effect - Not used ATM. */ + Uint16 type; /**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER, + SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION */ + SDL_HapticDirection direction; /**< Direction of the effect. */ /* Replay */ Uint32 length; /**< Duration of the effect. */ @@ -633,22 +644,22 @@ typedef struct SDL_HapticCondition } SDL_HapticCondition; /** - * \brief A structure containing a template for a Ramp effect. + * A structure containing a template for a Ramp effect. * - * This struct is exclusively for the ::SDL_HAPTIC_RAMP effect. + * This struct is exclusively for the SDL_HAPTIC_RAMP effect. * - * The ramp effect starts at start strength and ends at end strength. - * It augments in linear fashion. If you use attack and fade with a ramp - * the effects get added to the ramp effect making the effect become - * quadratic instead of linear. + * The ramp effect starts at start strength and ends at end strength. It + * augments in linear fashion. If you use attack and fade with a ramp the + * effects get added to the ramp effect making the effect become quadratic + * instead of linear. * - * \sa SDL_HAPTIC_RAMP - * \sa SDL_HapticEffect + * \sa SDL_HAPTIC_RAMP + * \sa SDL_HapticEffect */ typedef struct SDL_HapticRamp { /* Header */ - Uint16 type; /**< ::SDL_HAPTIC_RAMP */ + Uint16 type; /**< SDL_HAPTIC_RAMP */ SDL_HapticDirection direction; /**< Direction of the effect. */ /* Replay */ @@ -671,9 +682,9 @@ typedef struct SDL_HapticRamp } SDL_HapticRamp; /** - * \brief A structure containing a template for a Left/Right effect. + * A structure containing a template for a Left/Right effect. * - * This struct is exclusively for the ::SDL_HAPTIC_LEFTRIGHT effect. + * This struct is exclusively for the SDL_HAPTIC_LEFTRIGHT effect. * * The Left/Right effect is used to explicitly control the large and small * motors, commonly found in modern game controllers. The small (right) motor @@ -685,7 +696,7 @@ typedef struct SDL_HapticRamp typedef struct SDL_HapticLeftRight { /* Header */ - Uint16 type; /**< ::SDL_HAPTIC_LEFTRIGHT */ + Uint16 type; /**< SDL_HAPTIC_LEFTRIGHT */ /* Replay */ Uint32 length; /**< Duration of the effect in milliseconds. */ @@ -696,24 +707,24 @@ typedef struct SDL_HapticLeftRight } SDL_HapticLeftRight; /** - * \brief A structure containing a template for the ::SDL_HAPTIC_CUSTOM effect. + * A structure containing a template for the SDL_HAPTIC_CUSTOM effect. * - * This struct is exclusively for the ::SDL_HAPTIC_CUSTOM effect. + * This struct is exclusively for the SDL_HAPTIC_CUSTOM effect. * - * A custom force feedback effect is much like a periodic effect, where the - * application can define its exact shape. You will have to allocate the - * data yourself. Data should consist of channels * samples Uint16 samples. + * A custom force feedback effect is much like a periodic effect, where the + * application can define its exact shape. You will have to allocate the data + * yourself. Data should consist of channels * samples Uint16 samples. * - * If channels is one, the effect is rotated using the defined direction. - * Otherwise it uses the samples in data for the different axes. + * If channels is one, the effect is rotated using the defined direction. + * Otherwise it uses the samples in data for the different axes. * - * \sa SDL_HAPTIC_CUSTOM - * \sa SDL_HapticEffect + * \sa SDL_HAPTIC_CUSTOM + * \sa SDL_HapticEffect */ typedef struct SDL_HapticCustom { /* Header */ - Uint16 type; /**< ::SDL_HAPTIC_CUSTOM */ + Uint16 type; /**< SDL_HAPTIC_CUSTOM */ SDL_HapticDirection direction; /**< Direction of the effect. */ /* Replay */ @@ -738,27 +749,28 @@ typedef struct SDL_HapticCustom } SDL_HapticCustom; /** - * \brief The generic template for any haptic effect. + * The generic template for any haptic effect. + * + * All values max at 32767 (0x7FFF). Signed values also can be negative. Time + * values unless specified otherwise are in milliseconds. * - * All values max at 32767 (0x7FFF). Signed values also can be negative. - * Time values unless specified otherwise are in milliseconds. + * You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value. + * Neither delay, interval, attack_length nor fade_length support + * SDL_HAPTIC_INFINITY. Fade will also not be used since effect never ends. * - * You can also pass ::SDL_HAPTIC_INFINITY to length instead of a 0-32767 - * value. Neither delay, interval, attack_length nor fade_length support - * ::SDL_HAPTIC_INFINITY. Fade will also not be used since effect never ends. + * Additionally, the SDL_HAPTIC_RAMP effect does not support a duration of + * SDL_HAPTIC_INFINITY. * - * Additionally, the ::SDL_HAPTIC_RAMP effect does not support a duration of - * ::SDL_HAPTIC_INFINITY. + * Button triggers may not be supported on all devices, it is advised to not + * use them if possible. Buttons start at index 1 instead of index 0 like the + * joystick. * - * Button triggers may not be supported on all devices, it is advised to not - * use them if possible. Buttons start at index 1 instead of index 0 like - * the joystick. + * If both attack_length and fade_level are 0, the envelope is not used, + * otherwise both values are used. * - * If both attack_length and fade_level are 0, the envelope is not used, - * otherwise both values are used. + * Common parts: * - * Common parts: - * \code + * ```c * // Replay - All effects have this * Uint32 length; // Duration of effect (ms). * Uint16 delay; // Delay before starting effect. @@ -772,39 +784,39 @@ typedef struct SDL_HapticCustom * Uint16 attack_level; // Level at the start of the attack. * Uint16 fade_length; // Duration of the fade out (ms). * Uint16 fade_level; // Level at the end of the fade. - * \endcode - * - * - * Here we have an example of a constant effect evolution in time: - * \verbatim - Strength - ^ - | - | effect level --> _________________ - | / \ - | / \ - | / \ - | / \ - | attack_level --> | \ - | | | <--- fade_level - | - +--------------------------------------------------> Time - [--] [---] - attack_length fade_length - - [------------------][-----------------------] - delay length - \endverbatim - * - * Note either the attack_level or the fade_level may be above the actual - * effect level. - * - * \sa SDL_HapticConstant - * \sa SDL_HapticPeriodic - * \sa SDL_HapticCondition - * \sa SDL_HapticRamp - * \sa SDL_HapticLeftRight - * \sa SDL_HapticCustom + * ``` + * + * Here we have an example of a constant effect evolution in time: + * + * ``` + * Strength + * ^ + * | + * | effect level --> _________________ + * | / \ + * | / \ + * | / \ + * | / \ + * | attack_level --> | \ + * | | | <--- fade_level + * | + * +--------------------------------------------------> Time + * [--] [---] + * attack_length fade_length + * + * [------------------][-----------------------] + * delay length + * ``` + * + * Note either the attack_level or the fade_level may be above the actual + * effect level. + * + * \sa SDL_HapticConstant + * \sa SDL_HapticPeriodic + * \sa SDL_HapticCondition + * \sa SDL_HapticRamp + * \sa SDL_HapticLeftRight + * \sa SDL_HapticCustom */ typedef union SDL_HapticEffect { @@ -859,7 +871,7 @@ extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index); * autocenter will be disabled. To modify these values use SDL_HapticSetGain() * and SDL_HapticSetAutocenter(). * - * \param device_index index of the device to open + * \param device_index index of the device to open. * \returns the device identifier or NULL on failure; call SDL_GetError() for * more information. * @@ -879,7 +891,7 @@ extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index); /** * Check if the haptic device at the designated index has been opened. * - * \param device_index the index of the device to query + * \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. * @@ -893,7 +905,7 @@ extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index); /** * Get the index of a haptic device. * - * \param haptic the SDL_Haptic device to query + * \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. * @@ -931,7 +943,7 @@ extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void); /** * Query if a joystick has haptic features. * - * \param joystick the SDL_Joystick to test for haptic capabilities + * \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. @@ -953,7 +965,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick); * device will also get unallocated and you'll be unable to use force feedback * on that device. * - * \param joystick the SDL_Joystick to create a haptic device from + * \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. * @@ -969,7 +981,7 @@ extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick * /** * Close a haptic device previously opened with SDL_HapticOpen(). * - * \param haptic the SDL_Haptic device to close + * \param haptic the SDL_Haptic device to close. * * \since This function is available since SDL 2.0.0. * @@ -984,7 +996,7 @@ extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic); * approximation. Always check to see if your created effect was actually * created and do not rely solely on SDL_HapticNumEffects(). * - * \param haptic the SDL_Haptic device to query + * \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. * @@ -1000,7 +1012,7 @@ extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic); * * This is not supported on all platforms, but will always return a value. * - * \param haptic the SDL_Haptic device to query maximum playing effects + * \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. @@ -1015,7 +1027,7 @@ extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic); /** * Get the haptic device's supported features in bitwise manner. * - * \param haptic the SDL_Haptic device to query + * \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. * @@ -1033,7 +1045,7 @@ extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic); * The number of haptic axes might be useful if working with the * SDL_HapticDirection effect. * - * \param haptic the SDL_Haptic device to query + * \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. * @@ -1044,8 +1056,8 @@ extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic); /** * Check to see if an effect is supported by a haptic device. * - * \param haptic the SDL_Haptic device to query - * \param effect the desired effect to query + * \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. @@ -1062,9 +1074,9 @@ extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic, /** * Create a new haptic effect on a specified device. * - * \param haptic an SDL_Haptic device to create the effect on + * \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 + * 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. * @@ -1085,10 +1097,10 @@ extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic, * start playing from the start. You also cannot change the type either when * running SDL_HapticUpdateEffect(). * - * \param haptic the SDL_Haptic device that has the effect - * \param effect the identifier of the effect to update + * \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 + * properties to use. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1111,10 +1123,10 @@ extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic, * set the effect's `length` in its structure/union to `SDL_HAPTIC_INFINITY` * instead. * - * \param haptic the SDL_Haptic device to run the effect on - * \param effect the ID of the haptic effect to run + * \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 + * `SDL_HAPTIC_INFINITY` to repeat forever. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1133,8 +1145,8 @@ extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic, * * * * - * \param haptic the SDL_Haptic device to stop the effect on - * \param effect the ID of the haptic effect to stop + * \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. * @@ -1152,8 +1164,8 @@ extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic, * This will stop the effect if it's running. Effects are automatically * destroyed when the device is closed. * - * \param haptic the SDL_Haptic device to destroy the effect on - * \param effect the ID of the haptic effect to destroy + * \param haptic the SDL_Haptic device to destroy the effect on. + * \param effect the ID of the haptic effect to destroy. * * \since This function is available since SDL 2.0.0. * @@ -1167,8 +1179,8 @@ extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic, * * Device must support the SDL_HAPTIC_STATUS feature. * - * \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 + * \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. * @@ -1190,8 +1202,9 @@ extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic, * SDL_HapticSetGain() will scale linearly using `SDL_HAPTIC_GAIN_MAX` as the * maximum. * - * \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) + * \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. * @@ -1209,8 +1222,8 @@ extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain); * * Device must support the SDL_HAPTIC_AUTOCENTER feature. * - * \param haptic the SDL_Haptic device to set autocentering on - * \param autocenter value to set autocenter to (0-100) + * \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. * @@ -1230,7 +1243,7 @@ extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic, * Do not modify the effects nor add new ones while the device is paused. That * can cause all sorts of weird errors. * - * \param haptic the SDL_Haptic device to pause + * \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. * @@ -1245,7 +1258,7 @@ extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic); * * Call to unpause after SDL_HapticPause(). * - * \param haptic the SDL_Haptic device to unpause + * \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. * @@ -1258,7 +1271,7 @@ extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic); /** * Stop all the currently playing effects on a haptic device. * - * \param haptic the SDL_Haptic device to stop + * \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. * @@ -1269,7 +1282,7 @@ extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic); /** * Check whether rumble is supported on a haptic device. * - * \param haptic haptic device to check for rumble support + * \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. @@ -1285,7 +1298,7 @@ extern DECLSPEC int SDLCALL SDL_HapticRumbleSupported(SDL_Haptic * haptic); /** * Initialize a haptic device for simple rumble playback. * - * \param haptic the haptic device to initialize for simple rumble playback + * \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. * @@ -1301,9 +1314,9 @@ extern DECLSPEC int SDLCALL SDL_HapticRumbleInit(SDL_Haptic * haptic); /** * Run a simple rumble effect on a haptic device. * - * \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 + * \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. * @@ -1318,7 +1331,7 @@ extern DECLSPEC int SDLCALL SDL_HapticRumblePlay(SDL_Haptic * haptic, float stre /** * Stop the simple rumble on a haptic device. * - * \param haptic the haptic device to stop the rumble effect on + * \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. * diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_hidapi.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_hidapi.h @@ -19,44 +19,35 @@ 3. This notice may not be removed or altered from any source distribution. */ +/* WIKI CATEGORY: HIDAPI */ + /** - * \file SDL_hidapi.h - * - * Header file for SDL HIDAPI functions. - * - * This is an adaptation of the original HIDAPI interface by Alan Ott, - * and includes source code licensed under the following BSD license: - * - Copyright (c) 2010, Alan Ott, Signal 11 Software - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright notice, - this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - * Neither the name of Signal 11 Software nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE - LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS - INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. + * # CategoryHIDAPI + * + * Header file for SDL HIDAPI functions. + * + * This is an adaptation of the original HIDAPI interface by Alan Ott, and + * includes source code licensed under the following license: + * + * ``` + * HIDAPI - Multi-Platform library for + * communication with HID devices. + * + * Copyright 2009, Alan Ott, Signal 11 Software. + * All Rights Reserved. + * + * This software may be used by anyone for any reason so + * long as the copyright notice in the source files + * remains intact. + * ``` + * + * (Note that this license is the same as item three of SDL's zlib license, so + * it adds no new requirements on the user.) * * If you would like a version of SDL without this code, you can build SDL - * with SDL_HIDAPI_DISABLED defined to 1. You might want to do this for example - * on iOS or tvOS to avoid a dependency on the CoreBluetooth framework. + * with SDL_HIDAPI_DISABLED defined to 1. You might want to do this for + * example on iOS or tvOS to avoid a dependency on the CoreBluetooth + * framework. */ #ifndef SDL_hidapi_h_ @@ -71,14 +62,15 @@ extern "C" { #endif /** - * \brief A handle representing an open HID device + * A handle representing an open HID device */ struct SDL_hid_device_; typedef struct SDL_hid_device_ SDL_hid_device; /**< opaque hidapi structure */ /** hidapi info structure */ + /** - * \brief Information about a connected HID device + * Information about a connected HID device */ typedef struct SDL_hid_device_info { @@ -234,13 +226,13 @@ extern DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_id, * The path name be determined by calling SDL_hid_enumerate(), or a * platform-specific path name can be used (eg: /dev/hidraw0 on Linux). * - * \param path The path name of the device to open + * \param path The path name of the device to open. * \returns a pointer to a SDL_hid_device object on success or NULL on * failure. * * \since This function is available since SDL 2.0.18. */ -extern DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path, int bExclusive /* = false */); +extern DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path, int bExclusive); /** * Write an Output report to a HID device. @@ -434,7 +426,7 @@ extern DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev, int /** * Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers * - * \param active SDL_TRUE to start the scan, SDL_FALSE to stop the scan + * \param active SDL_TRUE to start the scan, SDL_FALSE to stop the scan. * * \since This function is available since SDL 2.0.18. */ diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_hints.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_hints.h @@ -20,20 +20,20 @@ */ /** - * \file SDL_hints.h + * # CategoryHints * - * Official documentation for SDL configuration variables + * Official documentation for SDL configuration variables * - * This file contains functions to set and get configuration hints, - * as well as listing each of them alphabetically. + * This file contains functions to set and get configuration hints, as well as + * listing each of them alphabetically. * - * The convention for naming hints is SDL_HINT_X, where "SDL_X" is - * the environment variable that can be used to override the default. + * The convention for naming hints is SDL_HINT_X, where "SDL_X" is the + * environment variable that can be used to override the default. * - * In general these hints are just that - they may or may not be - * supported or applicable on any given platform, but they provide - * a way for an application or user to give the library a hint as - * to how they would like the library to work. + * In general these hints are just that - they may or may not be supported or + * applicable on any given platform, but they provide a way for an application + * or user to give the library a hint as to how they would like the library to + * work. */ #ifndef SDL_hints_h_ @@ -48,110 +48,132 @@ extern "C" { #endif /** - * \brief A variable controlling whether the Android / iOS built-in - * accelerometer should be listed as a joystick device. + * A variable controlling whether the Android / iOS built-in accelerometer + * should be listed as a joystick device. * - * This variable can be set to the following values: - * "0" - The accelerometer is not listed as a joystick - * "1" - The accelerometer is available as a 3 axis joystick (the default). + * This variable can be set to the following values: + * + * - "0": The accelerometer is not listed as a joystick + * - "1": The accelerometer is available as a 3 axis joystick (the default). */ #define SDL_HINT_ACCELEROMETER_AS_JOYSTICK "SDL_ACCELEROMETER_AS_JOYSTICK" /** - * \brief Specify the behavior of Alt+Tab while the keyboard is grabbed. + * Specify the behavior of Alt+Tab while the keyboard is grabbed. * - * By default, SDL emulates Alt+Tab functionality while the keyboard is grabbed - * and your window is full-screen. This prevents the user from getting stuck in - * your application if you've enabled keyboard grab. + * By default, SDL emulates Alt+Tab functionality while the keyboard is + * grabbed and your window is full-screen. This prevents the user from getting + * stuck in your application if you've enabled keyboard grab. * * The variable can be set to the following values: - * "0" - SDL will not handle Alt+Tab. Your application is responsible - for handling Alt+Tab while the keyboard is grabbed. - * "1" - SDL will minimize your window when Alt+Tab is pressed (default) -*/ + * + * - "0": SDL will not handle Alt+Tab. Your application is responsible for + * handling Alt+Tab while the keyboard is grabbed. + * - "1": SDL will minimize your window when Alt+Tab is pressed (default) + */ #define SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED "SDL_ALLOW_ALT_TAB_WHILE_GRABBED" /** - * \brief If set to "0" then never set the top most bit on a SDL Window, even if the video mode expects it. - * This is a debugging aid for developers and not expected to be used by end users. The default is "1" + * If set to "0" then never set the top most bit on a SDL Window, even if the + * video mode expects it. + * + * This is a debugging aid for developers and not expected to be used by end + * users. The default is "1" * - * This variable can be set to the following values: - * "0" - don't allow topmost - * "1" - allow topmost + * This variable can be set to the following values: + * + * - "0": don't allow topmost + * - "1": allow topmost */ #define SDL_HINT_ALLOW_TOPMOST "SDL_ALLOW_TOPMOST" /** - * \brief Android APK expansion main file version. Should be a string number like "1", "2" etc. + * Android APK expansion main file version. + * + * Should be a string number like "1", "2" etc. * - * Must be set together with SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION. + * Must be set together with + * SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION. * * If both hints were set then SDL_RWFromFile() will look into expansion files - * after a given relative path was not found in the internal storage and assets. + * after a given relative path was not found in the internal storage and + * assets. * - * By default this hint is not set and the APK expansion files are not searched. + * By default this hint is not set and the APK expansion files are not + * searched. */ #define SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION "SDL_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION" /** - * \brief Android APK expansion patch file version. Should be a string number like "1", "2" etc. + * Android APK expansion patch file version. + * + * Should be a string number like "1", "2" etc. * * Must be set together with SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION. * * If both hints were set then SDL_RWFromFile() will look into expansion files - * after a given relative path was not found in the internal storage and assets. + * after a given relative path was not found in the internal storage and + * assets. * - * By default this hint is not set and the APK expansion files are not searched. + * By default this hint is not set and the APK expansion files are not + * searched. */ #define SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION "SDL_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION" /** - * \brief A variable to control whether the event loop will block itself when the app is paused. + * A variable to control whether the event loop will block itself when the app + * is paused. * * The variable can be set to the following values: - * "0" - Non blocking. - * "1" - Blocking. (default) + * + * - "0": Non blocking. + * - "1": Blocking. (default) * * The value should be set before SDL is initialized. */ #define SDL_HINT_ANDROID_BLOCK_ON_PAUSE "SDL_ANDROID_BLOCK_ON_PAUSE" /** - * \brief A variable to control whether SDL will pause audio in background - * (Requires SDL_ANDROID_BLOCK_ON_PAUSE as "Non blocking") + * A variable to control whether SDL will pause audio in background (Requires + * SDL_ANDROID_BLOCK_ON_PAUSE as "Non blocking") * * The variable can be set to the following values: - * "0" - Non paused. - * "1" - Paused. (default) + * + * - "0": Non paused. + * - "1": Paused. (default) * * The value should be set before SDL is initialized. */ #define SDL_HINT_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO "SDL_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO" /** - * \brief A variable to control whether we trap the Android back button to handle it manually. - * This is necessary for the right mouse button to work on some Android devices, or - * to be able to trap the back button for use in your code reliably. If set to true, - * the back button will show up as an SDL_KEYDOWN / SDL_KEYUP pair with a keycode of - * SDL_SCANCODE_AC_BACK. + * A variable to control whether we trap the Android back button to handle it + * manually. + * + * This is necessary for the right mouse button to work on some Android + * devices, or to be able to trap the back button for use in your code + * reliably. If set to true, the back button will show up as an SDL_KEYDOWN / + * SDL_KEYUP pair with a keycode of SDL_SCANCODE_AC_BACK. * * The variable can be set to the following values: - * "0" - Back button will be handled as usual for system. (default) - * "1" - Back button will be trapped, allowing you to handle the key press - * manually. (This will also let right mouse click work on systems - * where the right mouse button functions as back.) * - * The value of this hint is used at runtime, so it can be changed at any time. + * - "0": Back button will be handled as usual for system. (default) + * - "1": Back button will be trapped, allowing you to handle the key press + * manually. (This will also let right mouse click work on systems where the + * right mouse button functions as back.) + * + * The value of this hint is used at runtime, so it can be changed at any + * time. */ #define SDL_HINT_ANDROID_TRAP_BACK_BUTTON "SDL_ANDROID_TRAP_BACK_BUTTON" /** - * \brief Specify an application name. + * Specify an application name. * * This hint lets you specify the application name sent to the OS when * required. For example, this will often appear in volume control applets for * audio streams, and in lists of applications which are inhibiting the - * screensaver. You should use a string that describes your program ("My Game + * screensaver. You should use a string that describes your program ("My Game * 2: The Revenge") * * Setting this to "" or leaving it unset will have SDL use a reasonable @@ -166,48 +188,51 @@ extern "C" { #define SDL_HINT_APP_NAME "SDL_APP_NAME" /** - * \brief A variable controlling whether controllers used with the Apple TV - * generate UI events. + * A variable controlling whether controllers used with the Apple TV generate + * UI events. * * When UI events are generated by controller input, the app will be - * backgrounded when the Apple TV remote's menu button is pressed, and when the - * pause or B buttons on gamepads are pressed. + * backgrounded when the Apple TV remote's menu button is pressed, and when + * the pause or B buttons on gamepads are pressed. * * More information about properly making use of controllers for the Apple TV * can be found here: * https://developer.apple.com/tvos/human-interface-guidelines/remote-and-controllers/ * - * This variable can be set to the following values: - * "0" - Controller input does not generate UI events (the default). - * "1" - Controller input generates UI events. + * This variable can be set to the following values: + * + * - "0": Controller input does not generate UI events (the default). + * - "1": Controller input generates UI events. */ #define SDL_HINT_APPLE_TV_CONTROLLER_UI_EVENTS "SDL_APPLE_TV_CONTROLLER_UI_EVENTS" /** - * \brief A variable controlling whether the Apple TV remote's joystick axes - * will automatically match the rotation of the remote. + * A variable controlling whether the Apple TV remote's joystick axes will + * automatically match the rotation of the remote. * - * This variable can be set to the following values: - * "0" - Remote orientation does not affect joystick axes (the default). - * "1" - Joystick axes are based on the orientation of the remote. + * This variable can be set to the following values: + * + * - "0": Remote orientation does not affect joystick axes (the default). + * - "1": Joystick axes are based on the orientation of the remote. */ #define SDL_HINT_APPLE_TV_REMOTE_ALLOW_ROTATION "SDL_APPLE_TV_REMOTE_ALLOW_ROTATION" /** - * \brief A variable controlling the audio category on iOS and Mac OS X + * A variable controlling the audio category on iOS and Mac OS X * - * This variable can be set to the following values: + * This variable can be set to the following values: * - * "ambient" - Use the AVAudioSessionCategoryAmbient audio category, will be muted by the phone mute switch (default) - * "playback" - Use the AVAudioSessionCategoryPlayback category + * - "ambient": Use the AVAudioSessionCategoryAmbient audio category, will be + * muted by the phone mute switch (default) + * - "playback": Use the AVAudioSessionCategoryPlayback category * - * For more information, see Apple's documentation: - * https://developer.apple.com/library/content/documentation/Audio/Conceptual/AudioSessionProgrammingGuide/AudioSessionCategoriesandModes/AudioSessionCategoriesandModes.html + * For more information, see Apple's documentation: + * https://developer.apple.com/library/content/documentation/Audio/Conceptual/AudioSessionProgrammingGuide/AudioSessionCategoriesandModes/AudioSessionCategoriesandModes.html */ #define SDL_HINT_AUDIO_CATEGORY "SDL_AUDIO_CATEGORY" /** - * \brief Specify an application name for an audio device. + * Specify an application name for an audio device. * * Some audio backends (such as PulseAudio) allow you to describe your audio * stream. Among other things, this description might show up in a system @@ -228,7 +253,7 @@ extern "C" { #define SDL_HINT_AUDIO_DEVICE_APP_NAME "SDL_AUDIO_DEVICE_APP_NAME" /** - * \brief Specify an application name for an audio device. + * Specify an application name for an audio device. * * Some audio backends (such as PulseAudio) allow you to describe your audio * stream. Among other things, this description might show up in a system @@ -249,11 +274,11 @@ extern "C" { #define SDL_HINT_AUDIO_DEVICE_STREAM_NAME "SDL_AUDIO_DEVICE_STREAM_NAME" /** - * \brief Specify an application role for an audio device. + * Specify an application role for an audio device. * * Some audio backends (such as Pipewire) allow you to describe the role of - * your audio stream. Among other things, this description might show up in - * a system control panel or software for displaying and manipulating media + * your audio stream. Among other things, this description might show up in a + * system control panel or software for displaying and manipulating media * playback/capture graphs. * * This hints lets you transmit that information to the OS. The contents of @@ -269,1168 +294,1384 @@ extern "C" { #define SDL_HINT_AUDIO_DEVICE_STREAM_ROLE "SDL_AUDIO_DEVICE_STREAM_ROLE" /** - * \brief A variable controlling speed/quality tradeoff of audio resampling. + * A variable controlling speed/quality tradeoff of audio resampling. * - * If available, SDL can use libsamplerate ( http://www.mega-nerd.com/SRC/ ) - * to handle audio resampling. There are different resampling modes available - * that produce different levels of quality, using more CPU. + * If available, SDL can use libsamplerate ( http://www.mega-nerd.com/SRC/ ) + * to handle audio resampling. There are different resampling modes available + * that produce different levels of quality, using more CPU. * - * If this hint isn't specified to a valid setting, or libsamplerate isn't - * available, SDL will use the default, internal resampling algorithm. + * If this hint isn't specified to a valid setting, or libsamplerate isn't + * available, SDL will use the default, internal resampling algorithm. * - * As of SDL 2.26, SDL_ConvertAudio() respects this hint when libsamplerate is available. + * As of SDL 2.26, SDL_ConvertAudio() respects this hint when libsamplerate is + * available. * - * This hint is currently only checked at audio subsystem initialization. + * This hint is currently only checked at audio subsystem initialization. * - * This variable can be set to the following values: + * This variable can be set to the following values: * - * "0" or "default" - Use SDL's internal resampling (Default when not set - low quality, fast) - * "1" or "fast" - Use fast, slightly higher quality resampling, if available - * "2" or "medium" - Use medium quality resampling, if available - * "3" or "best" - Use high quality resampling, if available + * - "0" or "default": Use SDL's internal resampling (Default when not set - + * low quality, fast) + * - "1" or "fast": Use fast, slightly higher quality resampling, if available + * - "2" or "medium": Use medium quality resampling, if available + * - "3" or "best": Use high quality resampling, if available */ #define SDL_HINT_AUDIO_RESAMPLING_MODE "SDL_AUDIO_RESAMPLING_MODE" /** - * \brief A variable controlling whether SDL updates joystick state when getting input events + * A variable controlling whether SDL updates joystick state when getting + * input events * - * This variable can be set to the following values: + * This variable can be set to the following values: * - * "0" - You'll call SDL_JoystickUpdate() manually - * "1" - SDL will automatically call SDL_JoystickUpdate() (default) + * - "0": You'll call SDL_JoystickUpdate() manually + * - "1": SDL will automatically call SDL_JoystickUpdate() (default) * - * This hint can be toggled on and off at runtime. + * This hint can be toggled on and off at runtime. */ #define SDL_HINT_AUTO_UPDATE_JOYSTICKS "SDL_AUTO_UPDATE_JOYSTICKS" /** - * \brief A variable controlling whether SDL updates sensor state when getting input events + * A variable controlling whether SDL updates sensor state when getting input + * events * - * This variable can be set to the following values: + * This variable can be set to the following values: * - * "0" - You'll call SDL_SensorUpdate() manually - * "1" - SDL will automatically call SDL_SensorUpdate() (default) + * - "0": You'll call SDL_SensorUpdate() manually + * - "1": SDL will automatically call SDL_SensorUpdate() (default) * - * This hint can be toggled on and off at runtime. + * This hint can be toggled on and off at runtime. */ #define SDL_HINT_AUTO_UPDATE_SENSORS "SDL_AUTO_UPDATE_SENSORS" /** - * \brief Prevent SDL from using version 4 of the bitmap header when saving BMPs. + * Prevent SDL from using version 4 of the bitmap header when saving BMPs. * - * The bitmap header version 4 is required for proper alpha channel support and - * SDL will use it when required. Should this not be desired, this hint can - * force the use of the 40 byte header version which is supported everywhere. + * The bitmap header version 4 is required for proper alpha channel support + * and SDL will use it when required. Should this not be desired, this hint + * can force the use of the 40 byte header version which is supported + * everywhere. * * The variable can be set to the following values: - * "0" - Surfaces with a colorkey or an alpha channel are saved to a - * 32-bit BMP file with an alpha mask. SDL will use the bitmap - * header version 4 and set the alpha mask accordingly. - * "1" - Surfaces with a colorkey or an alpha channel are saved to a - * 32-bit BMP file without an alpha mask. The alpha channel data - * will be in the file, but applications are going to ignore it. + * + * - "0": Surfaces with a colorkey or an alpha channel are saved to a 32-bit + * BMP file with an alpha mask. SDL will use the bitmap header version 4 and + * set the alpha mask accordingly. + * - "1": Surfaces with a colorkey or an alpha channel are saved to a 32-bit + * BMP file without an alpha mask. The alpha channel data will be in the + * file, but applications are going to ignore it. * * The default value is "0". */ #define SDL_HINT_BMP_SAVE_LEGACY_FORMAT "SDL_BMP_SAVE_LEGACY_FORMAT" /** - * \brief Override for SDL_GetDisplayUsableBounds() + * Override for SDL_GetDisplayUsableBounds() * - * If set, this hint will override the expected results for - * SDL_GetDisplayUsableBounds() for display index 0. Generally you don't want - * to do this, but this allows an embedded system to request that some of the - * screen be reserved for other uses when paired with a well-behaved - * application. + * If set, this hint will override the expected results for + * SDL_GetDisplayUsableBounds() for display index 0. Generally you don't want + * to do this, but this allows an embedded system to request that some of the + * screen be reserved for other uses when paired with a well-behaved + * application. * - * The contents of this hint must be 4 comma-separated integers, the first - * is the bounds x, then y, width and height, in that order. + * The contents of this hint must be 4 comma-separated integers, the first is + * the bounds x, then y, width and height, in that order. */ #define SDL_HINT_DISPLAY_USABLE_BOUNDS "SDL_DISPLAY_USABLE_BOUNDS" /** - * \brief Disable giving back control to the browser automatically - * when running with asyncify + * Disable giving back control to the browser automatically when running with + * asyncify * - * With -s ASYNCIFY, SDL2 calls emscripten_sleep during operations - * such as refreshing the screen or polling events. + * With -s ASYNCIFY, SDL2 calls emscripten_sleep during operations such as + * refreshing the screen or polling events. * * This hint only applies to the emscripten platform * * The variable can be set to the following values: - * "0" - Disable emscripten_sleep calls (if you give back browser control manually or use asyncify for other purposes) - * "1" - Enable emscripten_sleep calls (the default) + * + * - "0": Disable emscripten_sleep calls (if you give back browser control + * manually or use asyncify for other purposes) + * - "1": Enable emscripten_sleep calls (the default) */ #define SDL_HINT_EMSCRIPTEN_ASYNCIFY "SDL_EMSCRIPTEN_ASYNCIFY" /** - * \brief override the binding element for keyboard inputs for Emscripten builds + * override the binding element for keyboard inputs for Emscripten builds * - * This hint only applies to the emscripten platform + * This hint only applies to the emscripten platform. * - * The variable can be one of - * "#window" - The javascript window object (this is the default) - * "#document" - The javascript document object - * "#screen" - the javascript window.screen object - * "#canvas" - the WebGL canvas element - * any other string without a leading # sign applies to the element on the page with that ID. - */ -#define SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT "SDL_EMSCRIPTEN_KEYBOARD_ELEMENT" - -/** - * \brief A variable that controls whether the on-screen keyboard should be shown when text input is active + * The variable can be one of: * - * The variable can be set to the following values: - * "0" - Do not show the on-screen keyboard - * "1" - Show the on-screen keyboard + * - "#window": the javascript window object (this is the default) + * - "#document": the javascript document object + * - "#screen": the javascript window.screen object + * - "#canvas": the WebGL canvas element * - * The default value is "1". This hint must be set before text input is activated. + * Any other string without a leading # sign applies to the element on the + * page with that ID. */ -#define SDL_HINT_ENABLE_SCREEN_KEYBOARD "SDL_ENABLE_SCREEN_KEYBOARD" +#define SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT "SDL_EMSCRIPTEN_KEYBOARD_ELEMENT" /** - * \brief A variable that controls whether Steam Controllers should be exposed using the SDL joystick and game controller APIs + * A variable that controls whether the on-screen keyboard should be shown + * when text input is active + * + * The variable can be set to the following values: * - * The variable can be set to the following values: - * "0" - Do not scan for Steam Controllers - * "1" - Scan for Steam Controllers (the default) + * - "0": Do not show the on-screen keyboard + * - "1": Show the on-screen keyboard * - * The default value is "1". This hint must be set before initializing the joystick subsystem. + * The default value is "1". This hint must be set before text input is + * activated. */ -#define SDL_HINT_ENABLE_STEAM_CONTROLLERS "SDL_ENABLE_STEAM_CONTROLLERS" +#define SDL_HINT_ENABLE_SCREEN_KEYBOARD "SDL_ENABLE_SCREEN_KEYBOARD" /** - * \brief A variable controlling verbosity of the logging of SDL events pushed onto the internal queue. + * A variable controlling verbosity of the logging of SDL events pushed onto + * the internal queue. * - * This variable can be set to the following values, from least to most verbose: + * This variable can be set to the following values, from least to most + * verbose: * - * "0" - Don't log any events (default) - * "1" - Log most events (other than the really spammy ones). - * "2" - Include mouse and finger motion events. - * "3" - Include SDL_SysWMEvent events. + * - "0": Don't log any events (default) + * - "1": Log most events (other than the really spammy ones). + * - "2": Include mouse and finger motion events. + * - "3": Include SDL_SysWMEvent events. * - * This is generally meant to be used to debug SDL itself, but can be useful - * for application developers that need better visibility into what is going - * on in the event queue. Logged events are sent through SDL_Log(), which - * means by default they appear on stdout on most platforms or maybe - * OutputDebugString() on Windows, and can be funneled by the app with - * SDL_LogSetOutputFunction(), etc. + * This is generally meant to be used to debug SDL itself, but can be useful + * for application developers that need better visibility into what is going + * on in the event queue. Logged events are sent through SDL_Log(), which + * means by default they appear on stdout on most platforms or maybe + * OutputDebugString() on Windows, and can be funneled by the app with + * SDL_LogSetOutputFunction(), etc. * - * This hint can be toggled on and off at runtime, if you only need to log - * events for a small subset of program execution. + * This hint can be toggled on and off at runtime, if you only need to log + * events for a small subset of program execution. */ #define SDL_HINT_EVENT_LOGGING "SDL_EVENT_LOGGING" /** - * \brief A variable controlling whether raising the window should be done more forcefully + * A variable controlling whether raising the window should be done more + * forcefully + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - No forcing (the default) - * "1" - Extra level of forcing + * - "0": No forcing (the default) + * - "1": Extra level of forcing * - * At present, this is only an issue under MS Windows, which makes it nearly impossible to - * programmatically move a window to the foreground, for "security" reasons. See - * http://stackoverflow.com/a/34414846 for a discussion. + * At present, this is only an issue under MS Windows, which makes it nearly + * impossible to programmatically move a window to the foreground, for + * "security" reasons. See http://stackoverflow.com/a/34414846 for a + * discussion. */ #define SDL_HINT_FORCE_RAISEWINDOW "SDL_HINT_FORCE_RAISEWINDOW" /** - * \brief A variable controlling how 3D acceleration is used to accelerate the SDL screen surface. + * A variable controlling how 3D acceleration is used to accelerate the SDL + * screen surface. + * + * SDL can try to accelerate the SDL screen surface by using streaming + * textures with a 3D rendering engine. This variable controls whether and how + * this is done. * - * SDL can try to accelerate the SDL screen surface by using streaming - * textures with a 3D rendering engine. This variable controls whether and - * how this is done. + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Disable 3D acceleration - * "1" - Enable 3D acceleration, using the default renderer. - * "X" - Enable 3D acceleration, using X where X is one of the valid rendering drivers. (e.g. "direct3d", "opengl", etc.) + * - "0": Disable 3D acceleration + * - "1": Enable 3D acceleration, using the default renderer. + * - "X": Enable 3D acceleration, using X where X is one of the valid + * rendering drivers. (e.g. "direct3d", "opengl", etc.) * - * By default SDL tries to make a best guess for each platform whether - * to use acceleration or not. + * By default SDL tries to make a best guess for each platform whether to use + * acceleration or not. */ #define SDL_HINT_FRAMEBUFFER_ACCELERATION "SDL_FRAMEBUFFER_ACCELERATION" /** - * \brief A variable that lets you manually hint extra gamecontroller db entries. + * A variable that lets you manually hint extra gamecontroller db entries. * - * The variable should be newline delimited rows of gamecontroller config data, see SDL_gamecontroller.h + * The variable should be newline delimited rows of gamecontroller config + * data, see SDL_gamecontroller.h * - * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) - * You can update mappings after the system is initialized with SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping() + * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) You + * can update mappings after the system is initialized with + * SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping() */ #define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG" /** - * \brief A variable that lets you provide a file with extra gamecontroller db entries. + * A variable that lets you provide a file with extra gamecontroller db + * entries. * - * The file should contain lines of gamecontroller config data, see SDL_gamecontroller.h + * The file should contain lines of gamecontroller config data, see + * SDL_gamecontroller.h * - * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) - * You can update mappings after the system is initialized with SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping() + * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) You + * can update mappings after the system is initialized with + * SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping() */ #define SDL_HINT_GAMECONTROLLERCONFIG_FILE "SDL_GAMECONTROLLERCONFIG_FILE" /** - * \brief A variable that overrides the automatic controller type detection + * A variable that overrides the automatic controller type detection * - * The variable should be comma separated entries, in the form: VID/PID=type + * The variable should be comma separated entries, in the form: VID/PID=type * - * The VID and PID should be hexadecimal with exactly 4 digits, e.g. 0x00fd + * The VID and PID should be hexadecimal with exactly 4 digits, e.g. 0x00fd * - * The type should be one of: - * Xbox360 - * XboxOne - * PS3 - * PS4 - * PS5 - * SwitchPro + * The type should be one of: Xbox360 XboxOne PS3 PS4 PS5 SwitchPro * - * This hint affects what driver is used, and must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) + * This hint affects what driver is used, and must be set before calling + * SDL_Init(SDL_INIT_GAMECONTROLLER) */ #define SDL_HINT_GAMECONTROLLERTYPE "SDL_GAMECONTROLLERTYPE" /** - * \brief A variable containing a list of devices to skip when scanning for game controllers. + * A variable containing a list of devices to skip when scanning for game + * controllers. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES "SDL_GAMECONTROLLER_IGNORE_DEVICES" /** - * \brief If set, all devices will be skipped when scanning for game controllers except for the ones listed in this variable. + * If set, all devices will be skipped when scanning for game controllers + * except for the ones listed in this variable. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT" /** - * \brief If set, game controller face buttons report their values according to their labels instead of their positional layout. + * If set, game controller face buttons report their values according to their + * labels instead of their positional layout. * - * For example, on Nintendo Switch controllers, normally you'd get: + * For example, on Nintendo Switch controllers, normally you'd get: * + * ``` * (Y) * (X) (B) * (A) + * ``` * - * but if this hint is set, you'll get: + * but if this hint is set, you'll get: * + * ``` * (X) * (Y) (A) * (B) + * ``` * - * The variable can be set to the following values: - * "0" - Report the face buttons by position, as though they were on an Xbox controller. - * "1" - Report the face buttons by label instead of position + * The variable can be set to the following values: + * + * - "0": Report the face buttons by position, as though they were on an Xbox + * controller. + * - "1": Report the face buttons by label instead of position * - * The default value is "1". This hint may be set at any time. + * The default value is "1". This hint may be set at any time. */ #define SDL_HINT_GAMECONTROLLER_USE_BUTTON_LABELS "SDL_GAMECONTROLLER_USE_BUTTON_LABELS" /** - * \brief A variable controlling whether grabbing input grabs the keyboard + * A variable controlling whether grabbing input grabs the keyboard * - * This variable can be set to the following values: - * "0" - Grab will affect only the mouse - * "1" - Grab will affect mouse and keyboard + * This variable can be set to the following values: * - * By default SDL will not grab the keyboard so system shortcuts still work. + * - "0": Grab will affect only the mouse + * - "1": Grab will affect mouse and keyboard + * + * By default SDL will not grab the keyboard so system shortcuts still work. */ #define SDL_HINT_GRAB_KEYBOARD "SDL_GRAB_KEYBOARD" /** - * \brief A variable containing a list of devices to ignore in SDL_hid_enumerate() + * A variable containing a list of devices to ignore in SDL_hid_enumerate() * - * For example, to ignore the Shanwan DS3 controller and any Valve controller, you might - * have the string "0x2563/0x0523,0x28de/0x0000" + * For example, to ignore the Shanwan DS3 controller and any Valve controller, + * you might have the string "0x2563/0x0523,0x28de/0x0000" */ #define SDL_HINT_HIDAPI_IGNORE_DEVICES "SDL_HIDAPI_IGNORE_DEVICES" /** - * \brief A variable controlling whether the idle timer is disabled on iOS. + * A variable controlling whether the idle timer is disabled on iOS. + * + * When an iOS app does not receive touches for some time, the screen is + * dimmed automatically. For games where the accelerometer is the only input + * this is problematic. This functionality can be disabled by setting this + * hint. * - * When an iOS app does not receive touches for some time, the screen is - * dimmed automatically. For games where the accelerometer is the only input - * this is problematic. This functionality can be disabled by setting this - * hint. + * As of SDL 2.0.4, SDL_EnableScreenSaver() and SDL_DisableScreenSaver() + * accomplish the same thing on iOS. They should be preferred over this hint. * - * As of SDL 2.0.4, SDL_EnableScreenSaver() and SDL_DisableScreenSaver() - * accomplish the same thing on iOS. They should be preferred over this hint. + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Enable idle timer - * "1" - Disable idle timer + * - "0": Enable idle timer + * - "1": Disable idle timer */ #define SDL_HINT_IDLE_TIMER_DISABLED "SDL_IOS_IDLE_TIMER_DISABLED" /** - * \brief A variable to control whether certain IMEs should handle text editing internally instead of sending SDL_TEXTEDITING events. + * A variable to control whether certain IMEs should handle text editing + * internally instead of sending SDL_TEXTEDITING events. * * The variable can be set to the following values: - * "0" - SDL_TEXTEDITING events are sent, and it is the application's - * responsibility to render the text from these events and - * differentiate it somehow from committed text. (default) - * "1" - If supported by the IME then SDL_TEXTEDITING events are not sent, - * and text that is being composed will be rendered in its own UI. + * + * - "0": SDL_TEXTEDITING events are sent, and it is the application's + * responsibility to render the text from these events and differentiate it + * somehow from committed text. (default) + * - "1": If supported by the IME then SDL_TEXTEDITING events are not sent, + * and text that is being composed will be rendered in its own UI. */ #define SDL_HINT_IME_INTERNAL_EDITING "SDL_IME_INTERNAL_EDITING" /** - * \brief A variable to control whether certain IMEs should show native UI components (such as the Candidate List) instead of suppressing them. + * A variable to control whether certain IMEs should show native UI components + * (such as the Candidate List) instead of suppressing them. * * The variable can be set to the following values: - * "0" - Native UI components are not display. (default) - * "1" - Native UI components are displayed. + * + * - "0": Native UI components are not display. (default) + * - "1": Native UI components are displayed. */ #define SDL_HINT_IME_SHOW_UI "SDL_IME_SHOW_UI" /** - * \brief A variable to control if extended IME text support is enabled. - * If enabled then SDL_TextEditingExtEvent will be issued if the text would be truncated otherwise. - * Additionally SDL_TextInputEvent will be dispatched multiple times so that it is not truncated. + * A variable to control if extended IME text support is enabled. + * + * If enabled then SDL_TextEditingExtEvent will be issued if the text would be + * truncated otherwise. Additionally SDL_TextInputEvent will be dispatched + * multiple times so that it is not truncated. * * The variable can be set to the following values: - * "0" - Legacy behavior. Text can be truncated, no heap allocations. (default) - * "1" - Modern behavior. + * + * - "0": Legacy behavior. Text can be truncated, no heap allocations. + * (default) + * - "1": Modern behavior. */ #define SDL_HINT_IME_SUPPORT_EXTENDED_TEXT "SDL_IME_SUPPORT_EXTENDED_TEXT" /** - * \brief A variable controlling whether the home indicator bar on iPhone X - * should be hidden. + * A variable controlling whether the home indicator bar on iPhone X should be + * hidden. * - * This variable can be set to the following values: - * "0" - The indicator bar is not hidden (default for windowed applications) - * "1" - The indicator bar is hidden and is shown when the screen is touched (useful for movie playback applications) - * "2" - The indicator bar is dim and the first swipe makes it visible and the second swipe performs the "home" action (default for fullscreen applications) + * This variable can be set to the following values: + * + * - "0": The indicator bar is not hidden (default for windowed applications) + * - "1": The indicator bar is hidden and is shown when the screen is touched + * (useful for movie playback applications) + * - "2": The indicator bar is dim and the first swipe makes it visible and + * the second swipe performs the "home" action (default for fullscreen + * applications) */ #define SDL_HINT_IOS_HIDE_HOME_INDICATOR "SDL_IOS_HIDE_HOME_INDICATOR" /** - * \brief A variable that lets you enable joystick (and gamecontroller) events even when your app is in the background. + * A variable that lets you enable joystick (and gamecontroller) events even + * when your app is in the background. + * + * The variable can be set to the following values: * - * The variable can be set to the following values: - * "0" - Disable joystick & gamecontroller input events when the - * application is in the background. - * "1" - Enable joystick & gamecontroller input events when the - * application is in the background. + * - "0": Disable joystick & gamecontroller input events when the application + * is in the background. + * - "1": Enable joystick & gamecontroller input events when the application + * is in the background. * - * The default value is "0". This hint may be set at any time. + * The default value is "0". This hint may be set at any time. */ #define SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS "SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS" /** - * A variable containing a list of arcade stick style controllers. + * A variable containing a list of arcade stick style controllers. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES "SDL_JOYSTICK_ARCADESTICK_DEVICES" /** - * A variable containing a list of devices that are not arcade stick style controllers. This will override SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES and the built in device list. + * A variable containing a list of devices that are not arcade stick style + * controllers. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * This will override SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES and the built in + * device list. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED" /** - * A variable containing a list of devices that should not be considerd joysticks. + * A variable containing a list of devices that should not be considerd + * joysticks. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES "SDL_JOYSTICK_BLACKLIST_DEVICES" /** - * A variable containing a list of devices that should be considered joysticks. This will override SDL_HINT_JOYSTICK_BLACKLIST_DEVICES and the built in device list. + * A variable containing a list of devices that should be considered + * joysticks. + * + * This will override SDL_HINT_JOYSTICK_BLACKLIST_DEVICES and the built in + * device list. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED "SDL_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED" /** - * A variable containing a list of flightstick style controllers. + * A variable containing a list of flightstick style controllers. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES "SDL_JOYSTICK_FLIGHTSTICK_DEVICES" /** - * A variable containing a list of devices that are not flightstick style controllers. This will override SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES and the built in device list. + * A variable containing a list of devices that are not flightstick style + * controllers. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * This will override SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES and the built in + * device list. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED" /** - * A variable containing a list of devices known to have a GameCube form factor. + * A variable containing a list of devices known to have a GameCube form + * factor. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES "SDL_JOYSTICK_GAMECUBE_DEVICES" /** - * A variable containing a list of devices known not to have a GameCube form factor. This will override SDL_HINT_JOYSTICK_GAMECUBE_DEVICES and the built in device list. + * A variable containing a list of devices known not to have a GameCube form + * factor. + * + * This will override SDL_HINT_JOYSTICK_GAMECUBE_DEVICES and the built in + * device list. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED "SDL_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED" /** - * \brief A variable controlling whether the HIDAPI joystick drivers should be used. + * A variable controlling whether the HIDAPI joystick drivers should be used. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - HIDAPI drivers are not used - * "1" - HIDAPI drivers are used (the default) + * - "0": HIDAPI drivers are not used + * - "1": HIDAPI drivers are used (the default) * - * This variable is the default for all drivers, but can be overridden by the hints for specific drivers below. + * This variable is the default for all drivers, but can be overridden by the + * hints for specific drivers below. */ #define SDL_HINT_JOYSTICK_HIDAPI "SDL_JOYSTICK_HIDAPI" /** - * \brief A variable controlling whether the HIDAPI driver for Nintendo GameCube controllers should be used. + * A variable controlling whether the HIDAPI driver for Nintendo GameCube + * controllers should be used. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI */ #define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE "SDL_JOYSTICK_HIDAPI_GAMECUBE" /** - * \brief A variable controlling whether "low_frequency_rumble" and "high_frequency_rumble" is used to implement - * the GameCube controller's 3 rumble modes, Stop(0), Rumble(1), and StopHard(2) - * this is useful for applications that need full compatibility for things like ADSR envelopes. - * Stop is implemented by setting "low_frequency_rumble" to "0" and "high_frequency_rumble" ">0" - * Rumble is both at any arbitrary value, - * StopHard is implemented by setting both "low_frequency_rumble" and "high_frequency_rumble" to "0" + * A variable controlling whether "low_frequency_rumble" and + * "high_frequency_rumble" is used to implement the GameCube controller's 3 + * rumble modes, Stop(0), Rumble(1), and StopHard(2) this is useful for + * applications that need full compatibility for things like ADSR envelopes. * - * This variable can be set to the following values: - * "0" - Normal rumble behavior is behavior is used (default) - * "1" - Proper GameCube controller rumble behavior is used + * Stop is implemented by setting "low_frequency_rumble" to "0" and + * "high_frequency_rumble" ">0" Rumble is both at any arbitrary value, + * StopHard is implemented by setting both "low_frequency_rumble" and + * "high_frequency_rumble" to "0" * + * This variable can be set to the following values: + * + * - "0": Normal rumble behavior is behavior is used (default) + * - "1": Proper GameCube controller rumble behavior is used */ #define SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE "SDL_JOYSTICK_GAMECUBE_RUMBLE_BRAKE" /** - * \brief A variable controlling whether the HIDAPI driver for Nintendo Switch Joy-Cons should be used. - * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used - * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI - */ + * A variable controlling whether the HIDAPI driver for Nintendo Switch + * Joy-Cons should be used. + * + * This variable can be set to the following values: + * + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + */ #define SDL_HINT_JOYSTICK_HIDAPI_JOY_CONS "SDL_JOYSTICK_HIDAPI_JOY_CONS" /** - * \brief A variable controlling whether Nintendo Switch Joy-Con controllers will be combined into a single Pro-like controller when using the HIDAPI driver - * - * This variable can be set to the following values: - * "0" - Left and right Joy-Con controllers will not be combined and each will be a mini-gamepad - * "1" - Left and right Joy-Con controllers will be combined into a single controller (the default) - */ + * A variable controlling whether Nintendo Switch Joy-Con controllers will be + * combined into a single Pro-like controller when using the HIDAPI driver + * + * This variable can be set to the following values: + * + * - "0": Left and right Joy-Con controllers will not be combined and each + * will be a mini-gamepad + * - "1": Left and right Joy-Con controllers will be combined into a single + * controller (the default) + */ #define SDL_HINT_JOYSTICK_HIDAPI_COMBINE_JOY_CONS "SDL_JOYSTICK_HIDAPI_COMBINE_JOY_CONS" /** - * \brief A variable controlling whether Nintendo Switch Joy-Con controllers will be in vertical mode when using the HIDAPI driver - * - * This variable can be set to the following values: - * "0" - Left and right Joy-Con controllers will not be in vertical mode (the default) - * "1" - Left and right Joy-Con controllers will be in vertical mode - * - * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) - */ + * A variable controlling whether Nintendo Switch Joy-Con controllers will be + * in vertical mode when using the HIDAPI driver + * + * This variable can be set to the following values: + * + * - "0": Left and right Joy-Con controllers will not be in vertical mode (the + * default) + * - "1": Left and right Joy-Con controllers will be in vertical mode + * + * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) + */ #define SDL_HINT_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS "SDL_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS" /** - * \brief A variable controlling whether the HIDAPI driver for Amazon Luna controllers connected via Bluetooth should be used. - * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used - * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI - */ + * A variable controlling whether the HIDAPI driver for Amazon Luna + * controllers connected via Bluetooth should be used. + * + * This variable can be set to the following values: + * + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + */ #define SDL_HINT_JOYSTICK_HIDAPI_LUNA "SDL_JOYSTICK_HIDAPI_LUNA" /** - * \brief A variable controlling whether the HIDAPI driver for Nintendo Online classic controllers should be used. - * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used - * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI - */ + * A variable controlling whether the HIDAPI driver for Nintendo Online + * classic controllers should be used. + * + * This variable can be set to the following values: + * + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + */ #define SDL_HINT_JOYSTICK_HIDAPI_NINTENDO_CLASSIC "SDL_JOYSTICK_HIDAPI_NINTENDO_CLASSIC" /** - * \brief A variable controlling whether the HIDAPI driver for NVIDIA SHIELD controllers should be used. - * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used - * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI - */ + * A variable controlling whether the HIDAPI driver for NVIDIA SHIELD + * controllers should be used. + * + * This variable can be set to the following values: + * + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + */ #define SDL_HINT_JOYSTICK_HIDAPI_SHIELD "SDL_JOYSTICK_HIDAPI_SHIELD" /** - * \brief A variable controlling whether the HIDAPI driver for PS3 controllers should be used. + * A variable controlling whether the HIDAPI driver for PS3 controllers should + * be used. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI on macOS, and "0" on other platforms. + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI on macOS, and "0" on + * other platforms. * - * It is not possible to use this driver on Windows, due to limitations in the default drivers - * installed. See https://github.com/ViGEm/DsHidMini for an alternative driver on Windows. + * It is not possible to use this driver on Windows, due to limitations in the + * default drivers installed. See https://github.com/ViGEm/DsHidMini for an + * alternative driver on Windows. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS3 "SDL_JOYSTICK_HIDAPI_PS3" /** - * \brief A variable controlling whether the HIDAPI driver for PS4 controllers should be used. + * A variable controlling whether the HIDAPI driver for PS4 controllers should + * be used. * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used + * This variable can be set to the following values: + * + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI */ #define SDL_HINT_JOYSTICK_HIDAPI_PS4 "SDL_JOYSTICK_HIDAPI_PS4" /** - * \brief A variable controlling whether extended input reports should be used for PS4 controllers when using the HIDAPI driver. + * A variable controlling whether extended input reports should be used for + * PS4 controllers when using the HIDAPI driver. * - * This variable can be set to the following values: - * "0" - extended reports are not enabled (the default) - * "1" - extended reports + * This variable can be set to the following values: * - * Extended input reports allow rumble on Bluetooth PS4 controllers, but - * break DirectInput handling for applications that don't use SDL. + * - "0": extended reports are not enabled (the default) + * - "1": extended reports * - * Once extended reports are enabled, they can not be disabled without - * power cycling the controller. + * Extended input reports allow rumble on Bluetooth PS4 controllers, but break + * DirectInput handling for applications that don't use SDL. * - * For compatibility with applications written for versions of SDL prior - * to the introduction of PS5 controller support, this value will also - * control the state of extended reports on PS5 controllers when the - * SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE hint is not explicitly set. + * Once extended reports are enabled, they can not be disabled without power + * cycling the controller. + * + * For compatibility with applications written for versions of SDL prior to + * the introduction of PS5 controller support, this value will also control + * the state of extended reports on PS5 controllers when the + * SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE hint is not explicitly set. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE "SDL_JOYSTICK_HIDAPI_PS4_RUMBLE" /** - * \brief A variable controlling whether the HIDAPI driver for PS5 controllers should be used. + * A variable controlling whether the HIDAPI driver for PS5 controllers should + * be used. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI */ #define SDL_HINT_JOYSTICK_HIDAPI_PS5 "SDL_JOYSTICK_HIDAPI_PS5" /** - * \brief A variable controlling whether the player LEDs should be lit to indicate which player is associated with a PS5 controller. + * A variable controlling whether the player LEDs should be lit to indicate + * which player is associated with a PS5 controller. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - player LEDs are not enabled - * "1" - player LEDs are enabled (the default) + * - "0": player LEDs are not enabled + * - "1": player LEDs are enabled (the default) */ #define SDL_HINT_JOYSTICK_HIDAPI_PS5_PLAYER_LED "SDL_JOYSTICK_HIDAPI_PS5_PLAYER_LED" /** - * \brief A variable controlling whether extended input reports should be used for PS5 controllers when using the HIDAPI driver. + * A variable controlling whether extended input reports should be used for + * PS5 controllers when using the HIDAPI driver. * - * This variable can be set to the following values: - * "0" - extended reports are not enabled (the default) - * "1" - extended reports + * This variable can be set to the following values: + * + * - "0": extended reports are not enabled (the default) + * - "1": extended reports * - * Extended input reports allow rumble on Bluetooth PS5 controllers, but - * break DirectInput handling for applications that don't use SDL. + * Extended input reports allow rumble on Bluetooth PS5 controllers, but break + * DirectInput handling for applications that don't use SDL. * - * Once extended reports are enabled, they can not be disabled without - * power cycling the controller. + * Once extended reports are enabled, they can not be disabled without power + * cycling the controller. * - * For compatibility with applications written for versions of SDL prior - * to the introduction of PS5 controller support, this value defaults to - * the value of SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE. + * For compatibility with applications written for versions of SDL prior to + * the introduction of PS5 controller support, this value defaults to the + * value of SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE "SDL_JOYSTICK_HIDAPI_PS5_RUMBLE" /** - * \brief A variable controlling whether the HIDAPI driver for Google Stadia controllers should be used. + * A variable controlling whether the HIDAPI driver for Google Stadia + * controllers should be used. * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used + * This variable can be set to the following values: * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI */ #define SDL_HINT_JOYSTICK_HIDAPI_STADIA "SDL_JOYSTICK_HIDAPI_STADIA" /** - * \brief A variable controlling whether the HIDAPI driver for Bluetooth Steam Controllers should be used. + * A variable controlling whether the HIDAPI driver for Bluetooth Steam + * Controllers should be used. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used for Steam Controllers, which requires Bluetooth access - * and may prompt the user for permission on iOS and Android. + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used for Steam Controllers, which requires + * Bluetooth access and may prompt the user for permission on iOS and + * Android. * - * The default is "0" + * The default is "0" */ #define SDL_HINT_JOYSTICK_HIDAPI_STEAM "SDL_JOYSTICK_HIDAPI_STEAM" /** - * \brief A variable controlling whether the HIDAPI driver for the Steam Deck builtin controller should be used. + * A variable controlling whether the HIDAPI driver for the Steam Deck builtin + * controller should be used. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI */ #define SDL_HINT_JOYSTICK_HIDAPI_STEAMDECK "SDL_JOYSTICK_HIDAPI_STEAMDECK" /** - * \brief A variable controlling whether the HIDAPI driver for Nintendo Switch controllers should be used. + * A variable controlling whether the HIDAPI driver for Nintendo Switch + * controllers should be used. * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used + * This variable can be set to the following values: + * + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI */ #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH "SDL_JOYSTICK_HIDAPI_SWITCH" /** - * \brief A variable controlling whether the Home button LED should be turned on when a Nintendo Switch Pro controller is opened + * A variable controlling whether the Home button LED should be turned on when + * a Nintendo Switch Pro controller is opened + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - home button LED is turned off - * "1" - home button LED is turned on + * - "0": home button LED is turned off + * - "1": home button LED is turned on * - * By default the Home button LED state is not changed. This hint can also be set to a floating point value between 0.0 and 1.0 which controls the brightness of the Home button LED. + * By default the Home button LED state is not changed. This hint can also be + * set to a floating point value between 0.0 and 1.0 which controls the + * brightness of the Home button LED. */ #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_HOME_LED "SDL_JOYSTICK_HIDAPI_SWITCH_HOME_LED" /** - * \brief A variable controlling whether the Home button LED should be turned on when a Nintendo Switch Joy-Con controller is opened + * A variable controlling whether the Home button LED should be turned on when + * a Nintendo Switch Joy-Con controller is opened + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - home button LED is turned off - * "1" - home button LED is turned on + * - "0": home button LED is turned off + * - "1": home button LED is turned on * - * By default the Home button LED state is not changed. This hint can also be set to a floating point value between 0.0 and 1.0 which controls the brightness of the Home button LED. + * By default the Home button LED state is not changed. This hint can also be + * set to a floating point value between 0.0 and 1.0 which controls the + * brightness of the Home button LED. */ #define SDL_HINT_JOYSTICK_HIDAPI_JOYCON_HOME_LED "SDL_JOYSTICK_HIDAPI_JOYCON_HOME_LED" /** - * \brief A variable controlling whether the player LEDs should be lit to indicate which player is associated with a Nintendo Switch controller. + * A variable controlling whether the player LEDs should be lit to indicate + * which player is associated with a Nintendo Switch controller. * - * This variable can be set to the following values: - * "0" - player LEDs are not enabled - * "1" - player LEDs are enabled (the default) + * This variable can be set to the following values: + * + * - "0": player LEDs are not enabled + * - "1": player LEDs are enabled (the default) */ #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED "SDL_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED" /** - * \brief A variable controlling whether the HIDAPI driver for Nintendo Wii and Wii U controllers should be used. + * A variable controlling whether the HIDAPI driver for Nintendo Wii and Wii U + * controllers should be used. * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used + * This variable can be set to the following values: * - * This driver doesn't work with the dolphinbar, so the default is SDL_FALSE for now. + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used + * + * This driver doesn't work with the dolphinbar, so the default is SDL_FALSE + * for now. */ #define SDL_HINT_JOYSTICK_HIDAPI_WII "SDL_JOYSTICK_HIDAPI_WII" /** - * \brief A variable controlling whether the player LEDs should be lit to indicate which player is associated with a Wii controller. + * A variable controlling whether the player LEDs should be lit to indicate + * which player is associated with a Wii controller. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - player LEDs are not enabled - * "1" - player LEDs are enabled (the default) + * - "0": player LEDs are not enabled + * - "1": player LEDs are enabled (the default) */ #define SDL_HINT_JOYSTICK_HIDAPI_WII_PLAYER_LED "SDL_JOYSTICK_HIDAPI_WII_PLAYER_LED" /** - * \brief A variable controlling whether the HIDAPI driver for XBox controllers should be used. + * A variable controlling whether the HIDAPI driver for XBox controllers + * should be used. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used * - * The default is "0" on Windows, otherwise the value of SDL_HINT_JOYSTICK_HIDAPI + * The default is "0" on Windows, otherwise the value of + * SDL_HINT_JOYSTICK_HIDAPI */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX "SDL_JOYSTICK_HIDAPI_XBOX" /** - * \brief A variable controlling whether the HIDAPI driver for XBox 360 controllers should be used. + * A variable controlling whether the HIDAPI driver for XBox 360 controllers + * should be used. * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used + * This variable can be set to the following values: + * + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 "SDL_JOYSTICK_HIDAPI_XBOX_360" /** - * \brief A variable controlling whether the player LEDs should be lit to indicate which player is associated with an Xbox 360 controller. + * A variable controlling whether the player LEDs should be lit to indicate + * which player is associated with an Xbox 360 controller. * - * This variable can be set to the following values: - * "0" - player LEDs are not enabled - * "1" - player LEDs are enabled (the default) + * This variable can be set to the following values: + * + * - "0": player LEDs are not enabled + * - "1": player LEDs are enabled (the default) */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED "SDL_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED" /** - * \brief A variable controlling whether the HIDAPI driver for XBox 360 wireless controllers should be used. + * A variable controlling whether the HIDAPI driver for XBox 360 wireless + * controllers should be used. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_WIRELESS "SDL_JOYSTICK_HIDAPI_XBOX_360_WIRELESS" /** - * \brief A variable controlling whether the HIDAPI driver for XBox One controllers should be used. + * A variable controlling whether the HIDAPI driver for XBox One controllers + * should be used. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - HIDAPI driver is not used - * "1" - HIDAPI driver is used + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE "SDL_JOYSTICK_HIDAPI_XBOX_ONE" /** - * \brief A variable controlling whether the Home button LED should be turned on when an Xbox One controller is opened + * A variable controlling whether the Home button LED should be turned on when + * an Xbox One controller is opened * - * This variable can be set to the following values: - * "0" - home button LED is turned off - * "1" - home button LED is turned on + * This variable can be set to the following values: + * + * - "0": home button LED is turned off + * - "1": home button LED is turned on * - * By default the Home button LED state is not changed. This hint can also be set to a floating point value between 0.0 and 1.0 which controls the brightness of the Home button LED. The default brightness is 0.4. + * By default the Home button LED state is not changed. This hint can also be + * set to a floating point value between 0.0 and 1.0 which controls the + * brightness of the Home button LED. The default brightness is 0.4. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED "SDL_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED" /** - * A variable controlling whether IOKit should be used for controller handling. - * - * This variable can be set to the following values: - * "0" - IOKit is not used - * "1" - IOKit is used (the default) - */ + * A variable controlling whether IOKit should be used for controller + * handling. + * + * This variable can be set to the following values: + * + * - "0": IOKit is not used + * - "1": IOKit is used (the default) + */ #define SDL_HINT_JOYSTICK_IOKIT "SDL_JOYSTICK_IOKIT" /** - * A variable controlling whether GCController should be used for controller handling. - * - * This variable can be set to the following values: - * "0" - GCController is not used - * "1" - GCController is used (the default) - */ + * A variable controlling whether GCController should be used for controller + * handling. + * + * This variable can be set to the following values: + * + * - "0": GCController is not used + * - "1": GCController is used (the default) + */ #define SDL_HINT_JOYSTICK_MFI "SDL_JOYSTICK_MFI" /** - * \brief A variable controlling whether the RAWINPUT joystick drivers should be used for better handling XInput-capable devices. - * - * This variable can be set to the following values: - * "0" - RAWINPUT drivers are not used - * "1" - RAWINPUT drivers are used (the default) - */ + * A variable controlling whether the RAWINPUT joystick drivers should be used + * for better handling XInput-capable devices. + * + * This variable can be set to the following values: + * + * - "0": RAWINPUT drivers are not used + * - "1": RAWINPUT drivers are used (the default) + */ #define SDL_HINT_JOYSTICK_RAWINPUT "SDL_JOYSTICK_RAWINPUT" /** - * \brief A variable controlling whether the RAWINPUT driver should pull correlated data from XInput. - * - * This variable can be set to the following values: - * "0" - RAWINPUT driver will only use data from raw input APIs - * "1" - RAWINPUT driver will also pull data from XInput, providing - * better trigger axes, guide button presses, and rumble support - * for Xbox controllers - * - * The default is "1". This hint applies to any joysticks opened after setting the hint. - */ + * A variable controlling whether the RAWINPUT driver should pull correlated + * data from XInput. + * + * This variable can be set to the following values: + * + * - "0": RAWINPUT driver will only use data from raw input APIs + * - "1": RAWINPUT driver will also pull data from XInput, providing better + * trigger axes, guide button presses, and rumble support for Xbox + * controllers + * + * The default is "1". This hint applies to any joysticks opened after setting + * the hint. + */ #define SDL_HINT_JOYSTICK_RAWINPUT_CORRELATE_XINPUT "SDL_JOYSTICK_RAWINPUT_CORRELATE_XINPUT" /** - * \brief A variable controlling whether the ROG Chakram mice should show up as joysticks - * - * This variable can be set to the following values: - * "0" - ROG Chakram mice do not show up as joysticks (the default) - * "1" - ROG Chakram mice show up as joysticks - */ + * A variable controlling whether the ROG Chakram mice should show up as + * joysticks + * + * This variable can be set to the following values: + * + * - "0": ROG Chakram mice do not show up as joysticks (the default) + * - "1": ROG Chakram mice show up as joysticks + */ #define SDL_HINT_JOYSTICK_ROG_CHAKRAM "SDL_JOYSTICK_ROG_CHAKRAM" /** - * \brief A variable controlling whether a separate thread should be used - * for handling joystick detection and raw input messages on Windows - * - * This variable can be set to the following values: - * "0" - A separate thread is not used (the default) - * "1" - A separate thread is used for handling raw input messages - * - */ + * A variable controlling whether a separate thread should be used for + * handling joystick detection and raw input messages on Windows + * + * This variable can be set to the following values: + * + * - "0": A separate thread is not used (the default) + * - "1": A separate thread is used for handling raw input messages + */ #define SDL_HINT_JOYSTICK_THREAD "SDL_JOYSTICK_THREAD" /** - * A variable containing a list of throttle style controllers. + * A variable containing a list of throttle style controllers. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_THROTTLE_DEVICES "SDL_JOYSTICK_THROTTLE_DEVICES" /** - * A variable containing a list of devices that are not throttle style controllers. This will override SDL_HINT_JOYSTICK_THROTTLE_DEVICES and the built in device list. + * A variable containing a list of devices that are not throttle style + * controllers. + * + * This will override SDL_HINT_JOYSTICK_THROTTLE_DEVICES and the built in + * device list. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_THROTTLE_DEVICES_EXCLUDED "SDL_JOYSTICK_THROTTLE_DEVICES_EXCLUDED" /** - * \brief A variable controlling whether Windows.Gaming.Input should be used for controller handling. - * - * This variable can be set to the following values: - * "0" - WGI is not used - * "1" - WGI is used (the default) - */ + * A variable controlling whether Windows.Gaming.Input should be used for + * controller handling. + * + * This variable can be set to the following values: + * + * - "0": WGI is not used + * - "1": WGI is used (the default) + */ #define SDL_HINT_JOYSTICK_WGI "SDL_JOYSTICK_WGI" /** - * A variable containing a list of wheel style controllers. + * A variable containing a list of wheel style controllers. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_WHEEL_DEVICES "SDL_JOYSTICK_WHEEL_DEVICES" /** - * A variable containing a list of devices that are not wheel style controllers. This will override SDL_HINT_JOYSTICK_WHEEL_DEVICES and the built in device list. + * A variable containing a list of devices that are not wheel style + * controllers. + * + * This will override SDL_HINT_JOYSTICK_WHEEL_DEVICES and the built in device + * list. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_WHEEL_DEVICES_EXCLUDED "SDL_JOYSTICK_WHEEL_DEVICES_EXCLUDED" /** - * A variable containing a list of devices known to have all axes centered at zero. + * A variable containing a list of devices known to have all axes centered at + * zero. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_JOYSTICK_ZERO_CENTERED_DEVICES "SDL_JOYSTICK_ZERO_CENTERED_DEVICES" /** - * \brief Determines whether SDL enforces that DRM master is required in order - * to initialize the KMSDRM video backend. + * Determines whether SDL enforces that DRM master is required in order to + * initialize the KMSDRM video backend. * - * The DRM subsystem has a concept of a "DRM master" which is a DRM client that - * has the ability to set planes, set cursor, etc. When SDL is DRM master, it - * can draw to the screen using the SDL rendering APIs. Without DRM master, SDL - * is still able to process input and query attributes of attached displays, - * but it cannot change display state or draw to the screen directly. + * The DRM subsystem has a concept of a "DRM master" which is a DRM client + * that has the ability to set planes, set cursor, etc. When SDL is DRM + * master, it can draw to the screen using the SDL rendering APIs. Without DRM + * master, SDL is still able to process input and query attributes of attached + * displays, but it cannot change display state or draw to the screen + * directly. * - * In some cases, it can be useful to have the KMSDRM backend even if it cannot - * be used for rendering. An app may want to use SDL for input processing while - * using another rendering API (such as an MMAL overlay on Raspberry Pi) or - * using its own code to render to DRM overlays that SDL doesn't support. + * In some cases, it can be useful to have the KMSDRM backend even if it + * cannot be used for rendering. An app may want to use SDL for input + * processing while using another rendering API (such as an MMAL overlay on + * Raspberry Pi) or using its own code to render to DRM overlays that SDL + * doesn't support. * * This hint must be set before initializing the video subsystem. * * This variable can be set to the following values: - * "0" - SDL will allow usage of the KMSDRM backend without DRM master - * "1" - SDL Will require DRM master to use the KMSDRM backend (default) + * + * - "0": SDL will allow usage of the KMSDRM backend without DRM master + * - "1": SDL Will require DRM master to use the KMSDRM backend (default) */ #define SDL_HINT_KMSDRM_REQUIRE_DRM_MASTER "SDL_KMSDRM_REQUIRE_DRM_MASTER" /** - * \brief A comma separated list of devices to open as joysticks - * - * This variable is currently only used by the Linux joystick driver. - */ + * A comma separated list of devices to open as joysticks + * + * This variable is currently only used by the Linux joystick driver. + */ #define SDL_HINT_JOYSTICK_DEVICE "SDL_JOYSTICK_DEVICE" + /** - * \brief A variable controlling whether joysticks on Linux will always treat 'hat' axis inputs (ABS_HAT0X - ABS_HAT3Y) as 8-way digital hats without checking whether they may be analog. - * - * This variable can be set to the following values: - * "0" - Only map hat axis inputs to digital hat outputs if the input axes appear to actually be digital (the default) - * "1" - Always handle the input axes numbered ABS_HAT0X to ABS_HAT3Y as digital hats - */ + * A variable containing a list of devices and their desired number of haptic + * (force feedback) enabled axis. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form plus the number of desired axes, e.g. + * + * `0xAAAA/0xBBBB/1,0xCCCC/0xDDDD/3` + * + * This hint supports a "wildcard" device that will set the number of haptic + * axes on all initialized haptic devices which were not defined explicitly in + * this hint. + * + * `0xFFFF/0xFFFF/1` + * + * This hint should be set before a controller is opened. The number of haptic + * axes won't exceed the number of real axes found on the device. + */ +#define SDL_HINT_JOYSTICK_HAPTIC_AXES "SDL_JOYSTICK_HAPTIC_AXES" + +/** + * A variable controlling whether joysticks on Linux will always treat 'hat' + * axis inputs (ABS_HAT0X - ABS_HAT3Y) as 8-way digital hats without checking + * whether they may be analog. + * + * This variable can be set to the following values: + * + * - "0": Only map hat axis inputs to digital hat outputs if the input axes + * appear to actually be digital (the default) + * - "1": Always handle the input axes numbered ABS_HAT0X to ABS_HAT3Y as + * digital hats + */ #define SDL_HINT_LINUX_DIGITAL_HATS "SDL_LINUX_DIGITAL_HATS" /** - * \brief A variable controlling whether digital hats on Linux will apply deadzones to their underlying input axes or use unfiltered values. - * - * This variable can be set to the following values: - * "0" - Return digital hat values based on unfiltered input axis values - * "1" - Return digital hat values with deadzones on the input axes taken into account (the default) - */ + * A variable controlling whether digital hats on Linux will apply deadzones + * to their underlying input axes or use unfiltered values. + * + * This variable can be set to the following values: + * + * - "0": Return digital hat values based on unfiltered input axis values + * - "1": Return digital hat values with deadzones on the input axes taken + * into account (the default) + */ #define SDL_HINT_LINUX_HAT_DEADZONES "SDL_LINUX_HAT_DEADZONES" /** - * \brief A variable controlling whether to use the classic /dev/input/js* joystick interface or the newer /dev/input/event* joystick interface on Linux - * - * This variable can be set to the following values: - * "0" - Use /dev/input/event* - * "1" - Use /dev/input/js* - * - * By default the /dev/input/event* interfaces are used - */ + * A variable controlling whether to use the classic /dev/input/js* joystick + * interface or the newer /dev/input/event* joystick interface on Linux + * + * This variable can be set to the following values: + * + * - "0": Use /dev/input/event* + * - "1": Use /dev/input/js* + * + * By default the /dev/input/event* interfaces are used + */ #define SDL_HINT_LINUX_JOYSTICK_CLASSIC "SDL_LINUX_JOYSTICK_CLASSIC" /** - * \brief A variable controlling whether joysticks on Linux adhere to their HID-defined deadzones or return unfiltered values. - * - * This variable can be set to the following values: - * "0" - Return unfiltered joystick axis values (the default) - * "1" - Return axis values with deadzones taken into account - */ + * A variable controlling whether joysticks on Linux adhere to their + * HID-defined deadzones or return unfiltered values. + * + * This variable can be set to the following values: + * + * - "0": Return unfiltered joystick axis values (the default) + * - "1": Return axis values with deadzones taken into account + */ #define SDL_HINT_LINUX_JOYSTICK_DEADZONES "SDL_LINUX_JOYSTICK_DEADZONES" /** - * \brief A variable controlling the default SDL log levels. + * A variable controlling the default SDL log levels. * - * This variable is a comma separated set of category=level tokens that define the default logging levels for SDL applications. + * This variable is a comma separated set of category=level tokens that define + * the default logging levels for SDL applications. * - * The category can be a numeric category, one of "app", "error", "assert", "system", "audio", "video", "render", "input", "test", or `*` for any unspecified category. + * The category can be a numeric category, one of "app", "error", "assert", + * "system", "audio", "video", "render", "input", "test", or `*` for any + * unspecified category. * - * The level can be a numeric level, one of "verbose", "debug", "info", "warn", "error", "critical", or "quiet" to disable that category. + * The level can be a numeric level, one of "verbose", "debug", "info", + * "warn", "error", "critical", or "quiet" to disable that category. * - * You can omit the category if you want to set the logging level for all categories. + * You can omit the category if you want to set the logging level for all + * categories. * - * If this hint isn't set, the default log levels are equivalent to: - * "app=info,assert=warn,test=verbose,*=error" + * If this hint isn't set, the default log levels are equivalent to: + * "app=info,assert=warn,test=verbose,*=error" */ #define SDL_HINT_LOGGING "SDL_LOGGING" /** -* \brief When set don't force the SDL app to become a foreground process -* -* This hint only applies to Mac OS X. -* -*/ + * When set don't force the SDL app to become a foreground process + * + * This hint only applies to Mac OS X. + */ #define SDL_HINT_MAC_BACKGROUND_APP "SDL_MAC_BACKGROUND_APP" /** - * \brief A variable that determines whether ctrl+click should generate a right-click event on Mac + * A variable that determines whether ctrl+click should generate a right-click + * event on Mac * - * If present, holding ctrl while left clicking will generate a right click - * event when on Mac. + * If present, holding ctrl while left clicking will generate a right click + * event when on Mac. */ #define SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK "SDL_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK" /** - * \brief A variable controlling whether dispatching OpenGL context updates should block the dispatching thread until the main thread finishes processing + * A variable controlling whether dispatching OpenGL context updates should + * block the dispatching thread until the main thread finishes processing * - * This variable can be set to the following values: - * "0" - Dispatching OpenGL context updates will block the dispatching thread until the main thread finishes processing (default). - * "1" - Dispatching OpenGL context updates will allow the dispatching thread to continue execution. + * This variable can be set to the following values: * - * Generally you want the default, but if you have OpenGL code in a background thread on a Mac, and the main thread - * hangs because it's waiting for that background thread, but that background thread is also hanging because it's - * waiting for the main thread to do an update, this might fix your issue. + * - "0": Dispatching OpenGL context updates will block the dispatching thread + * until the main thread finishes processing (default). + * - "1": Dispatching OpenGL context updates will allow the dispatching thread + * to continue execution. * - * This hint only applies to macOS. + * Generally you want the default, but if you have OpenGL code in a background + * thread on a Mac, and the main thread hangs because it's waiting for that + * background thread, but that background thread is also hanging because it's + * waiting for the main thread to do an update, this might fix your issue. * - * This hint is available since SDL 2.24.0. + * This hint only applies to macOS. * + * This hint is available since SDL 2.24.0. */ #define SDL_HINT_MAC_OPENGL_ASYNC_DISPATCH "SDL_MAC_OPENGL_ASYNC_DISPATCH" /** - * \brief A variable setting the double click radius, in pixels. + * A variable setting the double click radius, in pixels. */ #define SDL_HINT_MOUSE_DOUBLE_CLICK_RADIUS "SDL_MOUSE_DOUBLE_CLICK_RADIUS" /** - * \brief A variable setting the double click time, in milliseconds. + * A variable setting the double click time, in milliseconds. */ #define SDL_HINT_MOUSE_DOUBLE_CLICK_TIME "SDL_MOUSE_DOUBLE_CLICK_TIME" /** - * \brief Allow mouse click events when clicking to focus an SDL window + * Allow mouse click events when clicking to focus an SDL window * - * This variable can be set to the following values: - * "0" - Ignore mouse clicks that activate a window - * "1" - Generate events for mouse clicks that activate a window + * This variable can be set to the following values: + * + * - "0": Ignore mouse clicks that activate a window + * - "1": Generate events for mouse clicks that activate a window * - * By default SDL will ignore mouse clicks that activate a window + * By default SDL will ignore mouse clicks that activate a window */ #define SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH "SDL_MOUSE_FOCUS_CLICKTHROUGH" /** - * \brief A variable setting the speed scale for mouse motion, in floating point, when the mouse is not in relative mode + * A variable setting the speed scale for mouse motion, in floating point, + * when the mouse is not in relative mode */ #define SDL_HINT_MOUSE_NORMAL_SPEED_SCALE "SDL_MOUSE_NORMAL_SPEED_SCALE" /** - * \brief A variable controlling whether relative mouse mode constrains the mouse to the center of the window + * A variable controlling whether relative mouse mode constrains the mouse to + * the center of the window + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Relative mouse mode constrains the mouse to the window - * "1" - Relative mouse mode constrains the mouse to the center of the window + * - "0": Relative mouse mode constrains the mouse to the window + * - "1": Relative mouse mode constrains the mouse to the center of the window * - * Constraining to the center of the window works better for FPS games and when the - * application is running over RDP. Constraining to the whole window works better - * for 2D games and increases the chance that the mouse will be in the correct - * position when using high DPI mice. + * Constraining to the center of the window works better for FPS games and + * when the application is running over RDP. Constraining to the whole window + * works better for 2D games and increases the chance that the mouse will be + * in the correct position when using high DPI mice. * - * By default SDL will constrain the mouse to the center of the window + * By default SDL will constrain the mouse to the center of the window */ #define SDL_HINT_MOUSE_RELATIVE_MODE_CENTER "SDL_MOUSE_RELATIVE_MODE_CENTER" /** - * \brief A variable controlling whether relative mouse mode is implemented using mouse warping + * A variable controlling whether relative mouse mode is implemented using + * mouse warping + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Relative mouse mode uses raw input - * "1" - Relative mouse mode uses mouse warping + * - "0": Relative mouse mode uses raw input + * - "1": Relative mouse mode uses mouse warping * - * By default SDL will use raw input for relative mouse mode + * By default SDL will use raw input for relative mouse mode */ #define SDL_HINT_MOUSE_RELATIVE_MODE_WARP "SDL_MOUSE_RELATIVE_MODE_WARP" /** - * \brief A variable controlling whether relative mouse motion is affected by renderer scaling + * A variable controlling whether relative mouse motion is affected by + * renderer scaling * - * This variable can be set to the following values: - * "0" - Relative motion is unaffected by DPI or renderer's logical size - * "1" - Relative motion is scaled according to DPI scaling and logical size + * This variable can be set to the following values: + * + * - "0": Relative motion is unaffected by DPI or renderer's logical size + * - "1": Relative motion is scaled according to DPI scaling and logical size * - * By default relative mouse deltas are affected by DPI and renderer scaling + * By default relative mouse deltas are affected by DPI and renderer scaling */ #define SDL_HINT_MOUSE_RELATIVE_SCALING "SDL_MOUSE_RELATIVE_SCALING" /** - * \brief A variable setting the scale for mouse motion, in floating point, when the mouse is in relative mode + * A variable setting the scale for mouse motion, in floating point, when the + * mouse is in relative mode */ #define SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE "SDL_MOUSE_RELATIVE_SPEED_SCALE" /** - * \brief A variable controlling whether the system mouse acceleration curve is used for relative mouse motion. + * A variable controlling whether the system mouse acceleration curve is used + * for relative mouse motion. * - * This variable can be set to the following values: - * "0" - Relative mouse motion will be unscaled (the default) - * "1" - Relative mouse motion will be scaled using the system mouse acceleration curve. + * This variable can be set to the following values: * - * If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will override the system speed scale. + * - "0": Relative mouse motion will be unscaled (the default) + * - "1": Relative mouse motion will be scaled using the system mouse + * acceleration curve. + * + * If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will override the + * system speed scale. */ #define SDL_HINT_MOUSE_RELATIVE_SYSTEM_SCALE "SDL_MOUSE_RELATIVE_SYSTEM_SCALE" /** - * \brief A variable controlling whether a motion event should be generated for mouse warping in relative mode. + * A variable controlling whether a motion event should be generated for mouse + * warping in relative mode. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Warping the mouse will not generate a motion event in relative mode - * "1" - Warping the mouse will generate a motion event in relative mode + * - "0": Warping the mouse will not generate a motion event in relative mode + * - "1": Warping the mouse will generate a motion event in relative mode * - * By default warping the mouse will not generate motion events in relative mode. This avoids the application having to filter out large relative motion due to warping. + * By default warping the mouse will not generate motion events in relative + * mode. This avoids the application having to filter out large relative + * motion due to warping. */ #define SDL_HINT_MOUSE_RELATIVE_WARP_MOTION "SDL_MOUSE_RELATIVE_WARP_MOTION" /** - * \brief A variable controlling whether the hardware cursor stays visible when relative mode is active. + * A variable controlling whether the hardware cursor stays visible when + * relative mode is active. * - * This variable can be set to the following values: - * "0" - The cursor will be hidden while relative mode is active (default) - * "1" - The cursor will remain visible while relative mode is active + * This variable can be set to the following values: "0" - The cursor will be + * hidden while relative mode is active (default) "1" - The cursor will remain + * visible while relative mode is active * - * Note that for systems without raw hardware inputs, relative mode is implemented using warping, so the hardware cursor will visibly warp between frames if this is enabled on those systems. + * Note that for systems without raw hardware inputs, relative mode is + * implemented using warping, so the hardware cursor will visibly warp between + * frames if this is enabled on those systems. */ #define SDL_HINT_MOUSE_RELATIVE_CURSOR_VISIBLE "SDL_MOUSE_RELATIVE_CURSOR_VISIBLE" @@ -1438,330 +1679,382 @@ extern "C" { * A variable controlling whether mouse events should generate synthetic touch * events * - * This variable can be set to the following values: - * "0" - Mouse events will not generate touch events (default for desktop platforms) - * "1" - Mouse events will generate touch events (default for mobile platforms, such as Android and iOS) + * This variable can be set to the following values: + * + * - "0": Mouse events will not generate touch events (default for desktop + * platforms) + * - "1": Mouse events will generate touch events (default for mobile + * platforms, such as Android and iOS) */ #define SDL_HINT_MOUSE_TOUCH_EVENTS "SDL_MOUSE_TOUCH_EVENTS" /** - * \brief A variable controlling whether the mouse is captured while mouse buttons are pressed + * A variable controlling whether the mouse is captured while mouse buttons + * are pressed * - * This variable can be set to the following values: - * "0" - The mouse is not captured while mouse buttons are pressed - * "1" - The mouse is captured while mouse buttons are pressed + * This variable can be set to the following values: + * + * - "0": The mouse is not captured while mouse buttons are pressed + * - "1": The mouse is captured while mouse buttons are pressed * - * By default the mouse is captured while mouse buttons are pressed so if the mouse is dragged - * outside the window, the application continues to receive mouse events until the button is - * released. + * By default the mouse is captured while mouse buttons are pressed so if the + * mouse is dragged outside the window, the application continues to receive + * mouse events until the button is released. */ #define SDL_HINT_MOUSE_AUTO_CAPTURE "SDL_MOUSE_AUTO_CAPTURE" /** - * \brief Tell SDL not to catch the SIGINT or SIGTERM signals. + * Tell SDL not to catch the SIGINT or SIGTERM signals. * - * This hint only applies to Unix-like platforms, and should set before - * any calls to SDL_Init() + * This hint only applies to Unix-like platforms, and should set before any + * calls to SDL_Init() * * The variable can be set to the following values: - * "0" - SDL will install a SIGINT and SIGTERM handler, and when it - * catches a signal, convert it into an SDL_QUIT event. - * "1" - SDL will not install a signal handler at all. + * + * - "0": SDL will install a SIGINT and SIGTERM handler, and when it catches a + * signal, convert it into an SDL_QUIT event. + * - "1": SDL will not install a signal handler at all. */ #define SDL_HINT_NO_SIGNAL_HANDLERS "SDL_NO_SIGNAL_HANDLERS" /** - * \brief A variable controlling what driver to use for OpenGL ES contexts. + * A variable controlling what driver to use for OpenGL ES contexts. * - * On some platforms, currently Windows and X11, OpenGL drivers may support - * creating contexts with an OpenGL ES profile. By default SDL uses these - * profiles, when available, otherwise it attempts to load an OpenGL ES - * library, e.g. that provided by the ANGLE project. This variable controls - * whether SDL follows this default behaviour or will always load an - * OpenGL ES library. + * On some platforms, currently Windows and X11, OpenGL drivers may support + * creating contexts with an OpenGL ES profile. By default SDL uses these + * profiles, when available, otherwise it attempts to load an OpenGL ES + * library, e.g. that provided by the ANGLE project. This variable controls + * whether SDL follows this default behaviour or will always load an OpenGL ES + * library. * - * Circumstances where this is useful include - * - Testing an app with a particular OpenGL ES implementation, e.g ANGLE, - * or emulator, e.g. those from ARM, Imagination or Qualcomm. - * - Resolving OpenGL ES function addresses at link time by linking with - * the OpenGL ES library instead of querying them at run time with - * SDL_GL_GetProcAddress(). + * Circumstances where this is useful include - Testing an app with a + * particular OpenGL ES implementation, e.g ANGLE, or emulator, e.g. those + * from ARM, Imagination or Qualcomm. - Resolving OpenGL ES function addresses + * at link time by linking with the OpenGL ES library instead of querying them + * at run time with SDL_GL_GetProcAddress(). * - * Caution: for an application to work with the default behaviour across - * different OpenGL drivers it must query the OpenGL ES function - * addresses at run time using SDL_GL_GetProcAddress(). + * Caution: for an application to work with the default behaviour across + * different OpenGL drivers it must query the OpenGL ES function addresses at + * run time using SDL_GL_GetProcAddress(). * - * This variable is ignored on most platforms because OpenGL ES is native - * or not supported. + * This variable is ignored on most platforms because OpenGL ES is native or + * not supported. * - * This variable can be set to the following values: - * "0" - Use ES profile of OpenGL, if available. (Default when not set.) - * "1" - Load OpenGL ES library using the default library names. + * This variable can be set to the following values: * + * - "0": Use ES profile of OpenGL, if available. (Default when not set.) + * - "1": Load OpenGL ES library using the default library names. */ #define SDL_HINT_OPENGL_ES_DRIVER "SDL_OPENGL_ES_DRIVER" /** - * \brief A variable controlling which orientations are allowed on iOS/Android. + * A variable controlling which orientations are allowed on iOS/Android. + * + * In some circumstances it is necessary to be able to explicitly control + * which UI orientations are allowed. * - * In some circumstances it is necessary to be able to explicitly control - * which UI orientations are allowed. + * This variable is a space delimited list of the following values: * - * This variable is a space delimited list of the following values: - * "LandscapeLeft", "LandscapeRight", "Portrait" "PortraitUpsideDown" + * - "LandscapeLeft" + * - "LandscapeRight" + * - "Portrait" + * - "PortraitUpsideDown" */ #define SDL_HINT_ORIENTATIONS "SDL_IOS_ORIENTATIONS" /** - * \brief A variable controlling the use of a sentinel event when polling the event queue + * A variable controlling the use of a sentinel event when polling the event + * queue * - * This variable can be set to the following values: - * "0" - Disable poll sentinels - * "1" - Enable poll sentinels + * This variable can be set to the following values: * - * When polling for events, SDL_PumpEvents is used to gather new events from devices. - * If a device keeps producing new events between calls to SDL_PumpEvents, a poll loop will - * become stuck until the new events stop. - * This is most noticeable when moving a high frequency mouse. + * - "0": Disable poll sentinels + * - "1": Enable poll sentinels * - * By default, poll sentinels are enabled. + * When polling for events, SDL_PumpEvents is used to gather new events from + * devices. If a device keeps producing new events between calls to + * SDL_PumpEvents, a poll loop will become stuck until the new events stop. + * This is most noticeable when moving a high frequency mouse. + * + * By default, poll sentinels are enabled. */ #define SDL_HINT_POLL_SENTINEL "SDL_POLL_SENTINEL" /** - * \brief Override for SDL_GetPreferredLocales() + * Override for SDL_GetPreferredLocales() * - * If set, this will be favored over anything the OS might report for the - * user's preferred locales. Changing this hint at runtime will not generate - * a SDL_LOCALECHANGED event (but if you can change the hint, you can push - * your own event, if you want). + * If set, this will be favored over anything the OS might report for the + * user's preferred locales. Changing this hint at runtime will not generate a + * SDL_LOCALECHANGED event (but if you can change the hint, you can push your + * own event, if you want). * - * The format of this hint is a comma-separated list of language and locale, - * combined with an underscore, as is a common format: "en_GB". Locale is - * optional: "en". So you might have a list like this: "en_GB,jp,es_PT" + * The format of this hint is a comma-separated list of language and locale, + * combined with an underscore, as is a common format: "en_GB". Locale is + * optional: "en". So you might have a list like this: "en_GB,jp,es_PT" */ #define SDL_HINT_PREFERRED_LOCALES "SDL_PREFERRED_LOCALES" /** - * \brief A variable describing the content orientation on QtWayland-based platforms. + * A variable describing the content orientation on QtWayland-based platforms. + * + * On QtWayland platforms, windows are rotated client-side to allow for custom + * transitions. In order to correctly position overlays (e.g. volume bar) and + * gestures (e.g. events view, close/minimize gestures), the system needs to + * know in which orientation the application is currently drawing its + * contents. * - * On QtWayland platforms, windows are rotated client-side to allow for custom - * transitions. In order to correctly position overlays (e.g. volume bar) and - * gestures (e.g. events view, close/minimize gestures), the system needs to - * know in which orientation the application is currently drawing its contents. + * This does not cause the window to be rotated or resized, the application + * needs to take care of drawing the content in the right orientation (the + * framebuffer is always in portrait mode). * - * This does not cause the window to be rotated or resized, the application - * needs to take care of drawing the content in the right orientation (the - * framebuffer is always in portrait mode). + * This variable can be one of the following values: * - * This variable can be one of the following values: - * "primary" (default), "portrait", "landscape", "inverted-portrait", "inverted-landscape" + * - "primary" (default) + * - "portrait" + * - "landscape" + * - "inverted-portrait" + * - "inverted-landscape" * - * Since SDL 2.0.22 this variable accepts a comma-separated list of values above. + * Since SDL 2.0.22 this variable accepts a comma-separated list of values + * above. */ #define SDL_HINT_QTWAYLAND_CONTENT_ORIENTATION "SDL_QTWAYLAND_CONTENT_ORIENTATION" /** - * \brief Flags to set on QtWayland windows to integrate with the native window manager. + * Flags to set on QtWayland windows to integrate with the native window + * manager. * - * On QtWayland platforms, this hint controls the flags to set on the windows. - * For example, on Sailfish OS "OverridesSystemGestures" disables swipe gestures. + * On QtWayland platforms, this hint controls the flags to set on the windows. + * For example, on Sailfish OS "OverridesSystemGestures" disables swipe + * gestures. * - * This variable is a space-separated list of the following values (empty = no flags): - * "OverridesSystemGestures", "StaysOnTop", "BypassWindowManager" + * This variable is a space-separated list of the following values (empty = no + * flags): + * + * - "OverridesSystemGestures" + * - "StaysOnTop" + * - "BypassWindowManager" */ #define SDL_HINT_QTWAYLAND_WINDOW_FLAGS "SDL_QTWAYLAND_WINDOW_FLAGS" /** - * \brief A variable controlling whether the 2D render API is compatible or efficient. - * - * This variable can be set to the following values: + * A variable controlling whether the 2D render API is compatible or + * efficient. * - * "0" - Don't use batching to make rendering more efficient. - * "1" - Use batching, but might cause problems if app makes its own direct OpenGL calls. + * This variable can be set to the following values: * - * Up to SDL 2.0.9, the render API would draw immediately when requested. Now - * it batches up draw requests and sends them all to the GPU only when forced - * to (during SDL_RenderPresent, when changing render targets, by updating a - * texture that the batch needs, etc). This is significantly more efficient, - * but it can cause problems for apps that expect to render on top of the - * render API's output. As such, SDL will disable batching if a specific - * render backend is requested (since this might indicate that the app is - * planning to use the underlying graphics API directly). This hint can - * be used to explicitly request batching in this instance. It is a contract - * that you will either never use the underlying graphics API directly, or - * if you do, you will call SDL_RenderFlush() before you do so any current - * batch goes to the GPU before your work begins. Not following this contract - * will result in undefined behavior. + * - "0": Don't use batching to make rendering more efficient. + * - "1": Use batching, but might cause problems if app makes its own direct + * OpenGL calls. + * + * Up to SDL 2.0.9, the render API would draw immediately when requested. Now + * it batches up draw requests and sends them all to the GPU only when forced + * to (during SDL_RenderPresent, when changing render targets, by updating a + * texture that the batch needs, etc). This is significantly more efficient, + * but it can cause problems for apps that expect to render on top of the + * render API's output. As such, SDL will disable batching if a specific + * render backend is requested (since this might indicate that the app is + * planning to use the underlying graphics API directly). This hint can be + * used to explicitly request batching in this instance. It is a contract that + * you will either never use the underlying graphics API directly, or if you + * do, you will call SDL_RenderFlush() before you do so any current batch goes + * to the GPU before your work begins. Not following this contract will result + * in undefined behavior. */ #define SDL_HINT_RENDER_BATCHING "SDL_RENDER_BATCHING" /** - * \brief A variable controlling how the 2D render API renders lines + * A variable controlling how the 2D render API renders lines * - * This variable can be set to the following values: - * "0" - Use the default line drawing method (Bresenham's line algorithm as of SDL 2.0.20) - * "1" - Use the driver point API using Bresenham's line algorithm (correct, draws many points) - * "2" - Use the driver line API (occasionally misses line endpoints based on hardware driver quirks, was the default before 2.0.20) - * "3" - Use the driver geometry API (correct, draws thicker diagonal lines) + * This variable can be set to the following values: + * + * - "0": Use the default line drawing method (Bresenham's line algorithm as + * of SDL 2.0.20) + * - "1": Use the driver point API using Bresenham's line algorithm (correct, + * draws many points) + * - "2": Use the driver line API (occasionally misses line endpoints based on + * hardware driver quirks, was the default before 2.0.20) + * - "3": Use the driver geometry API (correct, draws thicker diagonal lines) * - * This variable should be set when the renderer is created. + * This variable should be set when the renderer is created. */ #define SDL_HINT_RENDER_LINE_METHOD "SDL_RENDER_LINE_METHOD" /** - * \brief A variable controlling whether to enable Direct3D 11+'s Debug Layer. + * A variable controlling whether to enable Direct3D 11+'s Debug Layer. * - * This variable does not have any effect on the Direct3D 9 based renderer. + * This variable does not have any effect on the Direct3D 9 based renderer. * - * This variable can be set to the following values: - * "0" - Disable Debug Layer use - * "1" - Enable Debug Layer use + * This variable can be set to the following values: * - * By default, SDL does not use Direct3D Debug Layer. + * - "0": Disable Debug Layer use + * - "1": Enable Debug Layer use + * + * By default, SDL does not use Direct3D Debug Layer. */ #define SDL_HINT_RENDER_DIRECT3D11_DEBUG "SDL_RENDER_DIRECT3D11_DEBUG" /** - * \brief A variable controlling whether the Direct3D device is initialized for thread-safe operations. + * A variable controlling whether the Direct3D device is initialized for + * thread-safe operations. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Thread-safety is not enabled (faster) - * "1" - Thread-safety is enabled + * - "0": Thread-safety is not enabled (faster) + * - "1": Thread-safety is enabled * - * By default the Direct3D device is created with thread-safety disabled. + * By default the Direct3D device is created with thread-safety disabled. */ #define SDL_HINT_RENDER_DIRECT3D_THREADSAFE "SDL_RENDER_DIRECT3D_THREADSAFE" /** - * \brief A variable specifying which render driver to use. + * A variable specifying which render driver to use. * - * If the application doesn't pick a specific renderer to use, this variable - * specifies the name of the preferred renderer. If the preferred renderer - * can't be initialized, the normal default renderer is used. + * If the application doesn't pick a specific renderer to use, this variable + * specifies the name of the preferred renderer. If the preferred renderer + * can't be initialized, the normal default renderer is used. * - * This variable is case insensitive and can be set to the following values: - * "direct3d" - * "direct3d11" - * "direct3d12" - * "opengl" - * "opengles2" - * "opengles" - * "metal" - * "software" + * This variable is case insensitive and can be set to the following values: * - * The default varies by platform, but it's the first one in the list that - * is available on the current platform. + * - "direct3d" + * - "direct3d11" + * - "direct3d12" + * - "opengl" + * - "opengles2" + * - "opengles" + * - "metal" + * - "software" + * + * The default varies by platform, but it's the first one in the list that is + * available on the current platform. */ #define SDL_HINT_RENDER_DRIVER "SDL_RENDER_DRIVER" /** - * \brief A variable controlling the scaling policy for SDL_RenderSetLogicalSize. + * A variable controlling the scaling policy for SDL_RenderSetLogicalSize. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" or "letterbox" - Uses letterbox/sidebars to fit the entire rendering on screen - * "1" or "overscan" - Will zoom the rendering so it fills the entire screen, allowing edges to be drawn offscreen + * "0" or "letterbox" - Uses letterbox/sidebars to fit the entire rendering on + * screen "1" or "overscan" - Will zoom the rendering so it fills the entire + * screen, allowing edges to be drawn offscreen * - * By default letterbox is used + * By default letterbox is used */ #define SDL_HINT_RENDER_LOGICAL_SIZE_MODE "SDL_RENDER_LOGICAL_SIZE_MODE" /** - * \brief A variable controlling whether the OpenGL render driver uses shaders if they are available. + * A variable controlling whether the OpenGL render driver uses shaders if + * they are available. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Disable shaders - * "1" - Enable shaders + * - "0": Disable shaders + * - "1": Enable shaders * - * By default shaders are used if OpenGL supports them. + * By default shaders are used if OpenGL supports them. */ #define SDL_HINT_RENDER_OPENGL_SHADERS "SDL_RENDER_OPENGL_SHADERS" /** - * \brief A variable controlling the scaling quality + * A variable controlling the scaling quality * - * This variable can be set to the following values: - * "0" or "nearest" - Nearest pixel sampling - * "1" or "linear" - Linear filtering (supported by OpenGL and Direct3D) - * "2" or "best" - Currently this is the same as "linear" + * This variable can be set to the following values: + * + * - "0" or "nearest": Nearest pixel sampling + * - "1" or "linear": Linear filtering (supported by OpenGL and Direct3D) + * - "2" or "best": Currently this is the same as "linear" * - * By default nearest pixel sampling is used + * By default nearest pixel sampling is used */ #define SDL_HINT_RENDER_SCALE_QUALITY "SDL_RENDER_SCALE_QUALITY" /** - * \brief A variable controlling whether updates to the SDL screen surface should be synchronized with the vertical refresh, to avoid tearing. + * A variable controlling whether updates to the SDL screen surface should be + * synchronized with the vertical refresh, to avoid tearing. * - * This variable can be set to the following values: - * "0" - Disable vsync - * "1" - Enable vsync + * This variable can be set to the following values: * - * By default SDL does not sync screen surface updates with vertical refresh. + * - "0": Disable vsync + * - "1": Enable vsync + * + * By default SDL does not sync screen surface updates with vertical refresh. */ #define SDL_HINT_RENDER_VSYNC "SDL_RENDER_VSYNC" /** - * \brief A variable controlling whether the Metal render driver select low power device over default one + * A variable controlling whether the Metal render driver select low power + * device over default one + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Use the prefered OS device - * "1" - Select a low power one + * - "0": Use the prefered OS device + * - "1": Select a low power one * - * By default the prefered OS device is used. + * By default the prefered OS device is used. */ #define SDL_HINT_RENDER_METAL_PREFER_LOW_POWER_DEVICE "SDL_RENDER_METAL_PREFER_LOW_POWER_DEVICE" /** - * A variable containing a list of ROG gamepad capable mice. + * A variable containing a list of ROG gamepad capable mice. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_ROG_GAMEPAD_MICE "SDL_ROG_GAMEPAD_MICE" /** - * A variable containing a list of devices that are not ROG gamepad capable mice. This will override SDL_HINT_ROG_GAMEPAD_MICE and the built in device list. + * A variable containing a list of devices that are not ROG gamepad capable + * mice. * - * The format of the string is a comma separated list of USB VID/PID pairs - * in hexadecimal form, e.g. + * This will override SDL_HINT_ROG_GAMEPAD_MICE and the built in device list. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * The variable can also take the form of @file, in which case the named - * file will be loaded and interpreted as the value of the variable. + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. */ #define SDL_HINT_ROG_GAMEPAD_MICE_EXCLUDED "SDL_ROG_GAMEPAD_MICE_EXCLUDED" /** - * \brief A variable controlling if VSYNC is automatically disable if doesn't reach the enough FPS + * A variable controlling if VSYNC is automatically disable if doesn't reach + * the enough FPS + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - It will be using VSYNC as defined in the main flag. Default - * "1" - If VSYNC was previously enabled, then it will disable VSYNC if doesn't reach enough speed + * - "0": It will be using VSYNC as defined in the main flag. Default + * - "1": If VSYNC was previously enabled, then it will disable VSYNC if + * doesn't reach enough speed * - * By default SDL does not enable the automatic VSYNC + * By default SDL does not enable the automatic VSYNC */ #define SDL_HINT_PS2_DYNAMIC_VSYNC "SDL_PS2_DYNAMIC_VSYNC" /** - * \brief A variable to control whether the return key on the soft keyboard - * should hide the soft keyboard on Android and iOS. + * A variable to control whether the return key on the soft keyboard should + * hide the soft keyboard on Android and iOS. * * The variable can be set to the following values: - * "0" - The return key will be handled as a key event. This is the behaviour of SDL <= 2.0.3. (default) - * "1" - The return key will hide the keyboard. * - * The value of this hint is used at runtime, so it can be changed at any time. + * - "0": The return key will be handled as a key event. This is the behaviour + * of SDL <= 2.0.3. (default) + * - "1": The return key will hide the keyboard. + * + * The value of this hint is used at runtime, so it can be changed at any + * time. */ #define SDL_HINT_RETURN_KEY_HIDES_IME "SDL_RETURN_KEY_HIDES_IME" /** - * \brief Tell SDL which Dispmanx layer to use on a Raspberry PI + * Tell SDL which Dispmanx layer to use on a Raspberry PI * * Also known as Z-order. The variable can take a negative or positive value. * The default is 10000. @@ -1769,7 +2062,7 @@ extern "C" { #define SDL_HINT_RPI_VIDEO_LAYER "SDL_RPI_VIDEO_LAYER" /** - * \brief Specify an "activity name" for screensaver inhibition. + * Specify an "activity name" for screensaver inhibition. * * Some platforms, notably Linux desktops, list the applications which are * inhibiting the screensaver or other power-saving features. @@ -1778,7 +2071,7 @@ extern "C" { * SDL_DisableScreenSaver() is used (or the screensaver is automatically * disabled). The contents of this hint are used when the screensaver is * disabled. You should use a string that describes what your program is doing - * (and, therefore, why the screensaver is disabled). For example, "Playing a + * (and, therefore, why the screensaver is disabled). For example, "Playing a * game" or "Watching a video". * * Setting this to "" or leaving it unset will have SDL use a reasonable @@ -1789,125 +2082,140 @@ extern "C" { #define SDL_HINT_SCREENSAVER_INHIBIT_ACTIVITY_NAME "SDL_SCREENSAVER_INHIBIT_ACTIVITY_NAME" /** - * \brief Specifies whether SDL_THREAD_PRIORITY_TIME_CRITICAL should be treated as realtime. + * Specifies whether SDL_THREAD_PRIORITY_TIME_CRITICAL should be treated as + * realtime. + * + * On some platforms, like Linux, a realtime priority thread may be subject to + * restrictions that require special handling by the application. This hint + * exists to let SDL know that the app is prepared to handle said + * restrictions. * - * On some platforms, like Linux, a realtime priority thread may be subject to restrictions - * that require special handling by the application. This hint exists to let SDL know that - * the app is prepared to handle said restrictions. + * On Linux, SDL will apply the following configuration to any thread that + * becomes realtime: * - * On Linux, SDL will apply the following configuration to any thread that becomes realtime: - * * The SCHED_RESET_ON_FORK bit will be set on the scheduling policy, - * * An RLIMIT_RTTIME budget will be configured to the rtkit specified limit. - * * Exceeding this limit will result in the kernel sending SIGKILL to the app, - * * Refer to the man pages for more information. + * - The SCHED_RESET_ON_FORK bit will be set on the scheduling policy. + * - An RLIMIT_RTTIME budget will be configured to the rtkit specified limit. + * - Exceeding this limit will result in the kernel sending SIGKILL to the + * app. + * + * Refer to the man pages for more information. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - default platform specific behaviour - * "1" - Force SDL_THREAD_PRIORITY_TIME_CRITICAL to a realtime scheduling policy + * - "0": default platform specific behaviour + * - "1": Force SDL_THREAD_PRIORITY_TIME_CRITICAL to a realtime scheduling + * policy */ #define SDL_HINT_THREAD_FORCE_REALTIME_TIME_CRITICAL "SDL_THREAD_FORCE_REALTIME_TIME_CRITICAL" /** -* \brief A string specifying additional information to use with SDL_SetThreadPriority. -* -* By default SDL_SetThreadPriority will make appropriate system changes in order to -* apply a thread priority. For example on systems using pthreads the scheduler policy -* is changed automatically to a policy that works well with a given priority. -* Code which has specific requirements can override SDL's default behavior with this hint. -* -* pthread hint values are "current", "other", "fifo" and "rr". -* Currently no other platform hint values are defined but may be in the future. -* -* \note On Linux, the kernel may send SIGKILL to realtime tasks which exceed the distro -* configured execution budget for rtkit. This budget can be queried through RLIMIT_RTTIME -* after calling SDL_SetThreadPriority(). -*/ + * A string specifying additional information to use with + * SDL_SetThreadPriority. + * + * By default SDL_SetThreadPriority will make appropriate system changes in + * order to apply a thread priority. For example on systems using pthreads the + * scheduler policy is changed automatically to a policy that works well with + * a given priority. Code which has specific requirements can override SDL's + * default behavior with this hint. + * + * pthread hint values are "current", "other", "fifo" and "rr". Currently no + * other platform hint values are defined but may be in the future. + */ #define SDL_HINT_THREAD_PRIORITY_POLICY "SDL_THREAD_PRIORITY_POLICY" /** -* \brief A string specifying SDL's threads stack size in bytes or "0" for the backend's default size -* -* Use this hint in case you need to set SDL's threads stack size to other than the default. -* This is specially useful if you build SDL against a non glibc libc library (such as musl) which -* provides a relatively small default thread stack size (a few kilobytes versus the default 8MB glibc uses). -* Support for this hint is currently available only in the pthread, Windows, and PSP backend. -* -* Instead of this hint, in 2.0.9 and later, you can use -* SDL_CreateThreadWithStackSize(). This hint only works with the classic -* SDL_CreateThread(). -*/ + * A string specifying SDL's threads stack size in bytes or "0" for the + * backend's default size + * + * Use this hint in case you need to set SDL's threads stack size to other + * than the default. This is specially useful if you build SDL against a non + * glibc libc library (such as musl) which provides a relatively small default + * thread stack size (a few kilobytes versus the default 8MB glibc uses). + * Support for this hint is currently available only in the pthread, Windows, + * and PSP backend. + * + * Instead of this hint, in 2.0.9 and later, you can use + * SDL_CreateThreadWithStackSize(). This hint only works with the classic + * SDL_CreateThread(). + */ #define SDL_HINT_THREAD_STACK_SIZE "SDL_THREAD_STACK_SIZE" /** - * \brief A variable that controls the timer resolution, in milliseconds. + * A variable that controls the timer resolution, in milliseconds. * - * The higher resolution the timer, the more frequently the CPU services - * timer interrupts, and the more precise delays are, but this takes up - * power and CPU time. This hint is only used on Windows. + * The higher resolution the timer, the more frequently the CPU services timer + * interrupts, and the more precise delays are, but this takes up power and + * CPU time. This hint is only used on Windows. * - * See this blog post for more information: - * http://randomascii.wordpress.com/2013/07/08/windows-timer-resolution-megawatts-wasted/ + * See this blog post for more information: + * http://randomascii.wordpress.com/2013/07/08/windows-timer-resolution-megawatts-wasted/ * - * If this variable is set to "0", the system timer resolution is not set. + * If this variable is set to "0", the system timer resolution is not set. * - * The default value is "1". This hint may be set at any time. + * The default value is "1". This hint may be set at any time. */ #define SDL_HINT_TIMER_RESOLUTION "SDL_TIMER_RESOLUTION" /** - * \brief A variable controlling whether touch events should generate synthetic mouse events + * A variable controlling whether touch events should generate synthetic mouse + * events + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Touch events will not generate mouse events - * "1" - Touch events will generate mouse events + * - "0": Touch events will not generate mouse events + * - "1": Touch events will generate mouse events * - * By default SDL will generate mouse events for touch events + * By default SDL will generate mouse events for touch events */ #define SDL_HINT_TOUCH_MOUSE_EVENTS "SDL_TOUCH_MOUSE_EVENTS" /** - * \brief A variable controlling which touchpad should generate synthetic mouse events + * A variable controlling which touchpad should generate synthetic mouse + * events + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Only front touchpad should generate mouse events. Default - * "1" - Only back touchpad should generate mouse events. - * "2" - Both touchpads should generate mouse events. + * - "0": Only front touchpad should generate mouse events. Default + * - "1": Only back touchpad should generate mouse events. + * - "2": Both touchpads should generate mouse events. * - * By default SDL will generate mouse events for all touch devices + * By default SDL will generate mouse events for all touch devices */ #define SDL_HINT_VITA_TOUCH_MOUSE_DEVICE "SDL_HINT_VITA_TOUCH_MOUSE_DEVICE" /** - * \brief A variable controlling whether the Android / tvOS remotes - * should be listed as joystick devices, instead of sending keyboard events. + * A variable controlling whether the Android / tvOS remotes should be listed + * as joystick devices, instead of sending keyboard events. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Remotes send enter/escape/arrow key events - * "1" - Remotes are available as 2 axis, 2 button joysticks (the default). + * - "0": Remotes send enter/escape/arrow key events + * - "1": Remotes are available as 2 axis, 2 button joysticks (the default). */ #define SDL_HINT_TV_REMOTE_AS_JOYSTICK "SDL_TV_REMOTE_AS_JOYSTICK" /** - * \brief A variable controlling whether the screensaver is enabled. + * A variable controlling whether the screensaver is enabled. * - * This variable can be set to the following values: - * "0" - Disable screensaver - * "1" - Enable screensaver + * This variable can be set to the following values: + * + * - "0": Disable screensaver + * - "1": Enable screensaver * - * By default SDL will disable the screensaver. + * By default SDL will disable the screensaver. */ #define SDL_HINT_VIDEO_ALLOW_SCREENSAVER "SDL_VIDEO_ALLOW_SCREENSAVER" /** - * \brief Tell the video driver that we only want a double buffer. + * Tell the video driver that we only want a double buffer. * * By default, most lowlevel 2D APIs will use a triple buffer scheme that * wastes no CPU time on waiting for vsync after issuing a flip, but * introduces a frame of latency. On the other hand, using a double buffer * scheme instead is recommended for cases where low latency is an important - * factor because we save a whole frame of latency. - * We do so by waiting for vsync immediately after issuing a flip, usually just - * after eglSwapBuffers call in the backend's *_SwapWindow function. + * factor because we save a whole frame of latency. We do so by waiting for + * vsync immediately after issuing a flip, usually just after eglSwapBuffers + * call in the backend's *_SwapWindow function. * * Since it's driver-specific, it's only supported where possible and * implemented. Currently supported the following drivers: @@ -1919,499 +2227,570 @@ extern "C" { #define SDL_HINT_VIDEO_DOUBLE_BUFFER "SDL_VIDEO_DOUBLE_BUFFER" /** - * \brief A variable controlling whether the EGL window is allowed to be - * composited as transparent, rather than opaque. + * A variable controlling whether the EGL window is allowed to be composited + * as transparent, rather than opaque. * * Most window systems will always render windows opaque, even if the surface - * format has an alpha channel. This is not always true, however, so by default - * SDL will try to enforce opaque composition. To override this behavior, you - * can set this hint to "1". + * format has an alpha channel. This is not always true, however, so by + * default SDL will try to enforce opaque composition. To override this + * behavior, you can set this hint to "1". */ #define SDL_HINT_VIDEO_EGL_ALLOW_TRANSPARENCY "SDL_VIDEO_EGL_ALLOW_TRANSPARENCY" /** - * \brief A variable controlling whether the graphics context is externally managed. + * A variable controlling whether the graphics context is externally managed. * * This variable can be set to the following values: - * "0" - SDL will manage graphics contexts that are attached to windows. - * "1" - Disable graphics context management on windows. * - * By default SDL will manage OpenGL contexts in certain situations. For example, on Android the - * context will be automatically saved and restored when pausing the application. Additionally, some - * platforms will assume usage of OpenGL if Vulkan isn't used. Setting this to "1" will prevent this - * behavior, which is desireable when the application manages the graphics context, such as - * an externally managed OpenGL context or attaching a Vulkan surface to the window. + * - "0": SDL will manage graphics contexts that are attached to windows. + * - "1": Disable graphics context management on windows. + * + * By default SDL will manage OpenGL contexts in certain situations. For + * example, on Android the context will be automatically saved and restored + * when pausing the application. Additionally, some platforms will assume + * usage of OpenGL if Vulkan isn't used. Setting this to "1" will prevent this + * behavior, which is desireable when the application manages the graphics + * context, such as an externally managed OpenGL context or attaching a Vulkan + * surface to the window. */ #define SDL_HINT_VIDEO_EXTERNAL_CONTEXT "SDL_VIDEO_EXTERNAL_CONTEXT" /** - * \brief If set to 1, then do not allow high-DPI windows. ("Retina" on Mac and iOS) + * If set to 1, then do not allow high-DPI windows. + * + * ("Retina" on Mac and iOS) */ #define SDL_HINT_VIDEO_HIGHDPI_DISABLED "SDL_VIDEO_HIGHDPI_DISABLED" /** - * \brief A variable that dictates policy for fullscreen Spaces on Mac OS X. + * A variable that dictates policy for fullscreen Spaces on Mac OS X. + * + * This hint only applies to Mac OS X. * - * This hint only applies to Mac OS X. + * The variable can be set to the following values: * - * The variable can be set to the following values: - * "0" - Disable Spaces support (FULLSCREEN_DESKTOP won't use them and - * SDL_WINDOW_RESIZABLE windows won't offer the "fullscreen" - * button on their titlebars). - * "1" - Enable Spaces support (FULLSCREEN_DESKTOP will use them and - * SDL_WINDOW_RESIZABLE windows will offer the "fullscreen" - * button on their titlebars). + * - "0": Disable Spaces support (FULLSCREEN_DESKTOP won't use them and + * SDL_WINDOW_RESIZABLE windows won't offer the "fullscreen" button on their + * titlebars). + * - "1": Enable Spaces support (FULLSCREEN_DESKTOP will use them and + * SDL_WINDOW_RESIZABLE windows will offer the "fullscreen" button on their + * titlebars). * - * The default value is "1". This hint must be set before any windows are created. + * The default value is "1". This hint must be set before any windows are + * created. */ #define SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES "SDL_VIDEO_MAC_FULLSCREEN_SPACES" /** - * \brief Minimize your SDL_Window if it loses key focus when in fullscreen mode. Defaults to false. - * \warning Before SDL 2.0.14, this defaulted to true! In 2.0.14, we're - * seeing if "true" causes more problems than it solves in modern times. + * Minimize your SDL_Window if it loses key focus when in fullscreen mode. * + * Defaults to false. */ #define SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS "SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS" /** - * \brief A variable controlling whether the libdecor Wayland backend is allowed to be used. + * A variable controlling whether the libdecor Wayland backend is allowed to + * be used. * - * This variable can be set to the following values: - * "0" - libdecor use is disabled. - * "1" - libdecor use is enabled (default). + * This variable can be set to the following values: + * + * - "0": libdecor use is disabled. + * - "1": libdecor use is enabled (default). * - * libdecor is used over xdg-shell when xdg-decoration protocol is unavailable. + * libdecor is used over xdg-shell when xdg-decoration protocol is + * unavailable. */ #define SDL_HINT_VIDEO_WAYLAND_ALLOW_LIBDECOR "SDL_VIDEO_WAYLAND_ALLOW_LIBDECOR" /** - * \brief A variable controlling whether the libdecor Wayland backend is preferred over native decrations. + * A variable controlling whether the libdecor Wayland backend is preferred + * over native decorations. * - * When this hint is set, libdecor will be used to provide window decorations, even if xdg-decoration is - * available. (Note that, by default, libdecor will use xdg-decoration itself if available). + * When this hint is set, libdecor will be used to provide window decorations, + * even if xdg-decoration is available. (Note that, by default, libdecor will + * use xdg-decoration itself if available). * - * This variable can be set to the following values: - * "0" - libdecor is enabled only if server-side decorations are unavailable. - * "1" - libdecor is always enabled if available. + * This variable can be set to the following values: * - * libdecor is used over xdg-shell when xdg-decoration protocol is unavailable. + * - "0": libdecor is enabled only if server-side decorations are unavailable. + * - "1": libdecor is always enabled if available. + * + * libdecor is used over xdg-shell when xdg-decoration protocol is + * unavailable. */ #define SDL_HINT_VIDEO_WAYLAND_PREFER_LIBDECOR "SDL_VIDEO_WAYLAND_PREFER_LIBDECOR" /** - * \brief A variable controlling whether video mode emulation is enabled under Wayland. + * A variable controlling whether video mode emulation is enabled under + * Wayland. + * + * When this hint is set, a standard set of emulated CVT video modes will be + * exposed for use by the application. If it is disabled, the only modes + * exposed will be the logical desktop size and, in the case of a scaled + * desktop, the native display resolution. * - * When this hint is set, a standard set of emulated CVT video modes will be exposed for use by the application. - * If it is disabled, the only modes exposed will be the logical desktop size and, in the case of a scaled - * desktop, the native display resolution. + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Video mode emulation is disabled. - * "1" - Video mode emulation is enabled. + * - "0": Video mode emulation is disabled. + * - "1": Video mode emulation is enabled. * - * By default video mode emulation is enabled. + * By default video mode emulation is enabled. */ #define SDL_HINT_VIDEO_WAYLAND_MODE_EMULATION "SDL_VIDEO_WAYLAND_MODE_EMULATION" /** - * \brief Enable or disable mouse pointer warp emulation, needed by some older games. + * Enable or disable mouse pointer warp emulation, needed by some older games. + * + * When this hint is set, any SDL will emulate mouse warps using relative + * mouse mode. This is required for some older games (such as Source engine + * games), which warp the mouse to the centre of the screen rather than using + * relative mouse motion. Note that relative mouse mode may have different + * mouse acceleration behaviour than pointer warps. * - * When this hint is set, any SDL will emulate mouse warps using relative mouse mode. - * This is required for some older games (such as Source engine games), which warp the - * mouse to the centre of the screen rather than using relative mouse motion. Note that - * relative mouse mode may have different mouse acceleration behaviour than pointer warps. + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - All mouse warps fail, as mouse warping is not available under wayland. - * "1" - Some mouse warps will be emulated by forcing relative mouse mode. + * - "0": All mouse warps fail, as mouse warping is not available under + * wayland. + * - "1": Some mouse warps will be emulated by forcing relative mouse mode. * - * If not set, this is automatically enabled unless an application uses relative mouse - * mode directly. + * If not set, this is automatically enabled unless an application uses + * relative mouse mode directly. */ #define SDL_HINT_VIDEO_WAYLAND_EMULATE_MOUSE_WARP "SDL_VIDEO_WAYLAND_EMULATE_MOUSE_WARP" /** -* \brief A variable that is the address of another SDL_Window* (as a hex string formatted with "%p"). -* -* If this hint is set before SDL_CreateWindowFrom() and the SDL_Window* it is set to has -* SDL_WINDOW_OPENGL set (and running on WGL only, currently), then two things will occur on the newly -* created SDL_Window: -* -* 1. Its pixel format will be set to the same pixel format as this SDL_Window. This is -* needed for example when sharing an OpenGL context across multiple windows. -* -* 2. The flag SDL_WINDOW_OPENGL will be set on the new window so it can be used for -* OpenGL rendering. -* -* This variable can be set to the following values: -* The address (as a string "%p") of the SDL_Window* that new windows created with SDL_CreateWindowFrom() should -* share a pixel format with. -*/ + * A variable that is the address of another SDL_Window* (as a hex string + * formatted with "%p"). + * + * If this hint is set before SDL_CreateWindowFrom() and the SDL_Window* it is + * set to has SDL_WINDOW_OPENGL set (and running on WGL only, currently), then + * two things will occur on the newly created SDL_Window: + * + * 1. Its pixel format will be set to the same pixel format as this + * SDL_Window. This is needed for example when sharing an OpenGL context + * across multiple windows. + * + * 2. The flag SDL_WINDOW_OPENGL will be set on the new window so it can be + * used for OpenGL rendering. + * + * This variable can be set to the following values: The address (as a string + * "%p") of the SDL_Window* that new windows created with + * SDL_CreateWindowFrom() should share a pixel format with. + */ #define SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT "SDL_VIDEO_WINDOW_SHARE_PIXEL_FORMAT" /** - * \brief When calling SDL_CreateWindowFrom(), make the window compatible with OpenGL. + * When calling SDL_CreateWindowFrom(), make the window compatible with + * OpenGL. * * This variable can be set to the following values: - * "0" - Don't add any graphics flags to the SDL_WindowFlags - * "1" - Add SDL_WINDOW_OPENGL to the SDL_WindowFlags + * + * - "0": Don't add any graphics flags to the SDL_WindowFlags + * - "1": Add SDL_WINDOW_OPENGL to the SDL_WindowFlags * * By default SDL will not make the foreign window compatible with OpenGL. */ #define SDL_HINT_VIDEO_FOREIGN_WINDOW_OPENGL "SDL_VIDEO_FOREIGN_WINDOW_OPENGL" /** - * \brief When calling SDL_CreateWindowFrom(), make the window compatible with Vulkan. + * When calling SDL_CreateWindowFrom(), make the window compatible with + * Vulkan. * * This variable can be set to the following values: - * "0" - Don't add any graphics flags to the SDL_WindowFlags - * "1" - Add SDL_WINDOW_VULKAN to the SDL_WindowFlags + * + * - "0": Don't add any graphics flags to the SDL_WindowFlags + * - "1": Add SDL_WINDOW_VULKAN to the SDL_WindowFlags * * By default SDL will not make the foreign window compatible with Vulkan. */ #define SDL_HINT_VIDEO_FOREIGN_WINDOW_VULKAN "SDL_VIDEO_FOREIGN_WINDOW_VULKAN" /** -* \brief A variable specifying which shader compiler to preload when using the Chrome ANGLE binaries -* -* SDL has EGL and OpenGL ES2 support on Windows via the ANGLE project. It -* can use two different sets of binaries, those compiled by the user from source -* or those provided by the Chrome browser. In the later case, these binaries require -* that SDL loads a DLL providing the shader compiler. -* -* This variable can be set to the following values: -* "d3dcompiler_46.dll" - default, best for Vista or later. -* "d3dcompiler_43.dll" - for XP support. -* "none" - do not load any library, useful if you compiled ANGLE from source and included the compiler in your binaries. -* -*/ + * A variable specifying which shader compiler to preload when using the + * Chrome ANGLE binaries + * + * SDL has EGL and OpenGL ES2 support on Windows via the ANGLE project. It can + * use two different sets of binaries, those compiled by the user from source + * or those provided by the Chrome browser. In the later case, these binaries + * require that SDL loads a DLL providing the shader compiler. + * + * This variable can be set to the following values: + * + * - "d3dcompiler_46.dll: default, best for Vista or later. + * - "d3dcompiler_43.dll: for XP support. + * - "none": do not load any library, useful if you compiled ANGLE from source + * and included the compiler in your binaries. + */ #define SDL_HINT_VIDEO_WIN_D3DCOMPILER "SDL_VIDEO_WIN_D3DCOMPILER" /** - * \brief A variable controlling whether X11 should use GLX or EGL by default + * A variable controlling whether X11 should use GLX or EGL by default * * This variable can be set to the following values: - * "0" - Use GLX - * "1" - Use EGL + * + * - "0": Use GLX + * - "1": Use EGL * * By default SDL will use GLX when both are present. */ #define SDL_HINT_VIDEO_X11_FORCE_EGL "SDL_VIDEO_X11_FORCE_EGL" /** - * \brief A variable controlling whether the X11 _NET_WM_BYPASS_COMPOSITOR hint should be used. + * A variable controlling whether the X11 _NET_WM_BYPASS_COMPOSITOR hint + * should be used. * * This variable can be set to the following values: - * "0" - Disable _NET_WM_BYPASS_COMPOSITOR - * "1" - Enable _NET_WM_BYPASS_COMPOSITOR * - * By default SDL will use _NET_WM_BYPASS_COMPOSITOR + * - "0": Disable _NET_WM_BYPASS_COMPOSITOR + * - "1": Enable _NET_WM_BYPASS_COMPOSITOR * + * By default SDL will use _NET_WM_BYPASS_COMPOSITOR */ #define SDL_HINT_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR "SDL_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR" /** - * \brief A variable controlling whether the X11 _NET_WM_PING protocol should be supported. + * A variable controlling whether the X11 _NET_WM_PING protocol should be + * supported. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Disable _NET_WM_PING - * "1" - Enable _NET_WM_PING + * - "0": Disable _NET_WM_PING + * - "1": Enable _NET_WM_PING * - * By default SDL will use _NET_WM_PING, but for applications that know they - * will not always be able to respond to ping requests in a timely manner they can - * turn it off to avoid the window manager thinking the app is hung. - * The hint is checked in CreateWindow. + * By default SDL will use _NET_WM_PING, but for applications that know they + * will not always be able to respond to ping requests in a timely manner they + * can turn it off to avoid the window manager thinking the app is hung. The + * hint is checked in CreateWindow. */ #define SDL_HINT_VIDEO_X11_NET_WM_PING "SDL_VIDEO_X11_NET_WM_PING" /** - * \brief A variable forcing the visual ID chosen for new X11 windows - * + * A variable forcing the visual ID chosen for new X11 windows */ #define SDL_HINT_VIDEO_X11_WINDOW_VISUALID "SDL_VIDEO_X11_WINDOW_VISUALID" /** - * \brief A no-longer-used variable controlling whether the X11 Xinerama extension should be used. + * A no-longer-used variable controlling whether the X11 Xinerama extension + * should be used. * - * Before SDL 2.0.24, this would let apps and users disable Xinerama support on X11. - * Now SDL never uses Xinerama, and does not check for this hint at all. - * The preprocessor define is left here for source compatibility. + * Before SDL 2.0.24, this would let apps and users disable Xinerama support + * on X11. Now SDL never uses Xinerama, and does not check for this hint at + * all. The preprocessor define is left here for source compatibility. */ #define SDL_HINT_VIDEO_X11_XINERAMA "SDL_VIDEO_X11_XINERAMA" /** - * \brief A variable controlling whether the X11 XRandR extension should be used. + * A variable controlling whether the X11 XRandR extension should be used. + * + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - Disable XRandR - * "1" - Enable XRandR + * - "0": Disable XRandR + * - "1": Enable XRandR * - * By default SDL will use XRandR. + * By default SDL will use XRandR. */ #define SDL_HINT_VIDEO_X11_XRANDR "SDL_VIDEO_X11_XRANDR" /** - * \brief A no-longer-used variable controlling whether the X11 VidMode extension should be used. + * A no-longer-used variable controlling whether the X11 VidMode extension + * should be used. * - * Before SDL 2.0.24, this would let apps and users disable XVidMode support on X11. - * Now SDL never uses XVidMode, and does not check for this hint at all. - * The preprocessor define is left here for source compatibility. + * Before SDL 2.0.24, this would let apps and users disable XVidMode support + * on X11. Now SDL never uses XVidMode, and does not check for this hint at + * all. The preprocessor define is left here for source compatibility. */ #define SDL_HINT_VIDEO_X11_XVIDMODE "SDL_VIDEO_X11_XVIDMODE" /** - * \brief Controls how the fact chunk affects the loading of a WAVE file. + * Controls how the fact chunk affects the loading of a WAVE file. * - * The fact chunk stores information about the number of samples of a WAVE - * file. The Standards Update from Microsoft notes that this value can be used - * to 'determine the length of the data in seconds'. This is especially useful - * for compressed formats (for which this is a mandatory chunk) if they produce - * multiple sample frames per block and truncating the block is not allowed. - * The fact chunk can exactly specify how many sample frames there should be - * in this case. + * The fact chunk stores information about the number of samples of a WAVE + * file. The Standards Update from Microsoft notes that this value can be used + * to 'determine the length of the data in seconds'. This is especially useful + * for compressed formats (for which this is a mandatory chunk) if they + * produce multiple sample frames per block and truncating the block is not + * allowed. The fact chunk can exactly specify how many sample frames there + * should be in this case. * - * Unfortunately, most application seem to ignore the fact chunk and so SDL - * ignores it by default as well. + * Unfortunately, most application seem to ignore the fact chunk and so SDL + * ignores it by default as well. * - * This variable can be set to the following values: + * This variable can be set to the following values: * - * "truncate" - Use the number of samples to truncate the wave data if - * the fact chunk is present and valid - * "strict" - Like "truncate", but raise an error if the fact chunk - * is invalid, not present for non-PCM formats, or if the - * data chunk doesn't have that many samples - * "ignorezero" - Like "truncate", but ignore fact chunk if the number of - * samples is zero - * "ignore" - Ignore fact chunk entirely (default) + * - "truncate": Use the number of samples to truncate the wave data if the + * fact chunk is present and valid + * - "strict": Like "truncate", but raise an error if the fact chunk is + * invalid, not present for non-PCM formats, or if the data chunk doesn't + * have that many samples + * - "ignorezero": Like "truncate", but ignore fact chunk if the number of + * samples is zero + * - "ignore": Ignore fact chunk entirely (default) */ #define SDL_HINT_WAVE_FACT_CHUNK "SDL_WAVE_FACT_CHUNK" /** - * \brief Controls how the size of the RIFF chunk affects the loading of a WAVE file. + * Controls how the size of the RIFF chunk affects the loading of a WAVE file. * - * The size of the RIFF chunk (which includes all the sub-chunks of the WAVE - * file) is not always reliable. In case the size is wrong, it's possible to - * just ignore it and step through the chunks until a fixed limit is reached. + * The size of the RIFF chunk (which includes all the sub-chunks of the WAVE + * file) is not always reliable. In case the size is wrong, it's possible to + * just ignore it and step through the chunks until a fixed limit is reached. * - * Note that files that have trailing data unrelated to the WAVE file or - * corrupt files may slow down the loading process without a reliable boundary. - * By default, SDL stops after 10000 chunks to prevent wasting time. Use the - * environment variable SDL_WAVE_CHUNK_LIMIT to adjust this value. + * Note that files that have trailing data unrelated to the WAVE file or + * corrupt files may slow down the loading process without a reliable + * boundary. By default, SDL stops after 10000 chunks to prevent wasting time. + * Use the environment variable SDL_WAVE_CHUNK_LIMIT to adjust this value. * - * This variable can be set to the following values: + * This variable can be set to the following values: * - * "force" - Always use the RIFF chunk size as a boundary for the chunk search - * "ignorezero" - Like "force", but a zero size searches up to 4 GiB (default) - * "ignore" - Ignore the RIFF chunk size and always search up to 4 GiB - * "maximum" - Search for chunks until the end of file (not recommended) + * - "force": Always use the RIFF chunk size as a boundary for the chunk + * search + * - "ignorezero": Like "force", but a zero size searches up to 4 GiB + * (default) + * - "ignore": Ignore the RIFF chunk size and always search up to 4 GiB + * - "maximum": Search for chunks until the end of file (not recommended) */ #define SDL_HINT_WAVE_RIFF_CHUNK_SIZE "SDL_WAVE_RIFF_CHUNK_SIZE" /** - * \brief Controls how a truncated WAVE file is handled. + * Controls how a truncated WAVE file is handled. * - * A WAVE file is considered truncated if any of the chunks are incomplete or - * the data chunk size is not a multiple of the block size. By default, SDL - * decodes until the first incomplete block, as most applications seem to do. + * A WAVE file is considered truncated if any of the chunks are incomplete or + * the data chunk size is not a multiple of the block size. By default, SDL + * decodes until the first incomplete block, as most applications seem to do. * - * This variable can be set to the following values: + * This variable can be set to the following values: * - * "verystrict" - Raise an error if the file is truncated - * "strict" - Like "verystrict", but the size of the RIFF chunk is ignored - * "dropframe" - Decode until the first incomplete sample frame - * "dropblock" - Decode until the first incomplete block (default) + * - "verystrict": Raise an error if the file is truncated + * - "strict": Like "verystrict", but the size of the RIFF chunk is ignored + * - "dropframe": Decode until the first incomplete sample frame + * - "dropblock": Decode until the first incomplete block (default) */ #define SDL_HINT_WAVE_TRUNCATION "SDL_WAVE_TRUNCATION" /** - * \brief Tell SDL not to name threads on Windows with the 0x406D1388 Exception. - * The 0x406D1388 Exception is a trick used to inform Visual Studio of a - * thread's name, but it tends to cause problems with other debuggers, - * and the .NET runtime. Note that SDL 2.0.6 and later will still use - * the (safer) SetThreadDescription API, introduced in the Windows 10 - * Creators Update, if available. + * Tell SDL not to name threads on Windows with the 0x406D1388 Exception. + * + * The 0x406D1388 Exception is a trick used to inform Visual Studio of a + * thread's name, but it tends to cause problems with other debuggers, and the + * .NET runtime. Note that SDL 2.0.6 and later will still use the (safer) + * SetThreadDescription API, introduced in the Windows 10 Creators Update, if + * available. * * The variable can be set to the following values: - * "0" - SDL will raise the 0x406D1388 Exception to name threads. - * This is the default behavior of SDL <= 2.0.4. - * "1" - SDL will not raise this exception, and threads will be unnamed. (default) - * This is necessary with .NET languages or debuggers that aren't Visual Studio. + * + * - "0": SDL will raise the 0x406D1388 Exception to name threads. This is the + * default behavior of SDL <= 2.0.4. + * - "1": SDL will not raise this exception, and threads will be unnamed. + * (default) This is necessary with .NET languages or debuggers that aren't + * Visual Studio. */ #define SDL_HINT_WINDOWS_DISABLE_THREAD_NAMING "SDL_WINDOWS_DISABLE_THREAD_NAMING" /** - * \brief Controls whether menus can be opened with their keyboard shortcut (Alt+mnemonic). + * Controls whether menus can be opened with their keyboard shortcut + * (Alt+mnemonic). * - * If the mnemonics are enabled, then menus can be opened by pressing the Alt - * key and the corresponding mnemonic (for example, Alt+F opens the File menu). - * However, in case an invalid mnemonic is pressed, Windows makes an audible - * beep to convey that nothing happened. This is true even if the window has - * no menu at all! + * If the mnemonics are enabled, then menus can be opened by pressing the Alt + * key and the corresponding mnemonic (for example, Alt+F opens the File + * menu). However, in case an invalid mnemonic is pressed, Windows makes an + * audible beep to convey that nothing happened. This is true even if the + * window has no menu at all! * - * Because most SDL applications don't have menus, and some want to use the Alt - * key for other purposes, SDL disables mnemonics (and the beeping) by default. + * Because most SDL applications don't have menus, and some want to use the + * Alt key for other purposes, SDL disables mnemonics (and the beeping) by + * default. * - * Note: This also affects keyboard events: with mnemonics enabled, when a - * menu is opened from the keyboard, you will not receive a KEYUP event for - * the mnemonic key, and *might* not receive one for Alt. + * Note: This also affects keyboard events: with mnemonics enabled, when a + * menu is opened from the keyboard, you will not receive a KEYUP event for + * the mnemonic key, and *might* not receive one for Alt. * - * This variable can be set to the following values: - * "0" - Alt+mnemonic does nothing, no beeping. (default) - * "1" - Alt+mnemonic opens menus, invalid mnemonics produce a beep. + * This variable can be set to the following values: + * + * - "0": Alt+mnemonic does nothing, no beeping. (default) + * - "1": Alt+mnemonic opens menus, invalid mnemonics produce a beep. */ #define SDL_HINT_WINDOWS_ENABLE_MENU_MNEMONICS "SDL_WINDOWS_ENABLE_MENU_MNEMONICS" /** - * \brief A variable controlling whether the windows message loop is processed by SDL + * A variable controlling whether the windows message loop is processed by SDL * - * This variable can be set to the following values: - * "0" - The window message loop is not run - * "1" - The window message loop is processed in SDL_PumpEvents() + * This variable can be set to the following values: * - * By default SDL will process the windows message loop + * - "0": The window message loop is not run + * - "1": The window message loop is processed in SDL_PumpEvents() + * + * By default SDL will process the windows message loop */ #define SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP "SDL_WINDOWS_ENABLE_MESSAGELOOP" /** - * \brief Force SDL to use Critical Sections for mutexes on Windows. - * On Windows 7 and newer, Slim Reader/Writer Locks are available. - * They offer better performance, allocate no kernel ressources and - * use less memory. SDL will fall back to Critical Sections on older - * OS versions or if forced to by this hint. + * Force SDL to use Critical Sections for mutexes on Windows. + * + * On Windows 7 and newer, Slim Reader/Writer Locks are available. They offer + * better performance, allocate no kernel resources and use less memory. SDL + * will fall back to Critical Sections on older OS versions or if forced to by + * this hint. * - * This variable can be set to the following values: - * "0" - Use SRW Locks when available. If not, fall back to Critical Sections. (default) - * "1" - Force the use of Critical Sections in all cases. + * This variable can be set to the following values: * + * - "0": Use SRW Locks when available. If not, fall back to Critical + * Sections. (default) + * - "1": Force the use of Critical Sections in all cases. */ #define SDL_HINT_WINDOWS_FORCE_MUTEX_CRITICAL_SECTIONS "SDL_WINDOWS_FORCE_MUTEX_CRITICAL_SECTIONS" /** - * \brief Force SDL to use Kernel Semaphores on Windows. - * Kernel Semaphores are inter-process and require a context - * switch on every interaction. On Windows 8 and newer, the - * WaitOnAddress API is available. Using that and atomics to - * implement semaphores increases performance. - * SDL will fall back to Kernel Objects on older OS versions - * or if forced to by this hint. + * Force SDL to use Kernel Semaphores on Windows. * - * This variable can be set to the following values: - * "0" - Use Atomics and WaitOnAddress API when available. If not, fall back to Kernel Objects. (default) - * "1" - Force the use of Kernel Objects in all cases. + * Kernel Semaphores are inter-process and require a context switch on every + * interaction. On Windows 8 and newer, the WaitOnAddress API is available. + * Using that and atomics to implement semaphores increases performance. SDL + * will fall back to Kernel Objects on older OS versions or if forced to by + * this hint. * + * This variable can be set to the following values: + * + * - "0": Use Atomics and WaitOnAddress API when available. If not, fall back + * to Kernel Objects. (default) + * - "1": Force the use of Kernel Objects in all cases. */ #define SDL_HINT_WINDOWS_FORCE_SEMAPHORE_KERNEL "SDL_WINDOWS_FORCE_SEMAPHORE_KERNEL" /** - * \brief A variable to specify custom icon resource id from RC file on Windows platform + * A variable to specify custom icon resource id from RC file on Windows + * platform */ #define SDL_HINT_WINDOWS_INTRESOURCE_ICON "SDL_WINDOWS_INTRESOURCE_ICON" + +/** + * A variable to specify custom icon resource id from RC file on Windows + * platform + */ #define SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL "SDL_WINDOWS_INTRESOURCE_ICON_SMALL" /** - * \brief Tell SDL not to generate window-close events for Alt+F4 on Windows. + * Tell SDL not to generate window-close events for Alt+F4 on Windows. * * The variable can be set to the following values: - * "0" - SDL will generate a window-close event when it sees Alt+F4. - * "1" - SDL will only do normal key handling for Alt+F4. + * + * - "0": SDL will generate a window-close event when it sees Alt+F4. + * - "1": SDL will only do normal key handling for Alt+F4. */ #define SDL_HINT_WINDOWS_NO_CLOSE_ON_ALT_F4 "SDL_WINDOWS_NO_CLOSE_ON_ALT_F4" /** - * \brief Use the D3D9Ex API introduced in Windows Vista, instead of normal D3D9. - * Direct3D 9Ex contains changes to state management that can eliminate device - * loss errors during scenarios like Alt+Tab or UAC prompts. D3D9Ex may require - * some changes to your application to cope with the new behavior, so this - * is disabled by default. + * Use the D3D9Ex API introduced in Windows Vista, instead of normal D3D9. * - * This hint must be set before initializing the video subsystem. + * Direct3D 9Ex contains changes to state management that can eliminate device + * loss errors during scenarios like Alt+Tab or UAC prompts. D3D9Ex may + * require some changes to your application to cope with the new behavior, so + * this is disabled by default. + * + * This hint must be set before initializing the video subsystem. * - * For more information on Direct3D 9Ex, see: - * - https://docs.microsoft.com/en-us/windows/win32/direct3darticles/graphics-apis-in-windows-vista#direct3d-9ex - * - https://docs.microsoft.com/en-us/windows/win32/direct3darticles/direct3d-9ex-improvements + * For more information on Direct3D 9Ex, see: - + * https://docs.microsoft.com/en-us/windows/win32/direct3darticles/graphics-apis-in-windows-vista#direct3d-9ex + * - + * https://docs.microsoft.com/en-us/windows/win32/direct3darticles/direct3d-9ex-improvements * - * This variable can be set to the following values: - * "0" - Use the original Direct3D 9 API (default) - * "1" - Use the Direct3D 9Ex API on Vista and later (and fall back if D3D9Ex is unavailable) + * This variable can be set to the following values: * + * - "0": Use the original Direct3D 9 API (default) + * - "1": Use the Direct3D 9Ex API on Vista and later (and fall back if D3D9Ex + * is unavailable) */ #define SDL_HINT_WINDOWS_USE_D3D9EX "SDL_WINDOWS_USE_D3D9EX" /** - * \brief Controls whether SDL will declare the process to be DPI aware. + * Controls whether SDL will declare the process to be DPI aware. + * + * This hint must be set before initializing the video subsystem. * - * This hint must be set before initializing the video subsystem. + * The main purpose of declaring DPI awareness is to disable OS bitmap scaling + * of SDL windows on monitors with a DPI scale factor. * - * The main purpose of declaring DPI awareness is to disable OS bitmap scaling of SDL windows on monitors with - * a DPI scale factor. + * This hint is equivalent to requesting DPI awareness via external means + * (e.g. calling SetProcessDpiAwarenessContext) and does not cause SDL to use + * a virtualized coordinate system, so it will generally give you 1 SDL + * coordinate = 1 pixel even on high-DPI displays. * - * This hint is equivalent to requesting DPI awareness via external means (e.g. calling SetProcessDpiAwarenessContext) - * and does not cause SDL to use a virtualized coordinate system, so it will generally give you 1 SDL coordinate = 1 pixel - * even on high-DPI displays. + * For more information, see: + * https://docs.microsoft.com/en-us/windows/win32/hidpi/high-dpi-desktop-application-development-on-windows * - * For more information, see: - * https://docs.microsoft.com/en-us/windows/win32/hidpi/high-dpi-desktop-application-development-on-windows + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "" - Do not change the DPI awareness (default). - * "unaware" - Declare the process as DPI unaware. (Windows 8.1 and later). - * "system" - Request system DPI awareness. (Vista and later). - * "permonitor" - Request per-monitor DPI awareness. (Windows 8.1 and later). - * "permonitorv2" - Request per-monitor V2 DPI awareness. (Windows 10, version 1607 and later). - * The most visible difference from "permonitor" is that window title bar will be scaled - * to the visually correct size when dragging between monitors with different scale factors. - * This is the preferred DPI awareness level. + * - "": Do not change the DPI awareness (default). + * - "unaware": Declare the process as DPI unaware. (Windows 8.1 and later). + * - "system": Request system DPI awareness. (Vista and later). + * - "permonitor": Request per-monitor DPI awareness. (Windows 8.1 and later). + * - "permonitorv2": Request per-monitor V2 DPI awareness. (Windows 10, + * version 1607 and later). The most visible difference from "permonitor" is + * that window title bar will be scaled to the visually correct size when + * dragging between monitors with different scale factors. This is the + * preferred DPI awareness level. * - * If the requested DPI awareness is not available on the currently running OS, SDL will try to request the best - * available match. + * If the requested DPI awareness is not available on the currently running + * OS, SDL will try to request the best available match. */ #define SDL_HINT_WINDOWS_DPI_AWARENESS "SDL_WINDOWS_DPI_AWARENESS" /** - * \brief Uses DPI-scaled points as the SDL coordinate system on Windows. + * Uses DPI-scaled points as the SDL coordinate system on Windows. + * + * This changes the SDL coordinate system units to be DPI-scaled points, + * rather than pixels everywhere. This means windows will be appropriately + * sized, even when created on high-DPI displays with scaling. * - * This changes the SDL coordinate system units to be DPI-scaled points, rather than pixels everywhere. - * This means windows will be appropriately sized, even when created on high-DPI displays with scaling. + * e.g. requesting a 640x480 window from SDL, on a display with 125% scaling + * in Windows display settings, will create a window with an 800x600 client + * area (in pixels). * - * e.g. requesting a 640x480 window from SDL, on a display with 125% scaling in Windows display settings, - * will create a window with an 800x600 client area (in pixels). + * Setting this to "1" implicitly requests process DPI awareness (setting + * SDL_WINDOWS_DPI_AWARENESS is unnecessary), and forces + * SDL_WINDOW_ALLOW_HIGHDPI on all windows. * - * Setting this to "1" implicitly requests process DPI awareness (setting SDL_WINDOWS_DPI_AWARENESS is unnecessary), - * and forces SDL_WINDOW_ALLOW_HIGHDPI on all windows. + * This variable can be set to the following values: * - * This variable can be set to the following values: - * "0" - SDL coordinates equal Windows coordinates. No automatic window resizing when dragging - * between monitors with different scale factors (unless this is performed by - * Windows itself, which is the case when the process is DPI unaware). - * "1" - SDL coordinates are in DPI-scaled points. Automatically resize windows as needed on - * displays with non-100% scale factors. + * - "0": SDL coordinates equal Windows coordinates. No automatic window + * resizing when dragging between monitors with different scale factors + * (unless this is performed by Windows itself, which is the case when the + * process is DPI unaware). + * - "1": SDL coordinates are in DPI-scaled points. Automatically resize + * windows as needed on displays with non-100% scale factors. */ #define SDL_HINT_WINDOWS_DPI_SCALING "SDL_WINDOWS_DPI_SCALING" /** - * \brief A variable controlling whether the window frame and title bar are interactive when the cursor is hidden + * A variable controlling whether the window frame and title bar are + * interactive when the cursor is hidden * - * This variable can be set to the following values: - * "0" - The window frame is not interactive when the cursor is hidden (no move, resize, etc) - * "1" - The window frame is interactive when the cursor is hidden + * This variable can be set to the following values: + * + * - "0": The window frame is not interactive when the cursor is hidden (no + * move, resize, etc) + * - "1": The window frame is interactive when the cursor is hidden * - * By default SDL will allow interaction with the window frame when the cursor is hidden + * By default SDL will allow interaction with the window frame when the cursor + * is hidden */ #define SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN "SDL_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN" /** -* \brief A variable controlling whether the window is activated when the SDL_ShowWindow function is called -* -* This variable can be set to the following values: -* "0" - The window is activated when the SDL_ShowWindow function is called -* "1" - The window is not activated when the SDL_ShowWindow function is called -* -* By default SDL will activate the window when the SDL_ShowWindow function is called -*/ + * A variable controlling whether the window is activated when the + * SDL_ShowWindow function is called + * + * This variable can be set to the following values: + * + * - "0": The window is activated when the SDL_ShowWindow function is called + * - "1": The window is not activated when the SDL_ShowWindow function is + * called + * + * By default SDL will activate the window when the SDL_ShowWindow function is + * called + */ #define SDL_HINT_WINDOW_NO_ACTIVATION_WHEN_SHOWN "SDL_WINDOW_NO_ACTIVATION_WHEN_SHOWN" -/** \brief Allows back-button-press events on Windows Phone to be marked as handled +/** Allows back-button-press events on Windows Phone to be marked as handled * * Windows Phone devices typically feature a Back button. When pressed, * the OS will emit back-button-press events, which apps are expected to @@ -2459,11 +2838,12 @@ extern "C" { * * More details on back button behavior in Windows Phone apps can be found * at the following page, on Microsoft's developer site: + * * http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj247550(v=vs.105).aspx */ #define SDL_HINT_WINRT_HANDLE_BACK_BUTTON "SDL_WINRT_HANDLE_BACK_BUTTON" -/** \brief Label text for a WinRT app's privacy policy link +/** Label text for a WinRT app's privacy policy link * * Network-enabled WinRT apps must include a privacy policy. On Windows 8, 8.1, and RT, * Microsoft mandates that this policy be available via the Windows Settings charm. @@ -2485,213 +2865,221 @@ extern "C" { #define SDL_HINT_WINRT_PRIVACY_POLICY_LABEL "SDL_WINRT_PRIVACY_POLICY_LABEL" /** - * \brief A URL to a WinRT app's privacy policy + * A URL to a WinRT app's privacy policy * - * All network-enabled WinRT apps must make a privacy policy available to its - * users. On Windows 8, 8.1, and RT, Microsoft mandates that this policy be - * be available in the Windows Settings charm, as accessed from within the app. - * SDL provides code to add a URL-based link there, which can point to the app's - * privacy policy. + * All network-enabled WinRT apps must make a privacy policy available to its + * users. On Windows 8, 8.1, and RT, Microsoft mandates that this policy be be + * available in the Windows Settings charm, as accessed from within the app. + * SDL provides code to add a URL-based link there, which can point to the + * app's privacy policy. * - * To setup a URL to an app's privacy policy, set SDL_HINT_WINRT_PRIVACY_POLICY_URL - * before calling any SDL_Init() functions. The contents of the hint should - * be a valid URL. For example, "http://www.example.com". + * To setup a URL to an app's privacy policy, set + * SDL_HINT_WINRT_PRIVACY_POLICY_URL before calling any SDL_Init() functions. + * The contents of the hint should be a valid URL. For example, + * "http://www.example.com". * - * The default value is "", which will prevent SDL from adding a privacy policy - * link to the Settings charm. This hint should only be set during app init. + * The default value is "", which will prevent SDL from adding a privacy + * policy link to the Settings charm. This hint should only be set during app + * init. * - * The label text of an app's "Privacy Policy" link may be customized via another - * hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL. + * The label text of an app's "Privacy Policy" link may be customized via + * another hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL. * - * Please note that on Windows Phone, Microsoft does not provide standard UI - * for displaying a privacy policy link, and as such, SDL_HINT_WINRT_PRIVACY_POLICY_URL - * will not get used on that platform. Network-enabled phone apps should display - * their privacy policy through some other, in-app means. + * Please note that on Windows Phone, Microsoft does not provide standard UI + * for displaying a privacy policy link, and as such, + * SDL_HINT_WINRT_PRIVACY_POLICY_URL will not get used on that platform. + * Network-enabled phone apps should display their privacy policy through some + * other, in-app means. */ #define SDL_HINT_WINRT_PRIVACY_POLICY_URL "SDL_WINRT_PRIVACY_POLICY_URL" /** - * \brief Mark X11 windows as override-redirect. + * Mark X11 windows as override-redirect. * - * If set, this _might_ increase framerate at the expense of the desktop - * not working as expected. Override-redirect windows aren't noticed by the - * window manager at all. + * If set, this _might_ increase framerate at the expense of the desktop not + * working as expected. Override-redirect windows aren't noticed by the window + * manager at all. * - * You should probably only use this for fullscreen windows, and you probably - * shouldn't even use it for that. But it's here if you want to try! + * You should probably only use this for fullscreen windows, and you probably + * shouldn't even use it for that. But it's here if you want to try! */ #define SDL_HINT_X11_FORCE_OVERRIDE_REDIRECT "SDL_X11_FORCE_OVERRIDE_REDIRECT" /** - * \brief A variable that lets you disable the detection and use of Xinput gamepad devices + * A variable that lets you disable the detection and use of Xinput gamepad + * devices + * + * The variable can be set to the following values: * - * The variable can be set to the following values: - * "0" - Disable XInput detection (only uses direct input) - * "1" - Enable XInput detection (the default) + * - "0": Disable XInput detection (only uses direct input) + * - "1": Enable XInput detection (the default) */ #define SDL_HINT_XINPUT_ENABLED "SDL_XINPUT_ENABLED" - /** - * \brief A variable that lets you disable the detection and use of DirectInput gamepad devices - * - * The variable can be set to the following values: - * "0" - Disable DirectInput detection (only uses XInput) - * "1" - Enable DirectInput detection (the default) - */ +/** + * A variable that lets you disable the detection and use of DirectInput + * gamepad devices + * + * The variable can be set to the following values: + * + * - "0": Disable DirectInput detection (only uses XInput) + * - "1": Enable DirectInput detection (the default) + */ #define SDL_HINT_DIRECTINPUT_ENABLED "SDL_DIRECTINPUT_ENABLED" /** - * \brief A variable that causes SDL to use the old axis and button mapping for XInput devices. + * A variable that causes SDL to use the old axis and button mapping for + * XInput devices. * - * This hint is for backwards compatibility only and will be removed in SDL 2.1 + * This hint is for backwards compatibility only and will be removed in SDL + * 2.1 * - * The default value is "0". This hint must be set before SDL_Init() + * The default value is "0". This hint must be set before SDL_Init() */ #define SDL_HINT_XINPUT_USE_OLD_JOYSTICK_MAPPING "SDL_XINPUT_USE_OLD_JOYSTICK_MAPPING" /** - * \brief A variable that causes SDL to not ignore audio "monitors" + * A variable that causes SDL to not ignore audio "monitors" * - * This is currently only used for PulseAudio and ignored elsewhere. + * This is currently only used for PulseAudio and ignored elsewhere. * - * By default, SDL ignores audio devices that aren't associated with physical - * hardware. Changing this hint to "1" will expose anything SDL sees that - * appears to be an audio source or sink. This will add "devices" to the list - * that the user probably doesn't want or need, but it can be useful in - * scenarios where you want to hook up SDL to some sort of virtual device, - * etc. + * By default, SDL ignores audio devices that aren't associated with physical + * hardware. Changing this hint to "1" will expose anything SDL sees that + * appears to be an audio source or sink. This will add "devices" to the list + * that the user probably doesn't want or need, but it can be useful in + * scenarios where you want to hook up SDL to some sort of virtual device, + * etc. * - * The default value is "0". This hint must be set before SDL_Init(). + * The default value is "0". This hint must be set before SDL_Init(). * - * This hint is available since SDL 2.0.16. Before then, virtual devices are - * always ignored. + * This hint is available since SDL 2.0.16. Before then, virtual devices are + * always ignored. */ #define SDL_HINT_AUDIO_INCLUDE_MONITORS "SDL_AUDIO_INCLUDE_MONITORS" /** - * \brief A variable that forces X11 windows to create as a custom type. + * A variable that forces X11 windows to create as a custom type. * - * This is currently only used for X11 and ignored elsewhere. + * This is currently only used for X11 and ignored elsewhere. * - * During SDL_CreateWindow, SDL uses the _NET_WM_WINDOW_TYPE X11 property - * to report to the window manager the type of window it wants to create. - * This might be set to various things if SDL_WINDOW_TOOLTIP or - * SDL_WINDOW_POPUP_MENU, etc, were specified. For "normal" windows that - * haven't set a specific type, this hint can be used to specify a custom - * type. For example, a dock window might set this to - * "_NET_WM_WINDOW_TYPE_DOCK". + * During SDL_CreateWindow, SDL uses the _NET_WM_WINDOW_TYPE X11 property to + * report to the window manager the type of window it wants to create. This + * might be set to various things if SDL_WINDOW_TOOLTIP or + * SDL_WINDOW_POPUP_MENU, etc, were specified. For "normal" windows that + * haven't set a specific type, this hint can be used to specify a custom + * type. For example, a dock window might set this to + * "_NET_WM_WINDOW_TYPE_DOCK". * - * If not set or set to "", this hint is ignored. This hint must be set - * before the SDL_CreateWindow() call that it is intended to affect. + * If not set or set to "", this hint is ignored. This hint must be set before + * the SDL_CreateWindow() call that it is intended to affect. * - * This hint is available since SDL 2.0.22. + * This hint is available since SDL 2.0.22. */ #define SDL_HINT_X11_WINDOW_TYPE "SDL_X11_WINDOW_TYPE" /** - * \brief A variable that decides whether to send SDL_QUIT when closing the final window. + * A variable that decides whether to send SDL_QUIT when closing the final + * window. * - * By default, SDL sends an SDL_QUIT event when there is only one window - * and it receives an SDL_WINDOWEVENT_CLOSE event, under the assumption most - * apps would also take the loss of this window as a signal to terminate the - * program. + * By default, SDL sends an SDL_QUIT event when there is only one window and + * it receives an SDL_WINDOWEVENT_CLOSE event, under the assumption most apps + * would also take the loss of this window as a signal to terminate the + * program. * - * However, it's not unreasonable in some cases to have the program continue - * to live on, perhaps to create new windows later. + * However, it's not unreasonable in some cases to have the program continue + * to live on, perhaps to create new windows later. * - * Changing this hint to "0" will cause SDL to not send an SDL_QUIT event - * when the final window is requesting to close. Note that in this case, - * there are still other legitimate reasons one might get an SDL_QUIT - * event: choosing "Quit" from the macOS menu bar, sending a SIGINT (ctrl-c) - * on Unix, etc. + * Changing this hint to "0" will cause SDL to not send an SDL_QUIT event when + * the final window is requesting to close. Note that in this case, there are + * still other legitimate reasons one might get an SDL_QUIT event: choosing + * "Quit" from the macOS menu bar, sending a SIGINT (ctrl-c) on Unix, etc. * - * The default value is "1". This hint can be changed at any time. + * The default value is "1". This hint can be changed at any time. * - * This hint is available since SDL 2.0.22. Before then, you always get - * an SDL_QUIT event when closing the final window. + * This hint is available since SDL 2.0.22. Before then, you always get an + * SDL_QUIT event when closing the final window. */ #define SDL_HINT_QUIT_ON_LAST_WINDOW_CLOSE "SDL_QUIT_ON_LAST_WINDOW_CLOSE" /** - * \brief A variable that decides what video backend to use. + * A variable that decides what video backend to use. * - * By default, SDL will try all available video backends in a reasonable - * order until it finds one that can work, but this hint allows the app - * or user to force a specific target, such as "x11" if, say, you are - * on Wayland but want to try talking to the X server instead. + * By default, SDL will try all available video backends in a reasonable order + * until it finds one that can work, but this hint allows the app or user to + * force a specific target, such as "x11" if, say, you are on Wayland but want + * to try talking to the X server instead. * - * This functionality has existed since SDL 2.0.0 (indeed, before that) - * but before 2.0.22 this was an environment variable only. In 2.0.22, - * it was upgraded to a full SDL hint, so you can set the environment - * variable as usual or programatically set the hint with SDL_SetHint, - * which won't propagate to child processes. + * This functionality has existed since SDL 2.0.0 (indeed, before that) but + * before 2.0.22 this was an environment variable only. In 2.0.22, it was + * upgraded to a full SDL hint, so you can set the environment variable as + * usual or programatically set the hint with SDL_SetHint, which won't + * propagate to child processes. * - * The default value is unset, in which case SDL will try to figure out - * the best video backend on your behalf. This hint needs to be set - * before SDL_Init() is called to be useful. + * The default value is unset, in which case SDL will try to figure out the + * best video backend on your behalf. This hint needs to be set before + * SDL_Init() is called to be useful. * - * This hint is available since SDL 2.0.22. Before then, you could set - * the environment variable to get the same effect. + * This hint is available since SDL 2.0.22. Before then, you could set the + * environment variable to get the same effect. */ #define SDL_HINT_VIDEODRIVER "SDL_VIDEODRIVER" /** - * \brief A variable that decides what audio backend to use. + * A variable that decides what audio backend to use. * - * By default, SDL will try all available audio backends in a reasonable - * order until it finds one that can work, but this hint allows the app - * or user to force a specific target, such as "alsa" if, say, you are - * on PulseAudio but want to try talking to the lower level instead. + * By default, SDL will try all available audio backends in a reasonable order + * until it finds one that can work, but this hint allows the app or user to + * force a specific target, such as "alsa" if, say, you are on PulseAudio but + * want to try talking to the lower level instead. * - * This functionality has existed since SDL 2.0.0 (indeed, before that) - * but before 2.0.22 this was an environment variable only. In 2.0.22, - * it was upgraded to a full SDL hint, so you can set the environment - * variable as usual or programatically set the hint with SDL_SetHint, - * which won't propagate to child processes. + * This functionality has existed since SDL 2.0.0 (indeed, before that) but + * before 2.0.22 this was an environment variable only. In 2.0.22, it was + * upgraded to a full SDL hint, so you can set the environment variable as + * usual or programatically set the hint with SDL_SetHint, which won't + * propagate to child processes. * - * The default value is unset, in which case SDL will try to figure out - * the best audio backend on your behalf. This hint needs to be set - * before SDL_Init() is called to be useful. + * The default value is unset, in which case SDL will try to figure out the + * best audio backend on your behalf. This hint needs to be set before + * SDL_Init() is called to be useful. * - * This hint is available since SDL 2.0.22. Before then, you could set - * the environment variable to get the same effect. + * This hint is available since SDL 2.0.22. Before then, you could set the + * environment variable to get the same effect. */ #define SDL_HINT_AUDIODRIVER "SDL_AUDIODRIVER" /** - * \brief A variable that decides what KMSDRM device to use. + * A variable that decides what KMSDRM device to use. * - * Internally, SDL might open something like "/dev/dri/cardNN" to - * access KMSDRM functionality, where "NN" is a device index number. + * Internally, SDL might open something like "/dev/dri/cardNN" to access + * KMSDRM functionality, where "NN" is a device index number. * - * SDL makes a guess at the best index to use (usually zero), but the - * app or user can set this hint to a number between 0 and 99 to - * force selection. + * SDL makes a guess at the best index to use (usually zero), but the app or + * user can set this hint to a number between 0 and 99 to force selection. * - * This hint is available since SDL 2.24.0. + * This hint is available since SDL 2.24.0. */ #define SDL_HINT_KMSDRM_DEVICE_INDEX "SDL_KMSDRM_DEVICE_INDEX" /** - * \brief A variable that treats trackpads as touch devices. + * A variable that treats trackpads as touch devices. * - * On macOS (and possibly other platforms in the future), SDL will report - * touches on a trackpad as mouse input, which is generally what users - * expect from this device; however, these are often actually full - * multitouch-capable touch devices, so it might be preferable to some apps - * to treat them as such. + * On macOS (and possibly other platforms in the future), SDL will report + * touches on a trackpad as mouse input, which is generally what users expect + * from this device; however, these are often actually full multitouch-capable + * touch devices, so it might be preferable to some apps to treat them as + * such. * - * Setting this hint to true will make the trackpad input report as a - * multitouch device instead of a mouse. The default is false. + * Setting this hint to true will make the trackpad input report as a + * multitouch device instead of a mouse. The default is false. * - * Note that most platforms don't support this hint. As of 2.24.0, it - * only supports MacBooks' trackpads on macOS. Others may follow later. + * Note that most platforms don't support this hint. As of 2.24.0, it only + * supports MacBooks' trackpads on macOS. Others may follow later. * - * This hint is checked during SDL_Init and can not be changed after. + * This hint is checked during SDL_Init and can not be changed after. * - * This hint is available since SDL 2.24.0. + * This hint is available since SDL 2.24.0. */ #define SDL_HINT_TRACKPAD_IS_TOUCH_ONLY "SDL_TRACKPAD_IS_TOUCH_ONLY" @@ -2699,23 +3087,45 @@ extern "C" { * Cause SDL to call dbus_shutdown() on quit. * * This is useful as a debug tool to validate memory leaks, but shouldn't ever - * be set in production applications, as other libraries used by the application - * might use dbus under the hood and this cause cause crashes if they continue - * after SDL_Quit(). + * be set in production applications, as other libraries used by the + * application might use dbus under the hood and this cause cause crashes if + * they continue after SDL_Quit(). * * This variable can be set to the following values: - * "0" - SDL will not call dbus_shutdown() on quit (default) - * "1" - SDL will call dbus_shutdown() on quit + * + * - "0": SDL will not call dbus_shutdown() on quit (default) + * - "1": SDL will call dbus_shutdown() on quit * * This hint is available since SDL 2.30.0. */ #define SDL_HINT_SHUTDOWN_DBUS_ON_QUIT "SDL_SHUTDOWN_DBUS_ON_QUIT" +/** + * Specify if SDL_RWFromFile should use the resource dir on Apple platforms. + * + * SDL2 has always done this on Apple platforms, but it can be surprising to + * try opening a path to discover that SDL adjusts the path to elsewhere, so + * this hint allows that behavior to be disabled. + * + * If running from a App Bundle, this will be MyApp.app/Contents/Resources. If + * running as a normal Unix-like process, this will be the directory where the + * running binary lives. Setting this hint to 0 avoids this and just uses the + * requested path as-is. + * + * This variable can be set to the following values: + * + * - "0": SDL will not use the app resource directory. + * - "1": SDL will use the app's resource directory (default). + * + * This hint is available since SDL 2.32.0. + */ +#define SDL_HINT_APPLE_RWFROMFILE_USE_RESOURCES "SDL_APPLE_RWFROMFILE_USE_RESOURCES" + /** - * \brief An enumeration of hint priorities + * An enumeration of hint priorities */ -typedef enum +typedef enum SDL_HintPriority { SDL_HINT_DEFAULT, SDL_HINT_NORMAL, @@ -2730,9 +3140,9 @@ typedef enum * value. Hints will replace existing hints of their priority and lower. * Environment variables are considered to have override priority. * - * \param name the hint to set - * \param value the value of the hint variable - * \param priority the SDL_HintPriority level for the hint + * \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. * * \since This function is available since SDL 2.0.0. @@ -2751,8 +3161,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name, * 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 + * \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. * * \since This function is available since SDL 2.0.0. @@ -2770,7 +3180,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name, * the environment isn't set. Callbacks will be called normally with this * change. * - * \param name the hint to set + * \param name the hint to set. * \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise. * * \since This function is available since SDL 2.24.0. @@ -2798,7 +3208,7 @@ extern DECLSPEC void SDLCALL SDL_ResetHints(void); /** * Get the value of a hint. * - * \param name the hint to query + * \param name the hint to query. * \returns the string value of a hint or NULL if the hint isn't set. * * \since This function is available since SDL 2.0.0. @@ -2811,8 +3221,8 @@ extern DECLSPEC const char * SDLCALL SDL_GetHint(const char *name); /** * Get 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 + * \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. * @@ -2826,20 +3236,20 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bool d /** * 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 + * \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); /** * Add a function to watch a particular hint. * - * \param name the hint to watch + * \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 + * hint value changes. + * \param userdata a pointer to pass to the callback function. * * \since This function is available since SDL 2.0.0. * @@ -2852,10 +3262,10 @@ extern DECLSPEC void SDLCALL SDL_AddHintCallback(const char *name, /** * Remove a function watching a particular hint. * - * \param name the hint being watched + * \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 + * hint value changes. + * \param userdata a pointer being passed to the callback function. * * \since This function is available since SDL 2.0.0. * diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_joystick.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_joystick.h @@ -20,22 +20,26 @@ */ /** - * \file SDL_joystick.h + * # CategoryJoystick * - * Include file for SDL joystick event handling + * Include file for SDL joystick event handling * - * The term "device_index" identifies currently plugged in joystick devices between 0 and SDL_NumJoysticks(), with the exact joystick - * behind a device_index changing as joysticks are plugged and unplugged. + * The term "device_index" identifies currently plugged in joystick devices + * between 0 and SDL_NumJoysticks(), with the exact joystick behind a + * device_index changing as joysticks are plugged and unplugged. * - * 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 "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. + * 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. + * 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_ @@ -56,7 +60,7 @@ extern "C" { * \file SDL_joystick.h * * In order to use these functions, SDL_Init() must have been called - * with the ::SDL_INIT_JOYSTICK flag. This causes SDL to scan the system + * with the SDL_INIT_JOYSTICK flag. This causes SDL to scan the system * for joysticks, and load appropriate drivers. * * If you would like to receive joystick updates while the application @@ -73,15 +77,21 @@ extern SDL_mutex *SDL_joystick_lock; struct _SDL_Joystick; typedef struct _SDL_Joystick SDL_Joystick; -/* A structure that encodes the stable unique id for a joystick device */ +/** + * A structure that encodes the stable unique id for a joystick device. + * + * This is just a standard SDL_GUID by a different name. + */ typedef SDL_GUID SDL_JoystickGUID; /** - * This is a unique ID for a joystick for the time it is connected to the system, - * and is never reused for the lifetime of the application. If the joystick is - * disconnected and reconnected, it will get a new ID. + * This is a unique ID for a joystick for the time it is connected to the + * system, and is never reused for the lifetime of the application. + * + * If the joystick is disconnected and reconnected, it will get a new ID. * - * The ID value starts at 0 and increments from there. The value -1 is an invalid ID. + * The ID value starts at 0 and increments from there. The value -1 is an + * invalid ID. */ typedef Sint32 SDL_JoystickID; @@ -172,7 +182,7 @@ extern DECLSPEC int SDLCALL SDL_NumJoysticks(void); * 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) + * 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. * @@ -189,7 +199,7 @@ extern DECLSPEC const char *SDLCALL SDL_JoystickNameForIndex(int device_index); * 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) + * on the system). * \returns the path of the selected joystick. If no path can be found, this * function returns NULL; call SDL_GetError() for more information. * @@ -215,9 +225,9 @@ extern DECLSPEC int SDLCALL SDL_JoystickGetDevicePlayerIndex(int 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 + * on the system. * \returns the GUID of the selected joystick. If called on an invalid index, - * this function returns a zero GUID + * this function returns a zero GUID. * * \since This function is available since SDL 2.0.0. * @@ -233,9 +243,9 @@ extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetDeviceGUID(int device_in * available this function returns 0. * * \param device_index the index of the joystick to query (the N'th joystick - * on the system + * on the system. * \returns the USB vendor ID of the selected joystick. If called on an - * invalid index, this function returns zero + * invalid index, this function returns zero. * * \since This function is available since SDL 2.0.6. */ @@ -248,9 +258,9 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceVendor(int device_index); * available this function returns 0. * * \param device_index the index of the joystick to query (the N'th joystick - * on the system + * on the system. * \returns the USB product ID of the selected joystick. If called on an - * invalid index, this function returns zero + * invalid index, this function returns zero. * * \since This function is available since SDL 2.0.6. */ @@ -263,9 +273,9 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProduct(int device_index); * isn't available this function returns 0. * * \param device_index the index of the joystick to query (the N'th joystick - * on the system + * on the system. * \returns the product version of the selected joystick. If called on an - * invalid index, this function returns zero + * invalid index, this function returns zero. * * \since This function is available since SDL 2.0.6. */ @@ -277,9 +287,9 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProductVersion(int device_in * 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 + * on the system. * \returns the SDL_JoystickType of the selected joystick. If called on an - * invalid index, this function returns `SDL_JOYSTICK_TYPE_UNKNOWN` + * invalid index, this function returns `SDL_JOYSTICK_TYPE_UNKNOWN`. * * \since This function is available since SDL 2.0.6. */ @@ -291,7 +301,7 @@ extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetDeviceType(int device_in * 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 + * on the system. * \returns the instance id of the selected joystick. If called on an invalid * index, this function returns -1. * @@ -310,7 +320,7 @@ extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickGetDeviceInstanceID(int devic * The joystick subsystem must be initialized before a joystick can be opened * for use. * - * \param device_index the index of the joystick to query + * \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. * @@ -324,7 +334,7 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickOpen(int device_index); /** * Get the SDL_Joystick associated with an instance id. * - * \param instance_id the instance id to get the SDL_Joystick for + * \param instance_id 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. * @@ -335,7 +345,7 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickFromInstanceID(SDL_JoystickID /** * Get the SDL_Joystick associated with a player index. * - * \param player_index the player index to get the SDL_Joystick for + * \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. * @@ -358,8 +368,10 @@ extern DECLSPEC int SDLCALL SDL_JoystickAttachVirtual(SDL_JoystickType type, /** * The structure that defines an extended virtual joystick description * - * The caller must zero the structure and then initialize the version with `SDL_VIRTUAL_JOYSTICK_DESC_VERSION` before passing it to SDL_JoystickAttachVirtualEx() - * All other elements of this structure are optional and can be left 0. + * The caller must zero the structure and then initialize the version with + * `SDL_VIRTUAL_JOYSTICK_DESC_VERSION` before passing it to + * SDL_JoystickAttachVirtualEx() All other elements of this structure are + * optional and can be left 0. * * \sa SDL_JoystickAttachVirtualEx */ @@ -390,7 +402,7 @@ typedef struct SDL_VirtualJoystickDesc } SDL_VirtualJoystickDesc; /** - * \brief The current version of the SDL_VirtualJoystickDesc structure + * The current version of the SDL_VirtualJoystickDesc structure */ #define SDL_VIRTUAL_JOYSTICK_DESC_VERSION 1 @@ -407,7 +419,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickAttachVirtualEx(const SDL_VirtualJoystic * Detach a virtual joystick. * * \param device_index a value previously returned from - * SDL_JoystickAttachVirtual() + * SDL_JoystickAttachVirtual(). * \returns 0 on success, or -1 if an error occurred. * * \since This function is available since SDL 2.0.14. @@ -485,7 +497,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualHat(SDL_Joystick *joystick, in /** * Get the implementation dependent name of a joystick. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \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. * @@ -499,7 +511,7 @@ extern DECLSPEC const char *SDLCALL SDL_JoystickName(SDL_Joystick *joystick); /** * Get the implementation dependent path of a joystick. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the path of the selected joystick. If no path can be found, this * function returns NULL; call SDL_GetError() for more information. * @@ -515,7 +527,7 @@ extern DECLSPEC const char *SDLCALL SDL_JoystickPath(SDL_Joystick *joystick); * 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() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the player index, or -1 if it's not available. * * \since This function is available since SDL 2.0.9. @@ -525,7 +537,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickGetPlayerIndex(SDL_Joystick *joystick); /** * Set the player index of an opened joystick. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \param player_index Player index to assign to this joystick, or -1 to clear * the player index and turn off player LEDs. * @@ -538,7 +550,7 @@ extern DECLSPEC void SDLCALL SDL_JoystickSetPlayerIndex(SDL_Joystick *joystick, * * This function requires an open joystick. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \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. @@ -555,7 +567,7 @@ extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetGUID(SDL_Joystick *joyst * * If the vendor ID isn't available this function returns 0. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the USB vendor ID of the selected joystick, or 0 if unavailable. * * \since This function is available since SDL 2.0.6. @@ -567,7 +579,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetVendor(SDL_Joystick *joystick); * * If the product ID isn't available this function returns 0. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the USB product ID of the selected joystick, or 0 if unavailable. * * \since This function is available since SDL 2.0.6. @@ -579,7 +591,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProduct(SDL_Joystick *joystick); * * If the product version isn't available this function returns 0. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the product version of the selected joystick, or 0 if unavailable. * * \since This function is available since SDL 2.0.6. @@ -591,7 +603,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProductVersion(SDL_Joystick *joyst * * If the firmware version isn't available this function returns 0. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the firmware version of the selected joystick, or 0 if * unavailable. * @@ -604,7 +616,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetFirmwareVersion(SDL_Joystick *joys * * Returns the serial number of the joystick, or NULL if it is not available. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the serial number of the selected joystick, or NULL if * unavailable. * @@ -615,7 +627,7 @@ extern DECLSPEC const char * SDLCALL SDL_JoystickGetSerial(SDL_Joystick *joystic /** * Get the type of an opened joystick. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the SDL_JoystickType of the selected joystick. * * \since This function is available since SDL 2.0.6. @@ -627,9 +639,9 @@ extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetType(SDL_Joystick *joyst * * 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 + * \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. * * \since This function is available since SDL 2.0.0. * @@ -646,7 +658,7 @@ extern DECLSPEC void SDLCALL SDL_JoystickGetGUIDString(SDL_JoystickGUID guid, ch * 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 + * \param pchGUID string containing an ASCII representation of a GUID. * \returns a SDL_JoystickGUID structure. * * \since This function is available since SDL 2.0.0. @@ -658,15 +670,15 @@ extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetGUIDFromString(const cha /** * Get the device information encoded in a SDL_JoystickGUID structure * - * \param guid the SDL_JoystickGUID you wish to get info about + * \param guid the SDL_JoystickGUID you wish to get info about. * \param vendor A pointer filled in with the device VID, or 0 if not - * available + * available. * \param product A pointer filled in with the device PID, or 0 if not - * available + * available. * \param version A pointer filled in with the device version, or 0 if not - * available + * available. * \param crc16 A pointer filled in with a CRC used to distinguish different - * products with the same VID/PID, or 0 if not available + * products with the same VID/PID, or 0 if not available. * * \since This function is available since SDL 2.26.0. * @@ -677,7 +689,7 @@ extern DECLSPEC void SDLCALL SDL_GetJoystickGUIDInfo(SDL_JoystickGUID guid, Uint /** * Get the status of a specified joystick. * - * \param joystick the joystick to query + * \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. * @@ -691,7 +703,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAttached(SDL_Joystick *joystick) /** * Get the instance ID of an opened joystick. * - * \param joystick an SDL_Joystick structure containing joystick information + * \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. * @@ -708,7 +720,7 @@ extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickInstanceID(SDL_Joystick *joys * 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 + * \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. @@ -728,7 +740,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickNumAxes(SDL_Joystick *joystick); * * Most joysticks do not have trackballs. * - * \param joystick an SDL_Joystick structure containing joystick information + * \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. * @@ -741,7 +753,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(SDL_Joystick *joystick); /** * Get the number of POV hats on a joystick. * - * \param joystick an SDL_Joystick structure containing joystick information + * \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. * @@ -755,7 +767,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickNumHats(SDL_Joystick *joystick); /** * Get the number of buttons on a joystick. * - * \param joystick an SDL_Joystick structure containing joystick information + * \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. * @@ -794,10 +806,10 @@ extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void); * `SDL_ENABLE`, this function accepts any value, with any non-zero value that * isn't `SDL_QUERY` being treated as `SDL_ENABLE`. * - * If SDL was built with events disabled (extremely uncommon!), this will - * do nothing and always return `SDL_IGNORE`. + * If SDL was built with events disabled (extremely uncommon!), this will do + * nothing and always return `SDL_IGNORE`. * - * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE` + * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`. * \returns If `state` is `SDL_QUERY` then the current state is returned, * otherwise `state` is returned (even if it was not one of the * allowed values). @@ -808,6 +820,7 @@ extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void); */ extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state); +/* Limits for joystick axes... */ #define SDL_JOYSTICK_AXIS_MAX 32767 #define SDL_JOYSTICK_AXIS_MIN -32768 @@ -824,8 +837,8 @@ extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state); * 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 + * \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. * @@ -843,8 +856,8 @@ extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick *joystick, * * The axis indices start at index 0. * - * \param joystick an SDL_Joystick structure containing joystick information - * \param axis the axis to query; the axis indices start at index 0 + * \param 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. * @@ -883,8 +896,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAxisInitialState(SDL_Joystick *j * - `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; indices start at index 0 + * \param joystick an SDL_Joystick structure containing joystick information. + * \param hat the hat index to get the state from; indices start at index 0. * \returns the current hat position. * * \since This function is available since SDL 2.0.0. @@ -902,10 +915,10 @@ extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick *joystick, * * 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 + * \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. * @@ -919,9 +932,9 @@ extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick *joystick, /** * Get the current state of a button on a joystick. * - * \param joystick an SDL_Joystick structure containing joystick information + * \param joystick an SDL_Joystick structure containing joystick information. * \param button the button index to get the state from; indices start at - * index 0 + * index 0. * \returns 1 if the specified button is pressed, 0 otherwise. * * \since This function is available since SDL 2.0.0. @@ -937,13 +950,13 @@ extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick *joystick, * Each call to this function cancels any previous rumble effect, and calling * it with 0 intensity stops any rumbling. * - * \param joystick The joystick to vibrate + * \param joystick The joystick to vibrate. * \param low_frequency_rumble The intensity of the low frequency (left) - * rumble motor, from 0 to 0xFFFF + * 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 + * 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. * * \since This function is available since SDL 2.0.9. * @@ -962,13 +975,13 @@ extern DECLSPEC int SDLCALL SDL_JoystickRumble(SDL_Joystick *joystick, Uint16 lo * want the (more common) whole-controller rumble, use SDL_JoystickRumble() * instead. * - * \param joystick The joystick to vibrate + * \param joystick The joystick to vibrate. * \param left_rumble The intensity of the left trigger rumble motor, from 0 - * to 0xFFFF + * 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 + * 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. * * \since This function is available since SDL 2.0.14. * @@ -982,7 +995,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickRumbleTriggers(SDL_Joystick *joystick, U * An example of a joystick LED is the light on the back of a PlayStation 4's * DualShock 4 controller. * - * \param joystick The joystick to query + * \param joystick The joystick to query. * \return SDL_TRUE if the joystick has a modifiable LED, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.14. @@ -992,7 +1005,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasLED(SDL_Joystick *joystick); /** * Query whether a joystick has rumble support. * - * \param joystick The joystick to query + * \param joystick The joystick to query. * \return SDL_TRUE if the joystick has rumble, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.18. @@ -1004,7 +1017,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasRumble(SDL_Joystick *joystick); /** * Query whether a joystick has rumble support on triggers. * - * \param joystick The joystick to query + * \param joystick The joystick to query. * \return SDL_TRUE if the joystick has trigger rumble, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.18. @@ -1019,11 +1032,11 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasRumbleTriggers(SDL_Joystick *joy * An example of a joystick LED is the light on the back of a PlayStation 4's * DualShock 4 controller. * - * \param joystick The joystick to update - * \param red The intensity of the red LED - * \param green The intensity of the green LED - * \param blue The intensity of the blue LED - * \returns 0 on success, -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. * * \since This function is available since SDL 2.0.14. */ @@ -1032,10 +1045,11 @@ extern DECLSPEC int SDLCALL SDL_JoystickSetLED(SDL_Joystick *joystick, Uint8 red /** * Send a joystick specific effect packet * - * \param joystick The joystick to affect - * \param data The data to send to the joystick - * \param size The size of the data to send to the joystick - * \returns 0, or -1 if this joystick or driver doesn't support effect packets + * \param joystick The joystick to affect. + * \param data The data to send to the joystick. + * \param size The size of the data to send to the joystick. + * \returns 0, or -1 if this joystick or driver doesn't support effect + * packets. * * \since This function is available since SDL 2.0.16. */ @@ -1044,7 +1058,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickSendEffect(SDL_Joystick *joystick, const /** * Close a joystick previously opened with SDL_JoystickOpen(). * - * \param joystick The joystick device to close + * \param joystick The joystick device to close. * * \since This function is available since SDL 2.0.0. * @@ -1055,9 +1069,9 @@ extern DECLSPEC void SDLCALL SDL_JoystickClose(SDL_Joystick *joystick); /** * Get the battery level of a joystick as SDL_JoystickPowerLevel. * - * \param joystick the SDL_Joystick to query + * \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 + * `SDL_JOYSTICK_POWER_UNKNOWN` if it is unknown. * * \since This function is available since SDL 2.0.4. */ diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_keyboard.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_keyboard.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_keyboard.h + * # CategoryKeyboard * - * Include file for SDL keyboard event handling + * Include file for SDL keyboard event handling */ #ifndef SDL_keyboard_h_ @@ -40,14 +40,15 @@ extern "C" { #endif /** - * \brief The SDL keysym structure, used in key events. + * The SDL keysym structure, used in key events. * - * \note If you are looking for translated character input, see the ::SDL_TEXTINPUT event. + * If you are looking for translated character input, see the SDL_TEXTINPUT + * event. */ typedef struct SDL_Keysym { - SDL_Scancode scancode; /**< SDL physical key code - see ::SDL_Scancode for details */ - SDL_Keycode sym; /**< SDL virtual key code - see ::SDL_Keycode for details */ + SDL_Scancode scancode; /**< SDL physical key code - see SDL_Scancode for details */ + SDL_Keycode sym; /**< SDL virtual key code - see SDL_Keycode for details */ Uint16 mod; /**< current key modifiers */ Uint32 unused; } SDL_Keysym; @@ -84,7 +85,7 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); * 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 + * \param numkeys if non-NULL, receives the length of the returned array. * \returns a pointer to an array of key states. * * \since This function is available since SDL 2.0.0. @@ -129,7 +130,7 @@ extern DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void); * This does not change the keyboard state, only the key modifier flags that * SDL reports. * - * \param modstate the desired SDL_Keymod for the keyboard + * \param modstate the desired SDL_Keymod for the keyboard. * * \since This function is available since SDL 2.0.0. * @@ -143,7 +144,7 @@ extern DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate); * * See SDL_Keycode for details. * - * \param scancode the desired SDL_Scancode to query + * \param scancode the desired SDL_Scancode to query. * \returns the SDL_Keycode that corresponds to the given SDL_Scancode. * * \since This function is available since SDL 2.0.0. @@ -159,7 +160,7 @@ extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode * * See SDL_Scancode for details. * - * \param key the desired SDL_Keycode to query + * \param key the desired SDL_Keycode to query. * \returns the SDL_Scancode that corresponds to the given SDL_Keycode. * * \since This function is available since SDL 2.0.0. @@ -183,7 +184,7 @@ extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key); * unsuitable for creating a stable cross-platform two-way mapping between * strings and scancodes. * - * \param scancode the desired SDL_Scancode to query + * \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 (""). * @@ -197,7 +198,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_Scancode scancode); /** * Get a scancode from a human-readable name. * - * \param name the human-readable scancode name + * \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. * @@ -214,7 +215,7 @@ extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *name); * * See SDL_Scancode and SDL_Keycode for details. * - * \param key the desired SDL_Keycode to query + * \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 @@ -231,7 +232,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDL_Keycode key); /** * Get a key code from a human-readable name. * - * \param name the human-readable key name + * \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. * @@ -253,6 +254,10 @@ extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name); * * On some platforms using this function activates the screen keyboard. * + * On desktop platforms, SDL_StartTextInput() is implicitly called on SDL + * video subsystem initialization which will cause SDL_TextInputEvent and + * SDL_TextEditingEvent to begin emitting. + * * \since This function is available since SDL 2.0.0. * * \sa SDL_SetTextInputRect @@ -298,10 +303,11 @@ extern DECLSPEC void SDLCALL SDL_ClearComposition(void); extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputShown(void); /** - * Set the rectangle used to type Unicode text inputs. Native input methods - * will place a window with word suggestions near it, without covering the - * text being inputted. - * + * Set the rectangle used to type Unicode text inputs. + * + * Native input methods will place a window with word suggestions near it, + * without covering the text being inputted. + * * To start text input in a given location, this function is intended to be * called before SDL_StartTextInput, although some platforms support moving * the rectangle even while text input (and a composition) is active. @@ -311,7 +317,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputShown(void); * any feedback. * * \param rect the SDL_Rect structure representing the rectangle to receive - * text (ignored if NULL) + * text (ignored if NULL). * * \since This function is available since SDL 2.0.0. * @@ -335,7 +341,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void); /** * 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. * * \since This function is available since SDL 2.0.0. diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_keycode.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_keycode.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_keycode.h + * # CategoryKeycode * - * Defines constants which identify keyboard keys and modifiers. + * Defines constants which identify keyboard keys and modifiers. */ #ifndef SDL_keycode_h_ @@ -32,22 +32,22 @@ #include "SDL_scancode.h" /** - * \brief The SDL virtual key representation. + * The SDL virtual key representation. * - * Values of this type are used to represent keyboard keys using the current - * layout of the keyboard. These values include Unicode values representing - * the unmodified character that would be generated by pressing the key, or - * an SDLK_* constant for those keys that do not generate characters. + * Values of this type are used to represent keyboard keys using the current + * layout of the keyboard. These values include Unicode values representing + * the unmodified character that would be generated by pressing the key, or an + * SDLK_* constant for those keys that do not generate characters. * - * A special exception is the number keys at the top of the keyboard which - * map to SDLK_0...SDLK_9 on AZERTY layouts. + * A special exception is the number keys at the top of the keyboard which map + * to SDLK_0...SDLK_9 on AZERTY layouts. */ typedef Sint32 SDL_Keycode; #define SDLK_SCANCODE_MASK (1<<30) #define SDL_SCANCODE_TO_KEYCODE(X) (X | SDLK_SCANCODE_MASK) -typedef enum +typedef enum SDL_KeyCode { SDLK_UNKNOWN = 0, @@ -327,9 +327,9 @@ typedef enum } SDL_KeyCode; /** - * \brief Enumeration of valid key mods (possibly OR'd together). + * Enumeration of valid key mods (possibly OR'd together). */ -typedef enum +typedef enum SDL_Keymod { KMOD_NONE = 0x0000, KMOD_LSHIFT = 0x0001, diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_loadso.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_loadso.h @@ -19,23 +19,25 @@ 3. This notice may not be removed or altered from any source distribution. */ +/* WIKI CATEGORY: LoadSO */ + /** - * \file SDL_loadso.h - * - * System dependent library loading routines - * - * Some things to keep in mind: - * \li These functions only work on C function names. Other languages may - * have name mangling and intrinsic language support that varies from - * compiler to compiler. - * \li 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. - * \li Avoid namespace collisions. If you load a symbol from the library, - * it is not defined whether or not it goes into the global symbol - * namespace for the application. If it does and it conflicts with - * symbols in your code or other shared libraries, you will not get - * the results you expect. :) + * # CategoryLoadSO + * + * System-dependent library loading routines. + * + * Some things to keep in mind: + * + * - These functions only work on C function names. Other languages may have + * name mangling and intrinsic language support that varies from compiler to + * compiler. + * - Make sure you declare your function pointers with the same calling + * convention as the actual library function. Your code will crash + * mysteriously if you do not do this. + * - Avoid namespace collisions. If you load a symbol from the library, it is + * not defined whether or not it goes into the global symbol namespace for + * the application. If it does and it conflicts with symbols in your code or + * other shared libraries, you will not get the results you expect. :) */ #ifndef SDL_loadso_h_ @@ -53,7 +55,7 @@ extern "C" { /** * Dynamically load a shared object. * - * \param sofile a system-dependent name of the object file + * \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. * @@ -79,8 +81,8 @@ extern DECLSPEC void *SDLCALL SDL_LoadObject(const char *sofile); * * 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 + * \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. * @@ -95,7 +97,7 @@ extern DECLSPEC void *SDLCALL SDL_LoadFunction(void *handle, /** * Unload a shared object from memory. * - * \param handle a valid shared object handle returned by SDL_LoadObject() + * \param handle a valid shared object handle returned by SDL_LoadObject(). * * \since This function is available since SDL 2.0.0. * diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_locale.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_locale.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_locale.h + * # CategoryLocale * - * Include file for SDL locale services + * Include file for SDL locale services */ #ifndef _SDL_locale_h diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_log.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_log.h @@ -20,18 +20,19 @@ */ /** - * \file SDL_log.h + * # CategoryLog * - * Simple log messages with categories and priorities. + * Simple log messages with categories and priorities. * - * By default logs are quiet, but if you're debugging SDL you might want: + * By default logs are quiet, but if you're debugging SDL you might want: * - * SDL_LogSetAllPriority(SDL_LOG_PRIORITY_WARN); + * SDL_LogSetAllPriority(SDL_LOG_PRIORITY_WARN); * - * Here's where the messages go on different platforms: - * Windows: debug output stream - * Android: log output - * Others: standard error output (stderr) + * Here's where the messages go on different platforms: + * + * - Windows: debug output stream + * - Android: log output + * - Others: standard error output (stderr) */ #ifndef SDL_log_h_ @@ -47,21 +48,20 @@ extern "C" { /** - * \brief The maximum size of a log message prior to SDL 2.0.24 + * The maximum size of a log message prior to SDL 2.0.24 * - * As of 2.0.24 there is no limit to the length of SDL log messages. + * As of 2.0.24 there is no limit to the length of SDL log messages. */ #define SDL_MAX_LOG_MESSAGE 4096 /** - * \brief The predefined log categories + * The predefined log categories * - * By default the application category is enabled at the INFO level, - * the assert category is enabled at the WARN level, test is enabled - * at the VERBOSE level and all other categories are enabled at the - * ERROR level. + * By default the application category is enabled at the INFO level, the + * assert category is enabled at the WARN level, test is enabled at the + * VERBOSE level and all other categories are enabled at the ERROR level. */ -typedef enum +typedef enum SDL_LogCategory { SDL_LOG_CATEGORY_APPLICATION, SDL_LOG_CATEGORY_ERROR, @@ -97,9 +97,9 @@ typedef enum } SDL_LogCategory; /** - * \brief The predefined log priorities + * The predefined log priorities */ -typedef enum +typedef enum SDL_LogPriority { SDL_LOG_PRIORITY_VERBOSE = 1, SDL_LOG_PRIORITY_DEBUG, @@ -114,7 +114,7 @@ typedef enum /** * Set the priority of all log categories. * - * \param priority the SDL_LogPriority to assign + * \param priority the SDL_LogPriority to assign. * * \since This function is available since SDL 2.0.0. * @@ -125,8 +125,8 @@ extern DECLSPEC void SDLCALL SDL_LogSetAllPriority(SDL_LogPriority priority); /** * Set the priority of a particular log category. * - * \param category the category to assign a priority to - * \param priority the SDL_LogPriority to assign + * \param category the category to assign a priority to. + * \param priority the SDL_LogPriority to assign. * * \since This function is available since SDL 2.0.0. * @@ -139,8 +139,8 @@ extern DECLSPEC void SDLCALL SDL_LogSetPriority(int category, /** * Get the priority of a particular log category. * - * \param category the category to query - * \returns the SDL_LogPriority for the requested category + * \param category the category to query. + * \returns the SDL_LogPriority for the requested category. * * \since This function is available since SDL 2.0.0. * @@ -166,7 +166,7 @@ extern DECLSPEC void SDLCALL SDL_LogResetPriorities(void); * = * \param fmt a printf() style message format string * * \param ... additional parameters matching % tokens in the `fmt` string, if - * any + * any. * * \since This function is available since SDL 2.0.0. * @@ -184,10 +184,10 @@ extern DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, . /** * Log a message with SDL_LOG_PRIORITY_VERBOSE. * - * \param category the category of the message - * \param fmt a printf() style message format string + * \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 + * if any. * * \since This function is available since SDL 2.0.0. * @@ -205,10 +205,10 @@ extern DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRI /** * Log a message with SDL_LOG_PRIORITY_DEBUG. * - * \param category the category of the message - * \param fmt a printf() style message format string + * \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 + * if any. * * \since This function is available since SDL 2.0.0. * @@ -226,10 +226,10 @@ extern DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_STRING /** * Log a message with SDL_LOG_PRIORITY_INFO. * - * \param category the category of the message - * \param fmt a printf() style message format string + * \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 + * if any. * * \since This function is available since SDL 2.0.0. * @@ -247,10 +247,10 @@ extern DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STRING /** * Log a message with SDL_LOG_PRIORITY_WARN. * - * \param category the category of the message - * \param fmt a printf() style message format string + * \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 + * if any. * * \since This function is available since SDL 2.0.0. * @@ -268,10 +268,10 @@ extern DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING /** * Log a message with SDL_LOG_PRIORITY_ERROR. * - * \param category the category of the message - * \param fmt a printf() style message format string + * \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 + * if any. * * \since This function is available since SDL 2.0.0. * @@ -289,10 +289,10 @@ extern DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING /** * Log a message with SDL_LOG_PRIORITY_CRITICAL. * - * \param category the category of the message - * \param fmt a printf() style message format string + * \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 + * if any. * * \since This function is available since SDL 2.0.0. * @@ -310,11 +310,11 @@ extern DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT_STR /** * 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 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 + * if any. * * \since This function is available since SDL 2.0.0. * @@ -334,10 +334,10 @@ extern DECLSPEC void SDLCALL SDL_LogMessage(int category, /** * 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 + * \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. * @@ -359,10 +359,11 @@ extern DECLSPEC void SDLCALL SDL_LogMessageV(int category, * * 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 + * \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); @@ -370,9 +371,9 @@ typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_ * Get the current log output function. * * \param callback an SDL_LogOutputFunction filled in with the current log - * callback + * callback. * \param userdata a pointer filled in with the pointer that is passed to - * `callback` + * `callback`. * * \since This function is available since SDL 2.0.0. * @@ -383,8 +384,8 @@ extern DECLSPEC void SDLCALL SDL_LogGetOutputFunction(SDL_LogOutputFunction *cal /** * 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` + * \param callback an SDL_LogOutputFunction to call instead of the default. + * \param userdata a pointer that is passed to `callback`. * * \since This function is available since SDL 2.0.0. * diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_main.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_main.h @@ -25,9 +25,9 @@ #include "SDL_stdinc.h" /** - * \file SDL_main.h + * # CategoryMain * - * Redefine main() on some platforms so that it is called by SDL. + * Redefine main() on some platforms so that it is called by SDL. */ #ifndef SDL_MAIN_HANDLED @@ -129,14 +129,14 @@ * * The application's main() function must be called with C linkage, * and should be declared like this: - * \code + * ```c * #ifdef __cplusplus * extern "C" * #endif * int main(int argc, char *argv[]) * { * } - * \endcode + * ``` */ #if defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE) @@ -149,7 +149,7 @@ extern "C" { #endif /** - * The prototype for the application's main() function + * The prototype for the application's main() function */ typedef int (*SDL_main_func)(int argc, char *argv[]); extern SDLMAIN_DECLSPEC int SDL_main(int argc, char *argv[]); @@ -222,8 +222,8 @@ extern DECLSPEC void SDLCALL SDL_UnregisterApp(void); /** * Initialize and launch an SDL/WinRT application. * - * \param mainFunction the SDL app's C-style main(), an SDL_main_func - * \param reserved reserved for future use; should be NULL + * \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. * @@ -238,10 +238,10 @@ extern DECLSPEC int SDLCALL SDL_WinRTRunApp(SDL_main_func mainFunction, void * r /** * 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(), an SDL_main_func - * \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. * * \since This function is available since SDL 2.0.10. */ @@ -254,8 +254,8 @@ extern DECLSPEC int SDLCALL SDL_UIKitRunApp(int argc, char *argv[], SDL_main_fun /** * Initialize and launch an SDL GDK application. * - * \param mainFunction the SDL app's C-style main(), an SDL_main_func - * \param reserved reserved for future use; should be NULL + * \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. * diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_messagebox.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_messagebox.h @@ -32,9 +32,11 @@ extern "C" { #endif /** - * SDL_MessageBox flags. If supported will display warning icon, etc. + * SDL_MessageBox flags. + * + * If supported will display warning icon, etc. */ -typedef enum +typedef enum SDL_MessageBoxFlags { SDL_MESSAGEBOX_ERROR = 0x00000010, /**< error dialog */ SDL_MESSAGEBOX_WARNING = 0x00000020, /**< warning dialog */ @@ -46,7 +48,7 @@ typedef enum /** * Flags for SDL_MessageBoxButtonData. */ -typedef enum +typedef enum SDL_MessageBoxButtonFlags { SDL_MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT = 0x00000001, /**< Marks the default button when return is hit */ SDL_MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT = 0x00000002 /**< Marks the default button when escape is hit */ @@ -55,9 +57,9 @@ typedef enum /** * Individual button data. */ -typedef struct +typedef struct SDL_MessageBoxButtonData { - Uint32 flags; /**< ::SDL_MessageBoxButtonFlags */ + Uint32 flags; /**< SDL_MessageBoxButtonFlags */ int buttonid; /**< User defined button id (value returned via SDL_ShowMessageBox) */ const char * text; /**< The UTF-8 button text */ } SDL_MessageBoxButtonData; @@ -65,12 +67,12 @@ typedef struct /** * RGB value used in a message box color scheme */ -typedef struct +typedef struct SDL_MessageBoxColor { Uint8 r, g, b; } SDL_MessageBoxColor; -typedef enum +typedef enum SDL_MessageBoxColorType { SDL_MESSAGEBOX_COLOR_BACKGROUND, SDL_MESSAGEBOX_COLOR_TEXT, @@ -83,7 +85,7 @@ typedef enum /** * A set of colors to use for message box dialogs */ -typedef struct +typedef struct SDL_MessageBoxColorScheme { SDL_MessageBoxColor colors[SDL_MESSAGEBOX_COLOR_MAX]; } SDL_MessageBoxColorScheme; @@ -91,9 +93,9 @@ typedef struct /** * MessageBox structure containing title, text, window, etc. */ -typedef struct +typedef struct SDL_MessageBoxData { - Uint32 flags; /**< ::SDL_MessageBoxFlags */ + Uint32 flags; /**< SDL_MessageBoxFlags */ SDL_Window *window; /**< Parent window, can be NULL */ const char *title; /**< UTF-8 title */ const char *message; /**< UTF-8 message text */ @@ -101,7 +103,7 @@ typedef struct int numbuttons; const SDL_MessageBoxButtonData *buttons; - const SDL_MessageBoxColorScheme *colorScheme; /**< ::SDL_MessageBoxColorScheme, can be NULL to use system settings */ + const SDL_MessageBoxColorScheme *colorScheme; /**< SDL_MessageBoxColorScheme, can be NULL to use system settings */ } SDL_MessageBoxData; /** @@ -128,8 +130,9 @@ typedef struct * 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 + * 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. * @@ -168,10 +171,10 @@ extern DECLSPEC int SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *message * 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 + * \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. * diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_metal.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_metal.h @@ -20,9 +20,10 @@ */ /** - * \file SDL_metal.h + * # CategoryMetal * - * Header file for functions to creating Metal layers and views on SDL windows. + * Header file for functions to creating Metal layers and views on SDL + * windows. */ #ifndef SDL_metal_h_ @@ -37,9 +38,9 @@ extern "C" { #endif /** - * \brief A handle to a CAMetalLayer-backed NSView (macOS) or UIView (iOS/tvOS). + * A handle to a CAMetalLayer-backed NSView (macOS) or UIView (iOS/tvOS). * - * \note This can be cast directly to an NSView or UIView. + * This can be cast directly to an NSView or UIView. */ typedef void *SDL_MetalView; @@ -90,9 +91,9 @@ extern DECLSPEC void *SDLCALL SDL_Metal_GetLayer(SDL_MetalView view); * 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 + * \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. * * \since This function is available since SDL 2.0.14. * diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_misc.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_misc.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_misc.h + * # CategoryMisc * - * \brief Include file for SDL API functions that don't fit elsewhere. + * Include file for SDL API functions that don't fit elsewhere. */ #ifndef SDL_misc_h_ diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_mouse.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_mouse.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_mouse.h + * # CategoryMouse * - * Include file for SDL mouse event handling. + * Include file for SDL mouse event handling. */ #ifndef SDL_mouse_h_ @@ -41,9 +41,9 @@ extern "C" { typedef struct SDL_Cursor SDL_Cursor; /**< Implementation dependent */ /** - * \brief Cursor types for SDL_CreateSystemCursor(). + * Cursor types for SDL_CreateSystemCursor(). */ -typedef enum +typedef enum SDL_SystemCursor { SDL_SYSTEM_CURSOR_ARROW, /**< Arrow */ SDL_SYSTEM_CURSOR_IBEAM, /**< I-beam */ @@ -61,9 +61,9 @@ typedef enum } SDL_SystemCursor; /** - * \brief Scroll direction types for the Scroll event + * Scroll direction types for the Scroll event */ -typedef enum +typedef enum SDL_MouseWheelDirection { SDL_MOUSEWHEEL_NORMAL, /**< The scroll direction is normal */ SDL_MOUSEWHEEL_FLIPPED /**< The scroll direction is flipped / natural */ @@ -90,9 +90,9 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void); * either `x` or `y`. * * \param x the x coordinate of the mouse cursor position relative to the - * focus window + * focus window. * \param y the y coordinate of the mouse cursor position relative to the - * focus window + * focus window. * \returns a 32-bit button bitmask of the current button state. * * \since This function is available since SDL 2.0.0. @@ -120,9 +120,9 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetMouseState(int *x, int *y); * reason to use this function, you probably want SDL_GetMouseState() instead. * * \param x filled in with the current X coord relative to the desktop; can be - * NULL + * NULL. * \param y filled in with the current Y coord relative to the desktop; can be - * NULL + * NULL. * \returns the current button state as a bitmask which can be tested using * the SDL_BUTTON(X) macros. * @@ -141,8 +141,8 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetGlobalMouseState(int *x, int *y); * 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 + * \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. * * \since This function is available since SDL 2.0.0. @@ -162,9 +162,9 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetRelativeMouseState(int *x, int *y); * mouse when used over Microsoft Remote Desktop. * * \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 + * mouse focus. + * \param x the x coordinate within the window. + * \param y the y coordinate within the window. * * \since This function is available since SDL 2.0.0. * @@ -184,8 +184,8 @@ extern DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * window, * Note that this function will appear to succeed, but not actually move the * mouse when used over Microsoft Remote Desktop. * - * \param x the x coordinate - * \param y the y coordinate + * \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. * @@ -297,14 +297,14 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(void); * 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 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 + * 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 + * 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. * @@ -322,9 +322,9 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data, /** * Create a color cursor. * - * \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 + * \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. * @@ -340,7 +340,7 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateColorCursor(SDL_Surface *surface, /** * Create a system cursor. * - * \param id an SDL_SystemCursor enum value + * \param id an SDL_SystemCursor enum value. * \returns a cursor on success or NULL on failure; call SDL_GetError() for * more information. * @@ -358,7 +358,7 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor id); * 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 + * \param cursor a cursor to make active. * * \since This function is available since SDL 2.0.0. * @@ -402,7 +402,7 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetDefaultCursor(void); * Use this function to free cursor resources created with SDL_CreateCursor(), * SDL_CreateColorCursor() or SDL_CreateSystemCursor(). * - * \param cursor the cursor to free + * \param cursor the cursor to free. * * \since This function is available since SDL 2.0.0. * @@ -437,9 +437,9 @@ extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle); /** * Used as a mask when testing buttons in buttonstate. * - * - Button 1: Left mouse button - * - Button 2: Middle mouse button - * - Button 3: Right mouse button + * - Button 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 diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_mutex.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_mutex.h @@ -23,9 +23,9 @@ #define SDL_mutex_h_ /** - * \file SDL_mutex.h + * # CategoryMutex * - * Functions to provide thread synchronization primitives. + * Functions to provide thread synchronization primitives. */ #include "SDL_stdinc.h" @@ -112,13 +112,13 @@ extern "C" { #endif /** - * Synchronization functions which can time out return this value - * if they time out. + * Synchronization functions which can time out return this value if they time + * out. */ #define SDL_MUTEX_TIMEDOUT 1 /** - * This is the timeout value which corresponds to never time out. + * This is the timeout value which corresponds to never time out. */ #define SDL_MUTEX_MAXWAIT (~(Uint32)0) @@ -165,7 +165,7 @@ extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void); * 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 + * \param mutex the mutex to lock. * \return 0, or -1 on error. * * \since This function is available since SDL 2.0.0. @@ -182,7 +182,7 @@ extern DECLSPEC int SDLCALL SDL_LockMutex(SDL_mutex * mutex) SDL_ACQUIRE(mutex); * 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 + * \param mutex the mutex to try to lock. * \returns 0, `SDL_MUTEX_TIMEDOUT`, or -1 on error; call SDL_GetError() for * more information. * @@ -224,7 +224,7 @@ extern DECLSPEC int SDLCALL SDL_UnlockMutex(SDL_mutex * mutex) SDL_RELEASE(mutex * to destroy a locked mutex, and may result in undefined behavior depending * on the platform. * - * \param mutex the mutex to destroy + * \param mutex the mutex to destroy. * * \since This function is available since SDL 2.0.0. * @@ -256,7 +256,7 @@ typedef struct SDL_semaphore SDL_sem; * 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 + * \param initial_value the starting value of the semaphore. * \returns a new semaphore or NULL on failure; call SDL_GetError() for more * information. * @@ -277,7 +277,7 @@ extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value); * It is not safe to destroy a semaphore if there are threads currently * waiting on it. * - * \param sem the semaphore to destroy + * \param sem the semaphore to destroy. * * \since This function is available since SDL 2.0.0. * @@ -301,7 +301,7 @@ extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem); * This function is the equivalent of calling SDL_SemWaitTimeout() with a time * length of `SDL_MUTEX_MAXWAIT`. * - * \param sem the semaphore wait on + * \param sem the semaphore wait on. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -325,7 +325,7 @@ extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem); * the semaphore doesn't have a positive value, the function immediately * returns SDL_MUTEX_TIMEDOUT. * - * \param sem the semaphore to wait on + * \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. @@ -349,8 +349,8 @@ extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem); * signal or error, or the specified time has elapsed. If the call is * successful it will atomically decrement the semaphore value. * - * \param sem the semaphore to wait on - * \param timeout the length of the timeout, in milliseconds + * \param sem the semaphore to wait on. + * \param timeout 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. @@ -369,7 +369,7 @@ extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem *sem, Uint32 timeout); /** * Atomically increment a semaphore's value and wake waiting threads. * - * \param sem the semaphore to increment + * \param sem the semaphore to increment. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -387,7 +387,7 @@ extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem); /** * Get the current value of a semaphore. * - * \param sem the semaphore to query + * \param sem the semaphore to query. * \returns the current value of the semaphore. * * \since This function is available since SDL 2.0.0. @@ -427,7 +427,7 @@ extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void); /** * Destroy a condition variable. * - * \param cond the condition variable to destroy + * \param cond the condition variable to destroy. * * \since This function is available since SDL 2.0.0. * @@ -442,7 +442,7 @@ extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * cond); /** * Restart one of the threads that are waiting on the condition variable. * - * \param cond the condition variable to signal + * \param cond the condition variable to signal. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -459,7 +459,7 @@ extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * cond); /** * Restart all threads that are waiting on the condition variable. * - * \param cond the condition variable to signal + * \param cond the condition variable to signal. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -486,8 +486,8 @@ extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond); * 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 + * \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. * @@ -512,10 +512,10 @@ extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mutex); * * 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 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 + * 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. diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_opengl.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_opengl.h @@ -19,17 +19,11 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** - * \file SDL_opengl.h - * - * This is a simple file to encapsulate the OpenGL API headers. - */ - -/** - * \def NO_SDL_GLEXT +/* + * This is a simple file to encapsulate the OpenGL API headers. * - * Define this if you have your own version of glext.h and want to disable the - * version included in SDL_opengl.h. + * Define NO_SDL_GLEXT if you have your own version of glext.h and want + * to disable the version included in SDL_opengl.h. */ #ifndef SDL_opengl_h_ diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_opengles.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_opengles.h @@ -19,11 +19,10 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** - * \file SDL_opengles.h - * - * This is a simple file to encapsulate the OpenGL ES 1.X API headers. +/* + * This is a simple file to encapsulate the OpenGL ES 1.X API headers. */ + #include "SDL_config.h" #ifdef __IPHONEOS__ diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_opengles2.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_opengles2.h @@ -19,11 +19,10 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** - * \file SDL_opengles2.h - * - * This is a simple file to encapsulate the OpenGL ES 2.0 API headers. +/* + * This is a simple file to encapsulate the OpenGL ES 2.0 API headers. */ + #include "SDL_config.h" #if !defined(_MSC_VER) && !defined(SDL_USE_BUILTIN_OPENGL_DEFINITIONS) diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_pixels.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_pixels.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_pixels.h + * # CategoryPixels * - * Header for the enumerated pixel format definitions. + * Header for the enumerated pixel format definitions. */ #ifndef SDL_pixels_h_ @@ -320,9 +320,10 @@ typedef enum } SDL_PixelFormatEnum; /** - * The bits of this structure can be directly reinterpreted as an integer-packed - * color which uses the SDL_PIXELFORMAT_RGBA32 format (SDL_PIXELFORMAT_ABGR8888 - * on little-endian systems and SDL_PIXELFORMAT_RGBA8888 on big-endian systems). + * The bits of this structure can be directly reinterpreted as an + * integer-packed color which uses the SDL_PIXELFORMAT_RGBA32 format + * (SDL_PIXELFORMAT_ABGR8888 on little-endian systems and + * SDL_PIXELFORMAT_RGBA8888 on big-endian systems). */ typedef struct SDL_Color { @@ -342,7 +343,30 @@ typedef struct SDL_Palette } SDL_Palette; /** - * \note Everything in the pixel format structure is read-only. + * A structure that contains pixel format information. + * + * Everything in the pixel format structure is read-only. + * + * A pixel format has either a palette or masks. If a palette is used `Rmask`, + * `Gmask`, `Bmask`, and `Amask` will be 0. + * + * An SDL_PixelFormat describes the format of the pixel data stored at the + * `pixels` field of an SDL_Surface. Every surface stores an SDL_PixelFormat + * in the `format` field. + * + * If you wish to do pixel level modifications on a surface, then + * understanding how SDL stores its color information is essential. + * + * For information on modern pixel color spaces, see the following Wikipedia + * article: http://en.wikipedia.org/wiki/RGBA_color_space + * + * \sa SDL_ConvertSurface + * \sa SDL_GetRGB + * \sa SDL_GetRGBA + * \sa SDL_MapRGB + * \sa SDL_MapRGBA + * \sa SDL_AllocFormat + * \sa SDL_FreeFormat */ typedef struct SDL_PixelFormat { @@ -370,7 +394,7 @@ typedef struct SDL_PixelFormat /** * Get the human readable name of a pixel format. * - * \param format the pixel format to query + * \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. * @@ -381,12 +405,12 @@ extern DECLSPEC const char* SDLCALL SDL_GetPixelFormatName(Uint32 format); /** * Convert one of the enumerated pixel formats to a bpp value and RGBA masks. * - * \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 + * \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. * @@ -407,12 +431,12 @@ extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format, * This will return `SDL_PIXELFORMAT_UNKNOWN` if the conversion wasn't * possible. * - * \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 + * \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. * * \since This function is available since SDL 2.0.0. * @@ -431,7 +455,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp, * 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 + * \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. * @@ -444,7 +468,7 @@ extern DECLSPEC SDL_PixelFormat * SDLCALL SDL_AllocFormat(Uint32 pixel_format); /** * Free an SDL_PixelFormat structure allocated by SDL_AllocFormat(). * - * \param format the SDL_PixelFormat structure to free + * \param format the SDL_PixelFormat structure to free. * * \since This function is available since SDL 2.0.0. * @@ -457,7 +481,7 @@ extern DECLSPEC void SDLCALL SDL_FreeFormat(SDL_PixelFormat *format); * * The palette entries are initialized to white. * - * \param ncolors represents the number of color entries in the color palette + * \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. @@ -471,8 +495,8 @@ extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors); /** * 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 + * \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. * @@ -487,10 +511,10 @@ extern DECLSPEC int SDLCALL SDL_SetPixelFormatPalette(SDL_PixelFormat * format, /** * Set a range of colors in a palette. * - * \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 + * \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. * @@ -506,7 +530,7 @@ extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette, /** * Free a palette created with SDL_AllocPalette(). * - * \param palette the SDL_Palette structure to be freed + * \param palette the SDL_Palette structure to be freed. * * \since This function is available since SDL 2.0.0. * @@ -532,11 +556,11 @@ extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette); * 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 + * \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. * * \since This function is available since SDL 2.0.0. * @@ -566,12 +590,12 @@ extern DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format, * 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 + * 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. * * \since This function is available since SDL 2.0.0. * @@ -591,12 +615,12 @@ extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format, * (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 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 + * 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. * * \since This function is available since SDL 2.0.0. * @@ -619,13 +643,13 @@ extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, * If the surface has no alpha component, the alpha will be returned as 0xff * (100% opaque). * - * \param pixel a pixel value + * \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 + * 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. * * \since This function is available since SDL 2.0.0. * @@ -641,8 +665,8 @@ extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel, /** * 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 + * \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. * * \since This function is available since SDL 2.0.0. * diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_platform.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_platform.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_platform.h + * # CategoryPlatform * - * Try to get a standard set of platform defines. + * Try to get a standard set of platform defines. */ #ifndef SDL_platform_h_ diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_power.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_power.h @@ -23,9 +23,9 @@ #define SDL_power_h_ /** - * \file SDL_power.h + * # CategoryPower * - * Header for the SDL power management routines. + * Header for the SDL power management routines. */ #include "SDL_stdinc.h" @@ -37,9 +37,9 @@ extern "C" { #endif /** - * The basic state for the system's power supply. + * The basic state for the system's power supply. */ -typedef enum +typedef enum SDL_PowerState { SDL_POWERSTATE_UNKNOWN, /**< cannot determine power status */ SDL_POWERSTATE_ON_BATTERY, /**< Not plugged in, running on the battery */ @@ -66,10 +66,10 @@ typedef enum * * \param seconds 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 + * value, or we're not running on a battery. * \param percent 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 + * can't determine a value, or we're not running on a battery. * \returns an SDL_PowerState enum representing the current battery state. * * \since This function is available since SDL 2.0.0. diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_quit.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_quit.h @@ -20,9 +20,20 @@ */ /** - * \file SDL_quit.h + * # CategoryQuit * - * Include file for SDL quit event handling. + * An SDL_QUIT event is generated when the user tries to close the application + * window. If it is ignored or filtered out, the window will remain open. If + * it is not ignored or filtered, it is queued normally and the window is + * allowed to close. When the window is closed, screen updates will complete, + * but have no effect. + * + * SDL_Init() installs signal handlers for SIGINT (keyboard interrupt) and + * SIGTERM (system termination request), if handlers do not already exist, + * that generate SDL_QUIT events as well. There is no way to determine the + * cause of an SDL_QUIT event, but setting a signal handler in your + * application will override the default generation of quit events for that + * signal. */ #ifndef SDL_quit_h_ @@ -31,25 +42,6 @@ #include "SDL_stdinc.h" #include "SDL_error.h" -/** - * \file SDL_quit.h - * - * An ::SDL_QUIT event is generated when the user tries to close the application - * window. If it is ignored or filtered out, the window will remain open. - * If it is not ignored or filtered, it is queued normally and the window - * is allowed to close. When the window is closed, screen updates will - * complete, but have no effect. - * - * SDL_Init() installs signal handlers for SIGINT (keyboard interrupt) - * and SIGTERM (system termination request), if handlers do not already - * exist, that generate ::SDL_QUIT events as well. There is no way - * to determine the cause of an ::SDL_QUIT event, but setting a signal - * handler in your application will override the default generation of - * quit events for that signal. - * - * \sa SDL_Quit() - */ - /* There are no functions directly affecting the quit event */ #define SDL_QuitRequested() \ diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_rect.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_rect.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_rect.h + * # CategoryRect * - * Header file for SDL_rect definition and management functions. + * Header file for SDL_rect definition and management functions. */ #ifndef SDL_rect_h_ @@ -135,8 +135,8 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEquals(const SDL_Rect *a, const SDL_Rect *b) * * 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 + * \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. @@ -151,10 +151,10 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasIntersection(const SDL_Rect * A, * * 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 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` + * 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. @@ -168,10 +168,10 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IntersectRect(const SDL_Rect * A, /** * 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 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` + * `A` and `B`. * * \since This function is available since SDL 2.0.0. */ @@ -186,11 +186,11 @@ extern DECLSPEC void SDLCALL SDL_UnionRect(const SDL_Rect * A, * 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 + * 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 + * rectangle. * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the * points were outside of the clipping rectangle. * @@ -210,11 +210,11 @@ extern DECLSPEC SDL_bool SDLCALL SDL_EnclosePoints(const SDL_Point * points, * 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 + * \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. * * \since This function is available since SDL 2.0.0. @@ -274,8 +274,8 @@ SDL_FORCE_INLINE SDL_bool SDL_FRectEquals(const SDL_FRect *a, const SDL_FRect *b * * If either pointer is NULL the function will return SDL_FALSE. * - * \param A an SDL_FRect structure representing the first rectangle - * \param B an SDL_FRect structure representing the second rectangle + * \param A an SDL_FRect structure representing the first rectangle. + * \param B an SDL_FRect 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.22. @@ -290,10 +290,10 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasIntersectionF(const SDL_FRect * A, * * If `result` is NULL then this function will return SDL_FALSE. * - * \param A an SDL_FRect structure representing the first rectangle - * \param B an SDL_FRect structure representing the second rectangle + * \param A an SDL_FRect structure representing the first rectangle. + * \param B an SDL_FRect structure representing the second rectangle. * \param result an SDL_FRect structure filled in with the intersection of - * rectangles `A` and `B` + * rectangles `A` and `B`. * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.22. @@ -307,10 +307,10 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IntersectFRect(const SDL_FRect * A, /** * Calculate the union of two rectangles with float precision. * - * \param A an SDL_FRect structure representing the first rectangle - * \param B an SDL_FRect structure representing the second rectangle + * \param A an SDL_FRect structure representing the first rectangle. + * \param B an SDL_FRect structure representing the second rectangle. * \param result an SDL_FRect structure filled in with the union of rectangles - * `A` and `B` + * `A` and `B`. * * \since This function is available since SDL 2.0.22. */ @@ -326,11 +326,11 @@ extern DECLSPEC void SDLCALL SDL_UnionFRect(const SDL_FRect * A, * considered. * * \param points an array of SDL_FPoint structures representing points to be - * enclosed - * \param count the number of structures in the `points` array - * \param clip an SDL_FRect used for clipping or NULL to enclose all points + * enclosed. + * \param count the number of structures in the `points` array. + * \param clip an SDL_FRect used for clipping or NULL to enclose all points. * \param result an SDL_FRect structure filled in with the minimal enclosing - * rectangle + * rectangle. * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the * points were outside of the clipping rectangle. * @@ -351,11 +351,11 @@ extern DECLSPEC SDL_bool SDLCALL SDL_EncloseFPoints(const SDL_FPoint * points, * 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_FRect 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 + * \param rect an SDL_FRect 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. * * \since This function is available since SDL 2.0.22. diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_render.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_render.h @@ -20,29 +20,30 @@ */ /** - * \file SDL_render.h + * # CategoryRender * - * Header file for SDL 2D rendering functions. + * Header file for SDL 2D rendering functions. * - * This API supports the following features: - * * single pixel points - * * single pixel lines - * * filled rectangles - * * texture images + * This API supports the following features: * - * The primitives may be drawn in opaque, blended, or additive modes. + * - single pixel points + * - single pixel lines + * - filled rectangles + * - texture images * - * The texture images may be drawn in opaque, blended, or additive modes. - * They can have an additional color tint or alpha modulation applied to - * them, and may also be stretched with linear interpolation. + * The primitives may be drawn in opaque, blended, or additive modes. * - * This API is designed to accelerate simple 2D operations. You may - * want more functionality such as polygons and particle effects and - * in that case you should use SDL's OpenGL/Direct3D support or one - * of the many good 3D engines. + * The texture images may be drawn in opaque, blended, or additive modes. They + * can have an additional color tint or alpha modulation applied to them, and + * may also be stretched with linear interpolation. * - * These functions must be called from the main thread. - * See this bug for details: https://github.com/libsdl-org/SDL/issues/986 + * This API is designed to accelerate simple 2D operations. You may want more + * functionality such as polygons and particle effects and in that case you + * should use SDL's OpenGL/Direct3D support or one of the many good 3D + * engines. + * + * These functions must be called from the main thread. See this bug for + * details: https://github.com/libsdl-org/SDL/issues/986 */ #ifndef SDL_render_h_ @@ -61,7 +62,7 @@ extern "C" { /** * Flags used when creating a rendering context */ -typedef enum +typedef enum SDL_RendererFlags { SDL_RENDERER_SOFTWARE = 0x00000001, /**< The renderer is a software fallback */ SDL_RENDERER_ACCELERATED = 0x00000002, /**< The renderer uses hardware @@ -78,7 +79,7 @@ typedef enum typedef struct SDL_RendererInfo { const char *name; /**< The name of the renderer */ - Uint32 flags; /**< Supported ::SDL_RendererFlags */ + Uint32 flags; /**< Supported SDL_RendererFlags */ Uint32 num_texture_formats; /**< The number of available texture formats */ Uint32 texture_formats[16]; /**< The available texture formats */ int max_texture_width; /**< The maximum texture width */ @@ -86,7 +87,7 @@ typedef struct SDL_RendererInfo } SDL_RendererInfo; /** - * Vertex structure + * Vertex structure */ typedef struct SDL_Vertex { @@ -98,7 +99,7 @@ typedef struct SDL_Vertex /** * The scaling mode for a texture. */ -typedef enum +typedef enum SDL_ScaleMode { SDL_ScaleModeNearest, /**< nearest pixel sampling */ SDL_ScaleModeLinear, /**< linear filtering */ @@ -108,7 +109,7 @@ typedef enum /** * The access pattern allowed for a texture. */ -typedef enum +typedef enum SDL_TextureAccess { SDL_TEXTUREACCESS_STATIC, /**< Changes rarely, not lockable */ SDL_TEXTUREACCESS_STREAMING, /**< Changes frequently, lockable */ @@ -118,7 +119,7 @@ typedef enum /** * The texture channel modulation used in SDL_RenderCopy(). */ -typedef enum +typedef enum SDL_TextureModulate { SDL_TEXTUREMODULATE_NONE = 0x00000000, /**< No modulation */ SDL_TEXTUREMODULATE_COLOR = 0x00000001, /**< srcC = srcC * color */ @@ -128,7 +129,7 @@ typedef enum /** * Flip constants for SDL_RenderCopyEx */ -typedef enum +typedef enum SDL_RendererFlip { SDL_FLIP_NONE = 0x00000000, /**< Do not flip */ SDL_FLIP_HORIZONTAL = 0x00000001, /**< flip horizontally */ @@ -171,9 +172,9 @@ extern DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void); /** * Get info about a specific 2D rendering driver for the current display. * - * \param index the index of the driver to query information about + * \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 + * the rendering driver. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -188,12 +189,12 @@ extern DECLSPEC int SDLCALL SDL_GetRenderDriverInfo(int index, /** * Create a window and default renderer. * - * \param width the width of the window - * \param height the height of the window + * \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 + * 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. * @@ -210,10 +211,10 @@ extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer( /** * Create a 2D rendering context for a window. * - * \param window the window where rendering is displayed + * \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 + * 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. * @@ -236,7 +237,7 @@ extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window * window, * SDL_Window as the final destination and not an SDL_Surface. * * \param surface the SDL_Surface structure representing the surface where - * rendering is done + * rendering is done. * \returns a valid rendering context or NULL if there was an error; call * SDL_GetError() for more information. * @@ -251,7 +252,7 @@ extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateSoftwareRenderer(SDL_Surface * /** * Get the renderer associated with a window. * - * \param window the window to query + * \param window the window to query. * \returns the rendering context on success or NULL on failure; call * SDL_GetError() for more information. * @@ -264,7 +265,7 @@ extern DECLSPEC SDL_Renderer * SDLCALL SDL_GetRenderer(SDL_Window * window); /** * Get the window associated with a renderer. * - * \param renderer the renderer to query + * \param renderer the renderer to query. * \returns the window on success or NULL on failure; call SDL_GetError() for * more information. * @@ -275,9 +276,9 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_RenderGetWindow(SDL_Renderer *renderer) /** * Get information about a rendering context. * - * \param renderer the rendering context + * \param renderer the rendering context. * \param info an SDL_RendererInfo structure filled with information about the - * current renderer + * current renderer. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -295,9 +296,9 @@ extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_Renderer * renderer, * 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 + * \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. * @@ -314,11 +315,11 @@ extern DECLSPEC int SDLCALL SDL_GetRendererOutputSize(SDL_Renderer * renderer, * You can set the texture scaling method by setting * `SDL_HINT_RENDER_SCALE_QUALITY` before creating the texture. * - * \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 + * \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. @@ -347,9 +348,9 @@ extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTexture(SDL_Renderer * renderer, * format of the surface. Use SDL_QueryTexture() to query the pixel format of * the texture. * - * \param renderer the rendering context + * \param renderer the rendering context. * \param surface the SDL_Surface structure containing pixel data used to fill - * the texture + * the texture. * \returns the created texture or NULL on failure; call SDL_GetError() for * more information. * @@ -364,7 +365,7 @@ extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer /** * Query the attributes of a texture. * - * \param texture the texture to query + * \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). This argument @@ -399,10 +400,10 @@ extern DECLSPEC int SDLCALL SDL_QueryTexture(SDL_Texture * texture, * 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 + * \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. * @@ -418,10 +419,10 @@ extern DECLSPEC int SDLCALL SDL_SetTextureColorMod(SDL_Texture * texture, /** * 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. * @@ -445,8 +446,8 @@ extern DECLSPEC int SDLCALL SDL_GetTextureColorMod(SDL_Texture * texture, * 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 + * \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. * @@ -461,8 +462,8 @@ extern DECLSPEC int SDLCALL SDL_SetTextureAlphaMod(SDL_Texture * texture, /** * 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. * @@ -480,8 +481,8 @@ extern DECLSPEC int SDLCALL SDL_GetTextureAlphaMod(SDL_Texture * texture, * If the blend mode is not supported, the closest supported mode is chosen * and this function returns -1. * - * \param texture the texture to update - * \param blendMode the SDL_BlendMode to use for texture blending + * \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. * @@ -496,8 +497,8 @@ extern DECLSPEC int SDLCALL SDL_SetTextureBlendMode(SDL_Texture * texture, /** * Get the blend mode used for texture copy operations. * - * \param texture the texture to query - * \param blendMode a pointer filled in with the current SDL_BlendMode + * \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. * @@ -579,12 +580,12 @@ extern DECLSPEC void * SDLCALL SDL_GetTextureUserData(SDL_Texture * texture); * While this function will work with streaming textures, for optimization * reasons you may not get the pixels back if you lock the texture afterward. * - * \param texture the texture to update + * \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 + * 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 + * between lines. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -606,18 +607,18 @@ extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_Texture * texture, * block of Y and U/V planes in the proper order, but this function is * available if your pixel data is not contiguous. * - * \param texture the texture to update + * \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 + * 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 + * 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 + * 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 + * plane. * \returns 0 on success or -1 if the texture is not valid; call * SDL_GetError() for more information. * @@ -638,7 +639,7 @@ extern DECLSPEC int SDLCALL SDL_UpdateYUVTexture(SDL_Texture * texture, * 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 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. @@ -668,13 +669,13 @@ extern DECLSPEC int SDLCALL SDL_UpdateNVTexture(SDL_Texture * texture, * changes. * * \param texture the texture to lock for access, which was created with - * `SDL_TEXTUREACCESS_STREAMING` + * `SDL_TEXTUREACCESS_STREAMING`. * \param rect an SDL_Rect structure representing the area to lock for access; - * NULL to lock the entire texture + * 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 + * 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 + * 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. @@ -706,13 +707,13 @@ extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_Texture * texture, * or SDL_DestroyTexture(). The caller should not free it. * * \param texture the texture to lock for access, which was created with - * `SDL_TEXTUREACCESS_STREAMING` + * `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 + * NULL, the entire texture will be locked. * \param surface this is filled in with an SDL surface representing the - * locked area + * locked area. * \returns 0 on success, or -1 if the texture is not valid or was not created - * with `SDL_TEXTUREACCESS_STREAMING` + * with `SDL_TEXTUREACCESS_STREAMING`. * * \since This function is available since SDL 2.0.12. * @@ -734,7 +735,7 @@ extern DECLSPEC int SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture, * 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() + * \param texture a texture locked by SDL_LockTexture(). * * \since This function is available since SDL 2.0.0. * @@ -745,7 +746,7 @@ extern DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_Texture * texture); /** * 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. * * \since This function is available since SDL 2.0.0. @@ -763,9 +764,12 @@ extern DECLSPEC SDL_bool SDLCALL SDL_RenderTargetSupported(SDL_Renderer *rendere * * 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`. + * function with a NULL `texture`. This will reset the renderer's viewport, + * clipping rectangle, and scaling settings to the state they were in before + * setting a non-NULL `texture` target, losing any changes made in the + * meantime. * - * \param renderer the rendering context + * \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. @@ -785,7 +789,7 @@ extern DECLSPEC int SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, * The default render target is the window for which the renderer was created, * and is reported a NULL here. * - * \param renderer the rendering context + * \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. @@ -810,9 +814,9 @@ extern DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *renderer * 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 + * \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. * @@ -833,9 +837,9 @@ extern DECLSPEC int SDLCALL SDL_RenderSetLogicalSize(SDL_Renderer * renderer, in * When using a target texture: Never return 0 for `w` and `h` at first. Then * it returns the logical width and height that are set. * - * \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 + * \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. * @@ -850,8 +854,8 @@ extern DECLSPEC void SDLCALL SDL_RenderGetLogicalSize(SDL_Renderer * renderer, i * 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 + * \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. * @@ -866,7 +870,7 @@ extern DECLSPEC int SDLCALL SDL_RenderSetIntegerScale(SDL_Renderer * renderer, /** * 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. * @@ -882,9 +886,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_RenderGetIntegerScale(SDL_Renderer * render * When the window is resized, the viewport is reset to fill the entire new * window size. * - * \param renderer the rendering context + * \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 + * 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. * @@ -898,8 +902,8 @@ extern DECLSPEC int SDLCALL SDL_RenderSetViewport(SDL_Renderer * renderer, /** * Get the drawing area for the current target. * - * \param renderer the rendering context - * \param rect an SDL_Rect structure filled in with the current drawing area + * \param renderer the rendering context. + * \param rect an SDL_Rect structure filled in with the current drawing area. * * \since This function is available since SDL 2.0.0. * @@ -912,9 +916,9 @@ extern DECLSPEC void SDLCALL SDL_RenderGetViewport(SDL_Renderer * renderer, * Set the clip rectangle for rendering on the specified target. * * \param renderer the rendering context for which clip rectangle should be - * set + * set. * \param rect an SDL_Rect structure representing the clip area, relative to - * the viewport, or NULL to disable clipping + * the viewport, or NULL to disable clipping. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -930,9 +934,9 @@ extern DECLSPEC int SDLCALL SDL_RenderSetClipRect(SDL_Renderer * renderer, * Get the clip rectangle for the current target. * * \param renderer the rendering context from which clip rectangle should be - * queried + * queried. * \param rect an SDL_Rect structure filled in with the current clipping area - * or an empty rectangle if clipping is disabled + * or an empty rectangle if clipping is disabled. * * \since This function is available since SDL 2.0.0. * @@ -945,7 +949,7 @@ extern DECLSPEC void SDLCALL SDL_RenderGetClipRect(SDL_Renderer * 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. * @@ -968,9 +972,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_RenderIsClipEnabled(SDL_Renderer * renderer * 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 + * \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. * @@ -985,9 +989,9 @@ extern DECLSPEC int SDLCALL SDL_RenderSetScale(SDL_Renderer * renderer, /** * 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. * * \since This function is available since SDL 2.0.0. * @@ -1004,11 +1008,11 @@ extern DECLSPEC void SDLCALL SDL_RenderGetScale(SDL_Renderer * renderer, * and logical renderer size set * * \param renderer the renderer from which the logical coordinates should be - * calculated - * \param windowX the real X coordinate in the window - * \param windowY the real Y coordinate in the window - * \param logicalX the pointer filled with the logical x coordinate - * \param logicalY the pointer filled with the logical y coordinate + * calculated. + * \param windowX the real X coordinate in the window. + * \param windowY the real Y coordinate in the window. + * \param logicalX the pointer filled with the logical x coordinate. + * \param logicalY the pointer filled with the logical y coordinate. * * \since This function is available since SDL 2.0.18. * @@ -1030,11 +1034,11 @@ extern DECLSPEC void SDLCALL SDL_RenderWindowToLogical(SDL_Renderer * renderer, * and logical renderer size set * * \param renderer the renderer from which the window coordinates should be - * calculated - * \param logicalX the logical x coordinate - * \param logicalY the logical y coordinate - * \param windowX the pointer filled with the real X coordinate in the window - * \param windowY the pointer filled with the real Y coordinate in the window + * calculated. + * \param logicalX the logical x coordinate. + * \param logicalY the logical y coordinate. + * \param windowX the pointer filled with the real X coordinate in the window. + * \param windowY the pointer filled with the real Y coordinate in the window. * * \since This function is available since SDL 2.0.18. * @@ -1053,13 +1057,13 @@ extern DECLSPEC void SDLCALL SDL_RenderLogicalToWindow(SDL_Renderer * renderer, * Set the color for drawing or filling rectangles, lines, and points, and for * SDL_RenderClear(). * - * \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 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 + * specify how the alpha channel is used. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1083,15 +1087,15 @@ extern DECLSPEC int SDLCALL SDL_SetRenderDrawColor(SDL_Renderer * renderer, /** * Get the color used for drawing operations (Rect, Line and Clear). * - * \param renderer the rendering context + * \param renderer the rendering context. * \param r a pointer filled in with the red value used to draw on the - * rendering target + * rendering target. * \param g a pointer filled in with the green value used to draw on the - * rendering target + * rendering target. * \param b a pointer filled in with the blue value used to draw on the - * rendering target + * rendering target. * \param a a pointer filled in with the alpha value used to draw on the - * rendering target; usually `SDL_ALPHA_OPAQUE` (255) + * rendering target; usually `SDL_ALPHA_OPAQUE` (255). * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1108,8 +1112,8 @@ extern DECLSPEC int SDLCALL SDL_GetRenderDrawColor(SDL_Renderer * renderer, * * If the blend mode is not supported, the closest supported mode is chosen. * - * \param renderer the rendering context - * \param blendMode the SDL_BlendMode to use for blending + * \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. * @@ -1131,8 +1135,8 @@ extern DECLSPEC int SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer * renderer, /** * Get the blend mode used for drawing operations. * - * \param renderer the rendering context - * \param blendMode a pointer filled in with the current SDL_BlendMode + * \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. * @@ -1149,7 +1153,7 @@ extern DECLSPEC int SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer * renderer, * This function clears the entire rendering target, ignoring the viewport and * the clip rectangle. * - * \param renderer the rendering context + * \param renderer the rendering context. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1165,9 +1169,9 @@ extern DECLSPEC int SDLCALL SDL_RenderClear(SDL_Renderer * renderer); * SDL_RenderDrawPoint() draws a single point. If you want to draw multiple, * use SDL_RenderDrawPoints() instead. * - * \param renderer the rendering context - * \param x the x coordinate of the point - * \param y the y coordinate of the point + * \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. * @@ -1190,10 +1194,10 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawPoint(SDL_Renderer * renderer, /** * Draw multiple points on the current rendering target. * - * \param renderer the rendering context + * \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 + * 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. * @@ -1220,11 +1224,11 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawPoints(SDL_Renderer * renderer, * SDL_RenderDrawLine() draws the line to include both end points. If you want * to draw multiple, connecting lines use SDL_RenderDrawLines() instead. * - * \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 + * \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. * @@ -1247,10 +1251,10 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawLine(SDL_Renderer * renderer, /** * Draw a series of connected lines on the current rendering target. * - * \param renderer the rendering context + * \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 + * 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. * @@ -1274,9 +1278,9 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawLines(SDL_Renderer * renderer, /** * Draw a rectangle on the current rendering target. * - * \param renderer the rendering context + * \param renderer the rendering context. * \param rect an SDL_Rect structure representing the rectangle to draw, or - * NULL to outline the entire rendering target + * NULL to outline the entire rendering target. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1299,10 +1303,10 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawRect(SDL_Renderer * renderer, /** * Draw some number of rectangles on the current rendering target. * - * \param renderer the rendering context + * \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 + * 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. * @@ -1330,9 +1334,9 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawRects(SDL_Renderer * renderer, * color's alpha value is ignored unless blending is enabled with the * appropriate call to SDL_SetRenderDrawBlendMode(). * - * \param renderer the rendering context + * \param renderer the rendering context. * \param rect the SDL_Rect structure representing the rectangle to fill, or - * NULL for the entire rendering target + * NULL for the entire rendering target. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1356,10 +1360,10 @@ extern DECLSPEC int SDLCALL SDL_RenderFillRect(SDL_Renderer * renderer, * Fill some number of rectangles on the current rendering target with the * drawing color. * - * \param renderer the rendering context + * \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 + * 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. * @@ -1390,12 +1394,13 @@ extern DECLSPEC int SDLCALL SDL_RenderFillRects(SDL_Renderer * renderer, * 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 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 + * given rectangle. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1428,18 +1433,19 @@ extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_Renderer * renderer, * 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 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 + * rendering target. * \param angle an angle in degrees that indicates the rotation that will be - * applied to dstrect, rotating it in a clockwise direction + * 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`) + * around `dstrect.w / 2`, `dstrect.h / 2`). * \param flip a SDL_RendererFlip value stating which flipping actions should - * be performed on the texture + * be performed on the texture. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1465,7 +1471,7 @@ extern DECLSPEC int SDLCALL SDL_RenderCopyEx(SDL_Renderer * renderer, * \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 + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1476,9 +1482,9 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawPointF(SDL_Renderer * renderer, * 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 points The points to draw. + * \param count The number of points to draw. + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1494,7 +1500,7 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawPointsF(SDL_Renderer * renderer, * \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 + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1506,9 +1512,9 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawLineF(SDL_Renderer * renderer, * 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 points The points along the lines. + * \param count The number of points, drawing count-1 lines. + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1522,7 +1528,7 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawLinesF(SDL_Renderer * renderer, * \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 + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1536,7 +1542,7 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawRectF(SDL_Renderer * renderer, * \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 + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1551,7 +1557,7 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawRectsF(SDL_Renderer * renderer, * \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 + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1565,7 +1571,7 @@ extern DECLSPEC int SDLCALL SDL_RenderFillRectF(SDL_Renderer * renderer, * \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 + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1583,7 +1589,7 @@ extern DECLSPEC int SDLCALL SDL_RenderFillRectsF(SDL_Renderer * renderer, * texture. * \param dstrect A pointer to the destination rectangle, or NULL for the * entire rendering target. - * \return 0 on success, or -1 on error + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1603,13 +1609,13 @@ extern DECLSPEC int SDLCALL SDL_RenderCopyF(SDL_Renderer * renderer, * \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 + * 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 + * be performed on the texture. + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1634,7 +1640,7 @@ extern DECLSPEC int SDLCALL SDL_RenderCopyExF(SDL_Renderer * renderer, * array, if NULL all vertices will be rendered in sequential * order. * \param num_indices Number of indices. - * \return 0 on success, or -1 if the operation is not supported + * \return 0 on success, or -1 if the operation is not supported. * * \since This function is available since SDL 2.0.18. * @@ -1653,18 +1659,18 @@ extern DECLSPEC int SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, * * \param renderer The rendering context. * \param texture (optional) The SDL texture to use. - * \param xy Vertex positions - * \param xy_stride Byte size to move from one element to the next element - * \param color Vertex colors (as SDL_Color) - * \param color_stride Byte size to move from one element to the next element - * \param uv Vertex normalized texture coordinates - * \param uv_stride Byte size to move from one element to the next element + * \param xy Vertex positions. + * \param xy_stride Byte size to move from one element to the next element. + * \param color Vertex colors (as SDL_Color). + * \param color_stride Byte size to move from one element to the next element. + * \param uv Vertex normalized texture coordinates. + * \param uv_stride Byte size to move from one element to the next element. * \param num_vertices Number of vertices. * \param indices (optional) An array of indices into the 'vertices' arrays, * if NULL all vertices will be rendered in sequential order. * \param num_indices Number of indices. - * \param size_indices Index size: 1 (byte), 2 (short), 4 (int) - * \return 0 on success, or -1 if the operation is not supported + * \param size_indices Index size: 1 (byte), 2 (short), 4 (int). + * \return 0 on success, or -1 if the operation is not supported. * * \since This function is available since SDL 2.0.18. * @@ -1693,13 +1699,13 @@ extern DECLSPEC int SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer, * but it might contain additional padding (for example, 24bit RGB Windows * Bitmap data pads all rows to multiples of 4 bytes). * - * \param renderer the rendering context + * \param renderer the rendering context. * \param rect an SDL_Rect structure representing the area to read, or NULL - * for the entire render target + * 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 + * 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. * @@ -1729,7 +1735,7 @@ extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Renderer * renderer, * starting each new frame's drawing, even if you plan to overwrite every * pixel. * - * \param renderer the rendering context + * \param renderer the rendering context. * * \threadsafety You may only call this function on the main thread. If this * happens to work on a background thread on any given platform @@ -1738,6 +1744,7 @@ extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Renderer * renderer, * * \since This function is available since SDL 2.0.0. * + * \sa SDL_CreateRenderer * \sa SDL_RenderClear * \sa SDL_RenderDrawLine * \sa SDL_RenderDrawLines @@ -1758,7 +1765,7 @@ extern DECLSPEC void SDLCALL SDL_RenderPresent(SDL_Renderer * renderer); * Passing NULL or an otherwise invalid texture will set the SDL error message * to "Invalid texture". * - * \param texture the texture to destroy + * \param texture the texture to destroy. * * \since This function is available since SDL 2.0.0. * @@ -1773,7 +1780,7 @@ extern DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_Texture * texture); * If `renderer` is NULL, this function will return immediately after setting * the SDL error message to "Invalid renderer". See SDL_GetError(). * - * \param renderer the rendering context + * \param renderer the rendering context. * * \since This function is available since SDL 2.0.0. * @@ -1804,7 +1811,7 @@ extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer * renderer); * and earlier, as earlier versions did not queue rendering commands at all, * instead flushing them to the OS immediately. * - * \param renderer the rendering context + * \param renderer the rendering context. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1835,11 +1842,11 @@ extern DECLSPEC int SDLCALL SDL_RenderFlush(SDL_Renderer * renderer); * 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 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 + * 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 + * 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. * @@ -1855,8 +1862,9 @@ extern DECLSPEC int SDLCALL SDL_GL_BindTexture(SDL_Texture *texture, float *texw * * See SDL_GL_BindTexture() for examples on how to use these functions * - * \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 + * \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. * * \since This function is available since SDL 2.0.0. * @@ -1871,9 +1879,9 @@ extern DECLSPEC int SDLCALL SDL_GL_UnbindTexture(SDL_Texture *texture); * This function returns `void *`, so SDL doesn't have to include Metal's * headers, but it can be safely cast to a `CAMetalLayer *`. * - * \param renderer The renderer to query + * \param renderer The renderer to query. * \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a - * Metal renderer + * Metal renderer. * * \since This function is available since SDL 2.0.8. * @@ -1892,7 +1900,7 @@ extern DECLSPEC void *SDLCALL SDL_RenderGetMetalLayer(SDL_Renderer * renderer); * hidden/minimized/offscreen. This doesn't apply to command encoders for * render targets, just the window's backbuffer. Check your return values! * - * \param renderer The renderer to query + * \param renderer The renderer to query. * \returns an `id<MTLRenderCommandEncoder>` on success, or NULL if the * renderer isn't a Metal renderer or there was an error. * @@ -1905,9 +1913,9 @@ extern DECLSPEC void *SDLCALL SDL_RenderGetMetalCommandEncoder(SDL_Renderer * re /** * Toggle VSync of the given renderer. * - * \param renderer The renderer to toggle - * \param vsync 1 for on, 0 for off. All other values are reserved - * \returns a 0 int on success, or non-zero on failure + * \param renderer The renderer to toggle. + * \param vsync 1 for on, 0 for off. All other values are reserved. + * \returns a 0 int on success, or non-zero on failure. * * \since This function is available since SDL 2.0.18. */ diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_rwops.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_rwops.h @@ -19,11 +19,13 @@ 3. This notice may not be removed or altered from any source distribution. */ +/* WIKI CATEGORY: RWOPS */ + /** - * \file SDL_rwops.h + * # CategoryRWOPS * - * This file provides a general interface for SDL to read and write - * data streams. It can easily be extended to files, memory, etc. + * This file provides a general interface for SDL to read and write data + * streams. It can easily be extended to files, memory, etc. */ #ifndef SDL_rwops_h_ @@ -57,7 +59,7 @@ typedef struct SDL_RWops Sint64 (SDLCALL * size) (struct SDL_RWops * context); /** - * Seek to \c offset relative to \c whence, one of stdio's whence values: + * Seek to `offset` relative to `whence`, one of stdio's whence values: * RW_SEEK_SET, RW_SEEK_CUR, RW_SEEK_END * * \return the final offset in the data stream, or -1 on error. @@ -66,8 +68,8 @@ typedef struct SDL_RWops int whence); /** - * Read up to \c maxnum objects each of size \c size from the data - * stream to the area pointed at by \c ptr. + * Read up to `maxnum` objects each of size `size` from the data + * stream to the area pointed at by `ptr`. * * \return the number of objects read, or 0 at error or end of file. */ @@ -75,8 +77,8 @@ typedef struct SDL_RWops 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 exactly `num` objects each of size `size` from the area + * pointed at by `ptr` to data stream. * * \return the number of objects written, or 0 at error or end of file. */ @@ -186,7 +188,7 @@ typedef struct SDL_RWops * * Closing the SDL_RWops will close the file handle SDL is holding internally. * - * \param file a UTF-8 string representing the filename to open + * \param file a UTF-8 string representing the filename to open. * \param mode an ASCII string representing the mode to be used for opening * the file. * \returns a pointer to the SDL_RWops structure that is created, or NULL on @@ -224,10 +226,10 @@ extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFP(FILE * fp, SDL_bool autoclose); * `FILE*`, depending on what system headers are available to SDL. It is * always intended to be the `FILE*` type from the C runtime's stdio.h. * - * \param fp the `FILE*` that feeds the SDL_RWops stream + * \param fp the `FILE*` that feeds the SDL_RWops stream. * \param autoclose SDL_TRUE to close the `FILE*` when closing the SDL_RWops, * SDL_FALSE to leave the `FILE*` open when the RWops is - * closed + * closed. * \returns a pointer to the SDL_RWops structure that is created, or NULL on * failure; call SDL_GetError() for more information. * @@ -260,8 +262,8 @@ extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFP(void * fp, * If you need to make sure the RWops never writes to the memory buffer, you * should use SDL_RWFromConstMem() with a read-only buffer of memory instead. * - * \param mem a pointer to a buffer to feed an SDL_RWops stream - * \param size the buffer size, in bytes + * \param mem a pointer to a buffer to feed an SDL_RWops stream. + * \param size the buffer size, in bytes. * \returns a pointer to a new SDL_RWops structure, or NULL if it fails; call * SDL_GetError() for more information. * @@ -295,8 +297,8 @@ extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromMem(void *mem, int size); * If you need to write to a memory buffer, you should use SDL_RWFromMem() * with a writable buffer of memory instead. * - * \param mem a pointer to a read-only buffer to feed an SDL_RWops stream - * \param size the buffer size, in bytes + * \param mem a pointer to a read-only buffer to feed an SDL_RWops stream. + * \param size the buffer size, in bytes. * \returns a pointer to a new SDL_RWops structure, or NULL if it fails; call * SDL_GetError() for more information. * @@ -358,7 +360,7 @@ extern DECLSPEC SDL_RWops *SDLCALL SDL_AllocRW(void); * creation of the SDL_RWops is not freed by SDL_FreeRW(); the programmer must * be responsible for managing that memory in their **close** method. * - * \param area the SDL_RWops structure to be freed + * \param area the SDL_RWops structure to be freed. * * \since This function is available since SDL 2.0.0. * @@ -366,6 +368,7 @@ extern DECLSPEC SDL_RWops *SDLCALL SDL_AllocRW(void); */ extern DECLSPEC void SDLCALL SDL_FreeRW(SDL_RWops * area); +/* Possible `whence` values for SDL_RWops seeking... */ #define RW_SEEK_SET 0 /**< Seek from the beginning of data */ #define RW_SEEK_CUR 1 /**< Seek relative to current read point */ #define RW_SEEK_END 2 /**< Seek relative to the end of data */ @@ -375,7 +378,7 @@ extern DECLSPEC void SDLCALL SDL_FreeRW(SDL_RWops * area); * * Prior to SDL 2.0.10, this function was a macro. * - * \param context the SDL_RWops to get the size of the data stream from + * \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. @@ -402,10 +405,10 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWsize(SDL_RWops *context); * * Prior to SDL 2.0.10, this function was a macro. * - * \param context a pointer to an SDL_RWops structure + * \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` + * 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. * * \since This function is available since SDL 2.0.10. @@ -432,7 +435,7 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWseek(SDL_RWops *context, * Prior to SDL 2.0.10, this function was a macro. * * \param context a SDL_RWops data stream object from which to get the current - * offset + * offset. * \returns the current offset in the stream, or -1 if the information can not * be determined. * @@ -462,10 +465,10 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWtell(SDL_RWops *context); * * Prior to SDL 2.0.10, this function was a macro. * - * \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 + * \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. * @@ -496,10 +499,10 @@ extern DECLSPEC size_t SDLCALL SDL_RWread(SDL_RWops *context, * * Prior to SDL 2.0.10, this function was a macro. * - * \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 + * \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. * @@ -530,7 +533,7 @@ extern DECLSPEC size_t SDLCALL SDL_RWwrite(SDL_RWops *context, * * Prior to SDL 2.0.10, this function was a macro. * - * \param context SDL_RWops structure to close + * \param context SDL_RWops structure to close. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -555,9 +558,9 @@ extern DECLSPEC int SDLCALL SDL_RWclose(SDL_RWops *context); * * The data should be freed with SDL_free(). * - * \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 + * \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. * * \since This function is available since SDL 2.0.6. @@ -578,8 +581,8 @@ extern DECLSPEC void *SDLCALL SDL_LoadFile_RW(SDL_RWops *src, * Prior to SDL 2.0.10, this function was a macro wrapping around * SDL_LoadFile_RW. * - * \param file the path to read all available data from - * \param datasize if not NULL, will store the number of bytes read + * \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. * * \since This function is available since SDL 2.0.10. @@ -596,7 +599,7 @@ extern DECLSPEC void *SDLCALL SDL_LoadFile(const char *file, size_t *datasize); /** * Use this function to read a byte from an SDL_RWops. * - * \param src the SDL_RWops to read from + * \param src the SDL_RWops to read from. * \returns the read byte on success or 0 on failure; call SDL_GetError() for * more information. * @@ -613,7 +616,7 @@ extern DECLSPEC Uint8 SDLCALL SDL_ReadU8(SDL_RWops * src); * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * - * \param src the stream from which to read data + * \param src the stream from which to read data. * \returns 16 bits of data in the native byte order of the platform. * * \since This function is available since SDL 2.0.0. @@ -629,7 +632,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_ReadLE16(SDL_RWops * src); * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * - * \param src the stream from which to read data + * \param src the stream from which to read data. * \returns 16 bits of data in the native byte order of the platform. * * \since This function is available since SDL 2.0.0. @@ -645,7 +648,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_ReadBE16(SDL_RWops * src); * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * - * \param src the stream from which to read data + * \param src the stream from which to read data. * \returns 32 bits of data in the native byte order of the platform. * * \since This function is available since SDL 2.0.0. @@ -661,7 +664,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_ReadLE32(SDL_RWops * src); * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * - * \param src the stream from which to read data + * \param src the stream from which to read data. * \returns 32 bits of data in the native byte order of the platform. * * \since This function is available since SDL 2.0.0. @@ -677,7 +680,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_ReadBE32(SDL_RWops * src); * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * - * \param src the stream from which to read data + * \param src the stream from which to read data. * \returns 64 bits of data in the native byte order of the platform. * * \since This function is available since SDL 2.0.0. @@ -693,7 +696,7 @@ extern DECLSPEC Uint64 SDLCALL SDL_ReadLE64(SDL_RWops * src); * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * - * \param src the stream from which to read data + * \param src the stream from which to read data. * \returns 64 bits of data in the native byte order of the platform. * * \since This function is available since SDL 2.0.0. @@ -713,8 +716,8 @@ extern DECLSPEC Uint64 SDLCALL SDL_ReadBE64(SDL_RWops * src); /** * Use this function to write a byte to an SDL_RWops. * - * \param dst the SDL_RWops to write to - * \param value the byte value to write + * \param dst the SDL_RWops to write to. + * \param value the byte value to write. * \returns 1 on success or 0 on failure; call SDL_GetError() for more * information. * @@ -732,8 +735,8 @@ extern DECLSPEC size_t SDLCALL SDL_WriteU8(SDL_RWops * dst, Uint8 value); * specifies native format, and the data written will be in little-endian * format. * - * \param dst the stream to which data will be written - * \param value the data to be written, in native format + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. * \returns 1 on successful write, 0 on error. * * \since This function is available since SDL 2.0.0. @@ -749,8 +752,8 @@ extern DECLSPEC size_t SDLCALL SDL_WriteLE16(SDL_RWops * dst, Uint16 value); * SDL byteswaps the data only if necessary, so the application always * specifies native format, and the data written will be in big-endian format. * - * \param dst the stream to which data will be written - * \param value the data to be written, in native format + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. * \returns 1 on successful write, 0 on error. * * \since This function is available since SDL 2.0.0. @@ -767,8 +770,8 @@ extern DECLSPEC size_t SDLCALL SDL_WriteBE16(SDL_RWops * dst, Uint16 value); * specifies native format, and the data written will be in little-endian * format. * - * \param dst the stream to which data will be written - * \param value the data to be written, in native format + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. * \returns 1 on successful write, 0 on error. * * \since This function is available since SDL 2.0.0. @@ -784,8 +787,8 @@ extern DECLSPEC size_t SDLCALL SDL_WriteLE32(SDL_RWops * dst, Uint32 value); * SDL byteswaps the data only if necessary, so the application always * specifies native format, and the data written will be in big-endian format. * - * \param dst the stream to which data will be written - * \param value the data to be written, in native format + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. * \returns 1 on successful write, 0 on error. * * \since This function is available since SDL 2.0.0. @@ -802,8 +805,8 @@ extern DECLSPEC size_t SDLCALL SDL_WriteBE32(SDL_RWops * dst, Uint32 value); * specifies native format, and the data written will be in little-endian * format. * - * \param dst the stream to which data will be written - * \param value the data to be written, in native format + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. * \returns 1 on successful write, 0 on error. * * \since This function is available since SDL 2.0.0. @@ -819,8 +822,8 @@ extern DECLSPEC size_t SDLCALL SDL_WriteLE64(SDL_RWops * dst, Uint64 value); * SDL byteswaps the data only if necessary, so the application always * specifies native format, and the data written will be in big-endian format. * - * \param dst the stream to which data will be written - * \param value the data to be written, in native format + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. * \returns 1 on successful write, 0 on error. * * \since This function is available since SDL 2.0.0. diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_scancode.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_scancode.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_scancode.h + * # CategoryScancode * - * Defines keyboard scancodes. + * Defines keyboard scancodes. */ #ifndef SDL_scancode_h_ @@ -31,16 +31,16 @@ #include "SDL_stdinc.h" /** - * \brief The SDL keyboard scancode representation. + * The SDL keyboard scancode representation. * - * Values of this type are used to represent keyboard keys, among other places - * in the \link SDL_Keysym::scancode key.keysym.scancode \endlink field of the - * SDL_Event structure. + * Values of this type are used to represent keyboard keys, among other places + * in the SDL_Keysym::scancode key.keysym.scancode field of the SDL_Event + * structure. * - * The values in this enumeration are based on the USB usage page standard: - * https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf + * The values in this enumeration are based on the USB usage page standard: + * https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf */ -typedef enum +typedef enum SDL_Scancode { SDL_SCANCODE_UNKNOWN = 0, diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_sensor.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_sensor.h @@ -20,10 +20,9 @@ */ /** - * \file SDL_sensor.h - * - * Include file for SDL sensor event handling + * # CategorySensor * + * Include file for SDL sensor event handling */ #ifndef SDL_sensor_h_ @@ -44,7 +43,7 @@ extern "C" { * \brief SDL_sensor.h * * In order to use these functions, SDL_Init() must have been called - * with the ::SDL_INIT_SENSOR flag. This causes SDL to scan the system + * with the SDL_INIT_SENSOR flag. This causes SDL to scan the system * for sensors, and load appropriate drivers. */ @@ -52,21 +51,67 @@ struct _SDL_Sensor; typedef struct _SDL_Sensor SDL_Sensor; /** - * This is a unique ID for a sensor for the time it is connected to the system, - * and is never reused for the lifetime of the application. + * This is a unique ID for a sensor for the time it is connected to the + * system, and is never reused for the lifetime of the application. * - * The ID value starts at 0 and increments from there. The value -1 is an invalid ID. + * The ID value starts at 0 and increments from there. The value -1 is an + * invalid ID. */ typedef Sint32 SDL_SensorID; -/* The different sensors defined by SDL +/** + * The different sensors defined by SDL. * * Additional sensors may be available, using platform dependent semantics. * - * Hare are the additional Android sensors: + * Here are the additional Android sensors: + * * https://developer.android.com/reference/android/hardware/SensorEvent.html#values + * + * Accelerometer sensor notes: + * + * The accelerometer returns the current acceleration in SI meters per second + * squared. This measurement includes the force of gravity, so a device at + * rest will have an value of SDL_STANDARD_GRAVITY away from the center of the + * earth, which is a positive Y value. + * + * - `values[0]`: Acceleration on the x axis + * - `values[1]`: Acceleration on the y axis + * - `values[2]`: Acceleration on the z axis + * + * For phones and tablets held in natural orientation and game controllers + * held in front of you, the axes are defined as follows: + * + * - -X ... +X : left ... right + * - -Y ... +Y : bottom ... top + * - -Z ... +Z : farther ... closer + * + * The accelerometer axis data is not changed when the device is rotated. + * + * Gyroscope sensor notes: + * + * The gyroscope returns the current rate of rotation in radians per second. + * The rotation is positive in the counter-clockwise direction. That is, an + * observer looking from a positive location on one of the axes would see + * positive rotation on that axis when it appeared to be rotating + * counter-clockwise. + * + * - `values[0]`: Angular speed around the x axis (pitch) + * - `values[1]`: Angular speed around the y axis (yaw) + * - `values[2]`: Angular speed around the z axis (roll) + * + * For phones and tablets held in natural orientation and game controllers + * held in front of you, the axes are defined as follows: + * + * - -X ... +X : left ... right + * - -Y ... +Y : bottom ... top + * - -Z ... +Z : farther ... closer + * + * The gyroscope axis data is not changed when the device is rotated. + * + * \sa SDL_GetDisplayOrientation */ -typedef enum +typedef enum SDL_SensorType { SDL_SENSOR_INVALID = -1, /**< Returned for an invalid sensor */ SDL_SENSOR_UNKNOWN, /**< Unknown sensor type */ @@ -79,52 +124,14 @@ typedef enum } SDL_SensorType; /** - * Accelerometer sensor - * - * The accelerometer returns the current acceleration in SI meters per - * second squared. This measurement includes the force of gravity, so - * a device at rest will have an value of SDL_STANDARD_GRAVITY away - * from the center of the earth, which is a positive Y value. - * - * values[0]: Acceleration on the x axis - * values[1]: Acceleration on the y axis - * values[2]: Acceleration on the z axis - * - * For phones held in portrait mode and game controllers held in front of you, - * the axes are defined as follows: - * -X ... +X : left ... right - * -Y ... +Y : bottom ... top - * -Z ... +Z : farther ... closer - * - * The axis data is not changed when the phone is rotated. - * - * \sa SDL_GetDisplayOrientation() - */ -#define SDL_STANDARD_GRAVITY 9.80665f - -/** - * Gyroscope sensor - * - * The gyroscope returns the current rate of rotation in radians per second. - * The rotation is positive in the counter-clockwise direction. That is, - * an observer looking from a positive location on one of the axes would - * see positive rotation on that axis when it appeared to be rotating - * counter-clockwise. + * A constant to represent standard gravity for accelerometer sensors. * - * values[0]: Angular speed around the x axis (pitch) - * values[1]: Angular speed around the y axis (yaw) - * values[2]: Angular speed around the z axis (roll) - * - * For phones held in portrait mode and game controllers held in front of you, - * the axes are defined as follows: - * -X ... +X : left ... right - * -Y ... +Y : bottom ... top - * -Z ... +Z : farther ... closer - * - * The axis data is not changed when the phone or controller is rotated. - * - * \sa SDL_GetDisplayOrientation() + * The accelerometer returns the current acceleration in SI meters per second + * squared. This measurement includes the force of gravity, so a device at + * rest will have an value of SDL_STANDARD_GRAVITY away from the center of the + * earth, which is a positive Y value. */ +#define SDL_STANDARD_GRAVITY 9.80665f /* Function prototypes */ @@ -155,7 +162,7 @@ extern DECLSPEC int SDLCALL SDL_NumSensors(void); /** * Get the implementation dependent name of a sensor. * - * \param device_index The sensor to obtain name from + * \param device_index The sensor to obtain name from. * \returns the sensor name, or NULL if `device_index` is out of range. * * \since This function is available since SDL 2.0.9. @@ -165,7 +172,7 @@ extern DECLSPEC const char *SDLCALL SDL_SensorGetDeviceName(int device_index); /** * Get the type of a sensor. * - * \param device_index The sensor to get the type from + * \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. * @@ -176,7 +183,7 @@ extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetDeviceType(int device_index) /** * Get the platform dependent type of a sensor. * - * \param device_index The sensor to check + * \param device_index The sensor to check. * \returns the sensor platform dependent type, or -1 if `device_index` is out * of range. * @@ -187,7 +194,7 @@ extern DECLSPEC int SDLCALL SDL_SensorGetDeviceNonPortableType(int device_index) /** * Get the instance ID of a sensor. * - * \param device_index The sensor to get instance id from + * \param device_index The sensor to get instance id from. * \returns the sensor instance ID, or -1 if `device_index` is out of range. * * \since This function is available since SDL 2.0.9. @@ -197,7 +204,7 @@ extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetDeviceInstanceID(int device_in /** * Open a sensor for use. * - * \param device_index The sensor to open + * \param device_index The sensor to open. * \returns an SDL_Sensor sensor object, or NULL if an error occurred. * * \since This function is available since SDL 2.0.9. @@ -207,7 +214,7 @@ 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 + * \param instance_id The sensor from instance id. * \returns an SDL_Sensor object. * * \since This function is available since SDL 2.0.9. @@ -217,7 +224,7 @@ extern DECLSPEC SDL_Sensor *SDLCALL SDL_SensorFromInstanceID(SDL_SensorID instan /** * Get the implementation dependent name of a sensor * - * \param sensor The SDL_Sensor object + * \param sensor The SDL_Sensor object. * \returns the sensor name, or NULL if `sensor` is NULL. * * \since This function is available since SDL 2.0.9. @@ -227,7 +234,7 @@ extern DECLSPEC const char *SDLCALL SDL_SensorGetName(SDL_Sensor *sensor); /** * Get the type of a sensor. * - * \param sensor The SDL_Sensor object to inspect + * \param sensor The SDL_Sensor object to inspect. * \returns the SDL_SensorType type, or `SDL_SENSOR_INVALID` if `sensor` is * NULL. * @@ -238,7 +245,7 @@ extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetType(SDL_Sensor *sensor); /** * Get the platform dependent type of a sensor. * - * \param sensor The SDL_Sensor object to inspect + * \param sensor The SDL_Sensor object to inspect. * \returns the sensor platform dependent type, or -1 if `sensor` is NULL. * * \since This function is available since SDL 2.0.9. @@ -248,7 +255,7 @@ extern DECLSPEC int SDLCALL SDL_SensorGetNonPortableType(SDL_Sensor *sensor); /** * Get the instance ID of a sensor. * - * \param sensor The SDL_Sensor object to inspect + * \param sensor The SDL_Sensor object to inspect. * \returns the sensor instance ID, or -1 if `sensor` is NULL. * * \since This function is available since SDL 2.0.9. @@ -260,9 +267,9 @@ extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetInstanceID(SDL_Sensor *sensor) * * The number of values and interpretation of the data is sensor dependent. * - * \param sensor The 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 + * \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. * * \since This function is available since SDL 2.0.9. @@ -275,11 +282,11 @@ extern DECLSPEC int SDLCALL SDL_SensorGetData(SDL_Sensor *sensor, float *data, i * * The number of values and interpretation of the data is sensor dependent. * - * \param sensor The SDL_Sensor object to query + * \param sensor The SDL_Sensor object to query. * \param timestamp A pointer filled with the timestamp in microseconds of the - * current sensor reading if available, or 0 if not - * \param data A pointer filled with the current sensor state - * \param num_values The number of values to write to data + * current sensor reading if available, or 0 if not. + * \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. * * \since This function is available since SDL 2.26.0. @@ -289,7 +296,7 @@ extern DECLSPEC int SDLCALL SDL_SensorGetDataWithTimestamp(SDL_Sensor *sensor, U /** * Close a sensor previously opened with SDL_SensorOpen(). * - * \param sensor The SDL_Sensor object to close + * \param sensor The SDL_Sensor object to close. * * \since This function is available since SDL 2.0.9. */ diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_shape.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_shape.h @@ -48,18 +48,18 @@ extern "C" { * 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 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. * \param h The height of the window. * \param flags The flags for the window, a mask of SDL_WINDOW_BORDERLESS with - * any of the following: ::SDL_WINDOW_OPENGL, - * ::SDL_WINDOW_INPUT_GRABBED, ::SDL_WINDOW_HIDDEN, - * ::SDL_WINDOW_RESIZABLE, ::SDL_WINDOW_MAXIMIZED, - * ::SDL_WINDOW_MINIMIZED, ::SDL_WINDOW_BORDERLESS is always set, - * and ::SDL_WINDOW_FULLSCREEN is always unset. + * any of the following: SDL_WINDOW_OPENGL, + * SDL_WINDOW_INPUT_GRABBED, SDL_WINDOW_HIDDEN, + * SDL_WINDOW_RESIZABLE, SDL_WINDOW_MAXIMIZED, + * SDL_WINDOW_MINIMIZED, SDL_WINDOW_BORDERLESS is always set, and + * SDL_WINDOW_FULLSCREEN is always unset. * \return the window created, or NULL if window creation failed. * * \since This function is available since SDL 2.0.0. diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_stdinc.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_stdinc.h @@ -19,10 +19,12 @@ 3. This notice may not be removed or altered from any source distribution. */ +/* WIKI CATEGORY: StdInc */ + /** - * \file SDL_stdinc.h + * # CategoryStdInc * - * This is a general header that includes C language support. + * This is a general header that includes C language support. */ #ifndef SDL_stdinc_h_ @@ -129,15 +131,19 @@ void *alloca(size_t); #endif /** - * The number of elements in an array. + * The number of elements in an array. */ #define SDL_arraysize(array) (sizeof(array)/sizeof(array[0])) #define SDL_TABLESIZE(table) SDL_arraysize(table) /** - * Macro useful for building other macros with strings in them + * Macro useful for building other macros with strings in them + * + * e.g: * - * e.g. #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n") + * ```c + * #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n") + * ``` */ #define SDL_STRINGIFY_ARG(arg) #arg @@ -185,54 +191,61 @@ typedef enum #endif /** - * \brief A signed 8-bit integer type. + * A signed 8-bit integer type. */ +typedef int8_t Sint8; #define SDL_MAX_SINT8 ((Sint8)0x7F) /* 127 */ #define SDL_MIN_SINT8 ((Sint8)(~0x7F)) /* -128 */ -typedef int8_t Sint8; + /** - * \brief An unsigned 8-bit integer type. + * An unsigned 8-bit integer type. */ +typedef uint8_t Uint8; #define SDL_MAX_UINT8 ((Uint8)0xFF) /* 255 */ #define SDL_MIN_UINT8 ((Uint8)0x00) /* 0 */ -typedef uint8_t Uint8; + /** - * \brief A signed 16-bit integer type. + * A signed 16-bit integer type. */ +typedef int16_t Sint16; #define SDL_MAX_SINT16 ((Sint16)0x7FFF) /* 32767 */ #define SDL_MIN_SINT16 ((Sint16)(~0x7FFF)) /* -32768 */ -typedef int16_t Sint16; + /** - * \brief An unsigned 16-bit integer type. + * An unsigned 16-bit integer type. */ +typedef uint16_t Uint16; #define SDL_MAX_UINT16 ((Uint16)0xFFFF) /* 65535 */ #define SDL_MIN_UINT16 ((Uint16)0x0000) /* 0 */ -typedef uint16_t Uint16; + /** - * \brief A signed 32-bit integer type. + * A signed 32-bit integer type. */ +typedef int32_t Sint32; #define SDL_MAX_SINT32 ((Sint32)0x7FFFFFFF) /* 2147483647 */ #define SDL_MIN_SINT32 ((Sint32)(~0x7FFFFFFF)) /* -2147483648 */ -typedef int32_t Sint32; + /** - * \brief An unsigned 32-bit integer type. + * An unsigned 32-bit integer type. */ +typedef uint32_t Uint32; #define SDL_MAX_UINT32 ((Uint32)0xFFFFFFFFu) /* 4294967295 */ #define SDL_MIN_UINT32 ((Uint32)0x00000000) /* 0 */ -typedef uint32_t Uint32; /** - * \brief A signed 64-bit integer type. + * A signed 64-bit integer type. */ +typedef int64_t Sint64; #define SDL_MAX_SINT64 ((Sint64)0x7FFFFFFFFFFFFFFFll) /* 9223372036854775807 */ #define SDL_MIN_SINT64 ((Sint64)(~0x7FFFFFFFFFFFFFFFll)) /* -9223372036854775808 */ -typedef int64_t Sint64; + /** - * \brief An unsigned 64-bit integer type. + * An unsigned 64-bit integer type. */ +typedef uint64_t Uint64; #define SDL_MAX_UINT64 ((Uint64)0xFFFFFFFFFFFFFFFFull) /* 18446744073709551615 */ #define SDL_MIN_UINT64 ((Uint64)(0x0000000000000000ull)) /* 0 */ -typedef uint64_t Uint64; + /* @} *//* Basic data types */ @@ -415,8 +428,8 @@ SDL_COMPILE_TIME_ASSERT(sint64, sizeof(Sint64) == 8); /** \cond */ #ifndef DOXYGEN_SHOULD_IGNORE_THIS -#if !defined(__ANDROID__) && !defined(__VITA__) && !defined(__3DS__) - /* TODO: include/SDL_stdinc.h:174: error: size of array 'SDL_dummy_enum' is negative */ +#if !defined(__VITA__) && !defined(__3DS__) +/* TODO: include/SDL_stdinc.h:422: error: size of array 'SDL_dummy_enum' is negative */ typedef enum { DUMMY_ENUM_VALUE @@ -491,8 +504,9 @@ extern DECLSPEC int SDLCALL SDL_GetNumAllocations(void); extern DECLSPEC char *SDLCALL SDL_getenv(const char *name); extern DECLSPEC int SDLCALL SDL_setenv(const char *name, const char *value, int overwrite); -extern DECLSPEC void SDLCALL SDL_qsort(void *base, size_t nmemb, size_t size, int (SDLCALL *compare) (const void *, const void *)); -extern DECLSPEC void * SDLCALL SDL_bsearch(const void *key, const void *base, size_t nmemb, size_t size, int (SDLCALL *compare) (const void *, const void *)); +typedef int (SDLCALL *SDL_CompareCallback)(const void *, const void *); +extern DECLSPEC void SDLCALL SDL_qsort(void *base, size_t nmemb, size_t size, SDL_CompareCallback compare); +extern DECLSPEC void * SDLCALL SDL_bsearch(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback compare); extern DECLSPEC int SDLCALL SDL_abs(int x); @@ -521,6 +535,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_crc32(Uint32 crc, const void *data, size_t le extern DECLSPEC void *SDLCALL SDL_memset(SDL_OUT_BYTECAP(len) void *dst, int c, size_t len); +/* Some safe(r) macros for zero'ing structures... */ #define SDL_zero(x) SDL_memset(&(x), 0, sizeof((x))) #define SDL_zerop(x) SDL_memset((x), 0, sizeof(*(x))) #define SDL_zeroa(x) SDL_memset((x), 0, sizeof((x))) @@ -706,6 +721,8 @@ extern DECLSPEC char *SDLCALL SDL_iconv_string(const char *tocode, const char *fromcode, const char *inbuf, size_t inbytesleft); + +/* Some helper macros for common cases... */ #define SDL_iconv_utf8_locale(S) SDL_iconv_string("", "UTF-8", S, SDL_strlen(S)+1) #define SDL_iconv_utf8_ucs2(S) (Uint16 *)SDL_iconv_string("UCS-2", "UTF-8", S, SDL_strlen(S)+1) #define SDL_iconv_utf8_ucs4(S) (Uint32 *)SDL_iconv_string("UCS-4", "UTF-8", S, SDL_strlen(S)+1) @@ -733,6 +750,9 @@ size_t wcslcpy(wchar_t *dst, const wchar_t *src, size_t size); size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size); #endif +/* strdup is not ANSI but POSIX, and its prototype might be hidden... */ +char *strdup(const char *str); + /* Starting LLVM 16, the analyser errors out if these functions do not have their prototype defined (clang-diagnostic-implicit-function-declaration) */ #include <stdlib.h> @@ -778,8 +798,9 @@ SDL_FORCE_INLINE void *SDL_memcpy4(SDL_OUT_BYTECAP(dwords*4) void *dst, SDL_IN_B } /** - * If a * b would overflow, return -1. Otherwise store a * b via ret - * and return 0. + * If a * b would overflow, return -1. + * + * Otherwise store a * b via ret and return 0. * * \since This function is available since SDL 2.24.0. */ @@ -808,8 +829,9 @@ SDL_FORCE_INLINE int _SDL_size_mul_overflow_builtin (size_t a, #endif /** - * If a + b would overflow, return -1. Otherwise store a + b via ret - * and return 0. + * If a + b would overflow, return -1. + * + * Otherwise store a + b via ret and return 0. * * \since This function is available since SDL 2.24.0. */ diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_surface.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_surface.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_surface.h + * # CategorySurface * - * Header file for ::SDL_Surface definition and management functions. + * Header file for SDL_Surface definition and management functions. */ #ifndef SDL_surface_h_ @@ -43,7 +43,7 @@ extern "C" { /** * \name Surface flags * - * These are the currently supported flags for the ::SDL_Surface. + * These are the currently supported flags for the SDL_Surface. * * \internal * Used internally (read-only). @@ -57,17 +57,17 @@ extern "C" { /* @} *//* Surface flags */ /** - * Evaluates to true if the surface needs to be locked before access. + * Evaluates to true if the surface needs to be locked before access. */ #define SDL_MUSTLOCK(S) (((S)->flags & SDL_RLEACCEL) != 0) typedef struct SDL_BlitMap SDL_BlitMap; /* this is an opaque type. */ /** - * \brief A collection of pixels used in software blitting. + * A collection of pixels used in software blitting. * - * \note This structure should be treated as read-only, except for \c pixels, - * which, if not NULL, contains the raw pixel data for the surface. + * This structure should be treated as read-only, except for `pixels`, which, + * if not NULL, contains the raw pixel data for the surface. */ typedef struct SDL_Surface { @@ -97,15 +97,15 @@ typedef struct SDL_Surface } SDL_Surface; /** - * \brief The type of function used for surface blitting functions. + * The type of function used for surface blitting functions. */ typedef int (SDLCALL *SDL_blit) (struct SDL_Surface * src, SDL_Rect * srcrect, struct SDL_Surface * dst, SDL_Rect * dstrect); /** - * \brief The formula used for converting between YUV and RGB + * The formula used for converting between YUV and RGB */ -typedef enum +typedef enum SDL_YUV_CONVERSION_MODE { SDL_YUV_CONVERSION_JPEG, /**< Full range JPEG */ SDL_YUV_CONVERSION_BT601, /**< BT.601 (the default) */ @@ -140,14 +140,14 @@ typedef enum * 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 + * \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. * @@ -171,10 +171,10 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface * 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 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. @@ -198,15 +198,15 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceWithFormat * 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 + * \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. * @@ -214,6 +214,7 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceWithFormat * * \sa SDL_CreateRGBSurface * \sa SDL_CreateRGBSurfaceWithFormat + * \sa SDL_CreateRGBSurfaceWithFormatFrom * \sa SDL_FreeSurface */ extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels, @@ -239,11 +240,11 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels, * 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 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. @@ -278,8 +279,8 @@ extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface); * * 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 + * \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. * @@ -300,7 +301,7 @@ extern DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface * surface, * 0, then you can read and write to the surface at any time, and the pixel * format of the surface will not change. * - * \param surface the SDL_Surface structure to be locked + * \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. * @@ -314,7 +315,7 @@ extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface); /** * Release a surface after directly accessing the pixels. * - * \param surface the SDL_Surface structure to be unlocked + * \param surface the SDL_Surface structure to be unlocked. * * \since This function is available since SDL 2.0.0. * @@ -329,11 +330,11 @@ extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface); * result in a memory leak. * * src is an open SDL_RWops buffer, typically loaded with SDL_RWFromFile. - * Alternitavely, you might also use the macro SDL_LoadBMP to load a bitmap + * Alternatively, you might also use the macro SDL_LoadBMP to load a bitmap * from a file, convert it to an SDL_Surface and then close the file. * - * \param src the data stream for the surface - * \param freesrc non-zero to close the stream after being read + * \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. * @@ -363,9 +364,9 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src, * surface before they are saved. YUV and paletted 1-bit and 4-bit formats are * not supported. * - * \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 + * \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. * @@ -378,9 +379,9 @@ extern DECLSPEC int SDLCALL SDL_SaveBMP_RW (SDL_Surface * surface, SDL_RWops * dst, int freedst); /** - * Save a surface to a file. + * Save a surface to a file. * - * Convenience macro. + * Convenience macro. */ #define SDL_SaveBMP(surface, file) \ SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1) @@ -391,8 +392,8 @@ extern DECLSPEC int SDLCALL SDL_SaveBMP_RW * If RLE is enabled, color key 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 + * \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. * @@ -410,7 +411,7 @@ extern DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface * surface, * * It is safe to pass a NULL `surface` here; it will return SDL_FALSE. * - * \param surface the SDL_Surface structure to query + * \param surface the SDL_Surface structure to query. * \returns SDL_TRUE if the surface is RLE enabled, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.14. @@ -432,9 +433,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasSurfaceRLE(SDL_Surface * surface); * RLE acceleration can substantially speed up blitting of images with large * horizontal runs of transparent pixels. See SDL_SetSurfaceRLE() for details. * - * \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 + * \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. * @@ -451,7 +452,7 @@ extern DECLSPEC int SDLCALL SDL_SetColorKey(SDL_Surface * surface, * * It is safe to pass a NULL `surface` here; it will return SDL_FALSE. * - * \param surface the SDL_Surface structure to query + * \param surface the SDL_Surface structure to query. * \return SDL_TRUE if the surface has a color key, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.9. @@ -469,8 +470,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasColorKey(SDL_Surface * surface); * * 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 + * \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. * @@ -491,10 +492,10 @@ extern DECLSPEC int SDLCALL SDL_GetColorKey(SDL_Surface * surface, * * `srcC = srcC * (color / 255)` * - * \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 + * \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. * @@ -510,10 +511,10 @@ extern DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface * surface, /** * Get the additional color value multiplied into blit operations. * - * \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 + * \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. * @@ -534,8 +535,8 @@ extern DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface * surface, * * `srcA = srcA * (alpha / 255)` * - * \param surface the SDL_Surface structure to update - * \param alpha the alpha value multiplied into blit operations + * \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. * @@ -550,8 +551,8 @@ extern DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface * surface, /** * Get the additional alpha value used in blit operations. * - * \param surface the SDL_Surface structure 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. * @@ -570,8 +571,8 @@ extern DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface * surface, * existing data, the blendmode of the SOURCE surface should be set to * `SDL_BLENDMODE_NONE`. * - * \param surface the SDL_Surface structure to update - * \param blendMode the SDL_BlendMode to use for blit blending + * \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. * @@ -585,8 +586,8 @@ extern DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface * surface, /** * Get the blend mode used for blit operations. * - * \param surface the SDL_Surface structure to query - * \param blendMode a pointer filled in with the current SDL_BlendMode + * \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. * @@ -606,9 +607,9 @@ extern DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface * surface, * 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 surface the SDL_Surface structure to be clipped. * \param rect the SDL_Rect structure representing the clipping rectangle, or - * NULL to disable clipping + * NULL to disable clipping. * \returns SDL_TRUE if the rectangle intersects the surface, otherwise * SDL_FALSE and blits will be completely clipped. * @@ -627,9 +628,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface, * rectangle is drawn into. * * \param surface the SDL_Surface structure representing the surface to be - * clipped + * clipped. * \param rect an SDL_Rect structure filled in with the clipping rectangle for - * the surface + * the surface. * * \since This function is available since SDL 2.0.0. * @@ -658,11 +659,11 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_DuplicateSurface(SDL_Surface * surface) * 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 src the existing SDL_Surface structure to convert. * \param fmt the SDL_PixelFormat structure that the new surface is optimized - * for + * for. * \param flags the flags are unused and should be set to 0; this is a - * leftover from SDL 1.2's API + * 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. * @@ -683,11 +684,11 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface * 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 src the existing SDL_Surface structure to convert. * \param pixel_format the SDL_PixelFormatEnum that the new surface is - * optimized for + * optimized for. * \param flags the flags are unused and should be set to 0; this is a - * leftover from SDL 1.2's API + * 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. * @@ -703,14 +704,14 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurfaceFormat /** * Copy a block of pixels of one format to another format. * - * \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 source pixels, 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 + * \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 source pixels, 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. * @@ -729,14 +730,14 @@ extern DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height, * * This function is currently only implemented for SDL_PIXELFORMAT_ARGB8888. * - * \param width the width of the block to convert, in pixels - * \param height the height of the block to convert, 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 source pixels, in bytes - * \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format - * \param dst a pointer to be filled in with premultiplied pixel data - * \param dst_pitch the pitch of the destination pixels, in bytes + * \param width the width of the block to convert, in pixels. + * \param height the height of the block to convert, 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 source pixels, in bytes. + * \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format. + * \param dst a pointer to be filled in with premultiplied 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. * @@ -760,10 +761,10 @@ extern DECLSPEC int SDLCALL SDL_PremultiplyAlpha(int width, int height, * 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 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 + * 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. * @@ -786,10 +787,10 @@ extern DECLSPEC int SDLCALL SDL_FillRect * 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 + * \param dst the SDL_Surface structure that is the drawing target. + * \param rects an array of SDL_Rect 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. * @@ -801,62 +802,64 @@ 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. - * - * This assumes that the source and destination rectangles are - * the same size. If either \c srcrect or \c dstrect are NULL, the entire - * surface (\c src or \c dst) is copied. The final blit rectangles are saved - * in \c srcrect and \c dstrect after all clipping is performed. - * - * \returns 0 if the blit is successful, otherwise it returns -1. - * - * The blit function should not be called on a locked surface. - * - * The blit semantics for surfaces with and without blending and colorkey - * are defined as follows: - * \verbatim - RGBA->RGB: - Source surface blend mode set to SDL_BLENDMODE_BLEND: - alpha-blend (using the source alpha-channel and per-surface alpha) - SDL_SRCCOLORKEY ignored. - Source surface blend mode set to SDL_BLENDMODE_NONE: - copy RGB. - if SDL_SRCCOLORKEY set, only copy the pixels matching the - RGB values of the source color key, ignoring alpha in the - comparison. - - RGB->RGBA: - Source surface blend mode set to SDL_BLENDMODE_BLEND: - alpha-blend (using the source per-surface alpha) - Source surface blend mode set to SDL_BLENDMODE_NONE: - copy RGB, set destination alpha to source per-surface alpha value. - both: - if SDL_SRCCOLORKEY set, only copy the pixels matching the - source color key. - - RGBA->RGBA: - Source surface blend mode set to SDL_BLENDMODE_BLEND: - alpha-blend (using the source alpha-channel and per-surface alpha) - SDL_SRCCOLORKEY ignored. - Source surface blend mode set to SDL_BLENDMODE_NONE: - copy all of RGBA to the destination. - if SDL_SRCCOLORKEY set, only copy the pixels matching the - RGB values of the source color key, ignoring alpha in the - comparison. - - RGB->RGB: - Source surface blend mode set to SDL_BLENDMODE_BLEND: - alpha-blend (using the source per-surface alpha) - Source surface blend mode set to SDL_BLENDMODE_NONE: - copy RGB. - both: - if SDL_SRCCOLORKEY set, only copy the pixels matching the - source color key. - \endverbatim - * - * You should call SDL_BlitSurface() unless you know exactly how SDL - * blitting works internally and how to use the other blit functions. + * Performs a fast blit from the source surface to the destination surface. + * + * This assumes that the source and destination rectangles are the same size. + * If either `srcrect` or `dstrect` are NULL, the entire surface (`src` or + * `dst`) is copied. The final blit rectangles are saved in `srcrect` and + * `dstrect` after all clipping is performed. + * + * The blit function should not be called on a locked surface. + * + * The blit semantics for surfaces with and without blending and colorkey are + * defined as follows: + * + * ``` + * RGBA->RGB: + * Source surface blend mode set to SDL_BLENDMODE_BLEND: + * alpha-blend (using the source alpha-channel and per-surface alpha) + * SDL_SRCCOLORKEY ignored. + * Source surface blend mode set to SDL_BLENDMODE_NONE: + * copy RGB. + * if SDL_SRCCOLORKEY set, only copy the pixels matching the + * RGB values of the source color key, ignoring alpha in the + * comparison. + * + * RGB->RGBA: + * Source surface blend mode set to SDL_BLENDMODE_BLEND: + * alpha-blend (using the source per-surface alpha) + * Source surface blend mode set to SDL_BLENDMODE_NONE: + * copy RGB, set destination alpha to source per-surface alpha value. + * both: + * if SDL_SRCCOLORKEY set, only copy the pixels matching the + * source color key. + * + * RGBA->RGBA: + * Source surface blend mode set to SDL_BLENDMODE_BLEND: + * alpha-blend (using the source alpha-channel and per-surface alpha) + * SDL_SRCCOLORKEY ignored. + * Source surface blend mode set to SDL_BLENDMODE_NONE: + * copy all of RGBA to the destination. + * if SDL_SRCCOLORKEY set, only copy the pixels matching the + * RGB values of the source color key, ignoring alpha in the + * comparison. + * + * RGB->RGB: + * Source surface blend mode set to SDL_BLENDMODE_BLEND: + * alpha-blend (using the source per-surface alpha) + * Source surface blend mode set to SDL_BLENDMODE_NONE: + * copy RGB. + * both: + * if SDL_SRCCOLORKEY set, only copy the pixels matching the + * source color key. + * ``` + * + * You should call SDL_BlitSurface() unless you know exactly how SDL blitting + * works internally and how to use the other blit functions. + * + * \returns 0 if the blit is successful, otherwise it returns -1. */ #define SDL_BlitSurface SDL_UpperBlit @@ -883,12 +886,12 @@ extern DECLSPEC int SDLCALL SDL_UpperBlit * 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 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 + * 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 + * copied into. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -925,8 +928,6 @@ extern DECLSPEC int SDLCALL SDL_SoftStretchLinear(SDL_Surface * src, const SDL_Rect * dstrect); -#define SDL_BlitScaled SDL_UpperBlitScaled - /** * Perform a scaled surface copy to a destination surface. * @@ -941,18 +942,21 @@ extern DECLSPEC int SDLCALL SDL_UpperBlitScaled (SDL_Surface * src, const SDL_Rect * srcrect, SDL_Surface * dst, SDL_Rect * dstrect); +#define SDL_BlitScaled SDL_UpperBlitScaled + + /** * 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 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 + * 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 + * copied into. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_system.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_system.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_system.h + * # CategorySystem * - * Include file for platform specific SDL API functions + * Include file for platform specific SDL API functions */ #ifndef SDL_system_h_ @@ -49,7 +49,7 @@ typedef void (SDLCALL * SDL_WindowsMessageHook)(void *userdata, void *hWnd, unsi * 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` + * \param userdata a pointer to pass to every iteration of `callback`. * * \since This function is available since SDL 2.0.4. */ @@ -66,7 +66,7 @@ extern DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook ca * controls on which monitor a full screen application will appear. * * \param displayIndex the display index for which to get the D3D9 adapter - * index + * index. * \returns the D3D9 adapter index on success or a negative error code on * failure; call SDL_GetError() for more information. * @@ -82,7 +82,7 @@ typedef struct IDirect3DDevice9 IDirect3DDevice9; * 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 + * \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. * @@ -98,7 +98,7 @@ typedef struct ID3D11Device ID3D11Device; * 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 + * \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. * @@ -118,7 +118,7 @@ typedef struct ID3D12Device ID3D12Device; * 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 D3D12 device + * \param renderer the renderer from which to get the associated D3D12 device. * \returns the D3D12 device associated with given renderer or NULL if it is * not a D3D12 renderer; call SDL_GetError() for more information. * @@ -140,9 +140,9 @@ extern DECLSPEC ID3D12Device* SDLCALL SDL_RenderGetD3D12Device(SDL_Renderer* ren * 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 + * \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. * @@ -176,7 +176,7 @@ extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriority(Sint64 threadID, int prio * \param threadID The Unix thread ID to change priority of. * \param sdlPriority The new SDL_ThreadPriority value. * \param schedPolicy The new scheduling policy (SCHED_FIFO, SCHED_RR, - * SCHED_OTHER, etc...) + * SCHED_OTHER, etc...). * \returns 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.18. @@ -188,7 +188,7 @@ extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriorityAndPolicy(Sint64 threadID, /* Platform specific functions for iOS */ #ifdef __IPHONEOS__ -#define SDL_iOSSetAnimationCallback(window, interval, callback, callbackParam) SDL_iPhoneSetAnimationCallback(window, interval, callback, callbackParam) +typedef void (SDLCALL *SDL_iOSAnimationCallback)(void*); /** * Use this function to set the animation callback on Apple iOS. @@ -210,9 +210,9 @@ extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriorityAndPolicy(Sint64 threadID, * This functions is also accessible using the macro * SDL_iOSSetAnimationCallback() since SDL 2.0.4. * - * \param window the window for which the animation callback should be set + * \param window the window for which the animation callback should be set. * \param interval the number of frames after which **callback** will be - * called + * called. * \param callback the function to call for every frame. * \param callbackParam a pointer that is passed to `callback`. * \returns 0 on success or a negative error code on failure; call @@ -222,9 +222,10 @@ extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriorityAndPolicy(Sint64 threadID, * * \sa SDL_iPhoneSetEventPump */ -extern DECLSPEC int SDLCALL SDL_iPhoneSetAnimationCallback(SDL_Window * window, int interval, void (SDLCALL *callback)(void*), void *callbackParam); +extern DECLSPEC int SDLCALL SDL_iPhoneSetAnimationCallback(SDL_Window * window, int interval, SDL_iOSAnimationCallback callback, void *callbackParam); + +#define SDL_iOSSetAnimationCallback(window, interval, callback, callbackParam) SDL_iPhoneSetAnimationCallback(window, interval, callback, callbackParam) -#define SDL_iOSSetEventPump(enabled) SDL_iPhoneSetEventPump(enabled) /** * Use this function to enable or disable the SDL event pump on Apple iOS. @@ -234,7 +235,7 @@ extern DECLSPEC int SDLCALL SDL_iPhoneSetAnimationCallback(SDL_Window * window, * This functions is also accessible using the macro SDL_iOSSetEventPump() * since SDL 2.0.4. * - * \param enabled SDL_TRUE to enable the event pump, SDL_FALSE to disable it + * \param enabled SDL_TRUE to enable the event pump, SDL_FALSE to disable it. * * \since This function is available since SDL 2.0.0. * @@ -242,6 +243,9 @@ extern DECLSPEC int SDLCALL SDL_iPhoneSetAnimationCallback(SDL_Window * window, */ extern DECLSPEC void SDLCALL SDL_iPhoneSetEventPump(SDL_bool enabled); +#define SDL_iOSSetEventPump(enabled) SDL_iPhoneSetEventPump(enabled) + +/* end of iOS-specific functions. */ #endif /* __IPHONEOS__ */ @@ -356,9 +360,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IsDeXMode(void); extern DECLSPEC void SDLCALL SDL_AndroidBackButton(void); /** - See the official Android developer guide for more information: - http://developer.android.com/guide/topics/data/data-storage.html -*/ + * See the official Android developer guide for more information: + * http://developer.android.com/guide/topics/data/data-storage.html + */ #define SDL_ANDROID_EXTERNAL_STORAGE_READ 0x01 #define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02 @@ -441,11 +445,11 @@ extern DECLSPEC SDL_bool SDLCALL SDL_AndroidRequestPermission(const char *permis * * https://developer.android.com/reference/android/view/Gravity * - * \param message text message to be shown - * \param duration 0=short, 1=long + * \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 + * \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. * * \since This function is available since SDL 2.0.16. @@ -457,8 +461,8 @@ extern DECLSPEC int SDLCALL SDL_AndroidShowToast(const char* message, int durati * * Override "boolean onUnhandledMessage(Message msg)" to handle the message. * - * \param command user command that must be greater or equal to 0x8000 - * \param param user parameter + * \param command user command that must be greater or equal to 0x8000. + * \param param user parameter. * * \since This function is available since SDL 2.0.22. */ @@ -470,9 +474,9 @@ extern DECLSPEC int SDLCALL SDL_AndroidSendMessage(Uint32 command, int param); #ifdef __WINRT__ /** - * \brief WinRT / Windows Phone path types + * WinRT / Windows Phone path types */ -typedef enum +typedef enum SDL_WinRT_Path { /** \brief The installed app's root directory. Files here are likely to be read-only. */ @@ -494,9 +498,9 @@ typedef enum /** - * \brief WinRT Device Family + * WinRT Device Family */ -typedef enum +typedef enum SDL_WinRT_DeviceFamily { /** \brief Unknown family */ SDL_WINRT_DEVICEFAMILY_UNKNOWN, @@ -524,7 +528,7 @@ typedef enum * * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx * - * \param pathType the type of path to retrieve, one of SDL_WinRT_Path + * \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. @@ -547,7 +551,7 @@ extern DECLSPEC const wchar_t * SDLCALL SDL_WinRTGetFSPathUNICODE(SDL_WinRT_Path * * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx * - * \param pathType the type of path to retrieve, one of SDL_WinRT_Path + * \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. diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_syswm.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_syswm.h @@ -19,10 +19,17 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** - * \file SDL_syswm.h +/* WIKI CATEGORY: SYSWM */ + +/* + * # CategorySYSWM + * + * Include file for SDL custom system window manager hooks. * - * Include file for SDL custom system window manager hooks. + * Your application has access to a special type of event SDL_SYSWMEVENT, + * which contains window-manager specific information and arrives whenever + * an unhandled window event occurs. This event is ignored by default, but + * you can enable it with SDL_EventState(). */ #ifndef SDL_syswm_h_ @@ -33,14 +40,6 @@ #include "SDL_video.h" #include "SDL_version.h" -/** - * \brief SDL_syswm.h - * - * Your application has access to a special type of event ::SDL_SYSWMEVENT, - * which contains window-manager specific information and arrives whenever - * an unhandled window event occurs. This event is ignored by default, but - * you can enable it with SDL_EventState(). - */ struct SDL_SysWMinfo; #if !defined(SDL_PROTOTYPES_ONLY) @@ -129,10 +128,11 @@ extern "C" { #endif #if !defined(SDL_PROTOTYPES_ONLY) + /** - * These are the various supported windowing subsystems + * These are the various supported windowing subsystems */ -typedef enum +typedef enum SDL_SYSWM_TYPE { SDL_SYSWM_UNKNOWN, SDL_SYSWM_WINDOWS, @@ -152,7 +152,7 @@ typedef enum } SDL_SYSWM_TYPE; /** - * The custom event structure. + * The custom event structure. */ struct SDL_SysWMmsg { @@ -218,10 +218,10 @@ struct SDL_SysWMmsg }; /** - * The custom window manager information structure. + * The custom window manager information structure. * - * When this structure is returned, it holds information about which - * low level system it is using, and will be one of SDL_SYSWM_TYPE. + * When this structure is returned, it holds information about which low level + * system it is using, and will be one of SDL_SYSWM_TYPE. */ struct SDL_SysWMinfo { @@ -363,8 +363,8 @@ typedef struct SDL_SysWMinfo SDL_SysWMinfo; * `SDL_VERSION(&info.version)`, and then this function will fill in the rest * of the structure with information about the given window. * - * \param window the window about which information is being requested - * \param info an SDL_SysWMinfo structure filled in with window information + * \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. diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test.h @@ -19,7 +19,7 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** +/* * \file SDL_test.h * * Include file for SDL test framework. diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test_assert.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test_assert.h @@ -19,7 +19,7 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** +/* * \file SDL_test_assert.h * * Include file for SDL test framework. @@ -42,17 +42,17 @@ extern "C" { #endif -/** +/* * \brief Fails the assert. */ #define ASSERT_FAIL 0 -/** +/* * \brief Passes the assert. */ #define ASSERT_PASS 1 -/** +/* * \brief Assert that logs and break execution flow on failures. * * \param assertCondition Evaluated condition or variable to assert; fail (==0) or pass (!=0). @@ -60,7 +60,7 @@ extern "C" { */ void SDLTest_Assert(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2); -/** +/* * \brief Assert for test cases that logs but does not break execution flow on failures. Updates assertion counters. * * \param assertCondition Evaluated condition or variable to assert; fail (==0) or pass (!=0). @@ -70,25 +70,25 @@ void SDLTest_Assert(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *as */ int SDLTest_AssertCheck(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2); -/** +/* * \brief Explicitly pass without checking an assertion condition. Updates assertion counter. * * \param assertDescription Message to log with the assert describing it. */ void SDLTest_AssertPass(SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(1); -/** +/* * \brief Resets the assert summary counters to zero. */ void SDLTest_ResetAssertSummary(void); -/** +/* * \brief Logs summary of all assertions (total, pass, fail) since last reset as INFO or ERROR. */ void SDLTest_LogAssertSummary(void); -/** +/* * \brief Converts the current assert summary state to a test result. * * \returns TEST_RESULT_PASSED, TEST_RESULT_FAILED, or TEST_RESULT_NO_ASSERT diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test_common.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test_common.h @@ -19,7 +19,7 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** +/* * \file SDL_test_common.h * * Include file for SDL test framework. @@ -129,7 +129,7 @@ extern "C" { /* Function prototypes */ -/** +/* * \brief Parse command line parameters and create common state. * * \param argv Array of command line parameters @@ -139,7 +139,7 @@ extern "C" { */ SDLTest_CommonState *SDLTest_CommonCreateState(char **argv, Uint32 flags); -/** +/* * \brief Process one common argument. * * \param state The common state describing the test window to create. @@ -150,7 +150,7 @@ SDLTest_CommonState *SDLTest_CommonCreateState(char **argv, Uint32 flags); int SDLTest_CommonArg(SDLTest_CommonState * state, int index); -/** +/* * \brief Logs command line usage info. * * This logs the appropriate command line options for the subsystems in use @@ -164,7 +164,7 @@ int SDLTest_CommonArg(SDLTest_CommonState * state, int index); */ void SDLTest_CommonLogUsage(SDLTest_CommonState * state, const char *argv0, const char **options); -/** +/* * \brief Returns common usage information * * You should (probably) be using SDLTest_CommonLogUsage() instead, but this @@ -177,7 +177,7 @@ void SDLTest_CommonLogUsage(SDLTest_CommonState * state, const char *argv0, cons */ const char *SDLTest_CommonUsage(SDLTest_CommonState * state); -/** +/* * \brief Open test window. * * \param state The common state describing the test window to create. @@ -186,7 +186,7 @@ const char *SDLTest_CommonUsage(SDLTest_CommonState * state); */ SDL_bool SDLTest_CommonInit(SDLTest_CommonState * state); -/** +/* * \brief Easy argument handling when test app doesn't need any custom args. * * \param state The common state describing the test window to create. @@ -197,7 +197,7 @@ SDL_bool SDLTest_CommonInit(SDLTest_CommonState * state); */ SDL_bool SDLTest_CommonDefaultArgs(SDLTest_CommonState * state, const int argc, char **argv); -/** +/* * \brief Common event handler for test windows. * * \param state The common state used to create test window. @@ -207,7 +207,7 @@ SDL_bool SDLTest_CommonDefaultArgs(SDLTest_CommonState * state, const int argc, */ void SDLTest_CommonEvent(SDLTest_CommonState * state, SDL_Event * event, int *done); -/** +/* * \brief Close test window. * * \param state The common state used to create test window. @@ -215,7 +215,7 @@ void SDLTest_CommonEvent(SDLTest_CommonState * state, SDL_Event * event, int *do */ void SDLTest_CommonQuit(SDLTest_CommonState * state); -/** +/* * \brief Draws various window information (position, size, etc.) to the renderer. * * \param renderer The renderer to draw to. diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test_compare.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test_compare.h @@ -19,7 +19,7 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** +/* * \file SDL_test_compare.h * * Include file for SDL test framework. @@ -46,7 +46,7 @@ extern "C" { #endif -/** +/* * \brief Compares a surface and with reference image data for equality * * \param surface Surface used in comparison diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test_crc32.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test_crc32.h @@ -19,7 +19,7 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** +/* * \file SDL_test_crc32.h * * Include file for SDL test framework. @@ -60,7 +60,7 @@ extern "C" { #define CRC32_POLY 0xEDB88320 /* Perl String::CRC32 compatible */ #endif -/** +/* * Data structure for CRC32 (checksum) computation */ typedef struct { @@ -69,7 +69,7 @@ extern "C" { /* ---------- Function Prototypes ------------- */ -/** +/* * \brief Initialize the CRC context * * Note: The function initializes the crc table required for all crc calculations. @@ -82,7 +82,7 @@ extern "C" { int SDLTest_Crc32Init(SDLTest_Crc32Context * crcContext); -/** +/* * \brief calculate a crc32 from a data block * * \param crcContext pointer to context variable @@ -101,7 +101,7 @@ int SDLTest_Crc32CalcEnd(SDLTest_Crc32Context * crcContext, CrcUint32 *crc32); int SDLTest_Crc32CalcBuffer(SDLTest_Crc32Context * crcContext, CrcUint8 *inBuf, CrcUint32 inLen, CrcUint32 *crc32); -/** +/* * \brief clean up CRC context * * \param crcContext pointer to context variable diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test_font.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test_font.h @@ -19,7 +19,7 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** +/* * \file SDL_test_font.h * * Include file for SDL test framework. @@ -41,7 +41,7 @@ extern "C" { #define FONT_CHARACTER_SIZE 8 #define FONT_LINE_HEIGHT (FONT_CHARACTER_SIZE + 2) -/** +/* * \brief Draw a string in the currently set font. * * \param renderer The renderer to draw on. @@ -53,7 +53,7 @@ extern "C" { */ int SDLTest_DrawCharacter(SDL_Renderer *renderer, int x, int y, Uint32 c); -/** +/* * \brief Draw a UTF-8 string in the currently set font. * * The font currently only supports characters in the Basic Latin and Latin-1 Supplement sets. @@ -67,7 +67,7 @@ int SDLTest_DrawCharacter(SDL_Renderer *renderer, int x, int y, Uint32 c); */ int SDLTest_DrawString(SDL_Renderer *renderer, int x, int y, const char *s); -/** +/* * \brief Data used for multi-line text output */ typedef struct SDLTest_TextWindow @@ -78,7 +78,7 @@ typedef struct SDLTest_TextWindow char **lines; } SDLTest_TextWindow; -/** +/* * \brief Create a multi-line text output window * * \param x The X coordinate of the upper left corner of the window. @@ -92,7 +92,7 @@ typedef struct SDLTest_TextWindow */ SDLTest_TextWindow *SDLTest_TextWindowCreate(int x, int y, int w, int h); -/** +/* * \brief Display a multi-line text output window * * This function should be called every frame to display the text @@ -104,7 +104,7 @@ SDLTest_TextWindow *SDLTest_TextWindowCreate(int x, int y, int w, int h); */ void SDLTest_TextWindowDisplay(SDLTest_TextWindow *textwin, SDL_Renderer *renderer); -/** +/* * \brief Add text to a multi-line text output window * * Adds UTF-8 text to the end of the current text. The newline character starts a @@ -119,7 +119,7 @@ void SDLTest_TextWindowDisplay(SDLTest_TextWindow *textwin, SDL_Renderer *render */ void SDLTest_TextWindowAddText(SDLTest_TextWindow *textwin, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); -/** +/* * \brief Add text to a multi-line text output window * * Adds UTF-8 text to the end of the current text. The newline character starts a @@ -134,7 +134,7 @@ void SDLTest_TextWindowAddText(SDLTest_TextWindow *textwin, SDL_PRINTF_FORMAT_ST */ void SDLTest_TextWindowAddTextWithLength(SDLTest_TextWindow *textwin, const char *text, size_t len); -/** +/* * \brief Clear the text in a multi-line text output window * * \param textwin The text output window @@ -143,7 +143,7 @@ void SDLTest_TextWindowAddTextWithLength(SDLTest_TextWindow *textwin, const char */ void SDLTest_TextWindowClear(SDLTest_TextWindow *textwin); -/** +/* * \brief Free the storage associated with a multi-line text output window * * \param textwin The text output window @@ -152,7 +152,7 @@ void SDLTest_TextWindowClear(SDLTest_TextWindow *textwin); */ void SDLTest_TextWindowDestroy(SDLTest_TextWindow *textwin); -/** +/* * \brief Cleanup textures used by font drawing functions. */ void SDLTest_CleanupTextDrawing(void); diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test_fuzzer.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test_fuzzer.h @@ -19,7 +19,7 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** +/* * \file SDL_test_fuzzer.h * * Include file for SDL test framework. @@ -48,13 +48,13 @@ extern "C" { */ -/** +/* * \file * Note: The fuzzer implementation uses a static instance of random context * internally which makes it thread-UNsafe. */ -/** +/* * Initializes the fuzzer for a test * * \param execKey Execution "Key" that initializes the random number generator uniquely for the test. @@ -63,14 +63,14 @@ extern "C" { void SDLTest_FuzzerInit(Uint64 execKey); -/** +/* * Returns a random Uint8 * * \returns a generated integer */ Uint8 SDLTest_RandomUint8(void); -/** +/* * Returns a random Sint8 * * \returns a generated signed integer @@ -78,14 +78,14 @@ Uint8 SDLTest_RandomUint8(void); Sint8 SDLTest_RandomSint8(void); -/** +/* * Returns a random Uint16 * * \returns a generated integer */ Uint16 SDLTest_RandomUint16(void); -/** +/* * Returns a random Sint16 * * \returns a generated signed integer @@ -93,7 +93,7 @@ Uint16 SDLTest_RandomUint16(void); Sint16 SDLTest_RandomSint16(void); -/** +/* * Returns a random integer * * \returns a generated integer @@ -101,14 +101,14 @@ Sint16 SDLTest_RandomSint16(void); Sint32 SDLTest_RandomSint32(void); -/** +/* * Returns a random positive integer * * \returns a generated integer */ Uint32 SDLTest_RandomUint32(void); -/** +/* * Returns random Uint64. * * \returns a generated integer @@ -116,36 +116,36 @@ Uint32 SDLTest_RandomUint32(void); Uint64 SDLTest_RandomUint64(void); -/** +/* * Returns random Sint64. * * \returns a generated signed integer */ Sint64 SDLTest_RandomSint64(void); -/** +/* * \returns a random float in range [0.0 - 1.0] */ float SDLTest_RandomUnitFloat(void); -/** +/* * \returns a random double in range [0.0 - 1.0] */ double SDLTest_RandomUnitDouble(void); -/** +/* * \returns a random float. * */ float SDLTest_RandomFloat(void); -/** +/* * \returns a random double. * */ double SDLTest_RandomDouble(void); -/** +/* * Returns a random boundary value for Uint8 within the given boundaries. * Boundaries are inclusive, see the usage examples below. If validDomain * is true, the function will only return valid boundaries, otherwise non-valid @@ -166,7 +166,7 @@ double SDLTest_RandomDouble(void); */ Uint8 SDLTest_RandomUint8BoundaryValue(Uint8 boundary1, Uint8 boundary2, SDL_bool validDomain); -/** +/* * Returns a random boundary value for Uint16 within the given boundaries. * Boundaries are inclusive, see the usage examples below. If validDomain * is true, the function will only return valid boundaries, otherwise non-valid @@ -187,7 +187,7 @@ Uint8 SDLTest_RandomUint8BoundaryValue(Uint8 boundary1, Uint8 boundary2, SDL_boo */ Uint16 SDLTest_RandomUint16BoundaryValue(Uint16 boundary1, Uint16 boundary2, SDL_bool validDomain); -/** +/* * Returns a random boundary value for Uint32 within the given boundaries. * Boundaries are inclusive, see the usage examples below. If validDomain * is true, the function will only return valid boundaries, otherwise non-valid @@ -208,7 +208,7 @@ Uint16 SDLTest_RandomUint16BoundaryValue(Uint16 boundary1, Uint16 boundary2, SDL */ Uint32 SDLTest_RandomUint32BoundaryValue(Uint32 boundary1, Uint32 boundary2, SDL_bool validDomain); -/** +/* * Returns a random boundary value for Uint64 within the given boundaries. * Boundaries are inclusive, see the usage examples below. If validDomain * is true, the function will only return valid boundaries, otherwise non-valid @@ -229,7 +229,7 @@ Uint32 SDLTest_RandomUint32BoundaryValue(Uint32 boundary1, Uint32 boundary2, SDL */ Uint64 SDLTest_RandomUint64BoundaryValue(Uint64 boundary1, Uint64 boundary2, SDL_bool validDomain); -/** +/* * Returns a random boundary value for Sint8 within the given boundaries. * Boundaries are inclusive, see the usage examples below. If validDomain * is true, the function will only return valid boundaries, otherwise non-valid @@ -251,7 +251,7 @@ Uint64 SDLTest_RandomUint64BoundaryValue(Uint64 boundary1, Uint64 boundary2, SDL Sint8 SDLTest_RandomSint8BoundaryValue(Sint8 boundary1, Sint8 boundary2, SDL_bool validDomain); -/** +/* * Returns a random boundary value for Sint16 within the given boundaries. * Boundaries are inclusive, see the usage examples below. If validDomain * is true, the function will only return valid boundaries, otherwise non-valid @@ -272,7 +272,7 @@ Sint8 SDLTest_RandomSint8BoundaryValue(Sint8 boundary1, Sint8 boundary2, SDL_boo */ Sint16 SDLTest_RandomSint16BoundaryValue(Sint16 boundary1, Sint16 boundary2, SDL_bool validDomain); -/** +/* * Returns a random boundary value for Sint32 within the given boundaries. * Boundaries are inclusive, see the usage examples below. If validDomain * is true, the function will only return valid boundaries, otherwise non-valid @@ -293,7 +293,7 @@ Sint16 SDLTest_RandomSint16BoundaryValue(Sint16 boundary1, Sint16 boundary2, SDL */ Sint32 SDLTest_RandomSint32BoundaryValue(Sint32 boundary1, Sint32 boundary2, SDL_bool validDomain); -/** +/* * Returns a random boundary value for Sint64 within the given boundaries. * Boundaries are inclusive, see the usage examples below. If validDomain * is true, the function will only return valid boundaries, otherwise non-valid @@ -315,7 +315,7 @@ Sint32 SDLTest_RandomSint32BoundaryValue(Sint32 boundary1, Sint32 boundary2, SDL Sint64 SDLTest_RandomSint64BoundaryValue(Sint64 boundary1, Sint64 boundary2, SDL_bool validDomain); -/** +/* * Returns integer in range [min, max] (inclusive). * Min and max values can be negative values. * If Max in smaller than min, then the values are swapped. @@ -329,7 +329,7 @@ Sint64 SDLTest_RandomSint64BoundaryValue(Sint64 boundary1, Sint64 boundary2, SDL Sint32 SDLTest_RandomIntegerInRange(Sint32 min, Sint32 max); -/** +/* * Generates random null-terminated string. The minimum length for * the string is 1 character, maximum length for the string is 255 * characters and it can contain ASCII characters from 32 to 126. @@ -341,7 +341,7 @@ Sint32 SDLTest_RandomIntegerInRange(Sint32 min, Sint32 max); char * SDLTest_RandomAsciiString(void); -/** +/* * Generates random null-terminated string. The maximum length for * the string is defined by the maxLength parameter. * String can contain ASCII characters from 32 to 126. @@ -355,7 +355,7 @@ char * SDLTest_RandomAsciiString(void); char * SDLTest_RandomAsciiStringWithMaximumLength(int maxLength); -/** +/* * Generates random null-terminated string. The length for * the string is defined by the size parameter. * String can contain ASCII characters from 32 to 126. @@ -368,7 +368,8 @@ char * SDLTest_RandomAsciiStringWithMaximumLength(int maxLength); */ char * SDLTest_RandomAsciiStringOfSize(int size); -/** + +/* * Get the invocation count for the fuzzer since last ...FuzzerInit. * * \returns the invocation count. diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test_harness.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test_harness.h @@ -19,7 +19,7 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** +/* * \file SDL_test_harness.h * * Include file for SDL test framework. @@ -69,7 +69,7 @@ typedef int (*SDLTest_TestCaseFp)(void *arg); /* !< Function pointer to a test case teardown function (run after every test) */ typedef void (*SDLTest_TestCaseTearDownFp)(void *arg); -/** +/* * Holds information about a single test case. */ typedef struct SDLTest_TestCaseReference { @@ -83,7 +83,7 @@ typedef struct SDLTest_TestCaseReference { int enabled; } SDLTest_TestCaseReference; -/** +/* * Holds information about a test suite (multiple test cases). */ typedef struct SDLTest_TestSuiteReference { @@ -98,7 +98,7 @@ typedef struct SDLTest_TestSuiteReference { } SDLTest_TestSuiteReference; -/** +/* * \brief Generates a random run seed string for the harness. The generated seed will contain alphanumeric characters (0-9A-Z). * * Note: The returned string needs to be deallocated by the caller. @@ -109,7 +109,7 @@ typedef struct SDLTest_TestSuiteReference { */ char *SDLTest_GenerateRunSeed(const int length); -/** +/* * \brief Execute a test suite using the given run seed and execution key. * * \param testSuites Suites containing the test case. diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test_images.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test_images.h @@ -19,7 +19,7 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** +/* * \file SDL_test_images.h * * Include file for SDL test framework. @@ -44,7 +44,7 @@ extern "C" { #endif -/** +/* *Type for test images. */ typedef struct SDLTest_SurfaceImage_s { diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test_log.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test_log.h @@ -19,7 +19,7 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** +/* * \file SDL_test_log.h * * Include file for SDL test framework. @@ -42,14 +42,14 @@ extern "C" { #endif -/** +/* * \brief Prints given message with a timestamp in the TEST category and INFO priority. * * \param fmt Message to be logged */ void SDLTest_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); -/** +/* * \brief Prints given message with a timestamp in the TEST category and the ERROR priority. * * \param fmt Message to be logged diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test_md5.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test_md5.h @@ -19,7 +19,7 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** +/* * \file SDL_test_md5.h * * Include file for SDL test framework. @@ -77,7 +77,7 @@ extern "C" { /* ---------- Function Prototypes ------------- */ -/** +/* * \brief initialize the context * * \param mdContext pointer to context variable @@ -89,7 +89,7 @@ extern "C" { void SDLTest_Md5Init(SDLTest_Md5Context * mdContext); -/** +/* * \brief update digest from variable length data * * \param mdContext pointer to context variable @@ -105,7 +105,7 @@ extern "C" { unsigned int inLen); -/** +/* * \brief complete digest computation * * \param mdContext pointer to context variable diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test_memory.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test_memory.h @@ -19,7 +19,7 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** +/* * \file SDL_test_memory.h * * Include file for SDL test framework. @@ -37,14 +37,14 @@ extern "C" { #endif -/** +/* * \brief Start tracking SDL memory allocations * * \note This should be called before any other SDL functions for complete tracking coverage */ int SDLTest_TrackAllocations(void); -/** +/* * \brief Print a log of any outstanding allocations * * \note This can be called after SDL_Quit() diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test_random.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_test_random.h @@ -19,7 +19,7 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** +/* * \file SDL_test_random.h * * Include file for SDL test framework. @@ -67,7 +67,7 @@ extern "C" { /* --- Function prototypes */ -/** +/* * \brief Initialize random number generator with two integers. * * Note: The random sequence of numbers returned by ...Random() is the @@ -81,7 +81,7 @@ extern "C" { void SDLTest_RandomInit(SDLTest_RandomContext * rndContext, unsigned int xi, unsigned int ci); -/** +/* * \brief Initialize random number generator based on current system time. * * \param rndContext pointer to context structure @@ -90,7 +90,7 @@ extern "C" { void SDLTest_RandomInitTime(SDLTest_RandomContext *rndContext); -/** +/* * \brief Initialize random number generator based on current system time. * * Note: ...RandomInit() or ...RandomInitTime() must have been called diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_thread.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_thread.h @@ -23,9 +23,9 @@ #define SDL_thread_h_ /** - * \file SDL_thread.h + * # CategoryThread * - * Header for the SDL thread management routines. + * Header for the SDL thread management routines. */ #include "SDL_stdinc.h" @@ -63,16 +63,18 @@ typedef unsigned long SDL_threadID; typedef unsigned int SDL_TLSID; /** - * The SDL thread priority. + * The SDL thread priority. * - * SDL will make system changes as necessary in order to apply the thread priority. - * Code which attempts to control thread state related to priority should be aware - * that calling SDL_SetThreadPriority may alter such state. - * SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of this behavior. + * SDL will make system changes as necessary in order to apply the thread + * priority. Code which attempts to control thread state related to priority + * should be aware that calling SDL_SetThreadPriority may alter such state. + * SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of this + * behavior. * - * \note On many systems you require special privileges to set high or time critical priority. + * On many systems you require special privileges to set high or time critical + * priority. */ -typedef enum { +typedef enum SDL_ThreadPriority { SDL_THREAD_PRIORITY_LOW, SDL_THREAD_PRIORITY_NORMAL, SDL_THREAD_PRIORITY_HIGH, @@ -82,7 +84,7 @@ typedef enum { /** * The function passed to SDL_CreateThread(). * - * \param data what was passed as `data` 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); @@ -192,9 +194,9 @@ SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn, const char *name, const siz * 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` + * \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. @@ -238,10 +240,10 @@ SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data); * 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 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` + * \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. @@ -261,7 +263,7 @@ SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn, const char *name, const siz * 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 + * \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. * @@ -296,7 +298,7 @@ extern DECLSPEC SDL_threadID SDLCALL SDL_ThreadID(void); * 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 + * \param thread the thread to query. * \returns the ID of the specified thread, or the ID of the current thread if * `thread` is NULL. * @@ -313,7 +315,7 @@ extern DECLSPEC SDL_threadID SDLCALL SDL_GetThreadID(SDL_Thread * thread); * 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 + * \param priority the SDL_ThreadPriority to set. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -344,7 +346,7 @@ extern DECLSPEC int SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority priority); * afterward. * * \param thread the SDL_Thread pointer that was returned from the - * SDL_CreateThread() call that started this thread + * 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. @@ -383,7 +385,7 @@ extern DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread * thread, int *status); * 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 + * SDL_CreateThread() call that started this thread. * * \since This function is available since SDL 2.0.2. * @@ -410,7 +412,7 @@ extern DECLSPEC SDL_TLSID SDLCALL SDL_TLSCreate(void); /** * 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. * @@ -421,6 +423,8 @@ extern DECLSPEC SDL_TLSID SDLCALL SDL_TLSCreate(void); */ extern DECLSPEC void * SDLCALL SDL_TLSGet(SDL_TLSID id); +typedef void (SDLCALL *SDL_TLSDestructorCallback)(void*); + /** * Set the current thread's value associated with a thread local storage ID. * @@ -432,10 +436,10 @@ extern DECLSPEC void * SDLCALL SDL_TLSGet(SDL_TLSID id); * * 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 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 + * value. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -444,7 +448,7 @@ extern DECLSPEC void * SDLCALL SDL_TLSGet(SDL_TLSID id); * \sa SDL_TLSCreate * \sa SDL_TLSGet */ -extern DECLSPEC int SDLCALL SDL_TLSSet(SDL_TLSID id, const void *value, void (SDLCALL *destructor)(void*)); +extern DECLSPEC int SDLCALL SDL_TLSSet(SDL_TLSID id, const void *value, SDL_TLSDestructorCallback destructor); /** * Cleanup all TLS data for this thread. diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_timer.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_timer.h @@ -23,9 +23,9 @@ #define SDL_timer_h_ /** - * \file SDL_timer.h + * # CategoryTimer * - * Header for the SDL time management routines. + * Header for the SDL time management routines. */ #include "SDL_stdinc.h" @@ -89,8 +89,8 @@ extern DECLSPEC Uint64 SDLCALL SDL_GetTicks64(void); * days, but should _not_ be used with SDL_GetTicks64(), which does not have * that problem. * - * For example, with SDL_GetTicks(), if you want to wait 100 ms, you could - * do this: + * For example, with SDL_GetTicks(), if you want to wait 100 ms, you could do + * this: * * ```c * const Uint32 timeout = SDL_GetTicks() + 100; @@ -99,9 +99,9 @@ extern DECLSPEC Uint64 SDLCALL SDL_GetTicks64(void); * } * ``` * - * Note that this does not handle tick differences greater - * than 2^31 so take care when using the above kind of code - * with large timeout delays (tens of days). + * Note that this does not handle tick differences greater than 2^31 so take + * care when using the above kind of code with large timeout delays (tens of + * days). */ #define SDL_TICKS_PASSED(A, B) ((Sint32)((B) - (A)) <= 0) @@ -140,7 +140,7 @@ extern DECLSPEC Uint64 SDLCALL SDL_GetPerformanceFrequency(void); * waits at least the specified time, but possibly longer due to OS * scheduling. * - * \param ms the number of milliseconds to delay + * \param ms the number of milliseconds to delay. * * \since This function is available since SDL 2.0.0. */ @@ -149,10 +149,10 @@ extern DECLSPEC void SDLCALL SDL_Delay(Uint32 ms); /** * 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); @@ -182,10 +182,10 @@ typedef int SDL_TimerID; * 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 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` + * `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. * @@ -200,7 +200,7 @@ extern DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval, /** * Remove a timer created with SDL_AddTimer(). * - * \param id the ID of the timer to remove + * \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. * diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_touch.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_touch.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_touch.h + * # CategoryTouch * - * Include file for SDL touch event handling. + * Include file for SDL touch event handling. */ #ifndef SDL_touch_h_ @@ -85,7 +85,7 @@ extern DECLSPEC int SDLCALL SDL_GetNumTouchDevices(void); /** * Get the touch ID with the given index. * - * \param index the touch device 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. * @@ -113,7 +113,7 @@ extern DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_TouchID t /** * Get the number of active fingers for a given touch device. * - * \param touchID the ID of a 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. * @@ -128,8 +128,8 @@ extern DECLSPEC int SDLCALL SDL_GetNumTouchFingers(SDL_TouchID touchID); * * 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 + * \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. * diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_types.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_types.h @@ -19,11 +19,6 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** - * \file SDL_types.h - * - * \deprecated - */ - /* DEPRECATED */ + #include "SDL_stdinc.h" diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_version.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_version.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_version.h + * # CategoryVersion * - * This header defines the current SDL version. + * This header defines the current SDL version. */ #ifndef SDL_version_h_ @@ -40,10 +40,9 @@ extern "C" { * 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). + * (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 @@ -58,18 +57,17 @@ typedef struct SDL_version /* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL */ #define SDL_MAJOR_VERSION 2 -#define SDL_MINOR_VERSION 30 -#define SDL_PATCHLEVEL 12 +#define SDL_MINOR_VERSION 32 +#define SDL_PATCHLEVEL 2 /** * 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. * @@ -85,37 +83,40 @@ typedef struct SDL_version /* TODO: Remove this whole block in SDL 3 */ #if SDL_MAJOR_VERSION < 3 + /** - * This macro turns the version numbers into a numeric value: - * \verbatim - (1,2,3) -> (1203) - \endverbatim + * This macro turns the version numbers into a numeric value: + * + * ``` + * (1,2,3) -> (1203) + * ``` + * + * This assumes that there will never be more than 100 patchlevels. * - * This assumes that there will never be more than 100 patchlevels. + * In versions higher than 2.9.0, the minor version overflows into the + * thousands digit: for example, 2.23.0 is encoded as 4300, and 2.255.99 would + * be encoded as 25799. * - * In versions higher than 2.9.0, the minor version overflows into - * the thousands digit: for example, 2.23.0 is encoded as 4300, - * and 2.255.99 would be encoded as 25799. - * This macro will not be available in SDL 3.x. + * This macro will not be available in SDL 3.x. */ #define SDL_VERSIONNUM(X, Y, Z) \ ((X)*1000 + (Y)*100 + (Z)) /** - * This is the version number macro for the current SDL version. + * This is the version number macro for the current SDL version. * - * In versions higher than 2.9.0, the minor version overflows into - * the thousands digit: for example, 2.23.0 is encoded as 4300. - * This macro will not be available in SDL 3.x. + * In versions higher than 2.9.0, the minor version overflows into the + * thousands digit: for example, 2.23.0 is encoded as 4300. This macro will + * not be available in SDL 3.x. * - * Deprecated, use SDL_VERSION_ATLEAST or SDL_VERSION instead. + * Deprecated, use SDL_VERSION_ATLEAST or SDL_VERSION instead. */ #define SDL_COMPILEDVERSION \ SDL_VERSIONNUM(SDL_MAJOR_VERSION, SDL_MINOR_VERSION, SDL_PATCHLEVEL) #endif /* SDL_MAJOR_VERSION < 3 */ /** - * This macro will evaluate to true if compiled with SDL at least X.Y.Z. + * This macro will evaluate to true if compiled with SDL at least X.Y.Z. */ #define SDL_VERSION_ATLEAST(X, Y, Z) \ ((SDL_MAJOR_VERSION >= X) && \ @@ -132,7 +133,7 @@ typedef struct SDL_version * * This function may be called safely at any time, even before SDL_Init(). * - * \param ver the SDL_version structure that contains the version information + * \param ver the SDL_version structure that contains the version information. * * \since This function is available since SDL 2.0.0. * diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_video.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_video.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_video.h + * # CategoryVideo * - * Header file for SDL video functions. + * Header file for SDL video functions. */ #ifndef SDL_video_h_ @@ -40,17 +40,17 @@ extern "C" { #endif /** - * \brief The structure that defines a display mode + * The structure that defines a display mode * - * \sa SDL_GetNumDisplayModes() - * \sa SDL_GetDisplayMode() - * \sa SDL_GetDesktopDisplayMode() - * \sa SDL_GetCurrentDisplayMode() - * \sa SDL_GetClosestDisplayMode() - * \sa SDL_SetWindowDisplayMode() - * \sa SDL_GetWindowDisplayMode() + * \sa SDL_GetNumDisplayModes + * \sa SDL_GetDisplayMode + * \sa SDL_GetDesktopDisplayMode + * \sa SDL_GetCurrentDisplayMode + * \sa SDL_GetClosestDisplayMode + * \sa SDL_SetWindowDisplayMode + * \sa SDL_GetWindowDisplayMode */ -typedef struct +typedef struct SDL_DisplayMode { Uint32 format; /**< pixel format */ int w; /**< width, in screen coordinates */ @@ -60,46 +60,46 @@ typedef struct } SDL_DisplayMode; /** - * \brief The type used to identify a window - * - * \sa SDL_CreateWindow() - * \sa SDL_CreateWindowFrom() - * \sa SDL_DestroyWindow() - * \sa SDL_FlashWindow() - * \sa SDL_GetWindowData() - * \sa SDL_GetWindowFlags() - * \sa SDL_GetWindowGrab() - * \sa SDL_GetWindowKeyboardGrab() - * \sa SDL_GetWindowMouseGrab() - * \sa SDL_GetWindowPosition() - * \sa SDL_GetWindowSize() - * \sa SDL_GetWindowTitle() - * \sa SDL_HideWindow() - * \sa SDL_MaximizeWindow() - * \sa SDL_MinimizeWindow() - * \sa SDL_RaiseWindow() - * \sa SDL_RestoreWindow() - * \sa SDL_SetWindowData() - * \sa SDL_SetWindowFullscreen() - * \sa SDL_SetWindowGrab() - * \sa SDL_SetWindowKeyboardGrab() - * \sa SDL_SetWindowMouseGrab() - * \sa SDL_SetWindowIcon() - * \sa SDL_SetWindowPosition() - * \sa SDL_SetWindowSize() - * \sa SDL_SetWindowBordered() - * \sa SDL_SetWindowResizable() - * \sa SDL_SetWindowTitle() - * \sa SDL_ShowWindow() + * The opaque type used to identify a window. + * + * \sa SDL_CreateWindow + * \sa SDL_CreateWindowFrom + * \sa SDL_DestroyWindow + * \sa SDL_FlashWindow + * \sa SDL_GetWindowData + * \sa SDL_GetWindowFlags + * \sa SDL_GetWindowGrab + * \sa SDL_GetWindowKeyboardGrab + * \sa SDL_GetWindowMouseGrab + * \sa SDL_GetWindowPosition + * \sa SDL_GetWindowSize + * \sa SDL_GetWindowTitle + * \sa SDL_HideWindow + * \sa SDL_MaximizeWindow + * \sa SDL_MinimizeWindow + * \sa SDL_RaiseWindow + * \sa SDL_RestoreWindow + * \sa SDL_SetWindowData + * \sa SDL_SetWindowFullscreen + * \sa SDL_SetWindowGrab + * \sa SDL_SetWindowKeyboardGrab + * \sa SDL_SetWindowMouseGrab + * \sa SDL_SetWindowIcon + * \sa SDL_SetWindowPosition + * \sa SDL_SetWindowSize + * \sa SDL_SetWindowBordered + * \sa SDL_SetWindowResizable + * \sa SDL_SetWindowTitle + * \sa SDL_ShowWindow */ typedef struct SDL_Window SDL_Window; /** - * \brief The flags on a window + * The flags on a window * - * \sa SDL_GetWindowFlags() + * \sa SDL_GetWindowFlags */ -typedef enum +typedef enum SDL_WindowFlags { SDL_WINDOW_FULLSCREEN = 0x00000001, /**< fullscreen window */ SDL_WINDOW_OPENGL = 0x00000002, /**< window usable with OpenGL context */ @@ -131,7 +131,7 @@ typedef enum } SDL_WindowFlags; /** - * \brief Used to indicate that you don't care what the window position is. + * Used to indicate that you don't care what the window position is. */ #define SDL_WINDOWPOS_UNDEFINED_MASK 0x1FFF0000u #define SDL_WINDOWPOS_UNDEFINED_DISPLAY(X) (SDL_WINDOWPOS_UNDEFINED_MASK|(X)) @@ -140,7 +140,7 @@ typedef enum (((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK) /** - * \brief Used to indicate that the window position should be centered. + * Used to indicate that the window position should be centered. */ #define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u #define SDL_WINDOWPOS_CENTERED_DISPLAY(X) (SDL_WINDOWPOS_CENTERED_MASK|(X)) @@ -149,9 +149,9 @@ typedef enum (((X)&0xFFFF0000) == SDL_WINDOWPOS_CENTERED_MASK) /** - * \brief Event subtype for window events + * Event subtype for window events */ -typedef enum +typedef enum SDL_WindowEventID { SDL_WINDOWEVENT_NONE, /**< Never used */ SDL_WINDOWEVENT_SHOWN, /**< Window has been shown */ @@ -180,9 +180,9 @@ typedef enum } SDL_WindowEventID; /** - * \brief Event subtype for display events + * Event subtype for display events */ -typedef enum +typedef enum SDL_DisplayEventID { SDL_DISPLAYEVENT_NONE, /**< Never used */ SDL_DISPLAYEVENT_ORIENTATION, /**< Display orientation has changed to data1 */ @@ -192,9 +192,9 @@ typedef enum } SDL_DisplayEventID; /** - * \brief Display orientation + * Display orientation */ -typedef enum +typedef enum SDL_DisplayOrientation { SDL_ORIENTATION_UNKNOWN, /**< The display orientation can't be determined */ SDL_ORIENTATION_LANDSCAPE, /**< The display is in landscape mode, with the right side up, relative to portrait mode */ @@ -204,9 +204,9 @@ typedef enum } SDL_DisplayOrientation; /** - * \brief Window flash operation + * Window flash operation */ -typedef enum +typedef enum SDL_FlashOperation { SDL_FLASH_CANCEL, /**< Cancel any window flash state */ SDL_FLASH_BRIEFLY, /**< Flash the window briefly to get attention */ @@ -214,53 +214,85 @@ typedef enum } SDL_FlashOperation; /** - * \brief An opaque handle to an OpenGL context. + * An opaque handle to an OpenGL context. + * + * \sa SDL_GL_CreateContext */ typedef void *SDL_GLContext; /** - * \brief OpenGL configuration attributes + * OpenGL configuration attributes. + * + * While you can set most OpenGL attributes normally, the attributes listed + * above must be known before SDL creates the window that will be used with + * the OpenGL context. These attributes are set and read with + * SDL_GL_SetAttribute and SDL_GL_GetAttribute. + * + * In some cases, these attributes are minimum requests; the GL does not + * promise to give you exactly what you asked for. It's possible to ask for a + * 16-bit depth buffer and get a 24-bit one instead, for example, or to ask + * for no stencil buffer and still have one available. Context creation should + * fail if the GL can't provide your requested attributes at a minimum, but + * you should check to see exactly what you got. + * + * + * [Multisample anti-aliasing](http://en.wikipedia.org/wiki/Multisample_anti-aliasing) + * is a type of full screen anti-aliasing. Multipsampling defaults to off but + * can be turned on by setting SDL_GL_MULTISAMPLEBUFFERS to 1 and + * SDL_GL_MULTISAMPLESAMPLES to a value greater than 0. Typical values are 2 + * and 4. + * + * SDL_GL_CONTEXT_PROFILE_MASK determines the type of context created, while + * both SDL_GL_CONTEXT_MAJOR_VERSION and SDL_GL_CONTEXT_MINOR_VERSION + * determine which version. All three attributes must be set prior to creating + * the first window, and in general you can't change the value of + * SDL_GL_CONTEXT_PROFILE_MASK without first destroying all windows created + * with the previous setting. + * + * SDL_GL_CONTEXT_RELEASE_BEHAVIOR can be set to + * SDL_GL_CONTEXT_RELEASE_BEHAVIOR_NONE or + * SDL_GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH. */ -typedef enum +typedef enum SDL_GLattr { - SDL_GL_RED_SIZE, - SDL_GL_GREEN_SIZE, - SDL_GL_BLUE_SIZE, - SDL_GL_ALPHA_SIZE, - SDL_GL_BUFFER_SIZE, - SDL_GL_DOUBLEBUFFER, - SDL_GL_DEPTH_SIZE, - SDL_GL_STENCIL_SIZE, - SDL_GL_ACCUM_RED_SIZE, - SDL_GL_ACCUM_GREEN_SIZE, - SDL_GL_ACCUM_BLUE_SIZE, - SDL_GL_ACCUM_ALPHA_SIZE, - SDL_GL_STEREO, - SDL_GL_MULTISAMPLEBUFFERS, - SDL_GL_MULTISAMPLESAMPLES, - SDL_GL_ACCELERATED_VISUAL, - SDL_GL_RETAINED_BACKING, - SDL_GL_CONTEXT_MAJOR_VERSION, - SDL_GL_CONTEXT_MINOR_VERSION, - SDL_GL_CONTEXT_EGL, - SDL_GL_CONTEXT_FLAGS, - SDL_GL_CONTEXT_PROFILE_MASK, - SDL_GL_SHARE_WITH_CURRENT_CONTEXT, - SDL_GL_FRAMEBUFFER_SRGB_CAPABLE, - SDL_GL_CONTEXT_RELEASE_BEHAVIOR, + SDL_GL_RED_SIZE, /**< the minimum number of bits for the red channel of the color buffer; defaults to 3. */ + SDL_GL_GREEN_SIZE, /**< the minimum number of bits for the green channel of the color buffer; defaults to 3. */ + SDL_GL_BLUE_SIZE, /**< the minimum number of bits for the blue channel of the color buffer; defaults to 2. */ + SDL_GL_ALPHA_SIZE, /**< the minimum number of bits for the alpha channel of the color buffer; defaults to 0. */ + SDL_GL_BUFFER_SIZE, /**< the minimum number of bits for frame buffer size; defaults to 0. */ + SDL_GL_DOUBLEBUFFER, /**< whether the output is single or double buffered; defaults to double buffering on. */ + SDL_GL_DEPTH_SIZE, /**< the minimum number of bits in the depth buffer; defaults to 16. */ + SDL_GL_STENCIL_SIZE, /**< the minimum number of bits in the stencil buffer; defaults to 0. */ + SDL_GL_ACCUM_RED_SIZE, /**< the minimum number of bits for the red channel of the accumulation buffer; defaults to 0. */ + SDL_GL_ACCUM_GREEN_SIZE, /**< the minimum number of bits for the green channel of the accumulation buffer; defaults to 0. */ + SDL_GL_ACCUM_BLUE_SIZE, /**< the minimum number of bits for the blue channel of the accumulation buffer; defaults to 0. */ + SDL_GL_ACCUM_ALPHA_SIZE, /**< the minimum number of bits for the alpha channel of the accumulation buffer; defaults to 0. */ + SDL_GL_STEREO, /**< whether the output is stereo 3D; defaults to off. */ + SDL_GL_MULTISAMPLEBUFFERS, /**< the number of buffers used for multisample anti-aliasing; defaults to 0. */ + SDL_GL_MULTISAMPLESAMPLES, /**< the number of samples used around the current pixel used for multisample anti-aliasing. */ + SDL_GL_ACCELERATED_VISUAL, /**< set to 1 to require hardware acceleration, set to 0 to force software rendering; defaults to allow either. */ + SDL_GL_RETAINED_BACKING, /**< not used (deprecated). */ + SDL_GL_CONTEXT_MAJOR_VERSION, /**< OpenGL context major version. */ + SDL_GL_CONTEXT_MINOR_VERSION, /**< OpenGL context minor version. */ + SDL_GL_CONTEXT_EGL, /**< deprecated: set SDL_GL_CONTEXT_PROFILE_MASK to SDL_GL_CONTEXT_PROFILE_ES to enable instead. */ + SDL_GL_CONTEXT_FLAGS, /**< some combination of 0 or more of elements of the SDL_GLcontextFlag enumeration; defaults to 0. */ + SDL_GL_CONTEXT_PROFILE_MASK, /**< type of GL context (Core, Compatibility, ES). See SDL_GLprofile; default value depends on platform. */ + SDL_GL_SHARE_WITH_CURRENT_CONTEXT, /**< OpenGL context sharing; defaults to 0. */ + SDL_GL_FRAMEBUFFER_SRGB_CAPABLE, /**< requests sRGB capable visual; defaults to 0. (>= SDL 2.0.1) */ + SDL_GL_CONTEXT_RELEASE_BEHAVIOR, /**< sets context the release behavior; defaults to 1. (>= SDL 2.0.4) */ SDL_GL_CONTEXT_RESET_NOTIFICATION, SDL_GL_CONTEXT_NO_ERROR, SDL_GL_FLOATBUFFERS } SDL_GLattr; -typedef enum +typedef enum SDL_GLprofile { SDL_GL_CONTEXT_PROFILE_CORE = 0x0001, SDL_GL_CONTEXT_PROFILE_COMPATIBILITY = 0x0002, SDL_GL_CONTEXT_PROFILE_ES = 0x0004 /**< GLX_CONTEXT_ES2_PROFILE_BIT_EXT */ } SDL_GLprofile; -typedef enum +typedef enum SDL_GLcontextFlag { SDL_GL_CONTEXT_DEBUG_FLAG = 0x0001, SDL_GL_CONTEXT_FORWARD_COMPATIBLE_FLAG = 0x0002, @@ -268,13 +300,13 @@ typedef enum SDL_GL_CONTEXT_RESET_ISOLATION_FLAG = 0x0008 } SDL_GLcontextFlag; -typedef enum +typedef enum SDL_GLcontextReleaseFlag { SDL_GL_CONTEXT_RELEASE_BEHAVIOR_NONE = 0x0000, SDL_GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH = 0x0001 } SDL_GLcontextReleaseFlag; -typedef enum +typedef enum SDL_GLContextResetNotification { SDL_GL_CONTEXT_RESET_NO_NOTIFICATION = 0x0000, SDL_GL_CONTEXT_RESET_LOSE_CONTEXT = 0x0001 @@ -300,7 +332,7 @@ extern DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void); * The video drivers are presented in the order in which they are normally * checked during initialization. * - * \param index the index of a video driver + * \param index the index of a video driver. * \returns the name of the video driver with the given **index**. * * \since This function is available since SDL 2.0.0. @@ -327,7 +359,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetVideoDriver(int index); * specific `driver_name`. * * \param driver_name the name of a video driver to initialize, or NULL for - * the default driver + * the default driver. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -380,7 +412,7 @@ extern DECLSPEC int SDLCALL SDL_GetNumVideoDisplays(void); * Get the name of a display in UTF-8 encoding. * * \param displayIndex the index of display from which the name should be - * queried + * queried. * \returns the name of a display or NULL for an invalid display index or * failure; call SDL_GetError() for more information. * @@ -395,8 +427,8 @@ extern DECLSPEC const char * SDLCALL SDL_GetDisplayName(int displayIndex); * * The primary display (`displayIndex` zero) is always located at 0,0. * - * \param displayIndex the index of the display to query - * \param rect the SDL_Rect structure filled in with the display bounds + * \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. * @@ -425,8 +457,8 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayBounds(int displayIndex, SDL_Rect * re * 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 + * 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. * @@ -456,13 +488,13 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayUsableBounds(int displayIndex, SDL_Rec * more consistent, reliable, and clear. * * \param displayIndex the index of the display from which DPI information - * should be queried + * should be queried. * \param ddpi a pointer filled in with the diagonal DPI of the display; may - * be NULL + * be NULL. * \param hdpi a pointer filled in with the horizontal DPI of the display; may - * be NULL + * be NULL. * \param vdpi a pointer filled in with the vertical DPI of the display; may - * be NULL + * be NULL. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -475,7 +507,7 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayDPI(int displayIndex, float * ddpi, fl /** * Get the orientation of a display. * - * \param displayIndex the index of the display to query + * \param 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. * @@ -491,7 +523,7 @@ extern DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetDisplayOrientation(int dis * The `displayIndex` needs to be in the range from 0 to * SDL_GetNumVideoDisplays() - 1. * - * \param displayIndex the index of the display to query + * \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. * @@ -513,10 +545,10 @@ extern DECLSPEC int SDLCALL SDL_GetNumDisplayModes(int displayIndex); * - 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 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` + * `modeIndex`. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -535,9 +567,9 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayMode(int displayIndex, int modeIndex, * function will return the previous native display mode, and not the current * display mode. * - * \param displayIndex the index of the display to query + * \param displayIndex the index of the display to query. * \param mode an SDL_DisplayMode structure filled in with the current display - * mode + * mode. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -557,9 +589,9 @@ extern DECLSPEC int SDLCALL SDL_GetDesktopDisplayMode(int displayIndex, SDL_Disp * function will return the current display mode, and not the previous native * display mode. * - * \param displayIndex the index of the display to query + * \param displayIndex the index of the display to query. * \param mode an SDL_DisplayMode structure filled in with the current display - * mode + * mode. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -583,11 +615,11 @@ extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(int displayIndex, SDL_Disp * and finally checking the refresh rate. If all the available modes are too * small, then NULL is returned. * - * \param displayIndex the index of the display to query + * \param displayIndex the index of the display to query. * \param mode an SDL_DisplayMode structure containing the desired display - * mode + * mode. * \param closest an SDL_DisplayMode structure filled in with the closest - * match of the available display modes + * 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. * @@ -601,7 +633,7 @@ extern DECLSPEC SDL_DisplayMode * SDLCALL SDL_GetClosestDisplayMode(int displayI /** * Get the index of the display containing a point * - * \param point the point to query + * \param point the point to query. * \returns the index of the display containing the point or a negative error * code on failure; call SDL_GetError() for more information. * @@ -615,7 +647,7 @@ extern DECLSPEC int SDLCALL SDL_GetPointDisplayIndex(const SDL_Point * point); /** * Get the index of the display primarily containing a rect * - * \param rect the rect to query + * \param rect the rect to query. * \returns the index of the display entirely containing the rect or closest * to the center of the rect on success or a negative error code on * failure; call SDL_GetError() for more information. @@ -630,7 +662,7 @@ extern DECLSPEC int SDLCALL SDL_GetRectDisplayIndex(const SDL_Rect * rect); /** * Get the index of the display associated with a window. * - * \param window the window to query + * \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. @@ -649,10 +681,10 @@ extern DECLSPEC int SDLCALL SDL_GetWindowDisplayIndex(SDL_Window * window); * change the window size when the window is not fullscreen, use * SDL_SetWindowSize(). * - * \param window the window to affect + * \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 + * and refresh rate. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -667,9 +699,9 @@ extern DECLSPEC int SDLCALL SDL_SetWindowDisplayMode(SDL_Window * window, /** * Query the display mode to use when a window is visible at fullscreen. * - * \param window the window to query + * \param window the window to query. * \param mode an SDL_DisplayMode structure filled in with the fullscreen - * display mode + * display mode. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -686,8 +718,8 @@ extern DECLSPEC int SDLCALL SDL_GetWindowDisplayMode(SDL_Window * window, * * Data returned should be freed with SDL_free. * - * \param window the window to query - * \param size the size of the ICC profile + * \param window the window to query. + * \param size the size of the ICC profile. * \returns the raw ICC profile data on success or NULL on failure; call * SDL_GetError() for more information. * @@ -698,7 +730,7 @@ extern DECLSPEC void* SDLCALL SDL_GetWindowICCProfile(SDL_Window * window, size_ /** * Get the pixel format associated with the window. * - * \param window the window to query + * \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. @@ -762,15 +794,15 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window * window); * 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 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` + * `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_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 `SDL_Window` that was created or NULL on failure; call * SDL_GetError() for more information. * * \since This function is available since SDL 2.0.0. @@ -790,7 +822,7 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title, * before using SDL_CreateWindowFrom(). * * \param data a pointer to driver-dependent window creation data, typically - * your native window cast to a void* + * your native window cast to a void*. * \returns the window that was created or NULL on failure; call * SDL_GetError() for more information. * @@ -807,7 +839,7 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindowFrom(const void *data); * 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 + * \param window the window to query. * \returns the ID of the window on success or 0 on failure; call * SDL_GetError() for more information. * @@ -823,7 +855,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowID(SDL_Window * window); * 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 + * \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. * @@ -836,8 +868,8 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromID(Uint32 id); /** * Get the window flags. * - * \param window the window to query - * \returns a mask of the SDL_WindowFlags associated with `window` + * \param window the window to query. + * \returns a mask of the SDL_WindowFlags associated with `window`. * * \since This function is available since SDL 2.0.0. * @@ -856,8 +888,8 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowFlags(SDL_Window * window); * * 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 + * \param window the window to change. + * \param title the desired window title in UTF-8 format. * * \since This function is available since SDL 2.0.0. * @@ -869,7 +901,7 @@ extern DECLSPEC void SDLCALL SDL_SetWindowTitle(SDL_Window * window, /** * Get the title of a window. * - * \param window the window to query + * \param window the window to query. * \returns the title of the window in UTF-8 format or "" if there is no * title. * @@ -882,8 +914,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetWindowTitle(SDL_Window * window); /** * Set the icon for a window. * - * \param window the window to change - * \param icon an SDL_Surface structure containing the icon for the window + * \param window the window to change. + * \param icon an SDL_Surface structure containing the icon for the window. * * \since This function is available since SDL 2.0.0. */ @@ -895,9 +927,9 @@ extern DECLSPEC void SDLCALL SDL_SetWindowIcon(SDL_Window * window, * * `name` is case-sensitive. * - * \param window the window to associate with the pointer - * \param name the name of the pointer - * \param userdata the associated pointer + * \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`. * * \since This function is available since SDL 2.0.0. @@ -911,8 +943,8 @@ extern DECLSPEC void* SDLCALL SDL_SetWindowData(SDL_Window * 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`. * * \since This function is available since SDL 2.0.0. @@ -927,11 +959,11 @@ extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_Window * window, * * The window coordinate origin is the upper left of the display. * - * \param window the window to reposition + * \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` + * `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` + * `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED`. * * \since This function is available since SDL 2.0.0. * @@ -946,11 +978,11 @@ extern DECLSPEC void SDLCALL SDL_SetWindowPosition(SDL_Window * window, * If you do not need the value for one of the positions a NULL may be passed * in the `x` or `y` parameter. * - * \param window the window to query + * \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 + * coordinates, may be NULL. * \param y a pointer filled in with the y position of the window, in screen - * coordinates, may be NULL + * coordinates, may be NULL. * * \since This function is available since SDL 2.0.0. * @@ -970,11 +1002,11 @@ extern DECLSPEC void SDLCALL SDL_GetWindowPosition(SDL_Window * window, * Fullscreen windows automatically match the size of the display mode, and * you should use SDL_SetWindowDisplayMode() to change their size. * - * \param window the window to change + * \param window the window to change. * \param w the width of the window in pixels, in screen coordinates, must be - * > 0 + * > 0. * \param h the height of the window in pixels, in screen coordinates, must be - * > 0 + * > 0. * * \since This function is available since SDL 2.0.0. * @@ -996,11 +1028,11 @@ extern DECLSPEC void SDLCALL SDL_SetWindowSize(SDL_Window * window, int w, * SDL_Vulkan_GetDrawableSize(), or SDL_GetRendererOutputSize() to get the * real client area size in pixels. * - * \param window the window to query the width and height from + * \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 + * coordinates, may be NULL. * \param h a pointer filled in with the height of the window, in screen - * coordinates, may be NULL + * coordinates, may be NULL. * * \since This function is available since SDL 2.0.0. * @@ -1027,15 +1059,15 @@ extern DECLSPEC void SDLCALL SDL_GetWindowSize(SDL_Window * window, int *w, * This function also returns -1 if getting the information is not supported. * * \param window the window to query the size values of the border - * (decorations) from + * (decorations) from. * \param top pointer to variable for storing the size of the top border; NULL - * is permitted + * is permitted. * \param left pointer to variable for storing the size of the left border; - * NULL is permitted + * NULL is permitted. * \param bottom pointer to variable for storing the size of the bottom - * border; NULL is permitted + * border; NULL is permitted. * \param right pointer to variable for storing the size of the right border; - * NULL is permitted + * NULL is permitted. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1055,10 +1087,11 @@ extern DECLSPEC int SDLCALL SDL_GetWindowBordersSize(SDL_Window * window, * platform with high-DPI support (Apple calls this "Retina"), and not * disabled by the `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint. * - * \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 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 + * NULL. * * \since This function is available since SDL 2.26.0. * @@ -1071,9 +1104,9 @@ extern DECLSPEC void SDLCALL SDL_GetWindowSizeInPixels(SDL_Window * window, /** * Set the minimum size of a window's client area. * - * \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 + * \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. * * \since This function is available since SDL 2.0.0. * @@ -1086,11 +1119,11 @@ extern DECLSPEC void SDLCALL SDL_SetWindowMinimumSize(SDL_Window * window, /** * Get the minimum size of a window's client area. * - * \param window the window to query + * \param window the window to query. * \param w a pointer filled in with the minimum width of the window, may be - * NULL + * NULL. * \param h a pointer filled in with the minimum height of the window, may be - * NULL + * NULL. * * \since This function is available since SDL 2.0.0. * @@ -1103,9 +1136,9 @@ extern DECLSPEC void SDLCALL SDL_GetWindowMinimumSize(SDL_Window * window, /** * Set the maximum size of a window's client area. * - * \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 + * \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. * * \since This function is available since SDL 2.0.0. * @@ -1118,11 +1151,11 @@ extern DECLSPEC void SDLCALL SDL_SetWindowMaximumSize(SDL_Window * window, /** * Get the maximum size of a window's client area. * - * \param window the window to query + * \param window the window to query. * \param w a pointer filled in with the maximum width of the window, may be - * NULL + * NULL. * \param h a pointer filled in with the maximum height of the window, may be - * NULL + * NULL. * * \since This function is available since SDL 2.0.0. * @@ -1141,8 +1174,8 @@ extern DECLSPEC void SDLCALL SDL_GetWindowMaximumSize(SDL_Window * window, * * 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 + * \param window the window of which to change the border state. + * \param bordered SDL_FALSE to remove border, SDL_TRUE to add border. * * \since This function is available since SDL 2.0.0. * @@ -1160,8 +1193,8 @@ extern DECLSPEC void SDLCALL SDL_SetWindowBordered(SDL_Window * window, * * 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 + * \param window the window of which to change the resizable state. + * \param resizable SDL_TRUE to allow resizing, SDL_FALSE to disallow. * * \since This function is available since SDL 2.0.5. * @@ -1176,9 +1209,9 @@ extern DECLSPEC void SDLCALL SDL_SetWindowResizable(SDL_Window * window, * This will add or remove the window's `SDL_WINDOW_ALWAYS_ON_TOP` flag. This * will bring the window to the front and keep the window above the rest. * - * \param window The window of which to change the always on top state + * \param window The window of which to change the always on top state. * \param on_top SDL_TRUE to set the window always on top, SDL_FALSE to - * disable + * disable. * * \since This function is available since SDL 2.0.16. * @@ -1190,7 +1223,7 @@ extern DECLSPEC void SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window * window, /** * Show a window. * - * \param window the window to show + * \param window the window to show. * * \since This function is available since SDL 2.0.0. * @@ -1202,7 +1235,7 @@ extern DECLSPEC void SDLCALL SDL_ShowWindow(SDL_Window * window); /** * Hide a window. * - * \param window the window to hide + * \param window the window to hide. * * \since This function is available since SDL 2.0.0. * @@ -1213,7 +1246,7 @@ extern DECLSPEC void SDLCALL SDL_HideWindow(SDL_Window * window); /** * Raise a window above other windows and set the input focus. * - * \param window the window to raise + * \param window the window to raise. * * \since This function is available since SDL 2.0.0. */ @@ -1222,7 +1255,7 @@ extern DECLSPEC void SDLCALL SDL_RaiseWindow(SDL_Window * window); /** * Make a window as large as possible. * - * \param window the window to maximize + * \param window the window to maximize. * * \since This function is available since SDL 2.0.0. * @@ -1234,7 +1267,7 @@ extern DECLSPEC void SDLCALL SDL_MaximizeWindow(SDL_Window * window); /** * Minimize a window to an iconic representation. * - * \param window the window to minimize + * \param window the window to minimize. * * \since This function is available since SDL 2.0.0. * @@ -1246,7 +1279,7 @@ extern DECLSPEC void SDLCALL SDL_MinimizeWindow(SDL_Window * window); /** * Restore the size and position of a minimized or maximized window. * - * \param window the window to restore + * \param window the window to restore. * * \since This function is available since SDL 2.0.0. * @@ -1262,8 +1295,12 @@ extern DECLSPEC void SDLCALL SDL_RestoreWindow(SDL_Window * window); * videomode change; `SDL_WINDOW_FULLSCREEN_DESKTOP` for "fake" fullscreen * that takes the size of the desktop; and 0 for windowed mode. * - * \param window the window to change - * \param flags `SDL_WINDOW_FULLSCREEN`, `SDL_WINDOW_FULLSCREEN_DESKTOP` or 0 + * Note that for some renderers, this function may trigger an + * SDL_RENDER_TARGETS_RESET event. Your application should be prepared to + * handle this event by reuploading textures! + * + * \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. * @@ -1297,11 +1334,15 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasWindowSurface(SDL_Window *window); * 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 that on some platforms the pixels pointer of the surface may be + * modified after each call to SDL_UpdateWindowSurface(), so that the platform + * code can implement efficient double or triple buffering. + * * You may not combine this with 3D or the rendering API on this window. * * This function is affected by `SDL_HINT_FRAMEBUFFER_ACCELERATION`. * - * \param window the window to query + * \param window the window to query. * \returns the surface associated with the window, or NULL on failure; call * SDL_GetError() for more information. * @@ -1322,7 +1363,7 @@ extern DECLSPEC SDL_Surface * SDLCALL SDL_GetWindowSurface(SDL_Window * window); * * This function is equivalent to the SDL 1.2 API SDL_Flip(). * - * \param window the window to update + * \param window the window to update. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1343,13 +1384,13 @@ extern DECLSPEC int SDLCALL SDL_UpdateWindowSurface(SDL_Window * window); * * Note that this function will update _at least_ the rectangles specified, * but this is only intended as an optimization; in practice, this might - * update more of the screen (or all of the screen!), depending on what - * method SDL uses to send pixels to the system. + * update more of the screen (or all of the screen!), depending on what method + * SDL uses to send pixels to the system. * - * \param window the window to update + * \param window the window to update. * \param rects an array of SDL_Rect structures representing areas of the - * surface to copy, in pixels - * \param numrects the number of rectangles + * surface to copy, in pixels. + * \param numrects the number of rectangles. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1365,7 +1406,7 @@ extern DECLSPEC int SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window * window, /** * Destroy the surface associated with the window. * - * \param window the window to update + * \param window the window to update. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1386,8 +1427,8 @@ extern DECLSPEC int SDLCALL SDL_DestroyWindowSurface(SDL_Window *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 input grab mode should be set - * \param grabbed SDL_TRUE to grab input or SDL_FALSE to release 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. * * \since This function is available since SDL 2.0.0. * @@ -1448,7 +1489,7 @@ extern DECLSPEC void SDLCALL SDL_SetWindowMouseGrab(SDL_Window * window, /** * Get a window's input grab mode. * - * \param window the window to query + * \param window the window to query. * \returns SDL_TRUE if input is grabbed, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.0. @@ -1460,7 +1501,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowGrab(SDL_Window * window); /** * Get a window's keyboard grab mode. * - * \param window the window to query + * \param window the window to query. * \returns SDL_TRUE if keyboard is grabbed, and SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.16. @@ -1473,7 +1514,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window * window); /** * Get a window's mouse grab mode. * - * \param window the window to query + * \param window the window to query. * \returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.16. @@ -1517,7 +1558,7 @@ extern DECLSPEC int SDLCALL SDL_SetWindowMouseRect(SDL_Window * window, const SD /** * Get the mouse confinement rectangle of a window. * - * \param window The window to query + * \param window The window to query. * \returns A pointer to the mouse confinement rectangle of a window, or NULL * if there isn't one. * @@ -1542,9 +1583,9 @@ extern DECLSPEC const SDL_Rect * SDLCALL SDL_GetWindowMouseRect(SDL_Window * win * something similar. * * \param window the window used to select the display whose brightness will - * be changed + * be changed. * \param brightness the brightness (gamma multiplier) value to set where 0.0 - * is completely dark and 1.0 is normal brightness + * 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. * @@ -1564,7 +1605,7 @@ extern DECLSPEC int SDLCALL SDL_SetWindowBrightness(SDL_Window * window, float b * this display can be retrieved using SDL_GetWindowDisplayIndex().) * * \param window the window used to select the display whose brightness will - * be queried + * be queried. * \returns the brightness for the display where 0.0 is completely dark and * 1.0 is normal brightness. * @@ -1582,8 +1623,8 @@ extern DECLSPEC float SDLCALL SDL_GetWindowBrightness(SDL_Window * window); * * This function also returns -1 if setting the opacity isn't supported. * - * \param window the window which will be made transparent or opaque - * \param opacity the opacity value (0.0f - transparent, 1.0f - opaque) + * \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. * @@ -1603,8 +1644,8 @@ extern DECLSPEC int SDLCALL SDL_SetWindowOpacity(SDL_Window * window, float opac * * This function also returns -1 if an invalid window was provided. * - * \param window the window to get the current opacity value from - * \param out_opacity the float filled in (0.0f - transparent, 1.0f - opaque) + * \param window the window to get the current opacity value from. + * \param out_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. * @@ -1617,8 +1658,8 @@ extern DECLSPEC int SDLCALL SDL_GetWindowOpacity(SDL_Window * window, float * ou /** * Set the window as a modal for another window. * - * \param modal_window the window that should be set modal - * \param parent_window the parent window for the modal 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. * @@ -1633,7 +1674,7 @@ extern DECLSPEC int SDLCALL SDL_SetWindowModalFor(SDL_Window * modal_window, SDL * 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. * @@ -1659,13 +1700,13 @@ extern DECLSPEC int SDLCALL SDL_SetWindowInputFocus(SDL_Window * window); * ramp set will not follow the window if it is moved to another display. * * \param window the window used to select the display whose gamma ramp will - * be changed + * be changed. * \param red a 256 element array of 16-bit quantities representing the - * translation table for the red channel, or NULL + * 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 + * 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 + * 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. * @@ -1687,13 +1728,13 @@ extern DECLSPEC int SDLCALL SDL_SetWindowGammaRamp(SDL_Window * window, * this display can be retrieved using SDL_GetWindowDisplayIndex().) * * \param window the window used to select the display whose gamma ramp will - * be queried + * be queried. * \param red a 256 element array of 16-bit quantities filled in with the - * translation table for the red channel, or NULL + * 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 + * 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 + * 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. * @@ -1711,7 +1752,7 @@ extern DECLSPEC int SDLCALL SDL_GetWindowGammaRamp(SDL_Window * window, * * \sa SDL_HitTest */ -typedef enum +typedef enum SDL_HitTestResult { SDL_HITTEST_NORMAL, /**< Region is normal. No special properties. */ SDL_HITTEST_DRAGGABLE, /**< Region can drag entire window. */ @@ -1728,9 +1769,9 @@ typedef enum /** * Callback used for hit-testing. * - * \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() + * \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 @@ -1771,9 +1812,9 @@ typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win, * 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 function to call when doing a hit-test - * \param callback_data an app-defined void pointer passed to **callback** + * \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. * @@ -1786,8 +1827,8 @@ extern DECLSPEC int SDLCALL SDL_SetWindowHitTest(SDL_Window * window, /** * Request a window to demand attention from the user. * - * \param window the window to be flashed - * \param operation the flash operation + * \param window the window to be flashed. + * \param operation the flash operation. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1801,7 +1842,7 @@ extern DECLSPEC int SDLCALL SDL_FlashWindow(SDL_Window * window, SDL_FlashOperat * 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 + * \param window the window to destroy. * * \since This function is available since SDL 2.0.0. * @@ -1872,7 +1913,7 @@ extern DECLSPEC void SDLCALL SDL_DisableScreenSaver(void); * program from the dynamic library using SDL_GL_GetProcAddress(). * * \param path the platform dependent OpenGL library name, or NULL to open the - * default OpenGL library + * default OpenGL library. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1924,7 +1965,7 @@ extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path); * 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 + * \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. * @@ -1959,7 +2000,7 @@ extern DECLSPEC void SDLCALL SDL_GL_UnloadLibrary(void); * 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 + * \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. @@ -1985,8 +2026,9 @@ extern DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void); * 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 + * \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. * @@ -2000,8 +2042,9 @@ extern DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value); /** * Get the actual value for an attribute from the current context. * - * \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` + * \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. * @@ -2023,7 +2066,7 @@ extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value); * * SDL_GLContext is an alias for `void *`. It's opaque to the application. * - * \param window the window to associate with the context + * \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. * @@ -2040,8 +2083,8 @@ extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_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 + * \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. * @@ -2084,10 +2127,11 @@ extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_GetCurrentContext(void); * platform with high-DPI support (Apple calls this "Retina"), and not * disabled by the `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint. * - * \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 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 + * NULL. * * \since This function is available since SDL 2.0.1. * @@ -2116,7 +2160,7 @@ extern DECLSPEC void SDLCALL SDL_GL_GetDrawableSize(SDL_Window * window, int *w, * 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 + * 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. * @@ -2153,7 +2197,7 @@ extern DECLSPEC int SDLCALL SDL_GL_GetSwapInterval(void); * glBindFramebuffer(), this is the default and you won't have to do anything * extra. * - * \param window the window to change + * \param window the window to change. * * \since This function is available since SDL 2.0.0. */ @@ -2162,7 +2206,7 @@ extern DECLSPEC void SDLCALL SDL_GL_SwapWindow(SDL_Window * window); /** * Delete an OpenGL context. * - * \param context the OpenGL context to be deleted + * \param context the OpenGL context to be deleted. * * \since This function is available since SDL 2.0.0. * diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_vulkan.h b/vs2019_project/ft2-clone/sdl/include/SDL2/SDL_vulkan.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_vulkan.h + * # CategoryVulkan * - * Header file for functions to creating Vulkan surfaces on SDL windows. + * Header file for functions to creating Vulkan surfaces on SDL windows. */ #ifndef SDL_vulkan_h_ @@ -101,13 +101,13 @@ typedef VkSurfaceKHR SDL_vulkanSurface; /* for compatibility with Tizen */ * supported. Either do not link to the Vulkan loader or link to a dynamic * library version. * - * \param path The platform dependent Vulkan loader library name or NULL + * \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. * * \since This function is available since SDL 2.0.6. * - * \sa SDL_Vulkan_GetVkInstanceProcAddr + * \sa SDL_Vulkan_GetVkGetInstanceProcAddr * \sa SDL_Vulkan_UnloadLibrary */ extern DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path); @@ -150,11 +150,11 @@ extern DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void); * however, this parameter will likely be removed in future releases * * \param window A window for which the required Vulkan instance extensions - * should be retrieved (will be deprecated in a future release) + * 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 + * extensions to be returned. * \param pNames NULL or a pointer to an array to be filled with required - * Vulkan instance extensions + * Vulkan instance extensions. * \returns SDL_TRUE on success, SDL_FALSE on error. * * \since This function is available since SDL 2.0.6. @@ -172,10 +172,10 @@ extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_GetInstanceExtensions(SDL_Window *wi * `instance` must have been created with extensions returned by * SDL_Vulkan_GetInstanceExtensions() enabled. * - * \param window The window to which to attach the Vulkan surface - * \param instance The Vulkan instance handle + * \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 + * created surface. * \returns SDL_TRUE on success, SDL_FALSE on error. * * \since This function is available since SDL 2.0.6. @@ -195,9 +195,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window, * platform with high-DPI support (Apple calls this "Retina"), and not * disabled by the `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint. * - * \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 + * \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. * * \since This function is available since SDL 2.0.6. * diff --git a/vs2019_project/ft2-clone/sdl/include/SDL2/begin_code.h b/vs2019_project/ft2-clone/sdl/include/SDL2/begin_code.h @@ -19,12 +19,12 @@ 3. This notice may not be removed or altered from any source distribution. */ +/* WIKI CATEGORY: BeginCode */ + /** - * \file begin_code.h - * - * This file sets things up for C dynamic library function definitions, - * static inlined functions, and structures aligned at 4-byte alignment. - * If you don't like ugly C preprocessor code, don't look at this file. :) + * begin_code.h sets things up for C dynamic library function definitions, + * static inlined functions, and structures aligned at 4-byte alignment. + * If you don't like ugly C preprocessor code, don't look at this file. :) */ /* This shouldn't be nested -- included it around code only. */ @@ -172,7 +172,7 @@ (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 202000L) #define SDL_FALLTHROUGH [[fallthrough]] #else -#if defined(__has_attribute) +#if defined(__has_attribute) && !defined(__SUNPRO_C) && !defined(__SUNPRO_CC) #define SDL_HAS_FALLTHROUGH __has_attribute(__fallthrough__) #else #define SDL_HAS_FALLTHROUGH 0 diff --git a/vs2019_project/ft2-clone/sdl/lib/SDL2main.lib b/vs2019_project/ft2-clone/sdl/lib/SDL2main.lib Binary files differ. diff --git a/vs2019_project/ft2-clone/sdl/lib64/SDL2main.lib b/vs2019_project/ft2-clone/sdl/lib64/SDL2main.lib Binary files differ. diff --git a/vs2019_project/x64/Debug/SDL2.dll b/vs2019_project/x64/Debug/SDL2.dll Binary files differ.