diff --git a/android-project/app/src/main/java/org/libsdl/app/SDLActivity.java b/android-project/app/src/main/java/org/libsdl/app/SDLActivity.java index 8cb0679935832..27ecad87dfabb 100644 --- a/android-project/app/src/main/java/org/libsdl/app/SDLActivity.java +++ b/android-project/app/src/main/java/org/libsdl/app/SDLActivity.java @@ -60,8 +60,8 @@ public class SDLActivity extends Activity implements View.OnSystemUiVisibilityChangeListener { private static final String TAG = "SDL"; private static final int SDL_MAJOR_VERSION = 2; - private static final int SDL_MINOR_VERSION = 30; - private static final int SDL_MICRO_VERSION = 12; + private static final int SDL_MINOR_VERSION = 32; + private static final int SDL_MICRO_VERSION = 0; /* // Display InputType.SOURCE/CLASS of events and devices // @@ -790,6 +790,9 @@ public void handleMessage(Message msg) { window.clearFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN); SDLActivity.mFullscreenModeActive = false; } + if (Build.VERSION.SDK_INT >= 28 /* Android 9 (Pie) */) { + window.getAttributes().layoutInDisplayCutoutMode = WindowManager.LayoutParams.LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES; + } } } else { Log.e(TAG, "error handling message, getContext() returned no Activity"); diff --git a/build.zig b/build.zig index a684823c0ed97..fc2c323c839af 100644 --- a/build.zig +++ b/build.zig @@ -159,7 +159,7 @@ pub fn build(b: *std.Build) void { .style = .{ .cmake = b.path("include/SDL_revision.h.cmake") }, .include_path = "SDL_revision.h", }, .{ - .SDL_REVISION = "SDL-2.30.12", + .SDL_REVISION = "SDL-2.32.0", .SDL_VENDOR_INFO = "allyourcodebase.com", }); lib.addConfigHeader(revision_header); @@ -686,7 +686,6 @@ const unknown_src_files = [_][]const u8{ "src/test/SDL_test_memory.c", "src/test/SDL_test_random.c", - "src/thread/n3ds/SDL_syscond.c", "src/thread/n3ds/SDL_sysmutex.c", "src/thread/n3ds/SDL_syssem.c", "src/thread/n3ds/SDL_systhread.c", diff --git a/build.zig.zon b/build.zig.zon index 71aff48ccd424..f2412e10fd2fc 100644 --- a/build.zig.zon +++ b/build.zig.zon @@ -1,6 +1,6 @@ .{ .name = "SDL", - .version = "2.30.12", + .version = "2.32.0", .minimum_zig_version = "0.13.0", .dependencies = .{}, .paths = .{ diff --git a/include-pregen/SDL_config.h b/include-pregen/SDL_config.h index 87ea1c02573a5..eabd78b52a168 100644 --- a/include-pregen/SDL_config.h +++ b/include-pregen/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/include/SDL.h b/include/SDL.h index fd58ac35c436b..0fe0713391a97 100644 --- a/include/SDL.h +++ b/include/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/include/SDL_assert.h b/include/SDL_assert.h index a19c9f2202870..fea3f90f04084 100644 --- a/include/SDL_assert.h +++ b/include/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/include/SDL_atomic.h b/include/SDL_atomic.h index 3559ce9e4d304..226ec7c67f607 100644 --- a/include/SDL_atomic.h +++ b/include/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/include/SDL_audio.h b/include/SDL_audio.h index f65deb92f43f6..cb76e93e43a81 100644 --- a/include/SDL_audio.h +++ b/include/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/include/SDL_bits.h b/include/SDL_bits.h index 508351e490dd7..747f556511385 100644 --- a/include/SDL_bits.h +++ b/include/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/include/SDL_blendmode.h b/include/SDL_blendmode.h index 351b43dea6ffb..c0c68113315fd 100644 --- a/include/SDL_blendmode.h +++ b/include/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/include/SDL_clipboard.h b/include/SDL_clipboard.h index 2b3124513d8f5..2ae16a1d05eb5 100644 --- a/include/SDL_clipboard.h +++ b/include/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/include/SDL_cpuinfo.h b/include/SDL_cpuinfo.h index 155fc03cb9acd..c0230652b9493 100644 --- a/include/SDL_cpuinfo.h +++ b/include/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/include/SDL_egl.h b/include/SDL_egl.h index 3093ffa337449..296ed945d57cc 100644 --- a/include/SDL_egl.h +++ b/include/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(_WIN32) && !defined(__ANDROID__) && !defined(SDL_USE_BUILTIN_OPENGL_DEFINITIONS) #if defined(__vita__) || defined(__psp2__) diff --git a/include/SDL_endian.h b/include/SDL_endian.h index 942248c7acd12..5be66eafb9fa2 100644 --- a/include/SDL_endian.h +++ b/include/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 #define SDL_BYTEORDER __BYTE_ORDER +#elif defined(__sun) && defined(__SVR4) /* Solaris */ +#include +#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 #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/include/SDL_error.h b/include/SDL_error.h index 16dfd881af019..8d9cde0e77542 100644 --- a/include/SDL_error.h +++ b/include/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/include/SDL_events.h b/include/SDL_events.h index a39f1dfc9e033..b9596c0ef5eba 100644 --- a/include/SDL_events.h +++ b/include/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/include/SDL_filesystem.h b/include/SDL_filesystem.h index 8873995d18b0f..c72a6165fe5e1 100644 --- a/include/SDL_filesystem.h +++ b/include/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/include/SDL_gamecontroller.h b/include/SDL_gamecontroller.h index fa23a51b5c449..4d8bcce22bd9e 100644 --- a/include/SDL_gamecontroller.h +++ b/include/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/include/SDL_gesture.h b/include/SDL_gesture.h index 81ec3803094c8..acfa56f31f51c 100644 --- a/include/SDL_gesture.h +++ b/include/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/include/SDL_guid.h b/include/SDL_guid.h index 25e17324d5d24..fd9a50e322939 100644 --- a/include/SDL_guid.h +++ b/include/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/include/SDL_haptic.h b/include/SDL_haptic.h index 270940fb43594..f679c5734ecb5 100644 --- a/include/SDL_haptic.h +++ b/include/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/include/SDL_hidapi.h b/include/SDL_hidapi.h index c51cc91e7cd36..b14442a6c2b09 100644 --- a/include/SDL_hidapi.h +++ b/include/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/include/SDL_hints.h b/include/SDL_hints.h index febb2493dbeb5..4665107fd2b28 100644 --- a/include/SDL_hints.h +++ b/include/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,1363 @@ 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: - * "0" - Do not scan for Steam Controllers - * "1" - Scan for Steam Controllers (the default) + * The variable can be set to the following values: * - * The default value is "1". This hint must be set before initializing the joystick subsystem. + * - "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 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: - * "0" - No forcing (the default) - * "1" - Extra level of forcing + * This variable can be set to the following values: * - * 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. + * - "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. */ #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: * - * 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 + * - "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: * - * This variable can be set to the following values: - * "0" - Grab will affect only the mouse - * "1" - Grab will affect mouse and keyboard + * - "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. + * 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: - * "0" - Enable idle timer - * "1" - Disable idle timer + * This variable can be set to the following values: + * + * - "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: - * "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 variable can be set to the following values: * - * The default value is "0". This hint may be set at any time. + * - "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. */ #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. + * + * This will override SDL_HINT_JOYSTICK_ARCADESTICK_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_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. * - * 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_BLACKLIST_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_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. + * + * This will override SDL_HINT_JOYSTICK_FLIGHTSTICK_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_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: - * "0" - HIDAPI drivers are not used - * "1" - HIDAPI drivers are used (the default) + * This variable can be set to the following values: + * + * - "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: - * "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_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. + * + * 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 + * 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: - * "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 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: * - * 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_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: * - * This variable can be set to the following values: - * "0" - extended reports are not enabled (the default) - * "1" - extended reports + * - "0": extended reports are not enabled (the default) + * - "1": extended reports * - * Extended input reports allow rumble on Bluetooth PS4 controllers, but - * break DirectInput handling for applications that don't use SDL. + * Extended input reports allow rumble on Bluetooth PS4 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 will also - * control the state of extended reports on PS5 controllers when the - * SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE hint is not explicitly set. + * 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: - * "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_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: * - * Extended input reports allow rumble on Bluetooth PS5 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 PS5 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 defaults to - * the value of SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE. + * 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. */ #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: * - * 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_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: - * "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_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: * - * 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_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: - * "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. + * 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: - * "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_XBOX_360 + * - "0": HIDAPI driver is not used + * - "1": HIDAPI driver is used + * + * 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. * - * 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_THROTTLE_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_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. * - * 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_WHEEL_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_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 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: * - * 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 + * - "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: - * "0" - Relative mouse mode uses raw input - * "1" - Relative mouse mode uses mouse warping + * This variable can be set to the following values: + * + * - "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: * - * 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 + * - "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: * - * 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. + * - "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. + * 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: - * "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 + * 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 * - * 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 +1658,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: * - * 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. + * - "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. */ #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: - * "LandscapeLeft", "LandscapeRight", "Portrait" "PortraitUpsideDown" + * This variable is a space delimited list of the following values: + * + * - "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: * - * This variable can be set to the following values: - * "0" - Disable poll sentinels - * "1" - Enable poll sentinels + * - "0": Disable poll sentinels + * - "1": Enable poll sentinels * - * 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. + * 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. + * 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): * - * This variable is a space-separated list of the following values (empty = no flags): - * "OverridesSystemGestures", "StaysOnTop", "BypassWindowManager" + * - "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. + * A variable controlling whether the 2D render API is compatible or + * efficient. * - * This variable can be set to the following values: - * - * "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: * - * This variable can be set to the following values: - * "0" - Disable Debug Layer use - * "1" - Enable Debug Layer use + * - "0": Disable Debug Layer use + * - "1": Enable Debug Layer use * - * By default, SDL does not use Direct3D Debug Layer. + * 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: * - * This variable can be set to the following values: - * "0" - Disable vsync - * "1" - Enable vsync + * - "0": Disable vsync + * - "1": Enable vsync * - * By default SDL does not sync screen surface updates with vertical refresh. + * 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 +2041,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 +2050,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 +2061,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. * - * 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 + * Refer to the man pages for more information. + * + * 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 */ #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: * - * This variable can be set to the following values: - * "0" - Disable screensaver - * "1" - Enable screensaver + * - "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 +2206,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: * - * This variable can be set to the following values: - * "0" - libdecor use is disabled. - * "1" - libdecor use is enabled (default). + * - "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: + * + * - "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. + * 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: - * "0" - Video mode emulation is disabled. - * "1" - Video mode emulation is enabled. + * This variable can be set to the following values: * - * By default video mode emulation is enabled. + * - "0": Video mode emulation is disabled. + * - "1": 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: - * "0" - Disable XRandR - * "1" - Enable XRandR + * This variable can be set to the following values: * - * By default SDL will use XRandR. + * - "0": Disable XRandR + * - "1": Enable 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: * - * 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. + * - "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: * - * 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() + * - "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 + * 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. * - * 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. + * 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. */ #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. + * + * 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. + * 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. * - * 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 hint must be set before initializing the video subsystem. * - * 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) + * 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) */ #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 +2817,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 +2844,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 +3066,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 +3119,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 +3140,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 +3159,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 +3187,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 +3200,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 +3215,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 +3241,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/include/SDL_joystick.h b/include/SDL_joystick.h index 3907d6e949aa9..668db5e30f638 100644 --- a/include/SDL_joystick.h +++ b/include/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/include/SDL_keyboard.h b/include/SDL_keyboard.h index c6cdec99044d2..8c4efdd078658 100644 --- a/include/SDL_keyboard.h +++ b/include/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 + * window creation which will cause events 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/include/SDL_keycode.h b/include/SDL_keycode.h index 8ee0301189034..eb1678e3861c4 100644 --- a/include/SDL_keycode.h +++ b/include/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/include/SDL_loadso.h b/include/SDL_loadso.h index 20d22ede5d6f2..1763b5280123e 100644 --- a/include/SDL_loadso.h +++ b/include/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/include/SDL_locale.h b/include/SDL_locale.h index 27a71109ed5bc..8126efc79a5bd 100644 --- a/include/SDL_locale.h +++ b/include/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/include/SDL_log.h b/include/SDL_log.h index 46e3af88a62ea..75833ba3c37cd 100644 --- a/include/SDL_log.h +++ b/include/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/include/SDL_main.h b/include/SDL_main.h index 8f27c0266b883..a1ef3e746432f 100644 --- a/include/SDL_main.h +++ b/include/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/include/SDL_messagebox.h b/include/SDL_messagebox.h index 1a4bff3b71a2a..725d4124adc2f 100644 --- a/include/SDL_messagebox.h +++ b/include/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/include/SDL_metal.h b/include/SDL_metal.h index b02a294ad046f..d3f21d5ecff18 100644 --- a/include/SDL_metal.h +++ b/include/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/include/SDL_misc.h b/include/SDL_misc.h index ab11a9946d0f7..86a82bc5d6ab0 100644 --- a/include/SDL_misc.h +++ b/include/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/include/SDL_mouse.h b/include/SDL_mouse.h index 36e2d2da490b9..628b7a2f835dd 100644 --- a/include/SDL_mouse.h +++ b/include/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/include/SDL_mutex.h b/include/SDL_mutex.h index 2a6d7161b2ab6..0fe3eb5a5f8c5 100644 --- a/include/SDL_mutex.h +++ b/include/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/include/SDL_opengl.h b/include/SDL_opengl.h index ffcff602de6bb..c6250d131b7a0 100644 --- a/include/SDL_opengl.h +++ b/include/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/include/SDL_opengles.h b/include/SDL_opengles.h index b9ab4bb153660..adf6ef782f739 100644 --- a/include/SDL_opengles.h +++ b/include/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/include/SDL_opengles2.h b/include/SDL_opengles2.h index ca2d10852ebf1..b106aa6281285 100644 --- a/include/SDL_opengles2.h +++ b/include/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(_WIN32) && !defined(SDL_USE_BUILTIN_OPENGL_DEFINITIONS) diff --git a/include/SDL_pixels.h b/include/SDL_pixels.h index cea1c1b69f82a..6f29811d337be 100644 --- a/include/SDL_pixels.h +++ b/include/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/include/SDL_platform.h b/include/SDL_platform.h index a2bcb42cc3a56..64ece4fe70ace 100644 --- a/include/SDL_platform.h +++ b/include/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/include/SDL_power.h b/include/SDL_power.h index ce33d6643b5e9..755c5d42a391a 100644 --- a/include/SDL_power.h +++ b/include/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/include/SDL_quit.h b/include/SDL_quit.h index d396546dc75a0..03630e232b4ad 100644 --- a/include/SDL_quit.h +++ b/include/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/include/SDL_rect.h b/include/SDL_rect.h index 273b8c15dbbea..b7e609d941e1c 100644 --- a/include/SDL_rect.h +++ b/include/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/include/SDL_render.h b/include/SDL_render.h index d7722c4544140..2118ed99cc8bc 100644 --- a/include/SDL_render.h +++ b/include/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` 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/include/SDL_rwops.h b/include/SDL_rwops.h index 28065bdd12ba8..43c1b0ec7776e 100644 --- a/include/SDL_rwops.h +++ b/include/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/include/SDL_scancode.h b/include/SDL_scancode.h index 3f15c3a75e805..0652d7ef66d8b 100644 --- a/include/SDL_scancode.h +++ b/include/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/include/SDL_sensor.h b/include/SDL_sensor.h index 17b8c7aab62f5..d4b1c511d7df6 100644 --- a/include/SDL_sensor.h +++ b/include/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/include/SDL_shape.h b/include/SDL_shape.h index 4d3f7bf0aa812..d3560845f8587 100644 --- a/include/SDL_shape.h +++ b/include/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/include/SDL_stdinc.h b/include/SDL_stdinc.h index 430202afd9c53..71fcea5e4cf4e 100644 --- a/include/SDL_stdinc.h +++ b/include/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 @@ -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/include/SDL_surface.h b/include/SDL_surface.h index ddb5b731990b4..6169e66ebe024 100644 --- a/include/SDL_surface.h +++ b/include/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/include/SDL_system.h b/include/SDL_system.h index 01d5c6c1be556..2f7a236f17e7e 100644 --- a/include/SDL_system.h +++ b/include/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/include/SDL_syswm.h b/include/SDL_syswm.h index 7acf43da7626c..18f6873299d11 100644 --- a/include/SDL_syswm.h +++ b/include/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/include/SDL_test.h b/include/SDL_test.h index 630c904b020be..78a7e623e4c7a 100644 --- a/include/SDL_test.h +++ b/include/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/include/SDL_test_assert.h b/include/SDL_test_assert.h index 9408b4f59a003..ff3b6b6bcd857 100644 --- a/include/SDL_test_assert.h +++ b/include/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/include/SDL_test_common.h b/include/SDL_test_common.h index 8e7622d153173..64b5f83e80824 100644 --- a/include/SDL_test_common.h +++ b/include/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/include/SDL_test_compare.h b/include/SDL_test_compare.h index a116634200550..3fcb935970c5f 100644 --- a/include/SDL_test_compare.h +++ b/include/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/include/SDL_test_crc32.h b/include/SDL_test_crc32.h index 32a4740ed34b4..1dbeef27685f2 100644 --- a/include/SDL_test_crc32.h +++ b/include/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/include/SDL_test_font.h b/include/SDL_test_font.h index ec41b46828db9..0eade92394407 100644 --- a/include/SDL_test_font.h +++ b/include/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/include/SDL_test_fuzzer.h b/include/SDL_test_fuzzer.h index 351ab9916bf37..c6978ac810988 100644 --- a/include/SDL_test_fuzzer.h +++ b/include/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/include/SDL_test_harness.h b/include/SDL_test_harness.h index 02bbb706c3aaa..cfd62e8401bc0 100644 --- a/include/SDL_test_harness.h +++ b/include/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/include/SDL_test_images.h b/include/SDL_test_images.h index 4229d26780777..d593a31565b0a 100644 --- a/include/SDL_test_images.h +++ b/include/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/include/SDL_test_log.h b/include/SDL_test_log.h index 04e03e640493e..6f7f66145b05b 100644 --- a/include/SDL_test_log.h +++ b/include/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/include/SDL_test_md5.h b/include/SDL_test_md5.h index 5770603ff9e93..edd79451c70c4 100644 --- a/include/SDL_test_md5.h +++ b/include/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/include/SDL_test_memory.h b/include/SDL_test_memory.h index 128c1ab238be3..e789fa802a512 100644 --- a/include/SDL_test_memory.h +++ b/include/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/include/SDL_test_random.h b/include/SDL_test_random.h index e8468570b3014..05d6d3ee5e26a 100644 --- a/include/SDL_test_random.h +++ b/include/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/include/SDL_thread.h b/include/SDL_thread.h index d6ae47dadee76..ac405d85ed538 100644 --- a/include/SDL_thread.h +++ b/include/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/include/SDL_timer.h b/include/SDL_timer.h index e187a79848807..60969690b23a7 100644 --- a/include/SDL_timer.h +++ b/include/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/include/SDL_touch.h b/include/SDL_touch.h index a4633c802d019..80a0fef8ac6a3 100644 --- a/include/SDL_touch.h +++ b/include/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/include/SDL_types.h b/include/SDL_types.h index 12b5f7516da40..cb3b4a8df1a08 100644 --- a/include/SDL_types.h +++ b/include/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/include/SDL_version.h b/include/SDL_version.h index 734ae6f6aef0c..32d1133beea13 100644 --- a/include/SDL_version.h +++ b/include/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 0 /** * 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/include/SDL_video.h b/include/SDL_video.h index 4b69a993364e5..2db5552fa22fc 100644 --- a/include/SDL_video.h +++ b/include/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/include/SDL_vulkan.h b/include/SDL_vulkan.h index a506ef456c73c..e005ed373ba44 100644 --- a/include/SDL_vulkan.h +++ b/include/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/include/begin_code.h b/include/begin_code.h index 6ab655c882ddd..2044e5cb06eb4 100644 --- a/include/begin_code.h +++ b/include/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/mingw/pkg-support/INSTALL.txt b/mingw/pkg-support/INSTALL.txt new file mode 100644 index 0000000000000..607dafd0ee0a7 --- /dev/null +++ b/mingw/pkg-support/INSTALL.txt @@ -0,0 +1,18 @@ + +The 32-bit files are in i686-w64-mingw32 +The 64-bit files are in x86_64-w64-mingw32 + +To install SDL for native development: + make native + +To install SDL for cross-compiling development: + make cross + +Look at the example programs in ./test, and check out online documentation: + http://wiki.libsdl.org/ + +Join the SDL developer mailing list if you want to join the community: + http://www.libsdl.org/mailing-list.php + +That's it! +Sam Lantinga diff --git a/mingw/pkg-support/Makefile b/mingw/pkg-support/Makefile new file mode 100644 index 0000000000000..dd01419d17f41 --- /dev/null +++ b/mingw/pkg-support/Makefile @@ -0,0 +1,37 @@ +# +# Makefile for installing the mingw32 version of the SDL library + +CROSS_PATH := /usr/local +ARCHITECTURES := i686-w64-mingw32 x86_64-w64-mingw32 + +all install: + @echo "Type \"$(MAKE) native\" to install 32-bit to /usr" + @echo "Type \"$(MAKE) cross\" to install 32-bit and 64-bit to $(CROSS_PATH)" + +native: + $(MAKE) install-package arch=i686-w64-mingw32 prefix=/usr + +cross: + mkdir -p $(CROSS_PATH)/cmake + cp -rv cmake/* $(CROSS_PATH)/cmake + for arch in $(ARCHITECTURES); do \ + mkdir -p $(CROSS_PATH)/$$arch; \ + $(MAKE) install-package arch=$$arch prefix=$(CROSS_PATH)/$$arch; \ + done + +install-package: + @if test -d $(arch) && test -d $(prefix); then \ + (cd $(arch) && cp -rv bin include lib share $(prefix)/); \ + sed "s|^prefix=.*|prefix=$(prefix)|" <$(arch)/bin/sdl2-config >$(prefix)/bin/sdl2-config; \ + chmod 755 $(prefix)/bin/sdl2-config; \ + sed "s|^libdir=.*|libdir=\'$(prefix)/lib\'|" <$(arch)/lib/libSDL2.la >$(prefix)/lib/libSDL2.la; \ + sed -e "s|^set[(]bindir \".*|set(bindir \"$(prefix)/bin\")|" \ + -e "s|^set[(]includedir \".*|set(includedir \"$(prefix)/include\")|" \ + -e "s|^set[(]libdir \".*|set(libdir \"$(prefix)/lib\")|" <$(arch)/lib/cmake/SDL2/sdl2-config.cmake >$(prefix)/lib/cmake/SDL2/sdl2-config.cmake; \ + sed -e "s|^prefix=.*|prefix=$(prefix)|" \ + -e "s|^includedir=.*|includedir=$(prefix)/include|" \ + -e "s|^libdir=.*|libdir=$(prefix)/lib|" <$(arch)/lib/pkgconfig/sdl2.pc >$(prefix)/lib/pkgconfig/sdl2.pc; \ + else \ + echo "*** ERROR: $(arch) or $(prefix) does not exist!"; \ + exit 1; \ + fi diff --git a/src/atomic/SDL_atomic.c b/src/atomic/SDL_atomic.c index 755ae57c9ce30..ea65796e7fc5d 100644 --- a/src/atomic/SDL_atomic.c +++ b/src/atomic/SDL_atomic.c @@ -259,7 +259,7 @@ int SDL_AtomicGet(SDL_atomic_t *a) #elif defined(__MACOSX__) /* this is deprecated in 10.12 sdk; favor gcc atomics. */ return sizeof(a->value) == sizeof(uint32_t) ? OSAtomicOr32Barrier(0, (volatile uint32_t *)&a->value) : OSAtomicAdd64Barrier(0, (volatile int64_t *)&a->value); #elif defined(__SOLARIS__) - return atomic_or_uint((volatile uint_t *)&a->value, 0); + return atomic_or_uint_nv((volatile uint_t *)&a->value, 0); #else int value; do { diff --git a/src/audio/coreaudio/SDL_coreaudio.m b/src/audio/coreaudio/SDL_coreaudio.m index ff982b66b929c..edf6e2361743c 100644 --- a/src/audio/coreaudio/SDL_coreaudio.m +++ b/src/audio/coreaudio/SDL_coreaudio.m @@ -821,8 +821,8 @@ static int assign_device_to_audioqueue(_THIS) result = AudioObjectGetPropertyData(this->hidden->deviceID, &prop, 0, NULL, &devuidsize, &devuid); CHECK_RESULT("AudioObjectGetPropertyData (kAudioDevicePropertyDeviceUID)"); result = AudioQueueSetProperty(this->hidden->audioQueue, kAudioQueueProperty_CurrentDevice, &devuid, devuidsize); + CFRelease(devuid); /* Release devuid; we're done with it and AudioQueueSetProperty should have retained if it wants to keep it. */ CHECK_RESULT("AudioQueueSetProperty (kAudioQueueProperty_CurrentDevice)"); - return 1; } #endif diff --git a/src/audio/wasapi/SDL_wasapi_winrt.cpp b/src/audio/wasapi/SDL_wasapi_winrt.cpp index a44058b4d9a4b..6bf862800d8b6 100644 --- a/src/audio/wasapi/SDL_wasapi_winrt.cpp +++ b/src/audio/wasapi/SDL_wasapi_winrt.cpp @@ -145,7 +145,7 @@ SDL_WasapiDeviceEventHandler::~SDL_WasapiDeviceEventHandler() void SDL_WasapiDeviceEventHandler::OnDeviceAdded(DeviceWatcher ^ sender, DeviceInformation ^ info) { SDL_assert(sender == this->watcher); - char *utf8dev = WIN_StringToUTF8(info->Name->Data()); + char *utf8dev = WIN_StringToUTF8W(info->Name->Data()); if (utf8dev) { WAVEFORMATEXTENSIBLE fmt; Platform::Object ^ obj = info->Properties->Lookup(SDL_PKEY_AudioEngine_DeviceFormat); diff --git a/src/core/windows/SDL_windows.c b/src/core/windows/SDL_windows.c index 3caca6125d7b3..c4e760be33bd1 100644 --- a/src/core/windows/SDL_windows.c +++ b/src/core/windows/SDL_windows.c @@ -250,7 +250,7 @@ WASAPI doesn't need this. This is just for DirectSound/WinMM. char *WIN_LookupAudioDeviceName(const WCHAR *name, const GUID *guid) { #if defined(__WINRT__) || defined(__XBOXONE__) || defined(__XBOXSERIES__) - return WIN_StringToUTF8(name); /* No registry access on WinRT/UWP and Xbox, go with what we've got. */ + return WIN_StringToUTF8W(name); /* No registry access on WinRT/UWP and Xbox, go with what we've got. */ #else static const GUID nullguid = { 0 }; const unsigned char *ptr; diff --git a/src/cpuinfo/SDL_cpuinfo.c b/src/cpuinfo/SDL_cpuinfo.c index 5e65b6271cee6..1291d493aabea 100644 --- a/src/cpuinfo/SDL_cpuinfo.c +++ b/src/cpuinfo/SDL_cpuinfo.c @@ -85,6 +85,10 @@ #endif #endif +#if defined (__FreeBSD__) +#include +#endif + #if defined(__ANDROID__) && defined(__arm__) && !defined(HAVE_GETAUXVAL) #include #endif @@ -891,6 +895,7 @@ static const char *SDL_GetCPUName(void) int SDL_GetCPUCacheLineSize(void) { const char *cpuType = SDL_GetCPUType(); + int cacheline_size = SDL_CACHELINE_SIZE; /* initial guess */ int a, b, c, d; (void)a; (void)b; @@ -898,14 +903,34 @@ int SDL_GetCPUCacheLineSize(void) (void)d; if (SDL_strcmp(cpuType, "GenuineIntel") == 0 || SDL_strcmp(cpuType, "CentaurHauls") == 0 || SDL_strcmp(cpuType, " Shanghai ") == 0) { cpuid(0x00000001, a, b, c, d); - return ((b >> 8) & 0xff) * 8; + cacheline_size = ((b >> 8) & 0xff) * 8; } else if (SDL_strcmp(cpuType, "AuthenticAMD") == 0 || SDL_strcmp(cpuType, "HygonGenuine") == 0) { cpuid(0x80000005, a, b, c, d); - return c & 0xff; + cacheline_size = c & 0xff; } else { - /* Just make a guess here... */ - return SDL_CACHELINE_SIZE; +#if defined(HAVE_SYSCONF) && defined(_SC_LEVEL1_DCACHE_LINESIZE) + if ((cacheline_size = sysconf(_SC_LEVEL1_DCACHE_LINESIZE)) > 0) { + return cacheline_size; + } else { + cacheline_size = SDL_CACHELINE_SIZE; + } +#endif +#if defined(__LINUX__) + { + FILE *f = fopen("/sys/devices/system/cpu/cpu0/cache/index0/coherency_line_size", "r"); + if (f) { + int size; + if (fscanf(f, "%d", &size) == 1) { + cacheline_size = size; + } + fclose(f); + } + } +#elif defined(__FreeBSD__) && defined(CACHE_LINE_SIZE) + cacheline_size = CACHE_LINE_SIZE; +#endif } + return cacheline_size; } static Uint32 SDL_CPUFeatures = 0xFFFFFFFF; diff --git a/src/dynapi/SDL_dynapi.c b/src/dynapi/SDL_dynapi.c index 42dc8ed68672f..48f50954aeefc 100644 --- a/src/dynapi/SDL_dynapi.c +++ b/src/dynapi/SDL_dynapi.c @@ -440,7 +440,16 @@ extern SDL_NORETURN void SDL_ExitProcess(int exitcode); static void SDL_InitDynamicAPILocked(void) { - char *libname = SDL_getenv_REAL(SDL_DYNAMIC_API_ENVVAR); + /* this can't use SDL_getenv_REAL, because it might allocate memory before the app can set their allocator */ +#if defined(WIN32) || defined(_WIN32) || defined(__CYGWIN__) + /* We've always used LoadLibraryA for this, so this has never worked with Unicode paths on Windows. Sorry. */ + char envbuf[512]; /* overflows will just report as environment variable being unset, but LoadLibraryA has a MAX_PATH of 260 anyhow, apparently. */ + const DWORD rc = GetEnvironmentVariableA(SDL_DYNAMIC_API_ENVVAR, envbuf, (DWORD) sizeof (envbuf)); + char *libname = ((rc != 0) && (rc < sizeof (envbuf))) ? envbuf : NULL; +#else + char *libname = getenv(SDL_DYNAMIC_API_ENVVAR); +#endif + SDL_DYNAPI_ENTRYFN entry = NULL; /* funcs from here by default. */ SDL_bool use_internal = SDL_TRUE; diff --git a/src/dynapi/SDL_dynapi_procs.h b/src/dynapi/SDL_dynapi_procs.h index 695ee83d69cc3..db61f475f0bd3 100644 --- a/src/dynapi/SDL_dynapi_procs.h +++ b/src/dynapi/SDL_dynapi_procs.h @@ -73,7 +73,7 @@ SDL_DYNAPI_PROC(IDirect3DDevice9*,SDL_RenderGetD3D9Device,(SDL_Renderer *a),(a), #endif #ifdef __IPHONEOS__ -SDL_DYNAPI_PROC(int,SDL_iPhoneSetAnimationCallback,(SDL_Window *a, int b, void (SDLCALL *c)(void *), void *d),(a,b,c,d),return) +SDL_DYNAPI_PROC(int,SDL_iPhoneSetAnimationCallback,(SDL_Window *a, int b, SDL_iOSAnimationCallback c, void *d),(a,b,c,d),return) SDL_DYNAPI_PROC(void,SDL_iPhoneSetEventPump,(SDL_bool a),(a),) #endif @@ -411,7 +411,7 @@ SDL_DYNAPI_PROC(void*,SDL_realloc,(void *a, size_t b),(a,b),return) SDL_DYNAPI_PROC(void,SDL_free,(void *a),(a),) SDL_DYNAPI_PROC(char*,SDL_getenv,(const char *a),(a),return) SDL_DYNAPI_PROC(int,SDL_setenv,(const char *a, const char *b, int c),(a,b,c),return) -SDL_DYNAPI_PROC(void,SDL_qsort,(void *a, size_t b, size_t c, int (SDLCALL *d)(const void *, const void *)),(a,b,c,d),) +SDL_DYNAPI_PROC(void,SDL_qsort,(void *a, size_t b, size_t c, SDL_CompareCallback d),(a,b,c,d),) SDL_DYNAPI_PROC(int,SDL_abs,(int a),(a),return) SDL_DYNAPI_PROC(int,SDL_isdigit,(int a),(a),return) SDL_DYNAPI_PROC(int,SDL_isspace,(int a),(a),return) @@ -511,7 +511,7 @@ SDL_DYNAPI_PROC(void,SDL_WaitThread,(SDL_Thread *a, int *b),(a,b),) SDL_DYNAPI_PROC(void,SDL_DetachThread,(SDL_Thread *a),(a),) SDL_DYNAPI_PROC(SDL_TLSID,SDL_TLSCreate,(void),(),return) SDL_DYNAPI_PROC(void*,SDL_TLSGet,(SDL_TLSID a),(a),return) -SDL_DYNAPI_PROC(int,SDL_TLSSet,(SDL_TLSID a, const void *b, void (SDLCALL *c)(void*)),(a,b,c),return) +SDL_DYNAPI_PROC(int,SDL_TLSSet,(SDL_TLSID a, const void *b, SDL_TLSDestructorCallback c),(a,b,c),return) SDL_DYNAPI_PROC(Uint32,SDL_GetTicks,(void),(),return) SDL_DYNAPI_PROC(Uint64,SDL_GetPerformanceCounter,(void),(),return) SDL_DYNAPI_PROC(Uint64,SDL_GetPerformanceFrequency,(void),(),return) @@ -939,7 +939,7 @@ SDL_DYNAPI_PROC(void,SDL_UnionFRect,(const SDL_FRect *a, const SDL_FRect *b, SDL SDL_DYNAPI_PROC(SDL_bool,SDL_EncloseFPoints,(const SDL_FPoint *a, int b, const SDL_FRect *c, SDL_FRect *d),(a,b,c,d),return) SDL_DYNAPI_PROC(SDL_bool,SDL_IntersectFRectAndLine,(const SDL_FRect *a, float *b, float *c, float *d, float *e),(a,b,c,d,e),return) SDL_DYNAPI_PROC(SDL_Window*,SDL_RenderGetWindow,(SDL_Renderer *a),(a),return) -SDL_DYNAPI_PROC(void*,SDL_bsearch,(const void *a, const void *b, size_t c, size_t d, int (SDLCALL *e)(const void *, const void *)),(a,b,c,d,e),return) +SDL_DYNAPI_PROC(void*,SDL_bsearch,(const void *a, const void *b, size_t c, size_t d, SDL_CompareCallback e),(a,b,c,d,e),return) SDL_DYNAPI_PROC(const char*,SDL_GameControllerPathForIndex,(int a),(a),return) SDL_DYNAPI_PROC(const char*,SDL_GameControllerPath,(SDL_GameController *a),(a),return) SDL_DYNAPI_PROC(const char*,SDL_JoystickPathForIndex,(int a),(a),return) diff --git a/src/events/SDL_events.c b/src/events/SDL_events.c index 16916be94a1c1..1d4d785f5d71a 100644 --- a/src/events/SDL_events.c +++ b/src/events/SDL_events.c @@ -37,8 +37,11 @@ /* An arbitrary limit so we don't have unbounded growth */ #define SDL_MAX_QUEUED_EVENTS 65535 -/* Determines how often we wake to call SDL_PumpEvents() in SDL_WaitEventTimeout_Device() */ -#define PERIODIC_POLL_INTERVAL_MS 3000 +/* Determines how often we pump events if joystick or sensor subsystems are active */ +#define ENUMERATION_POLL_INTERVAL_MS 3000 + +/* Determines how often to pump events if joysticks or sensors are actively being read */ +#define EVENT_POLL_INTERVAL_MS 1 typedef struct SDL_EventWatcher { @@ -960,27 +963,41 @@ int SDL_PollEvent(SDL_Event *event) return SDL_WaitEventTimeout(event, 0); } -static SDL_bool SDL_events_need_periodic_poll(void) +static Sint16 SDL_events_get_polling_interval(void) { - SDL_bool need_periodic_poll = SDL_FALSE; + Sint16 poll_interval = SDL_MAX_SINT16; #ifndef SDL_JOYSTICK_DISABLED - need_periodic_poll = - SDL_WasInit(SDL_INIT_JOYSTICK) && SDL_update_joysticks; + if (SDL_WasInit(SDL_INIT_JOYSTICK) && SDL_update_joysticks) { + if (SDL_NumJoysticks() > 0) { + /* If we have joysticks open, we need to poll rapidly for events */ + poll_interval = SDL_min(poll_interval, EVENT_POLL_INTERVAL_MS); + } else { + /* If not, just poll every few seconds to enumerate new joysticks */ + poll_interval = SDL_min(poll_interval, ENUMERATION_POLL_INTERVAL_MS); + } + } #endif #ifndef SDL_SENSOR_DISABLED - need_periodic_poll = need_periodic_poll || - (SDL_WasInit(SDL_INIT_SENSOR) && SDL_update_sensors); + if (SDL_WasInit(SDL_INIT_SENSOR) && SDL_update_sensors) { + if (SDL_NumSensors() > 0) { + /* If we have sensors open, we need to poll rapidly for events */ + poll_interval = SDL_min(poll_interval, EVENT_POLL_INTERVAL_MS); + } else { + /* If not, just poll every few seconds to enumerate new sensors */ + poll_interval = SDL_min(poll_interval, ENUMERATION_POLL_INTERVAL_MS); + } + } #endif - return need_periodic_poll; + return poll_interval; } static int SDL_WaitEventTimeout_Device(_THIS, SDL_Window *wakeup_window, SDL_Event *event, Uint32 start, int timeout) { int loop_timeout = timeout; - SDL_bool need_periodic_poll = SDL_events_need_periodic_poll(); + Sint16 poll_interval = SDL_events_get_polling_interval(); for (;;) { /* Pump events on entry and each time we wake to ensure: @@ -1022,17 +1039,20 @@ static int SDL_WaitEventTimeout_Device(_THIS, SDL_Window *wakeup_window, SDL_Eve } loop_timeout = (int)((Uint32)timeout - elapsed); } - if (need_periodic_poll) { + + /* Adjust the timeout for any polling requirements we currently have. */ + if (poll_interval != SDL_MAX_SINT16) { if (loop_timeout >= 0) { - loop_timeout = SDL_min(loop_timeout, PERIODIC_POLL_INTERVAL_MS); + loop_timeout = SDL_min(loop_timeout, poll_interval); } else { - loop_timeout = PERIODIC_POLL_INTERVAL_MS; + loop_timeout = poll_interval; } } + status = _this->WaitEventTimeout(_this, loop_timeout); /* Set wakeup_window to NULL without holding the lock. */ _this->wakeup_window = NULL; - if (status == 0 && need_periodic_poll && loop_timeout == PERIODIC_POLL_INTERVAL_MS) { + if (status == 0 && poll_interval != SDL_MAX_SINT16 && loop_timeout == poll_interval) { /* We may have woken up to poll. Try again */ continue; } else if (status <= 0) { @@ -1045,25 +1065,6 @@ static int SDL_WaitEventTimeout_Device(_THIS, SDL_Window *wakeup_window, SDL_Eve return 0; } -static SDL_bool SDL_events_need_polling(void) -{ - SDL_bool need_polling = SDL_FALSE; - -#ifndef SDL_JOYSTICK_DISABLED - need_polling = - SDL_WasInit(SDL_INIT_JOYSTICK) && - SDL_update_joysticks && - (SDL_NumJoysticks() > 0); -#endif - -#ifndef SDL_SENSOR_DISABLED - need_polling = need_polling || - (SDL_WasInit(SDL_INIT_SENSOR) && SDL_update_sensors && (SDL_NumSensors() > 0)); -#endif - - return need_polling; -} - static SDL_Window *SDL_find_active_window(SDL_VideoDevice *_this) { SDL_Window *window; @@ -1136,7 +1137,7 @@ int SDL_WaitEventTimeout(SDL_Event *event, int timeout) expiration = 0; } - if (_this && _this->WaitEventTimeout && _this->SendWakeupEvent && !SDL_events_need_polling()) { + if (_this && _this->WaitEventTimeout && _this->SendWakeupEvent) { /* Look if a shown window is available to send the wakeup event. */ wakeup_window = SDL_find_active_window(_this); if (wakeup_window) { @@ -1160,7 +1161,7 @@ int SDL_WaitEventTimeout(SDL_Event *event, int timeout) /* Timeout expired and no events */ return 0; } - SDL_Delay(1); + SDL_Delay(EVENT_POLL_INTERVAL_MS); break; default: /* Has events */ diff --git a/src/file/SDL_rwops.c b/src/file/SDL_rwops.c index 76e8cee0904cb..ae20002a7a2b6 100644 --- a/src/file/SDL_rwops.c +++ b/src/file/SDL_rwops.c @@ -369,6 +369,7 @@ stdio_size(SDL_RWops * context) static Sint64 SDLCALL stdio_seek(SDL_RWops *context, Sint64 offset, int whence) { int stdiowhence; + SDL_bool is_noop; switch (whence) { case RW_SEEK_SET: @@ -390,7 +391,10 @@ static Sint64 SDLCALL stdio_seek(SDL_RWops *context, Sint64 offset, int whence) } #endif - if (fseek(context->hidden.stdio.fp, (fseek_off_t)offset, stdiowhence) == 0) { + /* don't make a possibly-costly API call for the noop seek from SDL_RWtell */ + is_noop = (whence == RW_SEEK_CUR) && (offset == 0); + + if (is_noop || fseek(context->hidden.stdio.fp, (fseek_off_t)offset, stdiowhence) == 0) { Sint64 pos = ftell(context->hidden.stdio.fp); if (pos < 0) { return SDL_SetError("Couldn't get stream offset"); diff --git a/src/file/cocoa/SDL_rwopsbundlesupport.m b/src/file/cocoa/SDL_rwopsbundlesupport.m index 5920e60dc1bfe..dbfc5a5b8458a 100644 --- a/src/file/cocoa/SDL_rwopsbundlesupport.m +++ b/src/file/cocoa/SDL_rwopsbundlesupport.m @@ -24,6 +24,7 @@ #import #include "SDL_rwopsbundlesupport.h" +#include "SDL_hints.h" /* For proper OS X applications, the resources are contained inside the application bundle. So the strategy is to first check the application bundle for the file, then fallback to the current working directory. @@ -41,6 +42,11 @@ NSString *ns_string_file_component; NSString *full_path_with_file_to_try; + /* if the app doesn't want this app bundle behavior, just use the path as-is. */ + if (!SDL_GetHintBoolean(SDL_HINT_APPLE_RWFROMFILE_USE_RESOURCES, SDL_TRUE)) { + return fopen(file, mode); + } + /* If the file mode is writable, skip all the bundle stuff because generally the bundle is read-only. */ if (SDL_strchr(mode, 'r') == NULL) { return fopen(file, mode); diff --git a/src/filesystem/ps2/SDL_sysfilesystem.c b/src/filesystem/ps2/SDL_sysfilesystem.c index d00edf901ccd8..a71cd553e69d9 100644 --- a/src/filesystem/ps2/SDL_sysfilesystem.c +++ b/src/filesystem/ps2/SDL_sysfilesystem.c @@ -33,16 +33,14 @@ char *SDL_GetBasePath(void) { - char *retval; + char *retval = NULL; size_t len; char cwd[FILENAME_MAX]; getcwd(cwd, sizeof(cwd)); - len = SDL_strlen(cwd) + 1; + len = SDL_strlen(cwd) + 2; retval = (char *)SDL_malloc(len); - if (retval) { - SDL_memcpy(retval, cwd, len); - } + SDL_snprintf(retval, len, "%s/", cwd); return retval; } diff --git a/src/filesystem/winrt/SDL_sysfilesystem.cpp b/src/filesystem/winrt/SDL_sysfilesystem.cpp index bdd7688cabf31..43c3d835419a5 100644 --- a/src/filesystem/winrt/SDL_sysfilesystem.cpp +++ b/src/filesystem/winrt/SDL_sysfilesystem.cpp @@ -115,7 +115,7 @@ SDL_WinRTGetFSPathUTF8(SDL_WinRT_Path pathType) return NULL; } - char *utf8Path = WIN_StringToUTF8(ucs2Path); + char *utf8Path = WIN_StringToUTF8W(ucs2Path); utf8Paths[pathType] = utf8Path; SDL_free(utf8Path); return utf8Paths[pathType].c_str(); @@ -181,13 +181,13 @@ SDL_GetPrefPath(const char *org, const char *app) } SDL_wcslcpy(path, srcPath, SDL_arraysize(path)); - worg = WIN_UTF8ToString(org); + worg = WIN_UTF8ToStringW(org); if (!worg) { SDL_OutOfMemory(); return NULL; } - wapp = WIN_UTF8ToString(app); + wapp = WIN_UTF8ToStringW(app); if (!wapp) { SDL_free(worg); SDL_OutOfMemory(); @@ -232,7 +232,7 @@ SDL_GetPrefPath(const char *org, const char *app) SDL_wcslcat(path, L"\\", new_wpath_len + 1); - retval = WIN_StringToUTF8(path); + retval = WIN_StringToUTF8W(path); return retval; } diff --git a/src/haptic/linux/SDL_syshaptic.c b/src/haptic/linux/SDL_syshaptic.c index eb8eb70798abe..3622e433ad7c6 100644 --- a/src/haptic/linux/SDL_syshaptic.c +++ b/src/haptic/linux/SDL_syshaptic.c @@ -812,7 +812,9 @@ static int SDL_SYS_ToFFEffect(struct ff_effect *dest, SDL_HapticEffect *src) dest->type = FF_FRICTION; } - dest->direction = 0; /* Handled by the condition-specifics. */ + if (SDL_SYS_ToDirection(&dest->direction, &condition->direction) == -1) { + return -1; + } /* Replay */ dest->replay.length = (condition->length == SDL_HAPTIC_INFINITY) ? 0 : CLAMP(condition->length); diff --git a/src/joystick/SDL_gamecontrollerdb.h b/src/joystick/SDL_gamecontrollerdb.h index cc93c808e6eda..1366fb25d7eab 100644 --- a/src/joystick/SDL_gamecontrollerdb.h +++ b/src/joystick/SDL_gamecontrollerdb.h @@ -136,7 +136,6 @@ static const char *s_ControllerMappings[] = { "03000000b80500000610000000000000,Elecom Gamepad,a:b2,b:b3,back:b8,dpdown:h0.4,dpleft:h0.8,dpright:h0.2,dpup:h0.1,leftshoulder:b4,leftstick:b10,lefttrigger:b6,leftx:a0,lefty:a1,rightshoulder:b5,rightstick:b11,righttrigger:b7,rightx:a2,righty:a3,start:b9,x:b0,y:b1,", "03000000852100000201000000000000,FF-GP1,a:b1,b:b2,back:b8,dpdown:h0.4,dpleft:h0.8,dpright:h0.2,dpup:h0.1,leftshoulder:b4,leftstick:b10,lefttrigger:b6,leftx:a0,lefty:a1,rightshoulder:b5,rightstick:b11,righttrigger:b7,rightx:a2,righty:a3,start:b9,x:b0,y:b3,", "030000000d0f00002700000000000000,FIGHTING STICK V3,a:b1,b:b2,back:b8,dpdown:h0.4,dpleft:h0.8,dpright:h0.2,dpup:h0.1,guide:b12,leftshoulder:b4,lefttrigger:b6,rightshoulder:b5,righttrigger:b7,start:b9,x:b0,y:b3,", - "03000000790000000600000000000000,G-Shark GS-GP702,crc:8e4f,a:b2,b:b1,back:b8,dpdown:h0.4,dpleft:h0.8,dpright:h0.2,dpup:h0.1,leftshoulder:b4,leftstick:b10,lefttrigger:b6,leftx:a0,lefty:a1,rightshoulder:b5,rightstick:b11,righttrigger:b7,rightx:a2,righty:a3,start:b9,x:b3,y:b0,", "030000008f0e00000d31000000000000,GAMEPAD 3 TURBO,a:b1,b:b2,back:b8,dpdown:h0.4,dpleft:h0.8,dpright:h0.2,dpup:h0.1,guide:b12,leftshoulder:b4,leftstick:b10,lefttrigger:b6,leftx:a0,lefty:a1,rightshoulder:b5,rightstick:b11,righttrigger:b7,rightx:a2,righty:a3,start:b9,x:b0,y:b3,", "03000000300f00000b01000000000000,GGE909 Recoil Pad,a:b2,b:b1,back:b8,dpdown:h0.4,dpleft:h0.8,dpright:h0.2,dpup:h0.1,leftshoulder:b4,leftstick:b10,lefttrigger:b6,leftx:a0,lefty:a1,rightshoulder:b5,rightstick:b11,righttrigger:b7,rightx:a3,righty:a2,start:b9,x:b3,y:b0,", "03000000790000002201000000000000,Game Controller for PC,a:b2,b:b1,back:b8,dpdown:h0.4,dpleft:h0.8,dpright:h0.2,dpup:h0.1,leftshoulder:b4,leftstick:b10,lefttrigger:b6,leftx:a0,lefty:a1,rightshoulder:b5,rightstick:b11,righttrigger:b7,rightx:a2,righty:a3,start:b9,x:b3,y:b0,", diff --git a/src/joystick/bsd/SDL_bsdjoystick.c b/src/joystick/bsd/SDL_bsdjoystick.c index 8a87d76e08ac1..8c0260d27e6e3 100644 --- a/src/joystick/bsd/SDL_bsdjoystick.c +++ b/src/joystick/bsd/SDL_bsdjoystick.c @@ -93,40 +93,11 @@ #define HUG_DPAD_RIGHT 0x92 #define HUG_DPAD_LEFT 0x93 -#define HAT_CENTERED 0x00 #define HAT_UP 0x01 #define HAT_RIGHT 0x02 #define HAT_DOWN 0x04 #define HAT_LEFT 0x08 -#define HAT_RIGHTUP (HAT_RIGHT | HAT_UP) -#define HAT_RIGHTDOWN (HAT_RIGHT | HAT_DOWN) -#define HAT_LEFTUP (HAT_LEFT | HAT_UP) -#define HAT_LEFTDOWN (HAT_LEFT | HAT_DOWN) - -/* calculate the value from the state of the dpad */ -int dpad_to_sdl(Sint32 *dpad) -{ - if (dpad[2]) { - if (dpad[0]) - return HAT_RIGHTUP; - else if (dpad[1]) - return HAT_RIGHTDOWN; - else - return HAT_RIGHT; - } else if (dpad[3]) { - if (dpad[0]) - return HAT_LEFTUP; - else if (dpad[1]) - return HAT_LEFTDOWN; - else - return HAT_LEFT; - } else if (dpad[0]) { - return HAT_UP; - } else if (dpad[1]) { - return HAT_DOWN; - } - return HAT_CENTERED; -} + #endif struct report @@ -724,19 +695,29 @@ static void BSD_JoystickUpdate(SDL_Joystick *joy) hitem.logical_minimum); } #ifdef __OpenBSD__ - else if (usage == HUG_DPAD_UP) { + /* here D-pad directions are reported like separate buttons. + * calculate the SDL hat value from the 4 separate values. + */ + switch (usage) { + case HUG_DPAD_UP: dpad[0] = (Sint32)hid_get_data(REP_BUF_DATA(rep), &hitem); - SDL_PrivateJoystickHat(joy, 0, dpad_to_sdl(dpad)); - } else if (usage == HUG_DPAD_DOWN) { + break; + case HUG_DPAD_DOWN: dpad[1] = (Sint32)hid_get_data(REP_BUF_DATA(rep), &hitem); - SDL_PrivateJoystickHat(joy, 0, dpad_to_sdl(dpad)); - } else if (usage == HUG_DPAD_RIGHT) { + break; + case HUG_DPAD_RIGHT: dpad[2] = (Sint32)hid_get_data(REP_BUF_DATA(rep), &hitem); - SDL_PrivateJoystickHat(joy, 0, dpad_to_sdl(dpad)); - } else if (usage == HUG_DPAD_LEFT) { + break; + case HUG_DPAD_LEFT: dpad[3] = (Sint32)hid_get_data(REP_BUF_DATA(rep), &hitem); - SDL_PrivateJoystickHat(joy, 0, dpad_to_sdl(dpad)); + break; + //default: + // no-op } + SDL_PrivateJoystickHat(joy, 0, (dpad[0] * HAT_UP) | + (dpad[1] * HAT_DOWN) | + (dpad[2] * HAT_RIGHT) | + (dpad[3] * HAT_LEFT) ); #endif break; } diff --git a/src/joystick/hidapi/SDL_hidapijoystick.c b/src/joystick/hidapi/SDL_hidapijoystick.c index a1cb9c4a57cc3..b839ef79c7386 100644 --- a/src/joystick/hidapi/SDL_hidapijoystick.c +++ b/src/joystick/hidapi/SDL_hidapijoystick.c @@ -197,7 +197,13 @@ SDL_bool HIDAPI_SupportsPlaystationDetection(Uint16 vendor, Uint16 product) case USB_VENDOR_SHANWAN_ALT: return SDL_TRUE; case USB_VENDOR_THRUSTMASTER: - return SDL_TRUE; + /* Most of these are wheels, don't have the full set of effects, and + * at least in the case of the T248 and T300 RS, the hid-tmff2 driver + * puts them in a non-standard report mode and they can't be read. + * + * If these should use the HIDAPI driver, add them to controller_list.h + */ + return SDL_FALSE; case USB_VENDOR_ZEROPLUS: return SDL_TRUE; case 0x7545 /* SZ-MYPOWER */: diff --git a/src/loadso/windows/SDL_sysloadso.c b/src/loadso/windows/SDL_sysloadso.c index dd1568e3366ed..8ee6ee8f96d61 100644 --- a/src/loadso/windows/SDL_sysloadso.c +++ b/src/loadso/windows/SDL_sysloadso.c @@ -32,23 +32,23 @@ void *SDL_LoadObject(const char *sofile) { void *handle; - LPTSTR tstr; + LPWSTR wstr; if (!sofile) { SDL_InvalidParamError("sofile"); return NULL; } - tstr = WIN_UTF8ToString(sofile); + wstr = WIN_UTF8ToStringW(sofile); #ifdef __WINRT__ /* WinRT only publicly supports LoadPackagedLibrary() for loading .dll files. LoadLibrary() is a private API, and not available for apps (that can be published to MS' Windows Store.) */ - handle = (void *)LoadPackagedLibrary(tstr, 0); + handle = (void *)LoadPackagedLibrary(wstr, 0); #else - handle = (void *)LoadLibrary(tstr); + handle = (void *)LoadLibraryW(wstr); #endif - SDL_free(tstr); + SDL_free(wstr); /* Generate an error message if all loads failed */ if (!handle) { diff --git a/src/main/haiku/SDL_BeApp.cc b/src/main/haiku/SDL_BeApp.cc index 1449cc47dfad7..d2a1e354d7008 100644 --- a/src/main/haiku/SDL_BeApp.cc +++ b/src/main/haiku/SDL_BeApp.cc @@ -118,9 +118,13 @@ static int StartBeLooper() } while ((!be_app) || be_app->IsLaunching()); } - /* Change working directory to that of executable */ + /* If started from the GUI, change working directory to that of executable. + * This matches behavior on other platforms and may be needed by some SDL software. + * Don't do it when started from terminal (TERM environment variable is set), because in that + * case, the current directory may be important, and after this there will be no way to know + * what it was. */ app_info info; - if (B_OK == be_app->GetAppInfo(&info)) { + if (NULL == getenv("TERM") && B_OK == be_app->GetAppInfo(&info)) { entry_ref ref = info.ref; BEntry entry; if (B_OK == entry.SetTo(&ref)) { diff --git a/src/main/psp/SDL_psp_main.c b/src/main/psp/SDL_psp_main.c index 3d083cc75a9fd..c3555b3cf083b 100644 --- a/src/main/psp/SDL_psp_main.c +++ b/src/main/psp/SDL_psp_main.c @@ -8,6 +8,7 @@ #include "SDL_main.h" #include #include +#include "../../events/SDL_events_c.h" #ifdef main #undef main @@ -28,7 +29,7 @@ PSP_MAIN_THREAD_ATTR(THREAD_ATTR_VFPU | THREAD_ATTR_USER); int sdl_psp_exit_callback(int arg1, int arg2, void *common) { - sceKernelExitGame(); + SDL_SendQuit(); return 0; } diff --git a/src/main/windows/version.rc b/src/main/windows/version.rc index 53621c282e531..42ba606fe4d72 100644 --- a/src/main/windows/version.rc +++ b/src/main/windows/version.rc @@ -9,8 +9,8 @@ LANGUAGE LANG_ENGLISH, SUBLANG_ENGLISH_US // VS_VERSION_INFO VERSIONINFO - FILEVERSION 2,30,12,0 - PRODUCTVERSION 2,30,12,0 + FILEVERSION 2,32,0,0 + PRODUCTVERSION 2,32,0,0 FILEFLAGSMASK 0x3fL FILEFLAGS 0x0L FILEOS 0x40004L @@ -23,12 +23,12 @@ BEGIN BEGIN VALUE "CompanyName", "\0" VALUE "FileDescription", "SDL\0" - VALUE "FileVersion", "2, 30, 12, 0\0" + VALUE "FileVersion", "2, 32, 0, 0\0" VALUE "InternalName", "SDL\0" VALUE "LegalCopyright", "Copyright (C) 2025 Sam Lantinga\0" VALUE "OriginalFilename", "SDL2.dll\0" VALUE "ProductName", "Simple DirectMedia Layer\0" - VALUE "ProductVersion", "2, 30, 12, 0\0" + VALUE "ProductVersion", "2, 32, 0, 0\0" END END BLOCK "VarFileInfo" diff --git a/src/render/SDL_render.c b/src/render/SDL_render.c index a70d38e32d3c6..cc3d16959bcb1 100644 --- a/src/render/SDL_render.c +++ b/src/render/SDL_render.c @@ -47,12 +47,19 @@ this should probably be removed at some point in the future. --ryan. */ #define SDL_WINDOWRENDERDATA "_SDL_WindowRenderData" -#define CHECK_RENDERER_MAGIC(renderer, retval) \ +#define CHECK_RENDERER_MAGIC_BUT_NOT_DESTROYED_FLAG(renderer, retval) \ if (!renderer || renderer->magic != &renderer_magic) { \ SDL_InvalidParamError("renderer"); \ return retval; \ } +#define CHECK_RENDERER_MAGIC(renderer, retval) \ + CHECK_RENDERER_MAGIC_BUT_NOT_DESTROYED_FLAG(renderer, retval); \ + if (renderer->destroyed) { \ + SDL_SetError("Renderer's window has been destroyed, can't use further"); \ + return retval; \ + } + #define CHECK_TEXTURE_MAGIC(texture, retval) \ if (!texture || texture->magic != &texture_magic) { \ SDL_InvalidParamError("texture"); \ @@ -954,6 +961,7 @@ SDL_Renderer *SDL_CreateRenderer(SDL_Window *window, int index, Uint32 flags) int n = SDL_GetNumRenderDrivers(); SDL_bool batching = SDL_TRUE; const char *hint; + int rc = -1; #if defined(__ANDROID__) Android_ActivityMutex_Lock_Running(); @@ -974,6 +982,14 @@ SDL_Renderer *SDL_CreateRenderer(SDL_Window *window, int index, Uint32 flags) goto error; } + renderer = (SDL_Renderer *)SDL_calloc(1, sizeof(*renderer)); + if (!renderer) { + SDL_OutOfMemory(); + goto error; + } + + renderer->magic = &renderer_magic; + hint = SDL_GetHint(SDL_HINT_RENDER_VSYNC); if (hint && *hint) { if (SDL_GetHintBoolean(SDL_HINT_RENDER_VSYNC, SDL_TRUE)) { @@ -991,30 +1007,36 @@ SDL_Renderer *SDL_CreateRenderer(SDL_Window *window, int index, Uint32 flags) if (SDL_strcasecmp(hint, driver->info.name) == 0) { /* Create a new renderer instance */ - renderer = driver->CreateRenderer(window, flags); - if (renderer) { + rc = driver->CreateRenderer(renderer, window, flags); + if (rc == 0) { batching = SDL_FALSE; + } else { + SDL_zerop(renderer); /* make sure we don't leave function pointers from a previous CreateRenderer() in this struct. */ + renderer->magic = &renderer_magic; } break; } } } - if (!renderer) { + if (rc == -1) { for (index = 0; index < n; ++index) { const SDL_RenderDriver *driver = render_drivers[index]; if ((driver->info.flags & flags) == flags) { /* Create a new renderer instance */ - renderer = driver->CreateRenderer(window, flags); - if (renderer) { + rc = driver->CreateRenderer(renderer, window, flags); + if (rc == 0) { /* Yay, we got one! */ break; + } else { + SDL_zerop(renderer); /* make sure we don't leave function pointers from a previous CreateRenderer() in this struct. */ + renderer->magic = &renderer_magic; } } } } - if (!renderer) { + if (rc == -1) { SDL_SetError("Couldn't find matching render driver"); goto error; } @@ -1025,9 +1047,9 @@ SDL_Renderer *SDL_CreateRenderer(SDL_Window *window, int index, Uint32 flags) goto error; } /* Create a new renderer instance */ - renderer = render_drivers[index]->CreateRenderer(window, flags); + rc = render_drivers[index]->CreateRenderer(renderer, window, flags); batching = SDL_FALSE; - if (!renderer) { + if (rc == -1) { goto error; } } @@ -1108,6 +1130,7 @@ SDL_Renderer *SDL_CreateRenderer(SDL_Window *window, int index, Uint32 flags) return renderer; error: + SDL_free(renderer); #if defined(__ANDROID__) Android_ActivityMutex_Unlock(); @@ -1124,12 +1147,23 @@ SDL_Renderer *SDL_CreateSoftwareRenderer(SDL_Surface *surface) { #if SDL_VIDEO_RENDER_SW SDL_Renderer *renderer; + int rc; - renderer = SW_CreateRendererForSurface(surface); + renderer = (SDL_Renderer *)SDL_calloc(1, sizeof(*renderer)); + if (!renderer) { + SDL_OutOfMemory(); + return NULL; + } - if (renderer) { + renderer->magic = &renderer_magic; + + rc = SW_CreateRendererForSurface(renderer, surface); + + if (rc == -1) { + SDL_free(renderer); + renderer = NULL; + } else { VerifyDrawQueueFunctions(renderer); - renderer->magic = &renderer_magic; renderer->target_mutex = SDL_CreateMutex(); renderer->scale.x = 1.0f; renderer->scale.y = 1.0f; @@ -4318,11 +4352,14 @@ void SDL_DestroyTexture(SDL_Texture *texture) SDL_free(texture); } -void SDL_DestroyRenderer(SDL_Renderer *renderer) +void SDL_DestroyRendererWithoutFreeing(SDL_Renderer *renderer) { SDL_RenderCommand *cmd; - CHECK_RENDERER_MAGIC(renderer, ); + SDL_assert(renderer != NULL); + SDL_assert(!renderer->destroyed); + + renderer->destroyed = SDL_TRUE; SDL_DelEventWatch(SDL_RendererEventWatch, renderer); @@ -4357,9 +4394,6 @@ void SDL_DestroyRenderer(SDL_Renderer *renderer) SDL_SetWindowData(renderer->window, SDL_WINDOWRENDERDATA, NULL); } - /* It's no longer magical... */ - renderer->magic = NULL; - /* Free the target mutex */ SDL_DestroyMutex(renderer->target_mutex); renderer->target_mutex = NULL; @@ -4368,6 +4402,22 @@ void SDL_DestroyRenderer(SDL_Renderer *renderer) renderer->DestroyRenderer(renderer); } +void SDL_DestroyRenderer(SDL_Renderer *renderer) +{ + CHECK_RENDERER_MAGIC_BUT_NOT_DESTROYED_FLAG(renderer,); + + /* if we've already destroyed the renderer through SDL_DestroyWindow, we just need + to free the renderer pointer. This lets apps destroy the window and renderer + in either order. */ + if (!renderer->destroyed) { + SDL_DestroyRendererWithoutFreeing(renderer); + renderer->magic = NULL; // It's no longer magical... + } + + SDL_free(renderer); +} + + int SDL_GL_BindTexture(SDL_Texture *texture, float *texw, float *texh) { SDL_Renderer *renderer; diff --git a/src/render/SDL_sysrender.h b/src/render/SDL_sysrender.h index 88d7d57bf9fb0..bab41e7729e1b 100644 --- a/src/render/SDL_sysrender.h +++ b/src/render/SDL_sysrender.h @@ -282,13 +282,15 @@ struct SDL_Renderer size_t vertex_data_used; size_t vertex_data_allocation; + SDL_bool destroyed; /* already destroyed by SDL_DestroyWindow; just free this struct in SDL_DestroyRenderer. */ + void *driverdata; }; /* Define the SDL render driver structure */ struct SDL_RenderDriver { - SDL_Renderer *(*CreateRenderer)(SDL_Window *window, Uint32 flags); + int (*CreateRenderer)(SDL_Renderer *renderer, SDL_Window *window, Uint32 flags); /* Info about the renderer capabilities */ SDL_RendererInfo info; @@ -324,6 +326,9 @@ extern void *SDL_AllocateRenderVertices(SDL_Renderer *renderer, const size_t num extern int SDL_PrivateLowerBlitScaled(SDL_Surface *src, SDL_Rect *srcrect, SDL_Surface *dst, SDL_Rect *dstrect, SDL_ScaleMode scaleMode); extern int SDL_PrivateUpperBlitScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, SDL_Rect *dstrect, SDL_ScaleMode scaleMode); +/* Let the video subsystem destroy a renderer without making its pointer invalid. */ +extern void SDL_DestroyRendererWithoutFreeing(SDL_Renderer *renderer); + /* Ends C function definitions when using C++ */ #ifdef __cplusplus } diff --git a/src/render/direct3d/SDL_render_d3d.c b/src/render/direct3d/SDL_render_d3d.c index 44fd6df412ef8..eaaf848a45ef1 100644 --- a/src/render/direct3d/SDL_render_d3d.c +++ b/src/render/direct3d/SDL_render_d3d.c @@ -1447,7 +1447,6 @@ static void D3D_DestroyRenderer(SDL_Renderer *renderer) } SDL_free(data); } - SDL_free(renderer); } static int D3D_Reset(SDL_Renderer *renderer) @@ -1547,9 +1546,8 @@ static int D3D_SetVSync(SDL_Renderer *renderer, const int vsync) return 0; } -SDL_Renderer *D3D_CreateRenderer(SDL_Window *window, Uint32 flags) +int D3D_CreateRenderer(SDL_Renderer *renderer, SDL_Window *window, Uint32 flags) { - SDL_Renderer *renderer; D3D_RenderData *data; SDL_SysWMinfo windowinfo; HRESULT result; @@ -1562,24 +1560,14 @@ SDL_Renderer *D3D_CreateRenderer(SDL_Window *window, Uint32 flags) SDL_DisplayMode fullscreen_mode; int displayIndex; - renderer = (SDL_Renderer *) SDL_calloc(1, sizeof(*renderer)); - if (!renderer) { - SDL_OutOfMemory(); - return NULL; - } - data = (D3D_RenderData *)SDL_calloc(1, sizeof(*data)); if (!data) { - SDL_free(renderer); - SDL_OutOfMemory(); - return NULL; + return SDL_OutOfMemory(); } if (!D3D_LoadDLL(&data->d3dDLL, &data->d3d)) { - SDL_free(renderer); SDL_free(data); - SDL_SetError("Unable to create Direct3D interface"); - return NULL; + return SDL_SetError("Unable to create Direct3D interface"); } renderer->WindowEvent = D3D_WindowEvent; @@ -1613,8 +1601,7 @@ SDL_Renderer *D3D_CreateRenderer(SDL_Window *window, Uint32 flags) if (!SDL_GetWindowWMInfo(window, &windowinfo) || windowinfo.subsystem != SDL_SYSWM_WINDOWS) { SDL_free(data); - SDL_SetError("Couldn't get window handle"); - return NULL; + return SDL_SetError("Couldn't get window handle"); } window_flags = SDL_GetWindowFlags(window); @@ -1667,23 +1654,20 @@ SDL_Renderer *D3D_CreateRenderer(SDL_Window *window, Uint32 flags) &pparams, &data->device); if (FAILED(result)) { D3D_DestroyRenderer(renderer); - D3D_SetError("CreateDevice()", result); - return NULL; + return D3D_SetError("CreateDevice()", result); } /* Get presentation parameters to fill info */ result = IDirect3DDevice9_GetSwapChain(data->device, 0, &chain); if (FAILED(result)) { D3D_DestroyRenderer(renderer); - D3D_SetError("GetSwapChain()", result); - return NULL; + return D3D_SetError("GetSwapChain()", result); } result = IDirect3DSwapChain9_GetPresentParameters(chain, &pparams); if (FAILED(result)) { IDirect3DSwapChain9_Release(chain); D3D_DestroyRenderer(renderer); - D3D_SetError("GetPresentParameters()", result); - return NULL; + return D3D_SetError("GetPresentParameters()", result); } IDirect3DSwapChain9_Release(chain); if (pparams.PresentationInterval == D3DPRESENT_INTERVAL_ONE) { @@ -1725,7 +1709,7 @@ SDL_Renderer *D3D_CreateRenderer(SDL_Window *window, Uint32 flags) data->drawstate.cliprect_enabled_dirty = SDL_TRUE; data->drawstate.blend = SDL_BLENDMODE_INVALID; - return renderer; + return 0; } SDL_RenderDriver D3D_RenderDriver = { diff --git a/src/render/direct3d11/SDL_render_d3d11.c b/src/render/direct3d11/SDL_render_d3d11.c index d3d8bc906a969..f5d0d80a3bd2d 100644 --- a/src/render/direct3d11/SDL_render_d3d11.c +++ b/src/render/direct3d11/SDL_render_d3d11.c @@ -304,7 +304,6 @@ static void D3D11_DestroyRenderer(SDL_Renderer *renderer) if (data) { SDL_free(data); } - SDL_free(renderer); } static D3D11_BLEND GetBlendFunc(SDL_BlendFactor factor) @@ -2313,22 +2312,13 @@ static int D3D11_SetVSync(SDL_Renderer *renderer, const int vsync) } #endif -SDL_Renderer *D3D11_CreateRenderer(SDL_Window *window, Uint32 flags) +int D3D11_CreateRenderer(SDL_Renderer *renderer, SDL_Window *window, Uint32 flags) { - SDL_Renderer *renderer; D3D11_RenderData *data; - renderer = (SDL_Renderer *)SDL_calloc(1, sizeof(*renderer)); - if (!renderer) { - SDL_OutOfMemory(); - return NULL; - } - data = (D3D11_RenderData *)SDL_calloc(1, sizeof(*data)); if (!data) { - SDL_free(renderer); - SDL_OutOfMemory(); - return NULL; + return SDL_OutOfMemory(); } data->identity = MatrixIdentity(); @@ -2390,14 +2380,14 @@ SDL_Renderer *D3D11_CreateRenderer(SDL_Window *window, Uint32 flags) /* Initialize Direct3D resources */ if (FAILED(D3D11_CreateDeviceResources(renderer))) { D3D11_DestroyRenderer(renderer); - return NULL; + return -1; } if (FAILED(D3D11_CreateWindowSizeDependentResources(renderer))) { D3D11_DestroyRenderer(renderer); - return NULL; + return -1; } - return renderer; + return 0; } SDL_RenderDriver D3D11_RenderDriver = { diff --git a/src/render/direct3d12/SDL_render_d3d12.c b/src/render/direct3d12/SDL_render_d3d12.c index 63a8410430f9c..e97189a002614 100644 --- a/src/render/direct3d12/SDL_render_d3d12.c +++ b/src/render/direct3d12/SDL_render_d3d12.c @@ -556,7 +556,6 @@ static void D3D12_DestroyRenderer(SDL_Renderer *renderer) if (data) { SDL_free(data); } - SDL_free(renderer); } static int D3D12_GetOutputSize(SDL_Renderer *renderer, int *w, int *h) @@ -3014,22 +3013,13 @@ static int D3D12_SetVSync(SDL_Renderer *renderer, const int vsync) return 0; } -SDL_Renderer *D3D12_CreateRenderer(SDL_Window *window, Uint32 flags) +int D3D12_CreateRenderer(SDL_Renderer *renderer, SDL_Window *window, Uint32 flags) { - SDL_Renderer *renderer; D3D12_RenderData *data; - renderer = (SDL_Renderer *)SDL_calloc(1, sizeof(*renderer)); - if (!renderer) { - SDL_OutOfMemory(); - return NULL; - } - data = (D3D12_RenderData *)SDL_calloc(1, sizeof(*data)); if (!data) { - SDL_free(renderer); - SDL_OutOfMemory(); - return NULL; + return SDL_OutOfMemory(); } data->identity = MatrixIdentity(); @@ -3074,14 +3064,14 @@ SDL_Renderer *D3D12_CreateRenderer(SDL_Window *window, Uint32 flags) /* Initialize Direct3D resources */ if (FAILED(D3D12_CreateDeviceResources(renderer))) { D3D12_DestroyRenderer(renderer); - return NULL; + return -1; } if (FAILED(D3D12_CreateWindowSizeDependentResources(renderer))) { D3D12_DestroyRenderer(renderer); - return NULL; + return -1; } - return renderer; + return 0; } SDL_RenderDriver D3D12_RenderDriver = { diff --git a/src/render/metal/SDL_render_metal.m b/src/render/metal/SDL_render_metal.m index 410885827acb6..246af41bde55b 100644 --- a/src/render/metal/SDL_render_metal.m +++ b/src/render/metal/SDL_render_metal.m @@ -1513,8 +1513,6 @@ in case we want to use it later (recreating the renderer) /* SDL_Metal_DestroyView(data.mtlview); */ CFBridgingRelease(data.mtlview); } - - SDL_free(renderer); }} static void *METAL_GetMetalLayer(SDL_Renderer * renderer) @@ -1580,9 +1578,8 @@ static SDL_MetalView GetWindowView(SDL_Window *window) return nil; } -static SDL_Renderer *METAL_CreateRenderer(SDL_Window * window, Uint32 flags) +static int METAL_CreateRenderer(SDL_Renderer *renderer, SDL_Window * window, Uint32 flags) { @autoreleasepool { - SDL_Renderer *renderer = NULL; METAL_RenderData *data = NULL; id mtldevice = nil; SDL_MetalView view = NULL; @@ -1641,17 +1638,11 @@ static SDL_MetalView GetWindowView(SDL_Window *window) SDL_VERSION(&syswm.version); if (!SDL_GetWindowWMInfo(window, &syswm)) { - return NULL; + return -1; } if (IsMetalAvailable(&syswm) == -1) { - return NULL; - } - - renderer = (SDL_Renderer *) SDL_calloc(1, sizeof(*renderer)); - if (!renderer) { - SDL_OutOfMemory(); - return NULL; + return -1; } #ifdef __MACOSX__ @@ -1672,9 +1663,7 @@ static SDL_MetalView GetWindowView(SDL_Window *window) } if (mtldevice == nil) { - SDL_free(renderer); - SDL_SetError("Failed to obtain Metal device"); - return NULL; + return SDL_SetError("Failed to obtain Metal device"); } view = GetWindowView(window); @@ -1683,8 +1672,7 @@ static SDL_MetalView GetWindowView(SDL_Window *window) } if (view == NULL) { - SDL_free(renderer); - return NULL; + return -1; } // !!! FIXME: error checking on all of this. @@ -1696,8 +1684,7 @@ in case we want to use it later (recreating the renderer) */ /* SDL_Metal_DestroyView(view); */ CFBridgingRelease(view); - SDL_free(renderer); - return NULL; + return -1; } renderer->driverdata = (void*)CFBridgingRetain(data); @@ -1875,7 +1862,7 @@ in case we want to use it later (recreating the renderer) renderer->info.max_texture_width = maxtexsize; renderer->info.max_texture_height = maxtexsize; - return renderer; + return 0; }} SDL_RenderDriver METAL_RenderDriver = { diff --git a/src/render/opengl/SDL_render_gl.c b/src/render/opengl/SDL_render_gl.c index 31eddbd099cbf..ea3fe1074104e 100644 --- a/src/render/opengl/SDL_render_gl.c +++ b/src/render/opengl/SDL_render_gl.c @@ -1555,7 +1555,6 @@ static void GL_DestroyRenderer(SDL_Renderer *renderer) } SDL_free(data); } - SDL_free(renderer); } static int GL_BindTexture(SDL_Renderer *renderer, SDL_Texture *texture, float *texw, float *texh) @@ -1700,9 +1699,8 @@ static SDL_bool GL_IsProbablyAccelerated(const GL_RenderData *data) return SDL_TRUE; } -static SDL_Renderer *GL_CreateRenderer(SDL_Window *window, Uint32 flags) +static int GL_CreateRenderer(SDL_Renderer *renderer, SDL_Window *window, Uint32 flags) { - SDL_Renderer *renderer; GL_RenderData *data; GLint value; Uint32 window_flags; @@ -1731,15 +1729,8 @@ static SDL_Renderer *GL_CreateRenderer(SDL_Window *window, Uint32 flags) } #endif - renderer = (SDL_Renderer *)SDL_calloc(1, sizeof(*renderer)); - if (!renderer) { - SDL_OutOfMemory(); - goto error; - } - data = (GL_RenderData *)SDL_calloc(1, sizeof(*data)); if (!data) { - SDL_free(renderer); SDL_OutOfMemory(); goto error; } @@ -1777,20 +1768,17 @@ static SDL_Renderer *GL_CreateRenderer(SDL_Window *window, Uint32 flags) data->context = SDL_GL_CreateContext(window); if (!data->context) { - SDL_free(renderer); SDL_free(data); goto error; } if (SDL_GL_MakeCurrent(window, data->context) < 0) { SDL_GL_DeleteContext(data->context); - SDL_free(renderer); SDL_free(data); goto error; } if (GL_LoadFunctions(data) < 0) { SDL_GL_DeleteContext(data->context); - SDL_free(renderer); SDL_free(data); goto error; } @@ -1944,7 +1932,7 @@ static SDL_Renderer *GL_CreateRenderer(SDL_Window *window, Uint32 flags) data->drawstate.color = 0xFFFFFFFF; data->drawstate.clear_color = 0xFFFFFFFF; - return renderer; + return 0; error: if (changed_window) { @@ -1954,7 +1942,7 @@ static SDL_Renderer *GL_CreateRenderer(SDL_Window *window, Uint32 flags) SDL_GL_SetAttribute(SDL_GL_CONTEXT_MINOR_VERSION, minor); SDL_RecreateWindow(window, window_flags); } - return NULL; + return -1; } SDL_RenderDriver GL_RenderDriver = { diff --git a/src/render/opengles/SDL_render_gles.c b/src/render/opengles/SDL_render_gles.c index f0652861a64f4..4f1a9401e971c 100644 --- a/src/render/opengles/SDL_render_gles.c +++ b/src/render/opengles/SDL_render_gles.c @@ -997,7 +997,6 @@ static void GLES_DestroyRenderer(SDL_Renderer *renderer) } SDL_free(data); } - SDL_free(renderer); } static int GLES_BindTexture(SDL_Renderer *renderer, SDL_Texture *texture, float *texw, float *texh) @@ -1054,10 +1053,9 @@ static int GLES_SetVSync(SDL_Renderer *renderer, const int vsync) return retval; } -static SDL_Renderer *GLES_CreateRenderer(SDL_Window *window, Uint32 flags) +static int GLES_CreateRenderer(SDL_Renderer *renderer, SDL_Window *window, Uint32 flags) { - SDL_Renderer *renderer; - GLES_RenderData *data; + GLES_RenderData *data = NULL; GLint value; Uint32 window_flags; int profile_mask = 0, major = 0, minor = 0; @@ -1081,12 +1079,6 @@ static SDL_Renderer *GLES_CreateRenderer(SDL_Window *window, Uint32 flags) } } - renderer = (SDL_Renderer *)SDL_calloc(1, sizeof(*renderer)); - if (!renderer) { - SDL_OutOfMemory(); - goto error; - } - data = (GLES_RenderData *)SDL_calloc(1, sizeof(*data)); if (!data) { GLES_DestroyRenderer(renderer); @@ -1192,7 +1184,7 @@ static SDL_Renderer *GLES_CreateRenderer(SDL_Window *window, Uint32 flags) data->drawstate.color = 0xFFFFFFFF; data->drawstate.clear_color = 0xFFFFFFFF; - return renderer; + return 0; error: if (changed_window) { @@ -1202,7 +1194,7 @@ static SDL_Renderer *GLES_CreateRenderer(SDL_Window *window, Uint32 flags) SDL_GL_SetAttribute(SDL_GL_CONTEXT_MINOR_VERSION, minor); SDL_RecreateWindow(window, window_flags); } - return NULL; + return -1; } SDL_RenderDriver GLES_RenderDriver = { diff --git a/src/render/opengles2/SDL_render_gles2.c b/src/render/opengles2/SDL_render_gles2.c index bb9b4ad7ea16d..f5f221c46b607 100644 --- a/src/render/opengles2/SDL_render_gles2.c +++ b/src/render/opengles2/SDL_render_gles2.c @@ -1406,7 +1406,6 @@ static void GLES2_DestroyRenderer(SDL_Renderer *renderer) SDL_free(data); } - SDL_free(renderer); } static int GLES2_CreateTexture(SDL_Renderer *renderer, SDL_Texture *texture) @@ -2030,10 +2029,9 @@ static int GLES2_UnbindTexture(SDL_Renderer *renderer, SDL_Texture *texture) * Renderer instantiation * *************************************************************************************************/ -static SDL_Renderer *GLES2_CreateRenderer(SDL_Window *window, Uint32 flags) +static int GLES2_CreateRenderer(SDL_Renderer *renderer, SDL_Window *window, Uint32 flags) { - SDL_Renderer *renderer; - GLES2_RenderData *data; + GLES2_RenderData *data = NULL; Uint32 window_flags = 0; /* -Wconditional-uninitialized */ GLint window_framebuffer; GLint value; @@ -2066,16 +2064,8 @@ static SDL_Renderer *GLES2_CreateRenderer(SDL_Window *window, Uint32 flags) } } - /* Create the renderer struct */ - renderer = (SDL_Renderer *)SDL_calloc(1, sizeof(SDL_Renderer)); - if (!renderer) { - SDL_OutOfMemory(); - goto error; - } - data = (GLES2_RenderData *)SDL_calloc(1, sizeof(GLES2_RenderData)); if (!data) { - SDL_free(renderer); SDL_OutOfMemory(); goto error; } @@ -2087,28 +2077,20 @@ static SDL_Renderer *GLES2_CreateRenderer(SDL_Window *window, Uint32 flags) /* Create an OpenGL ES 2.0 context */ data->context = SDL_GL_CreateContext(window); if (!data->context) { - SDL_free(renderer); - SDL_free(data); goto error; } if (SDL_GL_MakeCurrent(window, data->context) < 0) { SDL_GL_DeleteContext(data->context); - SDL_free(renderer); - SDL_free(data); goto error; } if (GLES2_LoadFunctions(data) < 0) { SDL_GL_DeleteContext(data->context); - SDL_free(renderer); - SDL_free(data); goto error; } if (GLES2_CacheShaders(data) < 0) { SDL_GL_DeleteContext(data->context); - SDL_free(renderer); - SDL_free(data); goto error; } @@ -2219,9 +2201,10 @@ static SDL_Renderer *GLES2_CreateRenderer(SDL_Window *window, Uint32 flags) GL_CheckError("", renderer); - return renderer; + return 0; error: + SDL_free(data); if (changed_window) { /* Uh oh, better try to put it back... */ SDL_GL_SetAttribute(SDL_GL_CONTEXT_PROFILE_MASK, profile_mask); @@ -2229,7 +2212,7 @@ static SDL_Renderer *GLES2_CreateRenderer(SDL_Window *window, Uint32 flags) SDL_GL_SetAttribute(SDL_GL_CONTEXT_MINOR_VERSION, minor); SDL_RecreateWindow(window, window_flags); } - return NULL; + return -1; } SDL_RenderDriver GLES2_RenderDriver = { @@ -2237,8 +2220,8 @@ SDL_RenderDriver GLES2_RenderDriver = { { "opengles2", (SDL_RENDERER_ACCELERATED | SDL_RENDERER_PRESENTVSYNC | SDL_RENDERER_TARGETTEXTURE), 4, - { SDL_PIXELFORMAT_RGBA32, - SDL_PIXELFORMAT_BGRA32, + { SDL_PIXELFORMAT_BGRA32, + SDL_PIXELFORMAT_ABGR32, SDL_PIXELFORMAT_BGRX32, SDL_PIXELFORMAT_RGBX32 }, 0, diff --git a/src/render/ps2/SDL_render_ps2.c b/src/render/ps2/SDL_render_ps2.c index 7c381d7a6d170..acf01fc7f59b4 100644 --- a/src/render/ps2/SDL_render_ps2.c +++ b/src/render/ps2/SDL_render_ps2.c @@ -593,8 +593,6 @@ static void PS2_DestroyRenderer(SDL_Renderer *renderer) if (vsync_sema_id >= 0) { DeleteSema(vsync_sema_id); } - - SDL_free(renderer); } static int PS2_SetVSync(SDL_Renderer *renderer, const int vsync) @@ -605,25 +603,17 @@ static int PS2_SetVSync(SDL_Renderer *renderer, const int vsync) return 0; } -static SDL_Renderer *PS2_CreateRenderer(SDL_Window *window, Uint32 flags) +static int PS2_CreateRenderer(SDL_Renderer *renderer, SDL_Window *window, Uint32 flags) { - SDL_Renderer *renderer; PS2_RenderData *data; GSGLOBAL *gsGlobal; ee_sema_t sema; SDL_bool dynamicVsync; - renderer = (SDL_Renderer *)SDL_calloc(1, sizeof(*renderer)); - if (!renderer) { - SDL_OutOfMemory(); - return NULL; - } - data = (PS2_RenderData *)SDL_calloc(1, sizeof(*data)); if (!data) { PS2_DestroyRenderer(renderer); - SDL_OutOfMemory(); - return NULL; + return SDL_OutOfMemory(); } /* Specific gsKit init */ @@ -689,7 +679,7 @@ static SDL_Renderer *PS2_CreateRenderer(SDL_Window *window, Uint32 flags) renderer->driverdata = data; renderer->window = window; - return renderer; + return 0; } SDL_RenderDriver PS2_RenderDriver = { diff --git a/src/render/psp/SDL_render_psp.c b/src/render/psp/SDL_render_psp.c index a53ea2075ce22..2b85309d81260 100644 --- a/src/render/psp/SDL_render_psp.c +++ b/src/render/psp/SDL_render_psp.c @@ -36,15 +36,9 @@ #include #include #include +#include "SDL_render_psp.h" /* PSP renderer implementation, based on the PGE */ - -#define PSP_SCREEN_WIDTH 480 -#define PSP_SCREEN_HEIGHT 272 - -#define PSP_FRAME_BUFFER_WIDTH 512 -#define PSP_FRAME_BUFFER_SIZE (PSP_FRAME_BUFFER_WIDTH * PSP_SCREEN_HEIGHT) - static unsigned int __attribute__((aligned(16))) DisplayList[262144]; #define COL5650(r, g, b, a) ((r >> 3) | ((g >> 2) << 5) | ((b >> 3) << 11)) @@ -124,6 +118,24 @@ typedef struct float x, y, z; } VertTCV; +int SDL_PSP_RenderGetProp(SDL_Renderer *r, enum SDL_PSP_RenderProps which, void** out) +{ + PSP_RenderData *rd; + if (r == NULL) { + return -1; + } + rd = r->driverdata; + switch (which) { + case SDL_PSP_RENDERPROPS_FRONTBUFFER: + *out = rd->frontbuffer; + return 0; + case SDL_PSP_RENDERPROPS_BACKBUFFER: + *out = rd->backbuffer; + return 0; + } + return -1; +} + #define PI 3.14159265358979f #define radToDeg(x) ((x)*180.f / PI) @@ -1268,8 +1280,6 @@ static void PSP_DestroyRenderer(SDL_Renderer *renderer) return; } - StartDrawing(renderer); - sceKernelDisableSubIntr(PSP_VBLANK_INT, 0); sceKernelReleaseSubIntrHandler(PSP_VBLANK_INT, 0); sceDisplayWaitVblankStart(); @@ -1282,7 +1292,6 @@ static void PSP_DestroyRenderer(SDL_Renderer *renderer) data->displayListAvail = SDL_FALSE; SDL_free(data); } - SDL_free(renderer); } static int PSP_SetVSync(SDL_Renderer *renderer, const int vsync) @@ -1292,25 +1301,16 @@ static int PSP_SetVSync(SDL_Renderer *renderer, const int vsync) return 0; } -SDL_Renderer *PSP_CreateRenderer(SDL_Window *window, Uint32 flags) +int PSP_CreateRenderer(SDL_Renderer *renderer, SDL_Window *window, Uint32 flags) { - - SDL_Renderer *renderer; PSP_RenderData *data; int pixelformat; void *doublebuffer = NULL; - renderer = (SDL_Renderer *)SDL_calloc(1, sizeof(*renderer)); - if (!renderer) { - SDL_OutOfMemory(); - return NULL; - } - data = (PSP_RenderData *)SDL_calloc(1, sizeof(*data)); if (!data) { PSP_DestroyRenderer(renderer); - SDL_OutOfMemory(); - return NULL; + return SDL_OutOfMemory(); } renderer->WindowEvent = PSP_WindowEvent; @@ -1402,7 +1402,7 @@ SDL_Renderer *PSP_CreateRenderer(SDL_Window *window, Uint32 flags) sceKernelRegisterSubIntrHandler(PSP_VBLANK_INT, 0, psp_on_vblank, data); sceKernelEnableSubIntr(PSP_VBLANK_INT, 0); - return renderer; + return 0; } SDL_RenderDriver PSP_RenderDriver = { diff --git a/src/render/psp/SDL_render_psp.h b/src/render/psp/SDL_render_psp.h new file mode 100644 index 0000000000000..74a964fcc3d1b --- /dev/null +++ b/src/render/psp/SDL_render_psp.h @@ -0,0 +1,38 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/* this header is meant to be included after the other related internal SDL + headers. it's the interface between psp renderer and video driver code. */ + +#define PSP_SCREEN_WIDTH 480 +#define PSP_SCREEN_HEIGHT 272 + +#define PSP_FRAME_BUFFER_WIDTH 512 +#define PSP_FRAME_BUFFER_SIZE (PSP_FRAME_BUFFER_WIDTH * PSP_SCREEN_HEIGHT) + +enum SDL_PSP_RenderProps +{ + SDL_PSP_RENDERPROPS_FRONTBUFFER, + SDL_PSP_RENDERPROPS_BACKBUFFER, +}; + +int SDL_PSP_RenderGetProp(SDL_Renderer *r, enum SDL_PSP_RenderProps which, void** out); + diff --git a/src/render/software/SDL_render_sw.c b/src/render/software/SDL_render_sw.c index 1eaf1078037b8..8abf428704543 100644 --- a/src/render/software/SDL_render_sw.c +++ b/src/render/software/SDL_render_sw.c @@ -987,30 +987,20 @@ static void SW_DestroyRenderer(SDL_Renderer *renderer) SDL_DestroyWindowSurface(window); } SDL_free(data); - SDL_free(renderer); } -SDL_Renderer *SW_CreateRendererForSurface(SDL_Surface *surface) +int SW_CreateRendererForSurface(SDL_Renderer *renderer, SDL_Surface *surface) { - SDL_Renderer *renderer; SW_RenderData *data; if (!surface) { - SDL_InvalidParamError("surface"); - return NULL; - } - - renderer = (SDL_Renderer *)SDL_calloc(1, sizeof(*renderer)); - if (!renderer) { - SDL_OutOfMemory(); - return NULL; + return SDL_InvalidParamError("surface"); } data = (SW_RenderData *)SDL_calloc(1, sizeof(*data)); if (!data) { SW_DestroyRenderer(renderer); - SDL_OutOfMemory(); - return NULL; + return SDL_OutOfMemory(); } data->surface = surface; data->window = surface; @@ -1039,10 +1029,10 @@ SDL_Renderer *SW_CreateRendererForSurface(SDL_Surface *surface) renderer->info = SW_RenderDriver.info; renderer->driverdata = data; - return renderer; + return 0; } -static SDL_Renderer *SW_CreateRenderer(SDL_Window *window, Uint32 flags) +static int SW_CreateRenderer(SDL_Renderer *renderer, SDL_Window *window, Uint32 flags) { const char *hint; SDL_Surface *surface; @@ -1068,9 +1058,9 @@ static SDL_Renderer *SW_CreateRenderer(SDL_Window *window, Uint32 flags) } if (!surface) { - return NULL; + return -1; } - return SW_CreateRendererForSurface(surface); + return SW_CreateRendererForSurface(renderer, surface); } SDL_RenderDriver SW_RenderDriver = { diff --git a/src/render/software/SDL_render_sw_c.h b/src/render/software/SDL_render_sw_c.h index 351a9374ac71e..d59a85fdb9e7a 100644 --- a/src/render/software/SDL_render_sw_c.h +++ b/src/render/software/SDL_render_sw_c.h @@ -22,7 +22,7 @@ #ifndef SDL_render_sw_c_h_ #define SDL_render_sw_c_h_ -extern SDL_Renderer *SW_CreateRendererForSurface(SDL_Surface *surface); +extern int SW_CreateRendererForSurface(SDL_Renderer *renderer, SDL_Surface *surface); #endif /* SDL_render_sw_c_h_ */ diff --git a/src/render/vitagxm/SDL_render_vita_gxm.c b/src/render/vitagxm/SDL_render_vita_gxm.c index db61cf9369e51..9267b4e0e50ff 100644 --- a/src/render/vitagxm/SDL_render_vita_gxm.c +++ b/src/render/vitagxm/SDL_render_vita_gxm.c @@ -44,7 +44,7 @@ #include #endif -static SDL_Renderer *VITA_GXM_CreateRenderer(SDL_Window *window, Uint32 flags); +static int VITA_GXM_CreateRenderer(SDL_Renderer *renderer, SDL_Window *window, Uint32 flags); static void VITA_GXM_WindowEvent(SDL_Renderer *renderer, const SDL_WindowEvent *event); @@ -211,22 +211,13 @@ static int VITA_GXM_SetVSync(SDL_Renderer *renderer, const int vsync) return 0; } -SDL_Renderer *VITA_GXM_CreateRenderer(SDL_Window *window, Uint32 flags) +int VITA_GXM_CreateRenderer(SDL_Renderer *renderer, SDL_Window *window, Uint32 flags) { - SDL_Renderer *renderer; VITA_GXM_RenderData *data; - renderer = (SDL_Renderer *)SDL_calloc(1, sizeof(*renderer)); - if (!renderer) { - SDL_OutOfMemory(); - return NULL; - } - data = (VITA_GXM_RenderData *)SDL_calloc(1, sizeof(VITA_GXM_RenderData)); if (!data) { - SDL_free(renderer); - SDL_OutOfMemory(); - return NULL; + return SDL_OutOfMemory(); } renderer->WindowEvent = VITA_GXM_WindowEvent; @@ -273,11 +264,10 @@ SDL_Renderer *VITA_GXM_CreateRenderer(SDL_Window *window, Uint32 flags) if (gxm_init(renderer) != 0) { SDL_free(data); - SDL_free(renderer); - return NULL; + return -1; } - return renderer; + return 0; } static void VITA_GXM_WindowEvent(SDL_Renderer *renderer, const SDL_WindowEvent *event) @@ -1224,7 +1214,6 @@ static void VITA_GXM_DestroyRenderer(SDL_Renderer *renderer) data->drawing = SDL_FALSE; SDL_free(data); } - SDL_free(renderer); } #endif /* SDL_VIDEO_RENDER_VITA_GXM */ diff --git a/src/stdlib/SDL_qsort.c b/src/stdlib/SDL_qsort.c index dfeee626e51f8..63995594e67e9 100644 --- a/src/stdlib/SDL_qsort.c +++ b/src/stdlib/SDL_qsort.c @@ -28,7 +28,7 @@ #include "SDL_stdinc.h" #if defined(HAVE_QSORT) -void SDL_qsort(void *base, size_t nmemb, size_t size, int (SDLCALL *compare) (const void *, const void *)) +void SDL_qsort(void *base, size_t nmemb, size_t size, SDL_CompareCallback compare) { if (!base) { return; @@ -530,8 +530,7 @@ fprintf(stderr, "after partitioning first=#%lu last=#%lu\n", (first-(char*)base) /* ---------------------------------------------------------------------- */ -extern void qsortG(void *base, size_t nmemb, size_t size, - int (SDLCALL * compare)(const void *, const void *)) { +extern void qsortG(void *base, size_t nmemb, size_t size, SDL_CompareCallback compare) { if (nmemb<=1) return; if (((uintptr_t)base|size)&(WORD_BYTES-1)) @@ -544,7 +543,7 @@ extern void qsortG(void *base, size_t nmemb, size_t size, #endif /* HAVE_QSORT */ -void *SDL_bsearch(const void *key, const void *base, size_t nmemb, size_t size, int (SDLCALL * compare)(const void *, const void *)) +void *SDL_bsearch(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback compare) { #if defined(HAVE_BSEARCH) return bsearch(key, base, nmemb, size, compare); diff --git a/src/stdlib/SDL_string.c b/src/stdlib/SDL_string.c index 037f6d47f155f..9af6977fe6b28 100644 --- a/src/stdlib/SDL_string.c +++ b/src/stdlib/SDL_string.c @@ -55,234 +55,237 @@ static size_t UTF8_TrailingBytes(unsigned char c) } #if !defined(HAVE_VSSCANF) || !defined(HAVE_STRTOL) || !defined(HAVE_STRTOUL) || !defined(HAVE_STRTOD) -static size_t SDL_ScanLong(const char *text, int count, int radix, long *valuep) -{ - const char *textstart = text; - long value = 0; +/** + * Parses an unsigned long long and returns the unsigned value and sign bit. + * + * Positive values are clamped to ULLONG_MAX. + * The result `value == 0 && negative` indicates negative overflow + * and might need to be handled differently depending on whether a + * signed or unsigned integer is being parsed. + */ +static size_t SDL_ScanUnsignedLongLongInternal(const char *text, int count, int radix, unsigned long long *valuep, SDL_bool *negativep) +{ + const unsigned long long ullong_max = ~0ULL; + + const char *text_start = text; + const char *number_start = text_start; + unsigned long long value = 0; SDL_bool negative = SDL_FALSE; + SDL_bool overflow = SDL_FALSE; - if (*text == '-') { - negative = SDL_TRUE; - ++text; + if (radix == 0 || (radix >= 2 && radix <= 36)) { + while (SDL_isspace(*text)) { + ++text; + } + if (*text == '-' || *text == '+') { + negative = *text == '-'; + ++text; + } + if ((radix == 0 || radix == 16) && *text == '0' && text[1] != '\0') { + ++text; + if (*text == 'x' || *text == 'X') { + radix = 16; + ++text; + } else if (radix == 0) { + radix = 8; + } + } else if (radix == 0) { + radix = 10; + } + number_start = text; + do { + unsigned long long digit; + if (*text >= '0' && *text <= '9') { + digit = *text - '0'; + } else if (radix > 10) { + if (*text >= 'A' && *text < 'A' + (radix - 10)) { + digit = 10 + (*text - 'A'); + } else if (*text >= 'a' && *text < 'a' + (radix - 10)) { + digit = 10 + (*text - 'a'); + } else { + break; + } + } else { + break; + } + if (value != 0 && radix > ullong_max / value) { + overflow = SDL_TRUE; + } else { + value *= radix; + if (digit > ullong_max - value) { + overflow = SDL_TRUE; + } else { + value += digit; + } + } + ++text; + } while (count == 0 || (text - text_start) != count); } - if (radix == 16 && SDL_strncmp(text, "0x", 2) == 0) { - text += 2; - } - for (;;) { - int v; - if (SDL_isdigit((unsigned char)*text)) { - v = *text - '0'; - } else if (radix == 16 && SDL_isupperhex(*text)) { - v = 10 + (*text - 'A'); - } else if (radix == 16 && SDL_islowerhex(*text)) { - v = 10 + (*text - 'a'); + if (text == number_start) { + if (radix == 16 && text > text_start && (*(text - 1) == 'x' || *(text - 1) == 'X')) { + // the string was "0x"; consume the '0' but not the 'x' + --text; } else { - break; + // no number was parsed, and thus no characters were consumed + text = text_start; } - value *= radix; - value += v; - ++text; - - if (count > 0 && (text - textstart) == count) { - break; + } + if (overflow) { + if (negative) { + value = 0; + } else { + value = ullong_max; } + } else if (value == 0) { + negative = SDL_FALSE; } - if (valuep && text > textstart) { - if (negative && value) { - *valuep = -value; + *valuep = value; + *negativep = negative; + return text - text_start; +} + +static size_t SDL_ScanLong(const char *text, int count, int radix, long *valuep) +{ + const unsigned long long_max = (~0UL) >> 1; + unsigned long long value; + SDL_bool negative; + size_t len = SDL_ScanUnsignedLongLongInternal(text, count, radix, &value, &negative); + if (negative) { + const unsigned long abs_long_min = long_max + 1; + if (value == 0 || value > abs_long_min) { + value = 0ULL - abs_long_min; } else { - *valuep = value; + value = 0ULL - value; } + } else if (value > long_max) { + value = long_max; } - return text - textstart; + *valuep = (long)value; + return len; } #endif #if !defined(HAVE_VSSCANF) || !defined(HAVE_STRTOUL) || !defined(HAVE_STRTOD) static size_t SDL_ScanUnsignedLong(const char *text, int count, int radix, unsigned long *valuep) { - const char *textstart = text; - unsigned long value = 0; - - if (*text == '-') { - return SDL_ScanLong(text, count, radix, (long *)valuep); - } - - if (radix == 16 && SDL_strncmp(text, "0x", 2) == 0) { - text += 2; - } - for (;;) { - int v; - if (SDL_isdigit((unsigned char)*text)) { - v = *text - '0'; - } else if (radix == 16 && SDL_isupperhex(*text)) { - v = 10 + (*text - 'A'); - } else if (radix == 16 && SDL_islowerhex(*text)) { - v = 10 + (*text - 'a'); + const unsigned long ulong_max = ~0UL; + unsigned long long value; + SDL_bool negative; + size_t len = SDL_ScanUnsignedLongLongInternal(text, count, radix, &value, &negative); + if (negative) { + if (value == 0 || value > ulong_max) { + value = ulong_max; + } else if (value == ulong_max) { + value = 1; } else { - break; - } - value *= radix; - value += v; - ++text; - - if (count > 0 && (text - textstart) == count) { - break; + value = 0ULL - value; } + } else if (value > ulong_max) { + value = ulong_max; } - if (valuep && text > textstart) { - *valuep = value; - } - return text - textstart; + *valuep = (unsigned long)value; + return len; } #endif #ifndef HAVE_VSSCANF static size_t SDL_ScanUintPtrT(const char *text, int radix, uintptr_t *valuep) { - const char *textstart = text; - uintptr_t value = 0; - - if (radix == 16 && SDL_strncmp(text, "0x", 2) == 0) { - text += 2; - } - for (;;) { - int v; - if (SDL_isdigit((unsigned char)*text)) { - v = *text - '0'; - } else if (radix == 16 && SDL_isupperhex(*text)) { - v = 10 + (*text - 'A'); - } else if (radix == 16 && SDL_islowerhex(*text)) { - v = 10 + (*text - 'a'); + const uintptr_t uintptr_max = ~(uintptr_t)0; + unsigned long long value; + SDL_bool negative; + size_t len = SDL_ScanUnsignedLongLongInternal(text, 0, 16, &value, &negative); + if (negative) { + if (value == 0 || value > uintptr_max) { + value = uintptr_max; + } else if (value == uintptr_max) { + value = 1; } else { - break; + value = 0ULL - value; } - value *= radix; - value += v; - ++text; - } - if (valuep && text > textstart) { - *valuep = value; + } else if (value > uintptr_max) { + value = uintptr_max; } - return text - textstart; + *valuep = (uintptr_t)value; + return len; } #endif #if !defined(HAVE_VSSCANF) || !defined(HAVE_STRTOLL) || !defined(HAVE_STRTOULL) static size_t SDL_ScanLongLong(const char *text, int count, int radix, Sint64 *valuep) { - const char *textstart = text; - Sint64 value = 0; - SDL_bool negative = SDL_FALSE; - - if (*text == '-') { - negative = SDL_TRUE; - ++text; - } - if (radix == 16 && SDL_strncmp(text, "0x", 2) == 0) { - text += 2; - } - for (;;) { - int v; - if (SDL_isdigit((unsigned char)*text)) { - v = *text - '0'; - } else if (radix == 16 && SDL_isupperhex(*text)) { - v = 10 + (*text - 'A'); - } else if (radix == 16 && SDL_islowerhex(*text)) { - v = 10 + (*text - 'a'); + const unsigned long long llong_max = (~0ULL) >> 1; + unsigned long long value; + SDL_bool negative; + size_t len = SDL_ScanUnsignedLongLongInternal(text, count, radix, &value, &negative); + if (negative) { + const unsigned long long abs_llong_min = llong_max + 1; + if (value == 0 || value > abs_llong_min) { + value = 0ULL - abs_llong_min; } else { - break; - } - value *= radix; - value += v; - ++text; - - if (count > 0 && (text - textstart) == count) { - break; + value = 0ULL - value; } + } else if (value > llong_max) { + value = llong_max; } - if (valuep && text > textstart) { - if (negative && value) { - *valuep = -value; - } else { - *valuep = value; - } - } - return text - textstart; + *valuep = value; + return len; } #endif #if !defined(HAVE_VSSCANF) || !defined(HAVE_STRTOULL) static size_t SDL_ScanUnsignedLongLong(const char *text, int count, int radix, Uint64 *valuep) { - const char *textstart = text; - Uint64 value = 0; - - if (*text == '-') { - return SDL_ScanLongLong(text, count, radix, (Sint64 *)valuep); - } - - if (radix == 16 && SDL_strncmp(text, "0x", 2) == 0) { - text += 2; - } - for (;;) { - int v; - if (SDL_isdigit((unsigned char)*text)) { - v = *text - '0'; - } else if (radix == 16 && SDL_isupperhex(*text)) { - v = 10 + (*text - 'A'); - } else if (radix == 16 && SDL_islowerhex(*text)) { - v = 10 + (*text - 'a'); + const unsigned long long ullong_max = ~0ULL; + SDL_bool negative; + size_t len = SDL_ScanUnsignedLongLongInternal(text, count, radix, valuep, &negative); + if (negative) { + if (*valuep == 0) { + *valuep = ullong_max; } else { - break; + *valuep = 0ULL - *valuep; } - value *= radix; - value += v; - ++text; - - if (count > 0 && (text - textstart) == count) { - break; - } - } - if (valuep && text > textstart) { - *valuep = value; } - return text - textstart; + return len; } #endif #if !defined(HAVE_VSSCANF) || !defined(HAVE_STRTOD) static size_t SDL_ScanFloat(const char *text, double *valuep) { - const char *textstart = text; - unsigned long lvalue = 0; + const char *text_start = text; + const char *number_start = text_start; double value = 0.0; SDL_bool negative = SDL_FALSE; - if (*text == '-') { - negative = SDL_TRUE; + while (SDL_isspace(*text)) { ++text; } - text += SDL_ScanUnsignedLong(text, 0, 10, &lvalue); - value += lvalue; - if (*text == '.') { - int mult = 10; + if (*text == '-' || *text == '+') { + negative = *text == '-'; ++text; - while (SDL_isdigit((unsigned char)*text)) { - lvalue = *text - '0'; - value += (double)lvalue / mult; - mult *= 10; + } + number_start = text; + if (SDL_isdigit(*text)) { + value += SDL_strtoull(text, (char **)(&text), 10); + if (*text == '.') { + double denom = 10; ++text; + while (SDL_isdigit(*text)) { + value += (double)(*text - '0') / denom; + denom *= 10; + ++text; + } } } - if (valuep && text > textstart) { - if (negative && value) { - *valuep = -value; - } else { - *valuep = value; - } + if (text == number_start) { + // no number was parsed, and thus no characters were consumed + text = text_start; + } else if (negative) { + value = -value; } - return text - textstart; + *valuep = value; + return text - text_start; } #endif @@ -897,18 +900,8 @@ long SDL_strtol(const char *string, char **endp, int base) #if defined(HAVE_STRTOL) return strtol(string, endp, base); #else - size_t len; long value = 0; - - if (!base) { - if ((SDL_strlen(string) > 2) && (SDL_strncmp(string, "0x", 2) == 0)) { - base = 16; - } else { - base = 10; - } - } - - len = SDL_ScanLong(string, 0, base, &value); + size_t len = SDL_ScanLong(string, 0, base, &value); if (endp) { *endp = (char *)string + len; } @@ -922,18 +915,8 @@ SDL_strtoul(const char *string, char **endp, int base) #if defined(HAVE_STRTOUL) return strtoul(string, endp, base); #else - size_t len; unsigned long value = 0; - - if (!base) { - if ((SDL_strlen(string) > 2) && (SDL_strncmp(string, "0x", 2) == 0)) { - base = 16; - } else { - base = 10; - } - } - - len = SDL_ScanUnsignedLong(string, 0, base, &value); + size_t len = SDL_ScanUnsignedLong(string, 0, base, &value); if (endp) { *endp = (char *)string + len; } @@ -946,18 +929,8 @@ Sint64 SDL_strtoll(const char *string, char **endp, int base) #if defined(HAVE_STRTOLL) return strtoll(string, endp, base); #else - size_t len; - Sint64 value = 0; - - if (!base) { - if ((SDL_strlen(string) > 2) && (SDL_strncmp(string, "0x", 2) == 0)) { - base = 16; - } else { - base = 10; - } - } - - len = SDL_ScanLongLong(string, 0, base, &value); + long long value = 0; + size_t len = SDL_ScanLongLong(string, 0, base, &value); if (endp) { *endp = (char *)string + len; } @@ -970,18 +943,8 @@ Uint64 SDL_strtoull(const char *string, char **endp, int base) #if defined(HAVE_STRTOULL) return strtoull(string, endp, base); #else - size_t len; - Uint64 value = 0; - - if (!base) { - if ((SDL_strlen(string) > 2) && (SDL_strncmp(string, "0x", 2) == 0)) { - base = 16; - } else { - base = 10; - } - } - - len = SDL_ScanUnsignedLongLong(string, 0, base, &value); + unsigned long long value = 0; + size_t len = SDL_ScanUnsignedLongLong(string, 0, base, &value); if (endp) { *endp = (char *)string + len; } diff --git a/src/test/SDL_test_fuzzer.c b/src/test/SDL_test_fuzzer.c index 45468f39703f7..15bef31c88dc8 100644 --- a/src/test/SDL_test_fuzzer.c +++ b/src/test/SDL_test_fuzzer.c @@ -153,21 +153,22 @@ Sint32 SDLTest_RandomIntegerInRange(Sint32 pMin, Sint32 pMax) { Sint64 min = pMin; Sint64 max = pMax; - Sint64 temp; - Sint64 number; + Uint64 range; if (pMin > pMax) { - temp = min; - min = max; - max = temp; + min = pMax; + max = pMin; } else if (pMin == pMax) { return (Sint32)min; } - number = SDLTest_RandomUint32(); - /* invocation count increment in preceeding call */ - - return (Sint32)((number % ((max + 1) - min)) + min); + range = (Sint64)max - (Sint64)min; + if (range < SDL_MAX_SINT32) { + return (Sint32) (min + (Sint32) (SDLTest_RandomUint32() % (range + 1))); + } else { + const Uint64 add = SDLTest_RandomUint32() | SDLTest_RandomUint32(); + return (Sint32) (min + (Sint64) (add % (range + 1))); + } } /* ! diff --git a/src/test/SDL_test_memory.c b/src/test/SDL_test_memory.c index 723bd4b567eac..066c64f666f87 100644 --- a/src/test/SDL_test_memory.c +++ b/src/test/SDL_test_memory.c @@ -20,6 +20,8 @@ */ #include "SDL_config.h" #include "SDL_assert.h" +#include "SDL_atomic.h" +#include "SDL_loadso.h" #include "SDL_stdinc.h" #include "SDL_log.h" #include "SDL_test_crc32.h" @@ -28,6 +30,31 @@ #ifdef HAVE_LIBUNWIND_H #define UNW_LOCAL_ONLY #include +#ifndef unw_get_proc_name_by_ip +#define SDLTEST_UNWIND_NO_PROC_NAME_BY_IP +static SDL_bool s_unwind_symbol_names = SDL_TRUE; +#endif +#endif + +#if defined(__WIN32__) && !defined(__WATCOMC__) +#define WIN32_WITH_DBGHELP +#endif + +#ifdef WIN32_WITH_DBGHELP +#include +#include + +static struct { + HMODULE module; + BOOL (WINAPI *pSymInitialize)(HANDLE hProcess, PCSTR UserSearchPath, BOOL fInvadeProcess); + BOOL (WINAPI *pSymFromAddr)(HANDLE hProcess, DWORD64 Address, PDWORD64 Displacement, PSYMBOL_INFO Symbol); + BOOL (WINAPI *pSymGetLineFromAddr64)(HANDLE hProcess, DWORD64 qwAddr, PDWORD pdwDisplacement, PIMAGEHLP_LINE64 Line); +} dyn_dbghelp; + +/* older SDKs might not have this: */ +__declspec(dllimport) USHORT WINAPI RtlCaptureStackBackTrace(ULONG FramesToSkip, ULONG FramesToCapture, PVOID* BackTrace, PULONG BackTraceHash); +#define CaptureStackBackTrace RtlCaptureStackBackTrace + #endif /* This is a simple tracking allocator to demonstrate the use of SDL's @@ -37,13 +64,17 @@ for production code. */ +#define MAXIMUM_TRACKED_STACK_DEPTH 16 + typedef struct SDL_tracked_allocation { void *mem; size_t size; - Uint64 stack[10]; - char stack_names[10][256]; + Uint64 stack[MAXIMUM_TRACKED_STACK_DEPTH]; struct SDL_tracked_allocation *next; +#ifdef SDLTEST_UNWIND_NO_PROC_NAME_BY_IP + char stack_names[MAXIMUM_TRACKED_STACK_DEPTH][256]; +#endif } SDL_tracked_allocation; static SDLTest_Crc32Context s_crc32_context; @@ -53,6 +84,16 @@ static SDL_realloc_func SDL_realloc_orig = NULL; static SDL_free_func SDL_free_orig = NULL; static int s_previous_allocations = 0; static SDL_tracked_allocation *s_tracked_allocations[256]; +static SDL_atomic_t s_lock; + +#define LOCK_ALLOCATOR() \ + do { \ + if (SDL_AtomicCAS(&s_lock, 0, 1)) { \ + break; \ + } \ + SDL_CPUPauseInstruction(); \ + } while (SDL_TRUE) +#define UNLOCK_ALLOCATOR() do { SDL_AtomicSet(&s_lock, 0); } while (0) static unsigned int get_allocation_bucket(void *mem) { @@ -66,12 +107,17 @@ static unsigned int get_allocation_bucket(void *mem) static SDL_bool SDL_IsAllocationTracked(void *mem) { SDL_tracked_allocation *entry; - int index = get_allocation_bucket(mem); + int index; + + LOCK_ALLOCATOR(); + index = get_allocation_bucket(mem); for (entry = s_tracked_allocations[index]; entry; entry = entry->next) { if (mem == entry->mem) { + UNLOCK_ALLOCATOR(); return SDL_TRUE; } } + UNLOCK_ALLOCATOR(); return SDL_FALSE; } @@ -83,8 +129,10 @@ static void SDL_TrackAllocation(void *mem, size_t size) if (SDL_IsAllocationTracked(mem)) { return; } + LOCK_ALLOCATOR(); entry = (SDL_tracked_allocation *)SDL_malloc_orig(sizeof(*entry)); if (!entry) { + UNLOCK_ALLOCATOR(); return; } entry->mem = mem; @@ -103,15 +151,20 @@ static void SDL_TrackAllocation(void *mem, size_t size) stack_index = 0; while (unw_step(&cursor) > 0) { - unw_word_t offset, pc; + unw_word_t pc; +#ifdef SDLTEST_UNWIND_NO_PROC_NAME_BY_IP + unw_word_t offset; char sym[236]; +#endif unw_get_reg(&cursor, UNW_REG_IP, &pc); entry->stack[stack_index] = pc; - if (unw_get_proc_name(&cursor, sym, sizeof(sym), &offset) == 0) { +#ifdef SDLTEST_UNWIND_NO_PROC_NAME_BY_IP + if (s_unwind_symbol_names && unw_get_proc_name(&cursor, sym, sizeof(sym), &offset) == 0) { SDL_snprintf(entry->stack_names[stack_index], sizeof(entry->stack_names[stack_index]), "%s+0x%llx", sym, (unsigned long long)offset); } +#endif ++stack_index; if (stack_index == SDL_arraysize(entry->stack)) { @@ -119,10 +172,24 @@ static void SDL_TrackAllocation(void *mem, size_t size) } } } +#elif defined(WIN32_WITH_DBGHELP) + { + Uint32 count; + PVOID frames[63]; + Uint32 i; + + count = CaptureStackBackTrace(1, SDL_arraysize(frames), frames, NULL); + + count = SDL_min(count, MAXIMUM_TRACKED_STACK_DEPTH); + for (i = 0; i < count; i++) { + entry->stack[i] = (Uint64)(uintptr_t)frames[i]; + } + } #endif /* HAVE_LIBUNWIND_H */ entry->next = s_tracked_allocations[index]; s_tracked_allocations[index] = entry; + UNLOCK_ALLOCATOR(); } static void SDL_UntrackAllocation(void *mem) @@ -130,6 +197,7 @@ static void SDL_UntrackAllocation(void *mem) SDL_tracked_allocation *entry, *prev; int index = get_allocation_bucket(mem); + LOCK_ALLOCATOR(); prev = NULL; for (entry = s_tracked_allocations[index]; entry; entry = entry->next) { if (mem == entry->mem) { @@ -139,10 +207,12 @@ static void SDL_UntrackAllocation(void *mem) s_tracked_allocations[index] = entry->next; } SDL_free_orig(entry); + UNLOCK_ALLOCATOR(); return; } prev = entry; } + UNLOCK_ALLOCATOR(); } static void *SDLCALL SDLTest_TrackedMalloc(size_t size) @@ -207,6 +277,41 @@ int SDLTest_TrackAllocations(void) if (s_previous_allocations != 0) { SDL_Log("SDLTest_TrackAllocations(): There are %d previous allocations, disabling free() validation", s_previous_allocations); } +#ifdef SDLTEST_UNWIND_NO_PROC_NAME_BY_IP + do { + /* Don't use SDL_GetHint: SDL_malloc is off limits. */ + const char *env_trackmem = SDL_getenv("SDL_TRACKMEM_SYMBOL_NAMES"); + if (env_trackmem) { + if (SDL_strcasecmp(env_trackmem, "1") == 0 || SDL_strcasecmp(env_trackmem, "yes") == 0 || SDL_strcasecmp(env_trackmem, "true") == 0) { + s_unwind_symbol_names = SDL_TRUE; + } else if (SDL_strcasecmp(env_trackmem, "0") == 0 || SDL_strcasecmp(env_trackmem, "no") == 0 || SDL_strcasecmp(env_trackmem, "false") == 0) { + s_unwind_symbol_names = SDL_FALSE; + } + } + } while (0); +#elif defined(WIN32_WITH_DBGHELP) + do { + dyn_dbghelp.module = SDL_LoadObject("dbghelp.dll"); + if (!dyn_dbghelp.module) { + goto dbghelp_failed; + } + dyn_dbghelp.pSymInitialize = (void *)SDL_LoadFunction(dyn_dbghelp.module, "SymInitialize"); + dyn_dbghelp.pSymFromAddr = (void *)SDL_LoadFunction(dyn_dbghelp.module, "SymFromAddr"); + dyn_dbghelp.pSymGetLineFromAddr64 = (void *)SDL_LoadFunction(dyn_dbghelp.module, "SymGetLineFromAddr64"); + if (!dyn_dbghelp.pSymInitialize || !dyn_dbghelp.pSymFromAddr || !dyn_dbghelp.pSymGetLineFromAddr64) { + goto dbghelp_failed; + } + if (!dyn_dbghelp.pSymInitialize(GetCurrentProcess(), NULL, TRUE)) { + goto dbghelp_failed; + } + break; + dbghelp_failed: + if (dyn_dbghelp.module) { + SDL_UnloadObject(dyn_dbghelp.module); + dyn_dbghelp.module = NULL; + } + } while (0); +#endif SDL_GetMemoryFunctions(&SDL_malloc_orig, &SDL_calloc_orig, @@ -224,7 +329,7 @@ void SDLTest_LogAllocations(void) { char *message = NULL; size_t message_size = 0; - char line[128], *tmp; + char line[256], *tmp; SDL_tracked_allocation *entry; int index, count, stack_index; Uint64 total_allocated; @@ -261,10 +366,48 @@ void SDLTest_LogAllocations(void) ADD_LINE(); /* Start at stack index 1 to skip our tracking functions */ for (stack_index = 1; stack_index < SDL_arraysize(entry->stack); ++stack_index) { + char stack_entry_description[256] = "???"; if (!entry->stack[stack_index]) { break; } - (void)SDL_snprintf(line, sizeof(line), "\t0x%" SDL_PRIx64 ": %s\n", entry->stack[stack_index], entry->stack_names[stack_index]); +#ifdef HAVE_LIBUNWIND_H + { +#ifdef SDLTEST_UNWIND_NO_PROC_NAME_BY_IP + if (s_unwind_symbol_names) { + (void)SDL_snprintf(stack_entry_description, sizeof(stack_entry_description), "%s", entry->stack_names[stack_index]); + } +#else + char name[256] = "???"; + unw_word_t offset = 0; + unw_get_proc_name_by_ip(unw_local_addr_space, entry->stack[stack_index], name, sizeof(name), &offset, NULL); + (void)SDL_snprintf(stack_entry_description, sizeof(stack_entry_description), "%s+0x%llx", name, (long long unsigned int)offset); +#endif + } +#elif defined(WIN32_WITH_DBGHELP) + { + DWORD64 dwDisplacement = 0; + IMAGEHLP_LINE64 dbg_line; + char symbol_buffer[sizeof(SYMBOL_INFO) + MAX_SYM_NAME * sizeof(TCHAR)]; + PSYMBOL_INFO pSymbol = (PSYMBOL_INFO)symbol_buffer; + DWORD lineColumn = 0; + pSymbol->SizeOfStruct = sizeof(SYMBOL_INFO); + pSymbol->MaxNameLen = MAX_SYM_NAME; + dbg_line.SizeOfStruct = sizeof(dbg_line); + dbg_line.FileName = ""; + dbg_line.LineNumber = 0; + + if (dyn_dbghelp.module) { + if (!dyn_dbghelp.pSymFromAddr(GetCurrentProcess(), entry->stack[stack_index], &dwDisplacement, pSymbol)) { + SDL_strlcpy(pSymbol->Name, "???", MAX_SYM_NAME); + dwDisplacement = 0; + } + dyn_dbghelp.pSymGetLineFromAddr64(GetCurrentProcess(), (DWORD64)entry->stack[stack_index], &lineColumn, &dbg_line); + } + SDL_snprintf(stack_entry_description, sizeof(stack_entry_description), "%s+0x%I64x %s:%u", pSymbol->Name, dwDisplacement, dbg_line.FileName, (Uint32)dbg_line.LineNumber); + } +#endif + (void)SDL_snprintf(line, sizeof(line), "\t0x%" SDL_PRIx64 ": %s\n", entry->stack[stack_index], stack_entry_description); + ADD_LINE(); } total_allocated += entry->size; diff --git a/src/thread/SDL_thread.c b/src/thread/SDL_thread.c index 3d111198fb570..8ff094072a63e 100644 --- a/src/thread/SDL_thread.c +++ b/src/thread/SDL_thread.c @@ -54,7 +54,7 @@ void *SDL_TLSGet(SDL_TLSID id) return storage->array[id - 1].data; } -int SDL_TLSSet(SDL_TLSID id, const void *value, void(SDLCALL *destructor)(void *)) +int SDL_TLSSet(SDL_TLSID id, const void *value, SDL_TLSDestructorCallback destructor) { SDL_TLSData *storage; diff --git a/src/thread/n3ds/SDL_syscond.c b/src/thread/n3ds/SDL_syscond.c deleted file mode 100644 index 808def3dd8a25..0000000000000 --- a/src/thread/n3ds/SDL_syscond.c +++ /dev/null @@ -1,127 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ -#include "../../SDL_internal.h" - -#ifdef SDL_THREAD_N3DS - -/* An implementation of condition variables using libctru's CondVar */ - -#include "SDL_sysmutex_c.h" - -struct SDL_cond -{ - CondVar cond_variable; -}; - -/* Create a condition variable */ -SDL_cond *SDL_CreateCond(void) -{ - SDL_cond *cond = (SDL_cond *)SDL_malloc(sizeof(SDL_cond)); - if (cond) { - CondVar_Init(&cond->cond_variable); - } else { - SDL_OutOfMemory(); - } - return cond; -} - -/* Destroy a condition variable */ -void SDL_DestroyCond(SDL_cond *cond) -{ - if (cond) { - SDL_free(cond); - } -} - -/* Restart one of the threads that are waiting on the condition variable */ -int SDL_CondSignal(SDL_cond *cond) -{ - if (!cond) { - return SDL_InvalidParamError("cond"); - } - - CondVar_Signal(&cond->cond_variable); - return 0; -} - -/* Restart all threads that are waiting on the condition variable */ -int SDL_CondBroadcast(SDL_cond *cond) -{ - if (!cond) { - return SDL_InvalidParamError("cond"); - } - - CondVar_Broadcast(&cond->cond_variable); - return 0; -} - -/* Wait on the condition variable for at most 'ms' milliseconds. - The mutex must be locked before entering this function! - The mutex is unlocked during the wait, and locked again after the wait. - -Typical use: - -Thread A: - SDL_LockMutex(lock); - while ( ! condition ) { - SDL_CondWait(cond, lock); - } - SDL_UnlockMutex(lock); - -Thread B: - SDL_LockMutex(lock); - ... - condition = true; - ... - SDL_CondSignal(cond); - SDL_UnlockMutex(lock); - */ -int SDL_CondWaitTimeout(SDL_cond *cond, SDL_mutex *mutex, Uint32 ms) -{ - Result res; - - if (!cond) { - return SDL_InvalidParamError("cond"); - } - if (!mutex) { - return SDL_InvalidParamError("mutex"); - } - - res = 0; - if (ms == SDL_MUTEX_MAXWAIT) { - CondVar_Wait(&cond->cond_variable, &mutex->lock.lock); - } else { - res = CondVar_WaitTimeout(&cond->cond_variable, &mutex->lock.lock, - (s64)ms * 1000000LL); - } - - return R_SUCCEEDED(res) ? 0 : SDL_MUTEX_TIMEDOUT; -} - -/* Wait on the condition variable forever */ -int SDL_CondWait(SDL_cond *cond, SDL_mutex *mutex) -{ - return SDL_CondWaitTimeout(cond, mutex, SDL_MUTEX_MAXWAIT); -} - -#endif /* SDL_THREAD_N3DS */ - -/* vi: set sts=4 ts=4 sw=4 expandtab: */ diff --git a/src/timer/ps2/SDL_systimer.c b/src/timer/ps2/SDL_systimer.c index cc8040d7d5016..0b0cf1a904c31 100644 --- a/src/timer/ps2/SDL_systimer.c +++ b/src/timer/ps2/SDL_systimer.c @@ -34,6 +34,8 @@ static uint64_t start; static SDL_bool ticks_started = SDL_FALSE; +static Uint64 BUSCLK_MS = (kBUSCLK / 1000); + void SDL_TicksInit(void) { if (ticks_started) { @@ -58,7 +60,7 @@ Uint64 SDL_GetTicks64(void) } now = GetTimerSystemTime(); - return (Uint64)((now - start) / (kBUSCLK / CLOCKS_PER_SEC)); + return (Uint64)((now - start) / BUSCLK_MS); } Uint64 SDL_GetPerformanceCounter(void) diff --git a/src/timer/psp/SDL_systimer.c b/src/timer/psp/SDL_systimer.c index cfed572a1a94d..def21f8b565d5 100644 --- a/src/timer/psp/SDL_systimer.c +++ b/src/timer/psp/SDL_systimer.c @@ -30,45 +30,42 @@ #include #include #include +#include -static struct timeval start; -static SDL_bool ticks_started = SDL_FALSE; +static Uint64 start_tick; + +static Uint64 PSP_Ticks(void) +{ + Uint64 ticks; + sceRtcGetCurrentTick(&ticks); + return ticks; +} void SDL_TicksInit(void) { - if (ticks_started) { - return; + if (start_tick == 0) { + start_tick = PSP_Ticks(); } - ticks_started = SDL_TRUE; - - gettimeofday(&start, NULL); } void SDL_TicksQuit(void) { - ticks_started = SDL_FALSE; } +/* return ticks as milliseconds */ Uint64 SDL_GetTicks64(void) { - struct timeval now; - - if (!ticks_started) { - SDL_TicksInit(); - } - - gettimeofday(&now, NULL); - return (Uint64)(((Sint64)(now.tv_sec - start.tv_sec) * 1000) + ((now.tv_usec - start.tv_usec) / 1000)); + return (PSP_Ticks() - start_tick) / 1000ULL; } Uint64 SDL_GetPerformanceCounter(void) { - return SDL_GetTicks64(); + return PSP_Ticks(); } Uint64 SDL_GetPerformanceFrequency(void) { - return 1000; + return sceRtcGetTickResolution(); } void SDL_Delay(Uint32 ms) diff --git a/src/video/SDL_blit.h b/src/video/SDL_blit.h index 24944034c5797..563f00c628d1a 100644 --- a/src/video/SDL_blit.h +++ b/src/video/SDL_blit.h @@ -471,6 +471,15 @@ extern SDL_BlitFunc SDL_CalculateBlitA(SDL_Surface *surface); #else #define USE_DUFFS_LOOP #endif + +#define DUFFS_LOOP1(pixel_copy_increment, width) \ + { \ + int n; \ + for (n = width; n > 0; --n) { \ + pixel_copy_increment; \ + } \ + } + #ifdef USE_DUFFS_LOOP /* 8-times unrolled loop */ @@ -527,8 +536,26 @@ extern SDL_BlitFunc SDL_CalculateBlitA(SDL_Surface *surface); } \ } -/* Use the 8-times version of the loop by default */ +/* 2-times unrolled loop */ +#define DUFFS_LOOP2(pixel_copy_increment, width) \ + { \ + int n = (width + 1) / 2; \ + switch (width & 1) { \ + case 0: \ + do { \ + pixel_copy_increment; \ + SDL_FALLTHROUGH; \ + case 1: \ + pixel_copy_increment; \ + } while (--n > 0); \ + } \ + } + +/* Use the 4-times version of the loop by default */ #define DUFFS_LOOP(pixel_copy_increment, width) \ + DUFFS_LOOP4(pixel_copy_increment, width) +/* Use the 8-times version of the loop for simple routines */ +#define DUFFS_LOOP_TRIVIAL(pixel_copy_increment, width) \ DUFFS_LOOP8(pixel_copy_increment, width) /* Special version of Duff's device for even more optimization */ @@ -562,20 +589,19 @@ extern SDL_BlitFunc SDL_CalculateBlitA(SDL_Surface *surface); /* Don't use Duff's device to unroll loops */ #define DUFFS_LOOP(pixel_copy_increment, width) \ - { \ - int n; \ - for (n = width; n > 0; --n) { \ - pixel_copy_increment; \ - } \ - } + DUFFS_LOOP1(pixel_copy_increment, width) +#define DUFFS_LOOP_TRIVIAL(pixel_copy_increment, width) \ + DUFFS_LOOP1(pixel_copy_increment, width) #define DUFFS_LOOP8(pixel_copy_increment, width) \ - DUFFS_LOOP(pixel_copy_increment, width) + DUFFS_LOOP1(pixel_copy_increment, width) #define DUFFS_LOOP4(pixel_copy_increment, width) \ - DUFFS_LOOP(pixel_copy_increment, width) + DUFFS_LOOP1(pixel_copy_increment, width) +#define DUFFS_LOOP2(pixel_copy_increment, width) \ + DUFFS_LOOP1(pixel_copy_increment, width) #define DUFFS_LOOP_124(pixel_copy_increment1, \ pixel_copy_increment2, \ pixel_copy_increment4, width) \ - DUFFS_LOOP(pixel_copy_increment1, width) + DUFFS_LOOP1(pixel_copy_increment1, width) #endif /* USE_DUFFS_LOOP */ diff --git a/src/video/SDL_blit_1.c b/src/video/SDL_blit_1.c index 000fae77ca097..6e59b5030ac17 100644 --- a/src/video/SDL_blit_1.c +++ b/src/video/SDL_blit_1.c @@ -50,7 +50,7 @@ static void Blit1to1(SDL_BlitInfo *info) while (height--) { #ifdef USE_DUFFS_LOOP /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP( + DUFFS_LOOP_TRIVIAL( { *dst = map[*src]; } @@ -102,7 +102,7 @@ static void Blit1to2(SDL_BlitInfo *info) #ifdef USE_DUFFS_LOOP while (height--) { /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP( + DUFFS_LOOP_TRIVIAL( { *(Uint16 *)dst = map[*src++]; dst += 2; @@ -258,7 +258,7 @@ static void Blit1to4(SDL_BlitInfo *info) while (height--) { #ifdef USE_DUFFS_LOOP /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP( + DUFFS_LOOP_TRIVIAL( *dst++ = map[*src++]; , width); /* *INDENT-ON* */ /* clang-format on */ @@ -299,7 +299,7 @@ static void Blit1to1Key(SDL_BlitInfo *info) if (palmap) { while (height--) { /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP( + DUFFS_LOOP_TRIVIAL( { if ( *src != ckey ) { *dst = palmap[*src]; @@ -315,7 +315,7 @@ static void Blit1to1Key(SDL_BlitInfo *info) } else { while (height--) { /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP( + DUFFS_LOOP_TRIVIAL( { if ( *src != ckey ) { *dst = *src; @@ -347,7 +347,7 @@ static void Blit1to2Key(SDL_BlitInfo *info) while (height--) { /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP( + DUFFS_LOOP_TRIVIAL( { if ( *src != ckey ) { *dstp=palmap[*src]; @@ -410,7 +410,7 @@ static void Blit1to4Key(SDL_BlitInfo *info) while (height--) { /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP( + DUFFS_LOOP_TRIVIAL( { if ( *src != ckey ) { *dstp = palmap[*src]; @@ -446,7 +446,7 @@ static void Blit1toNAlpha(SDL_BlitInfo *info) while (height--) { /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP4( + DUFFS_LOOP( { sR = srcpal[*src].r; sG = srcpal[*src].g; diff --git a/src/video/SDL_blit_A.c b/src/video/SDL_blit_A.c index 3c990788d9bcd..9f1716c0db810 100644 --- a/src/video/SDL_blit_A.c +++ b/src/video/SDL_blit_A.c @@ -47,7 +47,7 @@ static void BlitNto1SurfaceAlpha(SDL_BlitInfo *info) while (height--) { /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP4( + DUFFS_LOOP( { DISEMBLE_RGB(src, srcbpp, srcfmt, Pixel, sR, sG, sB); dR = dstfmt->palette->colors[*dst].r; @@ -92,7 +92,7 @@ static void BlitNto1PixelAlpha(SDL_BlitInfo *info) while (height--) { /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP4( + DUFFS_LOOP( { DISEMBLE_RGBA(src,srcbpp,srcfmt,Pixel,sR,sG,sB,sA); dR = dstfmt->palette->colors[*dst].r; @@ -484,7 +484,7 @@ static void BlitRGBtoRGBSurfaceAlpha128(SDL_BlitInfo *info) while (height--) { /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP4({ + DUFFS_LOOP({ Uint32 s = *srcp++; Uint32 d = *dstp; *dstp++ = ((((s & 0x00fefefe) + (d & 0x00fefefe)) >> 1) @@ -516,7 +516,7 @@ static void BlitRGBtoRGBSurfaceAlpha(SDL_BlitInfo *info) while (height--) { /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP4({ + DUFFS_LOOP({ s = *srcp; d = *dstp; s1 = s & 0xff00ff; @@ -1148,7 +1148,7 @@ static void Blit565to565SurfaceAlpha(SDL_BlitInfo *info) while (height--) { /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP4({ + DUFFS_LOOP({ Uint32 s = *srcp++; Uint32 d = *dstp; /* @@ -1186,7 +1186,7 @@ static void Blit555to555SurfaceAlpha(SDL_BlitInfo *info) while (height--) { /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP4({ + DUFFS_LOOP({ Uint32 s = *srcp++; Uint32 d = *dstp; /* @@ -1219,7 +1219,7 @@ static void BlitARGBto565PixelAlpha(SDL_BlitInfo *info) while (height--) { /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP4({ + DUFFS_LOOP({ Uint32 s = *srcp; unsigned alpha = s >> 27; /* downscale alpha to 5 bits */ /* Here we special-case opaque alpha since the @@ -1262,7 +1262,7 @@ static void BlitARGBto555PixelAlpha(SDL_BlitInfo *info) while (height--) { /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP4({ + DUFFS_LOOP({ unsigned alpha; Uint32 s = *srcp; alpha = s >> 27; /* downscale alpha to 5 bits */ @@ -1315,7 +1315,7 @@ static void BlitNtoNSurfaceAlpha(SDL_BlitInfo *info) if (sA) { while (height--) { /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP4( + DUFFS_LOOP( { DISEMBLE_RGB(src, srcbpp, srcfmt, Pixel, sR, sG, sB); DISEMBLE_RGBA(dst, dstbpp, dstfmt, Pixel, dR, dG, dB, dA); @@ -1353,7 +1353,7 @@ static void BlitNtoNSurfaceAlphaKey(SDL_BlitInfo *info) while (height--) { /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP4( + DUFFS_LOOP( { RETRIEVE_RGB_PIXEL(src, srcbpp, Pixel); if (sA && Pixel != ckey) { @@ -1395,7 +1395,7 @@ static void BlitNtoNPixelAlpha(SDL_BlitInfo *info) while (height--) { /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP4( + DUFFS_LOOP( { DISEMBLE_RGBA(src, srcbpp, srcfmt, Pixel, sR, sG, sB, sA); if (sA) { diff --git a/src/video/SDL_blit_N.c b/src/video/SDL_blit_N.c index 01ba0c4349e57..41161d57d370d 100644 --- a/src/video/SDL_blit_N.c +++ b/src/video/SDL_blit_N.c @@ -2076,7 +2076,7 @@ static void Blit_RGB555_ARGB1555(SDL_BlitInfo *info) while (height--) { /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP( + DUFFS_LOOP_TRIVIAL( { *dst = *src | mask; ++dst; @@ -2200,7 +2200,7 @@ static void Blit4to4MaskAlpha(SDL_BlitInfo *info) while (height--) { /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP( + DUFFS_LOOP_TRIVIAL( { *dst = *src | mask; ++dst; @@ -2217,7 +2217,7 @@ static void Blit4to4MaskAlpha(SDL_BlitInfo *info) while (height--) { /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP( + DUFFS_LOOP_TRIVIAL( { *dst = *src & mask; ++dst; @@ -2576,7 +2576,7 @@ static void Blit2to2Key(SDL_BlitInfo *info) while (height--) { /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP( + DUFFS_LOOP_TRIVIAL( { if ( (*srcp & rgbmask) != ckey ) { *dstp = *srcp; @@ -2622,7 +2622,7 @@ static void BlitNtoNKey(SDL_BlitInfo *info) Uint32 mask = ((Uint32)info->a) << dstfmt->Ashift; while (height--) { /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP( + DUFFS_LOOP_TRIVIAL( { if ((*src32 & rgbmask) != ckey) { *dst32 = *src32 | mask; @@ -2640,7 +2640,7 @@ static void BlitNtoNKey(SDL_BlitInfo *info) Uint32 mask = srcfmt->Rmask | srcfmt->Gmask | srcfmt->Bmask; while (height--) { /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP( + DUFFS_LOOP_TRIVIAL( { if ((*src32 & rgbmask) != ckey) { *dst32 = *src32 & mask; @@ -2897,7 +2897,7 @@ static void BlitNtoNKeyCopyAlpha(SDL_BlitInfo *info) Uint32 *dst32 = (Uint32 *)dst; while (height--) { /* *INDENT-OFF* */ /* clang-format off */ - DUFFS_LOOP( + DUFFS_LOOP_TRIVIAL( { if ((*src32 & rgbmask) != ckey) { *dst32 = *src32; diff --git a/src/video/SDL_sysvideo.h b/src/video/SDL_sysvideo.h index 258d2afe5eef0..22bca8a222c92 100644 --- a/src/video/SDL_sysvideo.h +++ b/src/video/SDL_sysvideo.h @@ -155,6 +155,7 @@ typedef enum { VIDEO_DEVICE_QUIRK_DISABLE_DISPLAY_MODE_SWITCHING = 0x01, VIDEO_DEVICE_QUIRK_DISABLE_UNSET_FULLSCREEN_ON_MINIMIZE = 0x02, + VIDEO_DEVICE_QUIRK_FULLSCREEN_ONLY = 0x04, } DeviceQuirkFlags; struct SDL_VideoDevice diff --git a/src/video/SDL_video.c b/src/video/SDL_video.c index e20c702cda2f3..01023753c6e49 100644 --- a/src/video/SDL_video.c +++ b/src/video/SDL_video.c @@ -34,6 +34,8 @@ #include "SDL_syswm.h" +#include "../render/SDL_sysrender.h" + #ifdef SDL_VIDEO_OPENGL #include "SDL_opengl.h" #endif /* SDL_VIDEO_OPENGL */ @@ -192,6 +194,11 @@ static SDL_bool DisableUnsetFullscreenOnMinimize(_THIS) return !!(_this->quirk_flags & VIDEO_DEVICE_QUIRK_DISABLE_UNSET_FULLSCREEN_ON_MINIMIZE); } +static SDL_bool IsFullscreenOnly(_THIS) +{ + return !!(_this->quirk_flags & VIDEO_DEVICE_QUIRK_FULLSCREEN_ONLY); +} + /* Support for framebuffer emulation using an accelerated renderer */ #define SDL_WINDOWTEXTUREDATA "_SDL_WindowTextureData" @@ -577,7 +584,7 @@ int SDL_VideoInit(const char *driver_name) SDL_DisableScreenSaver(); } -#if !defined(SDL_VIDEO_DRIVER_N3DS) +#if !defined(SDL_VIDEO_DRIVER_N3DS) && !defined(SDL_VIDEO_DRIVER_PSP) /* In the initial state we don't want to pop up an on-screen keyboard, * but we do want to allow text input from other mechanisms. */ @@ -591,7 +598,7 @@ int SDL_VideoInit(const char *driver_name) SDL_SetHint(SDL_HINT_ENABLE_SCREEN_KEYBOARD, NULL); } } -#endif /* !SDL_VIDEO_DRIVER_N3DS */ +#endif /* !SDL_VIDEO_DRIVER_N3DS && !SDL_VIDEO_DRIVER_PSP */ SDL_MousePostInit(); @@ -1006,7 +1013,7 @@ static SDL_DisplayMode *SDL_GetClosestDisplayModeForDisplay(SDL_VideoDisplay *di match = current; continue; } - if (current->format != match->format) { + if (current->format != match->format && match->format != target_format) { /* Sorted highest depth to lowest */ if (current->format == target_format || (SDL_BITSPERPIXEL(current->format) >= @@ -1017,7 +1024,7 @@ static SDL_DisplayMode *SDL_GetClosestDisplayModeForDisplay(SDL_VideoDisplay *di } continue; } - if (current->refresh_rate != match->refresh_rate) { + if (current->refresh_rate != match->refresh_rate && match->refresh_rate != target_refresh_rate) { /* Sorted highest refresh to lowest */ if (current->refresh_rate >= target_refresh_rate) { match = current; @@ -1769,7 +1776,7 @@ SDL_Window *SDL_CreateWindow(const char *title, int x, int y, int w, int h, Uint window->windowed.w = window->w; window->windowed.h = window->h; - if (flags & SDL_WINDOW_FULLSCREEN) { + if (flags & SDL_WINDOW_FULLSCREEN || IsFullscreenOnly(_this)) { SDL_VideoDisplay *display = SDL_GetDisplayForWindow(window); int displayIndex; SDL_Rect bounds; @@ -1796,6 +1803,7 @@ SDL_Window *SDL_CreateWindow(const char *title, int x, int y, int w, int h, Uint window->y = bounds.y; window->w = bounds.w; window->h = bounds.h; + flags |= SDL_WINDOW_FULLSCREEN; } window->flags = ((flags & CREATE_FLAGS) | SDL_WINDOW_HIDDEN); @@ -3301,6 +3309,7 @@ SDL_Window *SDL_GetFocusWindow(void) void SDL_DestroyWindow(SDL_Window *window) { SDL_VideoDisplay *display; + SDL_Renderer *renderer; CHECK_WINDOW_MAGIC(window, ); @@ -3322,6 +3331,11 @@ void SDL_DestroyWindow(SDL_Window *window) SDL_SetMouseFocus(NULL); } + renderer = SDL_GetRenderer(window); + if (renderer) { + SDL_DestroyRendererWithoutFreeing(renderer); + } + SDL_DestroyWindowSurface(window); /* Make no context current if this is the current context window */ diff --git a/src/video/emscripten/SDL_emscriptenevents.c b/src/video/emscripten/SDL_emscriptenevents.c index 07ac87c814b76..9957c1a361fb2 100644 --- a/src/video/emscripten/SDL_emscriptenevents.c +++ b/src/video/emscripten/SDL_emscriptenevents.c @@ -812,7 +812,7 @@ static EM_BOOL Emscripten_HandleKey(int eventType, const EmscriptenKeyboardEvent { const SDL_Keycode keycode = Emscripten_MapKeyCode(keyEvent); SDL_Scancode scancode = Emscripten_MapScanCode(keyEvent->code); - SDL_bool prevent_default = SDL_TRUE; + SDL_bool prevent_default = SDL_FALSE; SDL_bool is_nav_key = SDL_FALSE; if (scancode == SDL_SCANCODE_UNKNOWN) { @@ -825,7 +825,7 @@ static EM_BOOL Emscripten_HandleKey(int eventType, const EmscriptenKeyboardEvent } if (scancode != SDL_SCANCODE_UNKNOWN) { - SDL_SendKeyboardKeyAndKeycode(eventType == EMSCRIPTEN_EVENT_KEYDOWN ? SDL_PRESSED : SDL_RELEASED, scancode, keycode); + prevent_default = SDL_SendKeyboardKeyAndKeycode(eventType == EMSCRIPTEN_EVENT_KEYDOWN ? SDL_PRESSED : SDL_RELEASED, scancode, keycode); } /* if TEXTINPUT events are enabled we can't prevent keydown or we won't get keypress diff --git a/src/video/n3ds/SDL_n3dsevents.c b/src/video/n3ds/SDL_n3dsevents.c index 7d661c287dfd4..5c6b9ce050ed8 100644 --- a/src/video/n3ds/SDL_n3dsevents.c +++ b/src/video/n3ds/SDL_n3dsevents.c @@ -31,7 +31,7 @@ void N3DS_PumpEvents(_THIS) { hidScanInput(); - N3DS_PollTouch(); + N3DS_PollTouch(_this); if (!aptMainLoop()) { SDL_Event ev; diff --git a/src/video/n3ds/SDL_n3dsframebuffer.c b/src/video/n3ds/SDL_n3dsframebuffer.c index 16e9e45fb9276..d093b442275e8 100644 --- a/src/video/n3ds/SDL_n3dsframebuffer.c +++ b/src/video/n3ds/SDL_n3dsframebuffer.c @@ -33,9 +33,9 @@ typedef struct int width, height; } Dimensions; -SDL_FORCE_INLINE void FreePreviousWindowFramebuffer(SDL_Window *window); -SDL_FORCE_INLINE SDL_Surface *CreateNewWindowFramebuffer(SDL_Window *window); -SDL_FORCE_INLINE void CopyFramebuffertoN3DS(u32 *dest, const Dimensions dest_dim, const u32 *source, const Dimensions source_dim); +SDL_FORCE_INLINE void CopyFramebuffertoN3DS_16(u16 *dest, const Dimensions dest_dim, const u16 *source, const Dimensions source_dim); +SDL_FORCE_INLINE void CopyFramebuffertoN3DS_24(u8 *dest, const Dimensions dest_dim, const u8 *source, const Dimensions source_dim); +SDL_FORCE_INLINE void CopyFramebuffertoN3DS_32(u32 *dest, const Dimensions dest_dim, const u32 *source, const Dimensions source_dim); SDL_FORCE_INLINE int GetDestOffset(int x, int y, int dest_width); SDL_FORCE_INLINE int GetSourceOffset(int x, int y, int source_width); SDL_FORCE_INLINE void FlushN3DSBuffer(const void *buffer, u32 bufsize, gfxScreen_t screen); @@ -43,44 +43,32 @@ SDL_FORCE_INLINE void FlushN3DSBuffer(const void *buffer, u32 bufsize, gfxScreen int SDL_N3DS_CreateWindowFramebuffer(_THIS, SDL_Window *window, Uint32 *format, void **pixels, int *pitch) { SDL_Surface *framebuffer; + SDL_DisplayMode mode; + int w, h; - FreePreviousWindowFramebuffer(window); - framebuffer = CreateNewWindowFramebuffer(window); + SDL_N3DS_DestroyWindowFramebuffer(_this, window); + + SDL_GetCurrentDisplayMode(SDL_GetWindowDisplayIndex(window), &mode); + SDL_GetWindowSizeInPixels(window, &w, &h); + framebuffer = SDL_CreateRGBSurfaceWithFormat(0, w, h, SDL_BYTESPERPIXEL(mode.format), mode.format); if (!framebuffer) { return SDL_OutOfMemory(); } SDL_SetWindowData(window, N3DS_SURFACE, framebuffer); - *format = FRAMEBUFFER_FORMAT; + *format = mode.format; *pixels = framebuffer->pixels; *pitch = framebuffer->pitch; return 0; } -SDL_FORCE_INLINE void -FreePreviousWindowFramebuffer(SDL_Window *window) -{ - SDL_Surface *surface = (SDL_Surface *)SDL_GetWindowData(window, N3DS_SURFACE); - SDL_FreeSurface(surface); -} - -SDL_FORCE_INLINE SDL_Surface * -CreateNewWindowFramebuffer(SDL_Window *window) -{ - int w, h, bpp; - Uint32 Rmask, Gmask, Bmask, Amask; - SDL_PixelFormatEnumToMasks(FRAMEBUFFER_FORMAT, &bpp, &Rmask, &Gmask, &Bmask, &Amask); - SDL_GetWindowSizeInPixels(window, &w, &h); - return SDL_CreateRGBSurface(0, w, h, bpp, Rmask, Gmask, Bmask, Amask); -} - int SDL_N3DS_UpdateWindowFramebuffer(_THIS, SDL_Window *window, const SDL_Rect *rects, int numrects) { SDL_WindowData *drv_data = (SDL_WindowData *)window->driverdata; SDL_Surface *surface; u16 width, height; - u32 *framebuffer; + void *framebuffer; u32 bufsize; surface = (SDL_Surface *)SDL_GetWindowData(window, N3DS_SURFACE); @@ -89,27 +77,63 @@ int SDL_N3DS_UpdateWindowFramebuffer(_THIS, SDL_Window *window, const SDL_Rect * } /* Get the N3DS internal framebuffer and its size */ - framebuffer = (u32 *)gfxGetFramebuffer(drv_data->screen, GFX_LEFT, &width, &height); + framebuffer = gfxGetFramebuffer(drv_data->screen, GFX_LEFT, &width, &height); bufsize = width * height * 4; - CopyFramebuffertoN3DS(framebuffer, (Dimensions){ width, height }, - surface->pixels, (Dimensions){ surface->w, surface->h }); + if (surface->format->BytesPerPixel == 2) + CopyFramebuffertoN3DS_16(framebuffer, (Dimensions){ width, height }, + surface->pixels, (Dimensions){ surface->w, surface->h }); + else if (surface->format->BytesPerPixel == 3) + CopyFramebuffertoN3DS_24(framebuffer, (Dimensions){ width, height }, + surface->pixels, (Dimensions){ surface->w, surface->h }); + else + CopyFramebuffertoN3DS_32(framebuffer, (Dimensions){ width, height }, + surface->pixels, (Dimensions){ surface->w, surface->h }); FlushN3DSBuffer(framebuffer, bufsize, drv_data->screen); return 0; } SDL_FORCE_INLINE void -CopyFramebuffertoN3DS(u32 *dest, const Dimensions dest_dim, const u32 *source, const Dimensions source_dim) +CopyFramebuffertoN3DS_16(u16 *dest, const Dimensions dest_dim, const u16 *source, const Dimensions source_dim) +{ + int rows = SDL_min(dest_dim.width, source_dim.height); + int cols = SDL_min(dest_dim.height, source_dim.width); + for (int y = 0; y < rows; ++y) { + for (int x = 0; x < cols; ++x) { + const u16 *s = source + GetSourceOffset(x, y, source_dim.width); + u16 *d = dest + GetDestOffset(x, y, dest_dim.width); + *d = *s; + } + } +} + +SDL_FORCE_INLINE void +CopyFramebuffertoN3DS_24(u8 *dest, const Dimensions dest_dim, const u8 *source, const Dimensions source_dim) +{ + int rows = SDL_min(dest_dim.width, source_dim.height); + int cols = SDL_min(dest_dim.height, source_dim.width); + for (int y = 0; y < rows; ++y) { + for (int x = 0; x < cols; ++x) { + const u8 *s = source + GetSourceOffset(x, y, source_dim.width) * 3; + u8 *d = dest + GetDestOffset(x, y, dest_dim.width) * 3; + d[0] = s[0]; + d[1] = s[1]; + d[2] = s[2]; + } + } +} + +SDL_FORCE_INLINE void +CopyFramebuffertoN3DS_32(u32 *dest, const Dimensions dest_dim, const u32 *source, const Dimensions source_dim) { int rows = SDL_min(dest_dim.width, source_dim.height); int cols = SDL_min(dest_dim.height, source_dim.width); for (int y = 0; y < rows; ++y) { for (int x = 0; x < cols; ++x) { - SDL_memcpy( - dest + GetDestOffset(x, y, dest_dim.width), - source + GetSourceOffset(x, y, source_dim.width), - 4); + const u32 *s = source + GetSourceOffset(x, y, source_dim.width); + u32 *d = dest + GetDestOffset(x, y, dest_dim.width); + *d = *s; } } } diff --git a/src/video/n3ds/SDL_n3dstouch.c b/src/video/n3ds/SDL_n3dstouch.c index 593f64d64115b..0b3f06ab559a5 100644 --- a/src/video/n3ds/SDL_n3dstouch.c +++ b/src/video/n3ds/SDL_n3dstouch.c @@ -26,7 +26,9 @@ #include <3ds.h> #include "../../events/SDL_touch_c.h" +#include "../SDL_sysvideo.h" #include "SDL_n3dstouch.h" +#include "SDL_n3dsvideo.h" #define N3DS_TOUCH_ID 1 @@ -49,19 +51,25 @@ void N3DS_QuitTouch(void) SDL_DelTouch(N3DS_TOUCH_ID); } -void N3DS_PollTouch(void) +void N3DS_PollTouch(_THIS) { + SDL_VideoData *driverdata = (SDL_VideoData *)_this->driverdata; touchPosition touch; + SDL_Window *window; + SDL_VideoDisplay *display; static SDL_bool was_pressed = SDL_FALSE; SDL_bool pressed; hidTouchRead(&touch); pressed = (touch.px != 0 || touch.py != 0); + display = SDL_GetDisplay(driverdata->touch_display); + window = display ? display->fullscreen_window : NULL; + if (pressed != was_pressed) { was_pressed = pressed; SDL_SendTouch(N3DS_TOUCH_ID, 0, - NULL, + window, pressed, touch.px * TOUCHSCREEN_SCALE_X, touch.py * TOUCHSCREEN_SCALE_Y, @@ -69,7 +77,7 @@ void N3DS_PollTouch(void) } else if (pressed) { SDL_SendTouchMotion(N3DS_TOUCH_ID, 0, - NULL, + window, touch.px * TOUCHSCREEN_SCALE_X, touch.py * TOUCHSCREEN_SCALE_Y, 1.0f); diff --git a/src/video/n3ds/SDL_n3dstouch.h b/src/video/n3ds/SDL_n3dstouch.h index 74aa5d5bff292..3d95fafcc3257 100644 --- a/src/video/n3ds/SDL_n3dstouch.h +++ b/src/video/n3ds/SDL_n3dstouch.h @@ -24,7 +24,7 @@ void N3DS_InitTouch(void); void N3DS_QuitTouch(void); -void N3DS_PollTouch(void); +void N3DS_PollTouch(_THIS); #endif /* SDL_n3dstouch_h_ */ diff --git a/src/video/n3ds/SDL_n3dsvideo.c b/src/video/n3ds/SDL_n3dsvideo.c index e3c4f49add98b..bb80f9c18d5dc 100644 --- a/src/video/n3ds/SDL_n3dsvideo.c +++ b/src/video/n3ds/SDL_n3dsvideo.c @@ -31,11 +31,12 @@ #define N3DSVID_DRIVER_NAME "n3ds" -SDL_FORCE_INLINE void AddN3DSDisplay(gfxScreen_t screen); +SDL_FORCE_INLINE int AddN3DSDisplay(gfxScreen_t screen); static int N3DS_VideoInit(_THIS); static void N3DS_VideoQuit(_THIS); static void N3DS_GetDisplayModes(_THIS, SDL_VideoDisplay *display); +static int N3DS_SetDisplayMode(_THIS, SDL_VideoDisplay *display, SDL_DisplayMode *mode); static int N3DS_GetDisplayBounds(_THIS, SDL_VideoDisplay *display, SDL_Rect *rect); static int N3DS_CreateWindow(_THIS, SDL_Window *window); static void N3DS_DestroyWindow(_THIS, SDL_Window *window); @@ -45,6 +46,23 @@ typedef struct gfxScreen_t screen; } DisplayDriverData; +typedef struct +{ + GSPGPU_FramebufferFormat fmt; +} ModeDriverData; + +static const struct +{ + SDL_PixelFormatEnum pixfmt; + GSPGPU_FramebufferFormat gspfmt; +} format_map[] = { + { SDL_PIXELFORMAT_RGBA8888, GSP_RGBA8_OES }, + { SDL_PIXELFORMAT_BGR24, GSP_BGR8_OES }, + { SDL_PIXELFORMAT_RGB565, GSP_RGB565_OES }, + { SDL_PIXELFORMAT_RGBA5551, GSP_RGB5_A1_OES }, + { SDL_PIXELFORMAT_RGBA4444, GSP_RGBA4_OES } +}; + /* N3DS driver bootstrap functions */ static void N3DS_DeleteDevice(SDL_VideoDevice *device) @@ -56,16 +74,31 @@ static void N3DS_DeleteDevice(SDL_VideoDevice *device) static SDL_VideoDevice *N3DS_CreateDevice(void) { - SDL_VideoDevice *device = (SDL_VideoDevice *)SDL_calloc(1, sizeof(SDL_VideoDevice)); + SDL_VideoDevice *device; + SDL_VideoData *phdata; + + /* Initialize all variables that we clean on shutdown */ + device = (SDL_VideoDevice *)SDL_calloc(1, sizeof(SDL_VideoDevice)); if (!device) { SDL_OutOfMemory(); return 0; } + /* Initialize internal data */ + phdata = (SDL_VideoData *)SDL_calloc(1, sizeof(SDL_VideoData)); + if (!phdata) { + SDL_OutOfMemory(); + SDL_free(device); + return NULL; + } + + device->driverdata = phdata; + device->VideoInit = N3DS_VideoInit; device->VideoQuit = N3DS_VideoQuit; device->GetDisplayModes = N3DS_GetDisplayModes; + device->SetDisplayMode = N3DS_SetDisplayMode; device->GetDisplayBounds = N3DS_GetDisplayBounds; device->CreateSDLWindow = N3DS_CreateWindow; @@ -83,6 +116,8 @@ static SDL_VideoDevice *N3DS_CreateDevice(void) device->free = N3DS_DeleteDevice; + device->quirk_flags = VIDEO_DEVICE_QUIRK_FULLSCREEN_ONLY; + return device; } @@ -90,11 +125,13 @@ VideoBootStrap N3DS_bootstrap = { N3DSVID_DRIVER_NAME, "N3DS Video Driver", N3DS static int N3DS_VideoInit(_THIS) { + SDL_VideoData *driverdata = (SDL_VideoData *)_this->driverdata; + gfxInit(GSP_RGBA8_OES, GSP_RGBA8_OES, false); hidInit(); - AddN3DSDisplay(GFX_TOP); - AddN3DSDisplay(GFX_BOTTOM); + driverdata->top_display = AddN3DSDisplay(GFX_TOP); + driverdata->touch_display = AddN3DSDisplay(GFX_BOTTOM); N3DS_InitTouch(); N3DS_SwkbInit(); @@ -102,15 +139,15 @@ static int N3DS_VideoInit(_THIS) return 0; } -SDL_FORCE_INLINE void +SDL_FORCE_INLINE int AddN3DSDisplay(gfxScreen_t screen) { SDL_DisplayMode mode; + ModeDriverData *modedata; SDL_VideoDisplay display; DisplayDriverData *display_driver_data = SDL_calloc(1, sizeof(DisplayDriverData)); if (!display_driver_data) { - SDL_OutOfMemory(); - return; + return SDL_OutOfMemory(); } SDL_zero(mode); @@ -118,18 +155,24 @@ AddN3DSDisplay(gfxScreen_t screen) display_driver_data->screen = screen; + modedata = SDL_malloc(sizeof(ModeDriverData)); + if (!modedata) { + return SDL_OutOfMemory(); + } + mode.w = (screen == GFX_TOP) ? GSP_SCREEN_HEIGHT_TOP : GSP_SCREEN_HEIGHT_BOTTOM; mode.h = GSP_SCREEN_WIDTH; mode.refresh_rate = 60; - mode.format = FRAMEBUFFER_FORMAT; - mode.driverdata = NULL; + mode.format = SDL_PIXELFORMAT_RGBA8888; + mode.driverdata = modedata; + modedata->fmt = GSP_RGBA8_OES; display.name = (screen == GFX_TOP) ? "N3DS top screen" : "N3DS bottom screen"; display.desktop_mode = mode; display.current_mode = mode; display.driverdata = display_driver_data; - SDL_AddVideoDisplay(&display, SDL_FALSE); + return SDL_AddVideoDisplay(&display, SDL_FALSE); } static void N3DS_VideoQuit(_THIS) @@ -143,8 +186,37 @@ static void N3DS_VideoQuit(_THIS) static void N3DS_GetDisplayModes(_THIS, SDL_VideoDisplay *display) { - /* Each display only has a single mode */ - SDL_AddDisplayMode(display, &display->current_mode); + DisplayDriverData *displaydata = display->driverdata; + ModeDriverData *modedata; + SDL_DisplayMode mode; + int i; + + for (i = 0; i < SDL_arraysize(format_map); i++) { + modedata = SDL_malloc(sizeof(ModeDriverData)); + if (!modedata) + continue; + + SDL_zero(mode); + mode.w = (displaydata->screen == GFX_TOP) ? GSP_SCREEN_HEIGHT_TOP : GSP_SCREEN_HEIGHT_BOTTOM; + mode.h = GSP_SCREEN_WIDTH; + mode.refresh_rate = 60; + mode.format = format_map[i].pixfmt; + mode.driverdata = modedata; + modedata->fmt = format_map[i].gspfmt; + + if (!SDL_AddDisplayMode(display, &mode)) { + SDL_free(modedata); + } + } +} + +static int N3DS_SetDisplayMode(_THIS, SDL_VideoDisplay *display, SDL_DisplayMode *mode) +{ + DisplayDriverData *displaydata = display->driverdata; + ModeDriverData *modedata = mode->driverdata; + + gfxSetScreenFormat(displaydata->screen, modedata->fmt); + return 0; } static int N3DS_GetDisplayBounds(_THIS, SDL_VideoDisplay *display, SDL_Rect *rect) diff --git a/src/video/n3ds/SDL_n3dsvideo.h b/src/video/n3ds/SDL_n3dsvideo.h index 3a9bfd94ee680..205f7d270f868 100644 --- a/src/video/n3ds/SDL_n3dsvideo.h +++ b/src/video/n3ds/SDL_n3dsvideo.h @@ -26,13 +26,18 @@ #include <3ds.h> #include "../SDL_sysvideo.h" + +typedef struct SDL_VideoData +{ + int top_display; + int touch_display; +} SDL_VideoData; + typedef struct SDL_WindowData { gfxScreen_t screen; /**< Keeps track of which N3DS screen is targetted */ } SDL_WindowData; -#define FRAMEBUFFER_FORMAT SDL_PIXELFORMAT_RGBA8888 - #endif /* SDL_n3dsvideo_h_ */ /* vi: set sts=4 ts=4 sw=4 expandtab: */ diff --git a/src/video/nacl/SDL_naclvideo.c b/src/video/nacl/SDL_naclvideo.c index 44e2aa9c2b724..f7f35e73a1bd8 100644 --- a/src/video/nacl/SDL_naclvideo.c +++ b/src/video/nacl/SDL_naclvideo.c @@ -128,6 +128,7 @@ static SDL_VideoDevice *NACL_CreateDevice(void) { device->GL_SwapWindow = NACL_GLES_SwapWindow; device->GL_DeleteContext = NACL_GLES_DeleteContext; + device->quirk_flags = VIDEO_DEVICE_QUIRK_FULLSCREEN_ONLY; return device; } diff --git a/src/video/nacl/SDL_naclwindow.c b/src/video/nacl/SDL_naclwindow.c index 3f61afc80a00b..072e4a8100c12 100644 --- a/src/video/nacl/SDL_naclwindow.c +++ b/src/video/nacl/SDL_naclwindow.c @@ -45,7 +45,6 @@ int NACL_CreateWindow(_THIS, SDL_Window * window) window->h = driverdata->h; window->flags &= ~SDL_WINDOW_RESIZABLE; /* window is NEVER resizeable */ - window->flags |= SDL_WINDOW_FULLSCREEN; /* window is always fullscreen */ window->flags &= ~SDL_WINDOW_HIDDEN; window->flags |= SDL_WINDOW_SHOWN; /* only one window on NaCl */ window->flags |= SDL_WINDOW_INPUT_FOCUS; /* always has input focus */ diff --git a/src/video/psp/SDL_pspvideo.c b/src/video/psp/SDL_pspvideo.c index f678842d5ebca..bcf5491829b11 100644 --- a/src/video/psp/SDL_pspvideo.c +++ b/src/video/psp/SDL_pspvideo.c @@ -29,8 +29,10 @@ #include "SDL_syswm.h" #include "SDL_loadso.h" #include "SDL_events.h" +#include "SDL_render.h" #include "../../events/SDL_mouse_c.h" #include "../../events/SDL_keyboard_c.h" +#include "../../render/SDL_sysrender.h" /* PSP declarations */ @@ -38,6 +40,123 @@ #include "SDL_pspevents_c.h" #include "SDL_pspgl_c.h" +#include +#include +#include +#include +#include "../../render/psp/SDL_render_psp.h" + +#define SDL_WINDOWTEXTUREDATA "_SDL_WindowTextureData" + +typedef struct +{ + SDL_Renderer *renderer; + SDL_Texture *texture; + void *pixels; + int pitch; + int bytes_per_pixel; +} SDL_WindowTextureData; + +int PSP_CreateWindowFramebuffer(SDL_VideoDevice *_this, SDL_Window *window, Uint32 *format, void **pixels, int *pitch) +{ + SDL_RendererInfo info; + SDL_WindowTextureData *data = SDL_GetWindowData(window, SDL_WINDOWTEXTUREDATA); + int i, w, h; + + SDL_GetWindowSizeInPixels(window, &w, &h); + + if (w != PSP_SCREEN_WIDTH) { + return SDL_SetError("Unexpected window size"); + } + + if (!data) { + SDL_Renderer *renderer = NULL; + for (i = 0; i < SDL_GetNumRenderDrivers(); ++i) { + SDL_GetRenderDriverInfo(i, &info); + if (SDL_strcmp(info.name, "software") != 0) { + renderer = SDL_CreateRenderer(window, i, 0); + if (renderer && (SDL_GetRendererInfo(renderer, &info) == 0) && (info.flags & SDL_RENDERER_ACCELERATED)) { + break; /* this will work. */ + } + if (renderer) { /* wasn't accelerated, etc, skip it. */ + SDL_DestroyRenderer(renderer); + renderer = NULL; + } + } + } + if (!renderer) { + return SDL_SetError("No hardware accelerated renderers available"); + } + + SDL_assert(renderer != NULL); /* should have explicitly checked this above. */ + + /* Create the data after we successfully create the renderer (bug #1116) */ + data = (SDL_WindowTextureData *)SDL_calloc(1, sizeof(*data)); + + if (!data) { + SDL_DestroyRenderer(renderer); + return SDL_OutOfMemory(); + } + + SDL_SetWindowData(window, SDL_WINDOWTEXTUREDATA, data); + data->renderer = renderer; + } else { + if (SDL_GetRendererInfo(data->renderer, &info) == -1) { + return -1; + } + } + + /* Find the first format without an alpha channel */ + *format = info.texture_formats[0]; + + for (i = 0; i < (int)info.num_texture_formats; ++i) { + if (!SDL_ISPIXELFORMAT_FOURCC(info.texture_formats[i]) && + !SDL_ISPIXELFORMAT_ALPHA(info.texture_formats[i])) { + *format = info.texture_formats[i]; + break; + } + } + + /* get the PSP renderer's "private" data */ + SDL_PSP_RenderGetProp(data->renderer, SDL_PSP_RENDERPROPS_FRONTBUFFER, &data->pixels); + + /* Create framebuffer data */ + data->bytes_per_pixel = SDL_BYTESPERPIXEL(*format); + /* since we point directly to VRAM's frontbuffer, we have to use + the upscaled pitch of 512 width - since PSP requires all textures to be + powers of 2. */ + data->pitch = 512 * data->bytes_per_pixel; + *pixels = data->pixels; + *pitch = data->pitch; + + /* Make sure we're not double-scaling the viewport */ + SDL_RenderSetViewport(data->renderer, NULL); + + return 0; +} + +int PSP_UpdateWindowFramebuffer(_THIS, SDL_Window *window, const SDL_Rect *rects, int numrects) +{ + SDL_WindowTextureData *data; + data = SDL_GetWindowData(window, SDL_WINDOWTEXTUREDATA); + if (!data || !data->renderer || !window->surface) { + return -1; + } + data->renderer->RenderPresent(data->renderer); + SDL_PSP_RenderGetProp(data->renderer, SDL_PSP_RENDERPROPS_BACKBUFFER, &window->surface->pixels); + return 0; +} + +void PSP_DestroyWindowFramebuffer(_THIS, SDL_Window *window) +{ + SDL_WindowTextureData *data = SDL_GetWindowData(window, SDL_WINDOWTEXTUREDATA); + if (!data || !data->renderer) { + return; + } + SDL_DestroyRenderer(data->renderer); + data->renderer = NULL; +} + /* unused static SDL_bool PSP_initialized = SDL_FALSE; */ @@ -128,14 +247,161 @@ static SDL_VideoDevice *PSP_Create() device->PumpEvents = PSP_PumpEvents; + /* backend to use VRAM directly as a framebuffer using + SDL_GetWindowSurface() API. */ + device->checked_texture_framebuffer = 1; + device->CreateWindowFramebuffer = PSP_CreateWindowFramebuffer; + device->UpdateWindowFramebuffer = PSP_UpdateWindowFramebuffer; + device->DestroyWindowFramebuffer = PSP_DestroyWindowFramebuffer; + return device; } +static void configure_dialog(pspUtilityMsgDialogParams *dialog, size_t dialog_size) +{ + /* clear structure and setup size */ + SDL_memset(dialog, 0, dialog_size); + dialog->base.size = dialog_size; + + /* set language */ + sceUtilityGetSystemParamInt(PSP_SYSTEMPARAM_ID_INT_LANGUAGE, &dialog->base.language); + + /* set X/O swap */ + sceUtilityGetSystemParamInt(PSP_SYSTEMPARAM_ID_INT_UNKNOWN, &dialog->base.buttonSwap); + + /* set thread priorities */ + /* TODO: understand how these work */ + dialog->base.soundThread = 0x10; + dialog->base.graphicsThread = 0x11; + dialog->base.fontThread = 0x12; + dialog->base.accessThread = 0x13; +} + +static void *setup_temporal_gu(void *list) +{ + // Using GU_PSM_8888 for the framebuffer + int bpp = 4; + + void *doublebuffer = vramalloc(PSP_FRAME_BUFFER_SIZE * bpp * 2); + void *backbuffer = doublebuffer; + void *frontbuffer = ((uint8_t *)doublebuffer) + PSP_FRAME_BUFFER_SIZE * bpp; + + sceGuInit(); + + sceGuStart(GU_DIRECT,list); + sceGuDrawBuffer(GU_PSM_8888, vrelptr(frontbuffer), PSP_FRAME_BUFFER_WIDTH); + sceGuDispBuffer(PSP_SCREEN_WIDTH, PSP_SCREEN_HEIGHT, vrelptr(backbuffer), PSP_FRAME_BUFFER_WIDTH); + + sceGuOffset(2048 - (PSP_SCREEN_WIDTH >> 1), 2048 - (PSP_SCREEN_HEIGHT >> 1)); + sceGuViewport(2048, 2048, PSP_SCREEN_WIDTH, PSP_SCREEN_HEIGHT); + + sceGuDisable(GU_DEPTH_TEST); + + /* Scissoring */ + sceGuScissor(0, 0, PSP_SCREEN_WIDTH, PSP_SCREEN_HEIGHT); + sceGuEnable(GU_SCISSOR_TEST); + + sceGuFinish(); + sceGuSync(0,0); + + sceDisplayWaitVblankStart(); + sceGuDisplay(GU_TRUE); + + return doublebuffer; +} + +static void term_temporal_gu(void *guBuffer) +{ + sceGuTerm(); + vfree(guBuffer); + sceDisplayWaitVblankStart(); +} + +int PSP_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid) +{ + unsigned char list[64] __attribute__((aligned(64))); + pspUtilityMsgDialogParams dialog; + int status; + void *guBuffer = NULL; + + /* check if it's possible to use existing video context */ + if (SDL_GetFocusWindow() == NULL) { + guBuffer = setup_temporal_gu(list); + } + + /* configure dialog */ + configure_dialog(&dialog, sizeof(dialog)); + + /* setup dialog options for text */ + dialog.mode = PSP_UTILITY_MSGDIALOG_MODE_TEXT; + dialog.options = PSP_UTILITY_MSGDIALOG_OPTION_TEXT; + + /* copy the message in, 512 bytes max */ + SDL_snprintf(dialog.message, sizeof(dialog.message), "%s\r\n\r\n%s", messageboxdata->title, messageboxdata->message); + + /* too many buttons */ + if (messageboxdata->numbuttons > 2) + return SDL_SetError("messageboxdata->numbuttons valid values are 0, 1, 2"); + + /* we only have two options, "yes/no" or "ok" */ + if (messageboxdata->numbuttons == 2) + dialog.options |= PSP_UTILITY_MSGDIALOG_OPTION_YESNO_BUTTONS | PSP_UTILITY_MSGDIALOG_OPTION_DEFAULT_NO; + + /* start dialog */ + if (sceUtilityMsgDialogInitStart(&dialog) != 0) + return SDL_SetError("sceUtilityMsgDialogInitStart() failed for some reason"); + + /* loop while the dialog is active */ + status = PSP_UTILITY_DIALOG_NONE; + do + { + sceGuStart(GU_DIRECT, list); + sceGuClearColor(0); + sceGuClearDepth(0); + sceGuClear(GU_COLOR_BUFFER_BIT|GU_DEPTH_BUFFER_BIT); + sceGuFinish(); + sceGuSync(0,0); + + status = sceUtilityMsgDialogGetStatus(); + + switch (status) + { + case PSP_UTILITY_DIALOG_VISIBLE: + sceUtilityMsgDialogUpdate(1); + break; + + case PSP_UTILITY_DIALOG_QUIT: + sceUtilityMsgDialogShutdownStart(); + break; + } + + sceDisplayWaitVblankStart(); + sceGuSwapBuffers(); + + } while (status != PSP_UTILITY_DIALOG_NONE); + + /* cleanup */ + if (guBuffer) + { + term_temporal_gu(guBuffer); + } + + /* success */ + if (dialog.buttonPressed == PSP_UTILITY_MSGDIALOG_RESULT_YES) + *buttonid = messageboxdata->buttons[0].buttonid; + else if (dialog.buttonPressed == PSP_UTILITY_MSGDIALOG_RESULT_NO) + *buttonid = messageboxdata->buttons[1].buttonid; + else + *buttonid = messageboxdata->buttons[0].buttonid; + + return 0; +} + VideoBootStrap PSP_bootstrap = { "PSP", "PSP Video Driver", PSP_Create, - NULL /* no ShowMessageBox implementation */ + PSP_ShowMessageBox }; /*****************************************************************************/ @@ -152,8 +418,8 @@ int PSP_VideoInit(_THIS) SDL_zero(current_mode); - current_mode.w = 480; - current_mode.h = 272; + current_mode.w = PSP_SCREEN_WIDTH; + current_mode.h = PSP_SCREEN_HEIGHT; current_mode.refresh_rate = 60; /* 32 bpp for default */ @@ -281,13 +547,79 @@ SDL_bool PSP_GetWindowWMInfo(_THIS, SDL_Window * window, struct SDL_SysWMinfo *i #endif -/* TO Write Me */ -SDL_bool PSP_HasScreenKeyboardSupport(_THIS) + +SDL_bool PSP_HasScreenKeyboardSupport(SDL_VideoDevice *_this) { - return SDL_FALSE; + return SDL_TRUE; } -void PSP_ShowScreenKeyboard(_THIS, SDL_Window *window) + +void PSP_ShowScreenKeyboard(SDL_VideoDevice *_this, SDL_Window *window) { + char list[0x20000] __attribute__((aligned(64))); // Needed for sceGuStart to work + int i; + int done = 0; + int input_text_length = 32; // SDL_SendKeyboardText supports up to 32 characters per event + unsigned short outtext[input_text_length]; + char text_string[input_text_length]; + + SceUtilityOskData data; + SceUtilityOskParams params; + + SDL_memset(outtext, 0, input_text_length * sizeof(unsigned short)); + + data.language = PSP_UTILITY_OSK_LANGUAGE_DEFAULT; + data.lines = 1; + data.unk_24 = 1; + data.inputtype = PSP_UTILITY_OSK_INPUTTYPE_ALL; + data.desc = NULL; + data.intext = NULL; + data.outtextlength = input_text_length; + data.outtextlimit = input_text_length; + data.outtext = outtext; + + params.base.size = sizeof(params); + sceUtilityGetSystemParamInt(PSP_SYSTEMPARAM_ID_INT_LANGUAGE, ¶ms.base.language); + sceUtilityGetSystemParamInt(PSP_SYSTEMPARAM_ID_INT_UNKNOWN, ¶ms.base.buttonSwap); + params.base.graphicsThread = 17; + params.base.accessThread = 19; + params.base.fontThread = 18; + params.base.soundThread = 16; + params.datacount = 1; + params.data = &data; + + sceUtilityOskInitStart(¶ms); + + while(!done) { + sceGuStart(GU_DIRECT, list); + sceGuClearColor(0); + sceGuClearDepth(0); + sceGuClear(GU_COLOR_BUFFER_BIT|GU_DEPTH_BUFFER_BIT); + sceGuFinish(); + sceGuSync(0,0); + + switch(sceUtilityOskGetStatus()) + { + case PSP_UTILITY_DIALOG_VISIBLE: + sceUtilityOskUpdate(1); + break; + case PSP_UTILITY_DIALOG_QUIT: + sceUtilityOskShutdownStart(); + break; + case PSP_UTILITY_DIALOG_NONE: + done = 1; + break; + default : + break; + } + sceDisplayWaitVblankStart(); + sceGuSwapBuffers(); + } + + // Convert input list to string + for (i = 0; i < input_text_length; i++) { + text_string[i] = outtext[i]; + } + SDL_SendKeyboardText((const char *) text_string); } void PSP_HideScreenKeyboard(_THIS, SDL_Window *window) { diff --git a/src/video/psp/SDL_pspvideo.h b/src/video/psp/SDL_pspvideo.h index 56452cb86f51b..ee150c6309b15 100644 --- a/src/video/psp/SDL_pspvideo.h +++ b/src/video/psp/SDL_pspvideo.h @@ -68,6 +68,14 @@ void PSP_MinimizeWindow(_THIS, SDL_Window *window); void PSP_RestoreWindow(_THIS, SDL_Window *window); void PSP_DestroyWindow(_THIS, SDL_Window *window); +/* "methods" aka callbacks for SDL_WindowSurface API */ +int PSP_CreateWindowFramebuffer(_THIS, SDL_Window *window, Uint32 *format, + void **pixels, int *pitch); +int PSP_UpdateWindowFramebuffer(_THIS, SDL_Window *window, +const SDL_Rect *rects, int numrects); +void PSP_DestroyWindowFramebuffer(_THIS, SDL_Window *window); + + /* Window manager function */ SDL_bool PSP_GetWindowWMInfo(_THIS, SDL_Window * window, struct SDL_SysWMinfo *info); diff --git a/src/video/raspberry/SDL_rpivideo.h b/src/video/raspberry/SDL_rpivideo.h index 2f0135f83958b..66ea28ff9ed65 100644 --- a/src/video/raspberry/SDL_rpivideo.h +++ b/src/video/raspberry/SDL_rpivideo.h @@ -30,6 +30,14 @@ #include "EGL/egl.h" #include "EGL/eglext.h" +/* This must match the definition of EGL_DISPMANX_WINDOW_T in EGL/eglplatform.h, + and is defined here to allow compiling with standard headers. */ +typedef struct { + DISPMANX_ELEMENT_HANDLE_T element; + int width; + int height; +} SDL_EGL_DISPMANX_WINDOW_T; + typedef struct SDL_VideoData { uint32_t egl_refcount; /* OpenGL ES reference count */ @@ -42,7 +50,7 @@ typedef struct SDL_DisplayData typedef struct SDL_WindowData { - EGL_DISPMANX_WINDOW_T dispman_window; + SDL_EGL_DISPMANX_WINDOW_T dispman_window; #ifdef SDL_VIDEO_OPENGL_EGL EGLSurface egl_surface; #endif diff --git a/src/video/riscos/SDL_riscosvideo.c b/src/video/riscos/SDL_riscosvideo.c index 380ad79893bc4..4e51ea0e3258d 100644 --- a/src/video/riscos/SDL_riscosvideo.c +++ b/src/video/riscos/SDL_riscosvideo.c @@ -90,6 +90,9 @@ static SDL_VideoDevice *RISCOS_CreateDevice(void) device->free = RISCOS_DeleteDevice; + /* TODO: Support windowed mode */ + device->quirk_flags = VIDEO_DEVICE_QUIRK_FULLSCREEN_ONLY; + return device; } diff --git a/src/video/riscos/SDL_riscoswindow.c b/src/video/riscos/SDL_riscoswindow.c index 32a7cfe3e8169..5792d2f544f7d 100644 --- a/src/video/riscos/SDL_riscoswindow.c +++ b/src/video/riscos/SDL_riscoswindow.c @@ -41,8 +41,6 @@ int RISCOS_CreateWindow(_THIS, SDL_Window *window) } driverdata->window = window; - window->flags |= SDL_WINDOW_FULLSCREEN; - SDL_SetMouseFocus(window); /* All done! */ diff --git a/src/video/uikit/SDL_uikitwindow.m b/src/video/uikit/SDL_uikitwindow.m index 8ce26a5f44a6b..0e0ea0577e673 100644 --- a/src/video/uikit/SDL_uikitwindow.m +++ b/src/video/uikit/SDL_uikitwindow.m @@ -481,7 +481,7 @@ NSUInteger UIKit_GetSupportedOrientations(SDL_Window * window) } #endif /* !TARGET_OS_TV */ -int SDL_iPhoneSetAnimationCallback(SDL_Window * window, int interval, void (*callback)(void*), void *callbackParam) +int SDL_iPhoneSetAnimationCallback(SDL_Window * window, int interval, SDL_iOSAnimationCallback callback, void *callbackParam) { if (!window || !window->driverdata) { return SDL_SetError("Invalid window"); diff --git a/src/video/wayland/SDL_waylandevents.c b/src/video/wayland/SDL_waylandevents.c index 562052869c925..496bb5e8feba6 100644 --- a/src/video/wayland/SDL_waylandevents.c +++ b/src/video/wayland/SDL_waylandevents.c @@ -64,6 +64,7 @@ #include #include "../../events/imKStoUCS.h" #include "../../events/SDL_keysym_to_scancode_c.h" +#include "cursor-shape-v1-client-protocol.h" /* Clamp the wl_seat version on older versions of libwayland. */ #if SDL_WAYLAND_CHECK_VERSION(1, 21, 0) @@ -178,6 +179,17 @@ static SDL_bool Wayland_SurfaceHasActiveTouches(struct wl_surface *surface) return SDL_FALSE; } +void Wayland_CreateCursorShapeDevice(struct SDL_WaylandInput *input) +{ + SDL_VideoData *viddata = input->display; + + if (viddata->cursor_shape_manager) { + if (input->pointer && !input->cursor_shape) { + input->cursor_shape = wp_cursor_shape_manager_v1_get_pointer(viddata->cursor_shape_manager, input->pointer); + } + } +} + /* Returns SDL_TRUE if a key repeat event was due */ static SDL_bool keyboard_repeat_handle(SDL_WaylandKeyboardRepeat *repeat_info, uint32_t elapsed) { @@ -920,6 +932,28 @@ static void touch_handler_frame(void *data, struct wl_touch *touch) static void touch_handler_cancel(void *data, struct wl_touch *touch) { + struct SDL_WaylandTouchPoint *tp; + while ((tp = touch_points.head)) { + wl_fixed_t fx = 0, fy = 0; + struct wl_surface *surface = NULL; + int id = tp->id; + + touch_del(id, &fx, &fy, &surface); + + if (surface) { + SDL_WindowData *window_data = (SDL_WindowData *)wl_surface_get_user_data(surface); + + if (window_data) { + const double dblx = wl_fixed_to_double(fx) * window_data->pointer_scale_x; + const double dbly = wl_fixed_to_double(fy) * window_data->pointer_scale_y; + const float x = dblx / window_data->sdlwindow->w; + const float y = dbly / window_data->sdlwindow->h; + + SDL_SendTouch((SDL_TouchID)(intptr_t)touch, (SDL_FingerID)id, + window_data->sdlwindow, SDL_FALSE, x, y, 1.0f); + } + } + } } static const struct wl_touch_listener touch_listener = { @@ -1306,10 +1340,8 @@ static void keyboard_handle_key(void *data, struct wl_keyboard *keyboard, keyboard_input_get_text(text, input, key, SDL_RELEASED, &handled_by_ime); } - if (!handled_by_ime) { - scancode = Wayland_get_scancode_from_key(input, key + 8); - SDL_SendKeyboardKey(state == WL_KEYBOARD_KEY_STATE_PRESSED ? SDL_PRESSED : SDL_RELEASED, scancode); - } + scancode = Wayland_get_scancode_from_key(input, key + 8); + SDL_SendKeyboardKey(state == WL_KEYBOARD_KEY_STATE_PRESSED ? SDL_PRESSED : SDL_RELEASED, scancode); Wayland_data_device_set_serial(input->data_device, serial); Wayland_primary_selection_device_set_serial(input->primary_selection_device, serial); @@ -1408,10 +1440,15 @@ static void seat_handle_capabilities(void *data, struct wl_seat *seat, input->pointer = wl_seat_get_pointer(seat); SDL_memset(&input->pointer_curr_axis_info, 0, sizeof(input->pointer_curr_axis_info)); input->display->pointer = input->pointer; + Wayland_CreateCursorShapeDevice(input); wl_pointer_set_user_data(input->pointer, input); wl_pointer_add_listener(input->pointer, &pointer_listener, input); } else if (!(caps & WL_SEAT_CAPABILITY_POINTER) && input->pointer) { + if (input->cursor_shape) { + wp_cursor_shape_device_v1_destroy(input->cursor_shape); + input->cursor_shape = NULL; + } wl_pointer_destroy(input->pointer); input->pointer = NULL; input->display->pointer = NULL; @@ -2562,6 +2599,10 @@ void Wayland_display_destroy_input(SDL_VideoData *d) wl_keyboard_destroy(input->keyboard); } + if (input->cursor_shape) { + wp_cursor_shape_device_v1_destroy(input->cursor_shape); + } + if (input->pointer) { wl_pointer_destroy(input->pointer); } diff --git a/src/video/wayland/SDL_waylandevents_c.h b/src/video/wayland/SDL_waylandevents_c.h index 1849b9a237a9c..b2b7890f0ae70 100644 --- a/src/video/wayland/SDL_waylandevents_c.h +++ b/src/video/wayland/SDL_waylandevents_c.h @@ -92,6 +92,7 @@ struct SDL_WaylandInput SDL_WaylandDataDevice *data_device; SDL_WaylandPrimarySelectionDevice *primary_selection_device; SDL_WaylandTextInput *text_input; + struct wp_cursor_shape_device_v1 *cursor_shape; struct zwp_relative_pointer_v1 *relative_pointer; SDL_WindowData *pointer_focus; SDL_WindowData *keyboard_focus; @@ -175,6 +176,8 @@ extern int Wayland_input_ungrab_keyboard(SDL_Window *window); extern void Wayland_input_add_tablet(struct SDL_WaylandInput *input, struct SDL_WaylandTabletManager *tablet_manager); extern void Wayland_input_destroy_tablet(struct SDL_WaylandInput *input); +extern void Wayland_CreateCursorShapeDevice(struct SDL_WaylandInput *input); + #endif /* SDL_waylandevents_h_ */ /* vi: set ts=4 sw=4 expandtab: */ diff --git a/src/video/wayland/SDL_waylandkeyboard.c b/src/video/wayland/SDL_waylandkeyboard.c index 486d4884e997c..46ac0528a9dd0 100644 --- a/src/video/wayland/SDL_waylandkeyboard.c +++ b/src/video/wayland/SDL_waylandkeyboard.c @@ -54,25 +54,13 @@ void Wayland_QuitKeyboard(_THIS) void Wayland_StartTextInput(_THIS) { SDL_VideoData *driverdata = _this->driverdata; + struct SDL_WaylandInput *input = driverdata->input; if (driverdata->text_input_manager) { - struct SDL_WaylandInput *input = driverdata->input; if (input && input->text_input) { const SDL_Rect *rect = &input->text_input->cursor_rect; - /* Don't re-enable if we're already enabled. */ - if (input->text_input->is_enabled) { - return; - } - - /* For some reason this has to be done twice, it appears to be a - * bug in mutter? Maybe? - * -flibit - */ zwp_text_input_v3_enable(input->text_input->text_input); - zwp_text_input_v3_commit(input->text_input->text_input); - zwp_text_input_v3_enable(input->text_input->text_input); - zwp_text_input_v3_commit(input->text_input->text_input); /* Now that it's enabled, set the input properties */ zwp_text_input_v3_set_content_type(input->text_input->text_input, @@ -87,29 +75,36 @@ void Wayland_StartTextInput(_THIS) rect->h); } zwp_text_input_v3_commit(input->text_input->text_input); - input->text_input->is_enabled = SDL_TRUE; } } + + if (input && input->xkb.compose_state) { + /* Reset compose state so composite and dead keys don't carry over */ + WAYLAND_xkb_compose_state_reset(input->xkb.compose_state); + } } void Wayland_StopTextInput(_THIS) { SDL_VideoData *driverdata = _this->driverdata; + struct SDL_WaylandInput *input = driverdata->input; if (driverdata->text_input_manager) { - struct SDL_WaylandInput *input = driverdata->input; if (input && input->text_input) { zwp_text_input_v3_disable(input->text_input->text_input); zwp_text_input_v3_commit(input->text_input->text_input); - input->text_input->is_enabled = SDL_FALSE; } } - #ifdef SDL_USE_IME else { SDL_IME_Reset(); } #endif + + if (input && input->xkb.compose_state) { + /* Reset compose state so composite and dead keys don't carry over */ + WAYLAND_xkb_compose_state_reset(input->xkb.compose_state); + } } void Wayland_SetTextInputRect(_THIS, const SDL_Rect *rect) diff --git a/src/video/wayland/SDL_waylandkeyboard.h b/src/video/wayland/SDL_waylandkeyboard.h index bdc34341a5d8e..8fb7448c05d73 100644 --- a/src/video/wayland/SDL_waylandkeyboard.h +++ b/src/video/wayland/SDL_waylandkeyboard.h @@ -28,7 +28,6 @@ typedef struct SDL_WaylandTextInput struct zwp_text_input_v3 *text_input; SDL_Rect cursor_rect; SDL_bool has_preedit; - SDL_bool is_enabled; } SDL_WaylandTextInput; extern int Wayland_InitKeyboard(_THIS); diff --git a/src/video/wayland/SDL_waylandmouse.c b/src/video/wayland/SDL_waylandmouse.c index 48529802112e5..bf1bf9b8d36a1 100644 --- a/src/video/wayland/SDL_waylandmouse.c +++ b/src/video/wayland/SDL_waylandmouse.c @@ -25,10 +25,7 @@ #include #include -#include -#include #include -#include #include "../SDL_sysvideo.h" @@ -40,6 +37,9 @@ #include "wayland-cursor.h" #include "SDL_waylandmouse.h" +#include "SDL_waylandshmbuffer.h" + +#include "cursor-shape-v1-client-protocol.h" #include "SDL_hints.h" #include "../../SDL_hints_c.h" @@ -48,7 +48,7 @@ static int Wayland_SetRelativeMouseMode(SDL_bool enabled); typedef struct { - struct wl_buffer *buffer; + struct Wayland_SHMBuffer shmBuffer; struct wl_surface *surface; int hot_x, hot_y; @@ -58,8 +58,6 @@ typedef struct * When shm_data is NULL, system_cursor must be valid */ SDL_SystemCursor system_cursor; - void *shm_data; - size_t shm_data_size; } Wayland_CursorData; #ifdef SDL_USE_LIBDBUS @@ -283,7 +281,7 @@ static SDL_bool wayland_get_system_cursor(SDL_VideoData *vdata, Wayland_CursorDa } /* ... Set the cursor data, finally. */ - cdata->buffer = WAYLAND_wl_cursor_image_get_buffer(cursor->images[0]); + cdata->shmBuffer.wl_buffer = WAYLAND_wl_cursor_image_get_buffer(cursor->images[0]); cdata->hot_x = cursor->images[0]->hotspot_x; cdata->hot_y = cursor->images[0]->hotspot_y; cdata->w = cursor->images[0]->width; @@ -291,136 +289,6 @@ static SDL_bool wayland_get_system_cursor(SDL_VideoData *vdata, Wayland_CursorDa return SDL_TRUE; } -static int set_tmp_file_size(int fd, off_t size) -{ -#ifdef HAVE_POSIX_FALLOCATE - sigset_t set, old_set; - int ret; - - /* SIGALRM can potentially block a large posix_fallocate() operation - * from succeeding, so block it. - */ - sigemptyset(&set); - sigaddset(&set, SIGALRM); - sigprocmask(SIG_BLOCK, &set, &old_set); - - do { - ret = posix_fallocate(fd, 0, size); - } while (ret == EINTR); - - sigprocmask(SIG_SETMASK, &old_set, NULL); - - if (ret == 0) { - return 0; - } - else if (ret != EINVAL && errno != EOPNOTSUPP) { - return -1; - } -#endif - - if (ftruncate(fd, size) < 0) { - return -1; - } - return 0; -} - -static int wayland_create_tmp_file(off_t size) -{ - int fd; - -#ifdef HAVE_MEMFD_CREATE - fd = memfd_create("SDL", MFD_CLOEXEC | MFD_ALLOW_SEALING); - if (fd >= 0) { - fcntl(fd, F_ADD_SEALS, F_SEAL_SHRINK | F_SEAL_SEAL); - } else -#endif - { - static const char template[] = "/sdl-shared-XXXXXX"; - char *xdg_path; - char tmp_path[PATH_MAX]; - - xdg_path = SDL_getenv("XDG_RUNTIME_DIR"); - if (!xdg_path) { - return -1; - } - - SDL_strlcpy(tmp_path, xdg_path, PATH_MAX); - SDL_strlcat(tmp_path, template, PATH_MAX); - - fd = mkostemp(tmp_path, O_CLOEXEC); - if (fd < 0) { - return -1; - } - - /* Need to manually unlink the temp files, or they can persist after close and fill up the temp storage. */ - unlink(tmp_path); - } - - if (set_tmp_file_size(fd, size) < 0) { - close(fd); - return -1; - } - - return fd; -} - -static void mouse_buffer_release(void *data, struct wl_buffer *buffer) -{ -} - -static const struct wl_buffer_listener mouse_buffer_listener = { - mouse_buffer_release -}; - -static int create_buffer_from_shm(Wayland_CursorData *d, - int width, - int height, - uint32_t format) -{ - SDL_VideoDevice *vd = SDL_GetVideoDevice(); - SDL_VideoData *data = (SDL_VideoData *)vd->driverdata; - struct wl_shm_pool *shm_pool; - int shm_fd; - - int stride = width * 4; - d->shm_data_size = stride * height; - - shm_fd = wayland_create_tmp_file(d->shm_data_size); - if (shm_fd < 0) { - return SDL_SetError("Creating mouse cursor buffer failed."); - } - - d->shm_data = mmap(NULL, - d->shm_data_size, - PROT_READ | PROT_WRITE, - MAP_SHARED, - shm_fd, - 0); - if (d->shm_data == MAP_FAILED) { - d->shm_data = NULL; - close(shm_fd); - return SDL_SetError("mmap() failed."); - } - - SDL_assert(d->shm_data != NULL); - - shm_pool = wl_shm_create_pool(data->shm, shm_fd, d->shm_data_size); - d->buffer = wl_shm_pool_create_buffer(shm_pool, - 0, - width, - height, - stride, - format); - wl_buffer_add_listener(d->buffer, - &mouse_buffer_listener, - d); - - wl_shm_pool_destroy(shm_pool); - close(shm_fd); - - return 0; -} - static SDL_Cursor *Wayland_CreateCursor(SDL_Surface *surface, int hot_x, int hot_y) { SDL_Cursor *cursor; @@ -438,10 +306,9 @@ static SDL_Cursor *Wayland_CreateCursor(SDL_Surface *surface, int hot_x, int hot cursor->driverdata = (void *)data; /* Allocate shared memory buffer for this cursor */ - if (create_buffer_from_shm(data, - surface->w, + if (Wayland_AllocSHMBuffer(surface->w, surface->h, - WL_SHM_FORMAT_ARGB8888) < 0) { + &data->shmBuffer) < 0) { SDL_free(cursor->driverdata); SDL_free(cursor); return NULL; @@ -450,7 +317,7 @@ static SDL_Cursor *Wayland_CreateCursor(SDL_Surface *surface, int hot_x, int hot /* Wayland requires premultiplied alpha for its surfaces. */ SDL_PremultiplyAlpha(surface->w, surface->h, surface->format->format, surface->pixels, surface->pitch, - SDL_PIXELFORMAT_ARGB8888, data->shm_data, surface->w * 4); + SDL_PIXELFORMAT_ARGB8888, data->shmBuffer.shm_data, surface->w * 4); data->surface = wl_compositor_create_surface(wd->compositor); wl_surface_set_user_data(data->surface, NULL); @@ -481,8 +348,10 @@ static SDL_Cursor *Wayland_CreateSystemCursor(SDL_SystemCursor id) } cursor->driverdata = (void *)cdata; - cdata->surface = wl_compositor_create_surface(data->compositor); - wl_surface_set_user_data(cdata->surface, NULL); + if (!data->cursor_shape_manager) { + cdata->surface = wl_compositor_create_surface(data->compositor); + wl_surface_set_user_data(cdata->surface, NULL); + } /* Note that we can't actually set any other cursor properties, as this * is output-specific. See wayland_get_system_cursor for the rest! @@ -502,12 +371,10 @@ static SDL_Cursor *Wayland_CreateDefaultCursor() static void Wayland_FreeCursorData(Wayland_CursorData *d) { - if (d->buffer) { - if (d->shm_data) { - wl_buffer_destroy(d->buffer); - munmap(d->shm_data, d->shm_data_size); - } - d->buffer = NULL; + if (d->shmBuffer.shm_data) { + Wayland_ReleaseSHMBuffer(&d->shmBuffer); + } else { + d->shmBuffer.wl_buffer = NULL; } if (d->surface) { @@ -533,6 +400,55 @@ static void Wayland_FreeCursor(SDL_Cursor *cursor) SDL_free(cursor); } +static void Wayland_SetSystemCursorShape(struct SDL_WaylandInput *input, SDL_SystemCursor id) +{ + Uint32 shape; + + switch (id) { + case SDL_SYSTEM_CURSOR_ARROW: + shape = WP_CURSOR_SHAPE_DEVICE_V1_SHAPE_DEFAULT; + break; + case SDL_SYSTEM_CURSOR_IBEAM: + shape = WP_CURSOR_SHAPE_DEVICE_V1_SHAPE_TEXT; + break; + case SDL_SYSTEM_CURSOR_WAIT: + shape = WP_CURSOR_SHAPE_DEVICE_V1_SHAPE_WAIT; + break; + case SDL_SYSTEM_CURSOR_CROSSHAIR: + shape = WP_CURSOR_SHAPE_DEVICE_V1_SHAPE_CROSSHAIR; + break; + case SDL_SYSTEM_CURSOR_WAITARROW: + shape = WP_CURSOR_SHAPE_DEVICE_V1_SHAPE_PROGRESS; + break; + case SDL_SYSTEM_CURSOR_SIZENWSE: + shape = WP_CURSOR_SHAPE_DEVICE_V1_SHAPE_NWSE_RESIZE; + break; + case SDL_SYSTEM_CURSOR_SIZENESW: + shape = WP_CURSOR_SHAPE_DEVICE_V1_SHAPE_NESW_RESIZE; + break; + case SDL_SYSTEM_CURSOR_SIZEWE: + shape = WP_CURSOR_SHAPE_DEVICE_V1_SHAPE_EW_RESIZE; + break; + case SDL_SYSTEM_CURSOR_SIZENS: + shape = WP_CURSOR_SHAPE_DEVICE_V1_SHAPE_NS_RESIZE; + break; + case SDL_SYSTEM_CURSOR_SIZEALL: + shape = WP_CURSOR_SHAPE_DEVICE_V1_SHAPE_ALL_SCROLL; + break; + case SDL_SYSTEM_CURSOR_NO: + shape = WP_CURSOR_SHAPE_DEVICE_V1_SHAPE_NOT_ALLOWED; + break; + case SDL_SYSTEM_CURSOR_HAND: + shape = WP_CURSOR_SHAPE_DEVICE_V1_SHAPE_POINTER; + break; + default: + SDL_assert(0); /* Should never be here... */ + shape = WP_CURSOR_SHAPE_DEVICE_V1_SHAPE_DEFAULT; + } + + wp_cursor_shape_device_v1_set_shape(input->cursor_shape, input->pointer_enter_serial, shape); +} + static int Wayland_ShowCursor(SDL_Cursor *cursor) { SDL_VideoDevice *vd = SDL_GetVideoDevice(); @@ -549,8 +465,19 @@ static int Wayland_ShowCursor(SDL_Cursor *cursor) Wayland_CursorData *data = cursor->driverdata; /* TODO: High-DPI custom cursors? -flibit */ - if (!data->shm_data) { - if (!wayland_get_system_cursor(d, data, &scale)) { + if (!data->shmBuffer.shm_data) { + if (input->cursor_shape) { + Wayland_SetSystemCursorShape(input, data->system_cursor); + + input->cursor_visible = SDL_TRUE; + + if (input->relative_mode_override) { + Wayland_input_unlock_pointer(input); + input->relative_mode_override = SDL_FALSE; + } + + return 0; + } else if (!wayland_get_system_cursor(d, data, &scale)) { return -1; } } @@ -561,7 +488,7 @@ static int Wayland_ShowCursor(SDL_Cursor *cursor) data->surface, data->hot_x / scale, data->hot_y / scale); - wl_surface_attach(data->surface, data->buffer, 0, 0); + wl_surface_attach(data->surface, data->shmBuffer.wl_buffer, 0, 0); wl_surface_damage(data->surface, 0, 0, data->w, data->h); wl_surface_commit(data->surface); diff --git a/src/video/wayland/SDL_waylandshmbuffer.c b/src/video/wayland/SDL_waylandshmbuffer.c new file mode 100644 index 0000000000000..a64c7c3501a37 --- /dev/null +++ b/src/video/wayland/SDL_waylandshmbuffer.c @@ -0,0 +1,172 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +#include "../../SDL_internal.h" + +#ifdef SDL_VIDEO_DRIVER_WAYLAND + +#include +#include +#include +#include +#include +#include + +#include "SDL_waylandshmbuffer.h" +#include "SDL_waylandvideo.h" + +static int SetTempFileSize(int fd, off_t size) +{ +#ifdef HAVE_POSIX_FALLOCATE + sigset_t set, old_set; + int ret; + + /* SIGALRM can potentially block a large posix_fallocate() operation + * from succeeding, so block it. + */ + sigemptyset(&set); + sigaddset(&set, SIGALRM); + sigprocmask(SIG_BLOCK, &set, &old_set); + + do { + ret = posix_fallocate(fd, 0, size); + } while (ret == EINTR); + + sigprocmask(SIG_SETMASK, &old_set, NULL); + + if (ret == 0) { + return 0; + } else if (ret != EINVAL && errno != EOPNOTSUPP) { + return -1; + } +#endif + + if (ftruncate(fd, size) < 0) { + return -1; + } + return 0; +} + +static int CreateTempFD(off_t size) +{ + int fd; + +#ifdef HAVE_MEMFD_CREATE + fd = memfd_create("SDL", MFD_CLOEXEC | MFD_ALLOW_SEALING); + if (fd >= 0) { + fcntl(fd, F_ADD_SEALS, F_SEAL_SHRINK | F_SEAL_SEAL); + } else +#endif + { + static const char template[] = "/sdl-shared-XXXXXX"; + char *xdg_path; + char tmp_path[PATH_MAX]; + + xdg_path = SDL_getenv("XDG_RUNTIME_DIR"); + if (!xdg_path) { + return -1; + } + + SDL_strlcpy(tmp_path, xdg_path, PATH_MAX); + SDL_strlcat(tmp_path, template, PATH_MAX); + + fd = mkostemp(tmp_path, O_CLOEXEC); + if (fd < 0) { + return -1; + } + + /* Need to manually unlink the temp files, or they can persist after close and fill up the temp storage. */ + unlink(tmp_path); + } + + if (SetTempFileSize(fd, size) < 0) { + close(fd); + return -1; + } + + return fd; +} + +static void buffer_handle_release(void *data, struct wl_buffer *wl_buffer) +{ + /* NOP */ +} + +static struct wl_buffer_listener buffer_listener = { + buffer_handle_release +}; + +int Wayland_AllocSHMBuffer(int width, int height, struct Wayland_SHMBuffer *shmBuffer) +{ + SDL_VideoDevice *vd = SDL_GetVideoDevice(); + SDL_VideoData *data = vd->driverdata; + struct wl_shm_pool *shm_pool; + int shm_fd; + int stride; + const Uint32 SHM_FMT = WL_SHM_FORMAT_ARGB8888; + + if (!shmBuffer) { + return SDL_InvalidParamError("shmBuffer"); + } + + stride = width * 4; + shmBuffer->shm_data_size = stride * height; + + shm_fd = CreateTempFD(shmBuffer->shm_data_size); + if (shm_fd < 0) { + return SDL_SetError("Creating SHM buffer failed."); + } + + shmBuffer->shm_data = mmap(NULL, shmBuffer->shm_data_size, PROT_READ | PROT_WRITE, MAP_SHARED, shm_fd, 0); + if (shmBuffer->shm_data == MAP_FAILED) { + shmBuffer->shm_data = NULL; + close(shm_fd); + return SDL_SetError("mmap() failed."); + } + + SDL_assert(shmBuffer->shm_data != NULL); + + shm_pool = wl_shm_create_pool(data->shm, shm_fd, shmBuffer->shm_data_size); + shmBuffer->wl_buffer = wl_shm_pool_create_buffer(shm_pool, 0, width, height, stride, SHM_FMT); + wl_buffer_add_listener(shmBuffer->wl_buffer, &buffer_listener, shmBuffer); + + wl_shm_pool_destroy(shm_pool); + close(shm_fd); + + return 0; +} + +void Wayland_ReleaseSHMBuffer(struct Wayland_SHMBuffer *shmBuffer) +{ + if (shmBuffer) { + if (shmBuffer->wl_buffer) { + wl_buffer_destroy(shmBuffer->wl_buffer); + shmBuffer->wl_buffer = NULL; + } + if (shmBuffer->shm_data) { + munmap(shmBuffer->shm_data, shmBuffer->shm_data_size); + shmBuffer->shm_data = NULL; + } + shmBuffer->shm_data_size = 0; + } +} + +#endif \ No newline at end of file diff --git a/src/video/wayland/SDL_waylandshmbuffer.h b/src/video/wayland/SDL_waylandshmbuffer.h new file mode 100644 index 0000000000000..fb6649a08dfa6 --- /dev/null +++ b/src/video/wayland/SDL_waylandshmbuffer.h @@ -0,0 +1,34 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ +#include "../../SDL_internal.h" + +#ifndef SDL_waylandshmbuffer_h_ +#define SDL_waylandshmbuffer_h_ + +struct Wayland_SHMBuffer +{ + struct wl_buffer *wl_buffer; + void *shm_data; + int shm_data_size; +}; + +/* Allocates an SHM buffer with the format WL_SHM_FORMAT_ARGB8888 */ +extern int Wayland_AllocSHMBuffer(int width, int height, struct Wayland_SHMBuffer *shmBuffer); +extern void Wayland_ReleaseSHMBuffer(struct Wayland_SHMBuffer *shmBuffer); + +#endif \ No newline at end of file diff --git a/src/video/wayland/SDL_waylandsym.h b/src/video/wayland/SDL_waylandsym.h index 8565e700d7038..13fc0d8a7f3d4 100644 --- a/src/video/wayland/SDL_waylandsym.h +++ b/src/video/wayland/SDL_waylandsym.h @@ -146,6 +146,7 @@ SDL_WAYLAND_SYM(struct xkb_compose_table *, xkb_compose_table_new_from_locale, ( const char *locale, enum xkb_compose_compile_flags) ) SDL_WAYLAND_SYM(void, xkb_compose_table_unref, (struct xkb_compose_table *) ) SDL_WAYLAND_SYM(struct xkb_compose_state *, xkb_compose_state_new, (struct xkb_compose_table *, enum xkb_compose_state_flags) ) +SDL_WAYLAND_SYM(void, xkb_compose_state_reset, (struct xkb_compose_state *) ) SDL_WAYLAND_SYM(void, xkb_compose_state_unref, (struct xkb_compose_state *) ) SDL_WAYLAND_SYM(enum xkb_compose_feed_result, xkb_compose_state_feed, (struct xkb_compose_state *, xkb_keysym_t) ) SDL_WAYLAND_SYM(enum xkb_compose_status, xkb_compose_state_get_status, (struct xkb_compose_state *) ) diff --git a/src/video/wayland/SDL_waylandvideo.c b/src/video/wayland/SDL_waylandvideo.c index 947cb7aee4d3c..1d525be496542 100644 --- a/src/video/wayland/SDL_waylandvideo.c +++ b/src/video/wayland/SDL_waylandvideo.c @@ -58,6 +58,8 @@ #include "viewporter-client-protocol.h" #include "primary-selection-unstable-v1-client-protocol.h" #include "fractional-scale-v1-client-protocol.h" +#include "cursor-shape-v1-client-protocol.h" +#include "xdg-toplevel-icon-v1-client-protocol.h" #ifdef HAVE_LIBDECOR_H #include @@ -275,6 +277,7 @@ static SDL_VideoDevice *Wayland_CreateDevice(void) device->SetWindowMaximumSize = Wayland_SetWindowMaximumSize; device->SetWindowModalFor = Wayland_SetWindowModalFor; device->SetWindowTitle = Wayland_SetWindowTitle; + device->SetWindowIcon = Wayland_SetWindowIcon; device->GetWindowSizeInPixels = Wayland_GetWindowSizeInPixels; device->DestroyWindow = Wayland_DestroyWindow; device->SetWindowHitTest = Wayland_SetWindowHitTest; @@ -737,6 +740,7 @@ static void Wayland_free_display(SDL_VideoData *d, uint32_t id) int num_displays = SDL_GetNumVideoDisplays(); SDL_VideoDisplay *display; SDL_WaylandOutputData *data; + SDL_Window *window; int i; for (i = 0; i < num_displays; i += 1) { @@ -756,6 +760,14 @@ static void Wayland_free_display(SDL_VideoData *d, uint32_t id) } } } + + /* Surface leave events may be implicit when an output is destroyed, so make sure that + * no windows retain a reference to a destroyed output. + */ + for (window = SDL_GetVideoDevice()->windows; window; window = window->next) { + Wayland_RemoveOutputFromWindow(window->driverdata, data->output); + } + if (data->xdg_output) { zxdg_output_v1_destroy(data->xdg_output); } @@ -870,6 +882,13 @@ static void display_handle_global(void *data, struct wl_registry *registry, uint d->viewporter = wl_registry_bind(d->registry, id, &wp_viewporter_interface, 1); } else if (SDL_strcmp(interface, "wp_fractional_scale_manager_v1") == 0) { d->fractional_scale_manager = wl_registry_bind(d->registry, id, &wp_fractional_scale_manager_v1_interface, 1); + } else if (SDL_strcmp(interface, "wp_cursor_shape_manager_v1") == 0) { + d->cursor_shape_manager = wl_registry_bind(d->registry, id, &wp_cursor_shape_manager_v1_interface, 1); + if (d->input) { + Wayland_CreateCursorShapeDevice(d->input); + } + } else if (SDL_strcmp(interface, "xdg_toplevel_icon_manager_v1") == 0) { + d->xdg_toplevel_icon_manager_v1 = wl_registry_bind(d->registry, id, &xdg_toplevel_icon_manager_v1_interface, 1); #ifdef SDL_VIDEO_DRIVER_WAYLAND_QT_TOUCH } else if (SDL_strcmp(interface, "qt_touch_extension") == 0) { Wayland_touch_create(d, id); @@ -1113,6 +1132,16 @@ static void Wayland_VideoCleanup(_THIS) data->fractional_scale_manager = NULL; } + if (data->cursor_shape_manager) { + wp_cursor_shape_manager_v1_destroy(data->cursor_shape_manager); + data->cursor_shape_manager = NULL; + } + + if (data->xdg_toplevel_icon_manager_v1) { + xdg_toplevel_icon_manager_v1_destroy(data->xdg_toplevel_icon_manager_v1); + data->xdg_toplevel_icon_manager_v1 = NULL; + } + if (data->compositor) { wl_compositor_destroy(data->compositor); data->compositor = NULL; diff --git a/src/video/wayland/SDL_waylandvideo.h b/src/video/wayland/SDL_waylandvideo.h index f4247d112adbd..13e9b35ee8ea4 100644 --- a/src/video/wayland/SDL_waylandvideo.h +++ b/src/video/wayland/SDL_waylandvideo.h @@ -70,6 +70,7 @@ typedef struct } shell; struct zwp_relative_pointer_manager_v1 *relative_pointer_manager; struct zwp_pointer_constraints_v1 *pointer_constraints; + struct wp_cursor_shape_manager_v1 *cursor_shape_manager; struct wl_data_device_manager *data_device_manager; struct zwp_primary_selection_device_manager_v1 *primary_selection_device_manager; struct zxdg_decoration_manager_v1 *decoration_manager; @@ -77,6 +78,7 @@ typedef struct struct zwp_idle_inhibit_manager_v1 *idle_inhibit_manager; struct xdg_activation_v1 *activation_manager; struct zwp_text_input_manager_v3 *text_input_manager; + struct xdg_toplevel_icon_manager_v1 *xdg_toplevel_icon_manager_v1; struct zxdg_output_manager_v1 *xdg_output_manager; struct wp_viewporter *viewporter; struct wp_fractional_scale_manager_v1 *fractional_scale_manager; diff --git a/src/video/wayland/SDL_waylandwindow.c b/src/video/wayland/SDL_waylandwindow.c index 13b93c65633fa..d208c1ab268a4 100644 --- a/src/video/wayland/SDL_waylandwindow.c +++ b/src/video/wayland/SDL_waylandwindow.c @@ -31,6 +31,7 @@ #include "SDL_waylandwindow.h" #include "SDL_waylandvideo.h" #include "SDL_waylandtouch.h" +#include "SDL_waylandshmbuffer.h" #include "SDL_hints.h" #include "../../SDL_hints_c.h" #include "SDL_events.h" @@ -41,6 +42,7 @@ #include "xdg-activation-v1-client-protocol.h" #include "viewporter-client-protocol.h" #include "fractional-scale-v1-client-protocol.h" +#include "xdg-toplevel-icon-v1-client-protocol.h" #ifdef HAVE_LIBDECOR_H #include @@ -1061,39 +1063,11 @@ static void Wayland_move_window(SDL_Window *window, } } -static void handle_surface_enter(void *data, struct wl_surface *surface, - struct wl_output *output) -{ - SDL_WindowData *window = data; - SDL_WaylandOutputData *driverdata = wl_output_get_user_data(output); - - if (!SDL_WAYLAND_own_output(output) || !SDL_WAYLAND_own_surface(surface)) { - return; - } - - window->outputs = SDL_realloc(window->outputs, - sizeof(SDL_WaylandOutputData *) * (window->num_outputs + 1)); - window->outputs[window->num_outputs++] = driverdata; - - /* Update the scale factor after the move so that fullscreen outputs are updated. */ - Wayland_move_window(window->sdlwindow, driverdata); - - if (!window->fractional_scale) { - update_scale_factor(window); - } -} - -static void handle_surface_leave(void *data, struct wl_surface *surface, - struct wl_output *output) +void Wayland_RemoveOutputFromWindow(SDL_WindowData *window, struct wl_output *output) { - SDL_WindowData *window = data; int i, send_move_event = 0; SDL_WaylandOutputData *driverdata = wl_output_get_user_data(output); - if (!SDL_WAYLAND_own_output(output) || !SDL_WAYLAND_own_surface(surface)) { - return; - } - for (i = 0; i < window->num_outputs; i++) { if (window->outputs[i] == driverdata) { /* remove this one */ if (i == (window->num_outputs - 1)) { @@ -1122,6 +1096,40 @@ static void handle_surface_leave(void *data, struct wl_surface *surface, } } +static void handle_surface_enter(void *data, struct wl_surface *surface, + struct wl_output *output) +{ + SDL_WindowData *window = data; + SDL_WaylandOutputData *driverdata = wl_output_get_user_data(output); + + if (!SDL_WAYLAND_own_output(output) || !SDL_WAYLAND_own_surface(surface)) { + return; + } + + window->outputs = SDL_realloc(window->outputs, + sizeof(SDL_WaylandOutputData *) * (window->num_outputs + 1)); + window->outputs[window->num_outputs++] = driverdata; + + /* Update the scale factor after the move so that fullscreen outputs are updated. */ + Wayland_move_window(window->sdlwindow, driverdata); + + if (!window->fractional_scale) { + update_scale_factor(window); + } +} + +static void handle_surface_leave(void *data, struct wl_surface *surface, + struct wl_output *output) +{ + SDL_WindowData *window = (SDL_WindowData *)data; + + if (!SDL_WAYLAND_own_output(output) || !SDL_WAYLAND_own_surface(surface)) { + return; + } + + Wayland_RemoveOutputFromWindow(window, output); +} + static const struct wl_surface_listener surface_listener = { handle_surface_enter, handle_surface_leave @@ -1293,6 +1301,12 @@ void Wayland_ShowWindow(_THIS, SDL_Window *window) } else { libdecor_frame_set_app_id(data->shell_surface.libdecor.frame, c->classname); libdecor_frame_map(data->shell_surface.libdecor.frame); + + if (c->xdg_toplevel_icon_manager_v1 && data->xdg_toplevel_icon_v1) { + xdg_toplevel_icon_manager_v1_set_icon(c->xdg_toplevel_icon_manager_v1, + libdecor_frame_get_xdg_toplevel(data->shell_surface.libdecor.frame), + data->xdg_toplevel_icon_v1); + } } } else #endif @@ -1337,6 +1351,12 @@ void Wayland_ShowWindow(_THIS, SDL_Window *window) xdg_toplevel_set_app_id(data->shell_surface.xdg.roleobj.toplevel, c->classname); xdg_toplevel_add_listener(data->shell_surface.xdg.roleobj.toplevel, &toplevel_listener_xdg, data); + if (c->xdg_toplevel_icon_manager_v1 && data->xdg_toplevel_icon_v1) { + xdg_toplevel_icon_manager_v1_set_icon(c->xdg_toplevel_icon_manager_v1, + data->shell_surface.xdg.roleobj.toplevel, + data->xdg_toplevel_icon_v1); + } + SetMinMaxDimensions(window, SDL_FALSE); } } @@ -2190,6 +2210,46 @@ void Wayland_SetWindowTitle(_THIS, SDL_Window *window) WAYLAND_wl_display_flush(viddata->display); } +void Wayland_SetWindowIcon(SDL_VideoDevice *_this, SDL_Window *window, SDL_Surface *icon) +{ + SDL_WindowData *wind = window->driverdata; + SDL_VideoData *viddata = _this->driverdata; + struct xdg_toplevel *toplevel = NULL; + + if (!viddata->xdg_toplevel_icon_manager_v1) { + SDL_SetError("wayland: cannot set icon; xdg_toplevel_icon_v1 protocol not supported"); + return; + } + if (icon->w != icon->h) { + SDL_SetError("wayland: icon width and height must be equal, got %ix%i", icon->w, icon->h); + return; + } + if (wind->xdg_toplevel_icon_v1) { + xdg_toplevel_icon_v1_destroy(wind->xdg_toplevel_icon_v1); + wind->xdg_toplevel_icon_v1 = NULL; + } + + Wayland_ReleaseSHMBuffer(&wind->icon); + if (Wayland_AllocSHMBuffer(icon->w, icon->h, &wind->icon) != 0) { + SDL_SetError("wayland: failed to allocate SHM buffer for the icon"); + return; + } + SDL_PremultiplyAlpha(icon->w, icon->h, icon->format->format, icon->pixels, icon->pitch, SDL_PIXELFORMAT_ARGB8888, wind->icon.shm_data, icon->w * 4); + wind->xdg_toplevel_icon_v1 = xdg_toplevel_icon_manager_v1_create_icon(viddata->xdg_toplevel_icon_manager_v1); + xdg_toplevel_icon_v1_add_buffer(wind->xdg_toplevel_icon_v1, wind->icon.wl_buffer, 1); +#ifdef HAVE_LIBDECOR_H + if (wind->shell_surface_type == WAYLAND_SURFACE_LIBDECOR && wind->shell_surface.libdecor.frame) { + toplevel = libdecor_frame_get_xdg_toplevel(wind->shell_surface.libdecor.frame); + } else +#endif + if (wind->shell_surface_type == WAYLAND_SURFACE_XDG_TOPLEVEL && wind->shell_surface.xdg.roleobj.toplevel) { + toplevel = wind->shell_surface.xdg.roleobj.toplevel; + } + if (toplevel) { + xdg_toplevel_icon_manager_v1_set_icon(viddata->xdg_toplevel_icon_manager_v1, toplevel, wind->xdg_toplevel_icon_v1); + } +} + void Wayland_SuspendScreenSaver(_THIS) { SDL_VideoData *data = (SDL_VideoData *)_this->driverdata; @@ -2258,6 +2318,12 @@ void Wayland_DestroyWindow(_THIS, SDL_Window *window) wp_fractional_scale_v1_destroy(wind->fractional_scale); } + if (wind->xdg_toplevel_icon_v1) { + xdg_toplevel_icon_v1_destroy(wind->xdg_toplevel_icon_v1); + } + + Wayland_ReleaseSHMBuffer(&wind->icon); + SDL_free(wind->outputs); if (wind->gles_swap_frame_callback) { diff --git a/src/video/wayland/SDL_waylandwindow.h b/src/video/wayland/SDL_waylandwindow.h index 61ee578a61bc7..618fd21cf181c 100644 --- a/src/video/wayland/SDL_waylandwindow.h +++ b/src/video/wayland/SDL_waylandwindow.h @@ -29,6 +29,7 @@ #include "../../events/SDL_touch_c.h" #include "SDL_waylandvideo.h" +#include "SDL_waylandshmbuffer.h" struct SDL_WaylandInput; @@ -89,6 +90,9 @@ typedef struct struct xdg_activation_token_v1 *activation_token; struct wp_viewport *draw_viewport; struct wp_fractional_scale_v1 *fractional_scale; + struct xdg_toplevel_icon_v1 *xdg_toplevel_icon_v1; + + struct Wayland_SHMBuffer icon; /* floating dimensions for restoring from maximized and fullscreen */ int floating_width, floating_height; @@ -144,11 +148,13 @@ extern int Wayland_SetWindowModalFor(_THIS, SDL_Window *modal_window, SDL_Window extern void Wayland_SetWindowTitle(_THIS, SDL_Window *window); extern void Wayland_DestroyWindow(_THIS, SDL_Window *window); extern void Wayland_SuspendScreenSaver(_THIS); +extern void Wayland_SetWindowIcon(_THIS, SDL_Window *window, SDL_Surface *icon); extern SDL_bool Wayland_GetWindowWMInfo(_THIS, SDL_Window * window, SDL_SysWMinfo * info); extern int Wayland_SetWindowHitTest(SDL_Window *window, SDL_bool enabled); extern int Wayland_FlashWindow(_THIS, SDL_Window *window, SDL_FlashOperation operation); +extern void Wayland_RemoveOutputFromWindow(SDL_WindowData *window, struct wl_output *output); extern void Wayland_InitWin(SDL_VideoData *data); extern void Wayland_QuitWin(SDL_VideoData *data); diff --git a/src/video/windows/SDL_windowsevents.c b/src/video/windows/SDL_windowsevents.c index 6f77ff750e6d3..559c1217185b9 100644 --- a/src/video/windows/SDL_windowsevents.c +++ b/src/video/windows/SDL_windowsevents.c @@ -318,7 +318,10 @@ static SDL_Scancode WindowsScanCodeToSDLScanCode(LPARAM lParam, WPARAM wParam) * value set, however we cannot simply map these in VKeytoScancode() or we will be * incorrectly handling the arrow keys on the number pad when NumLock is disabled * (which also generate VK_LEFT, VK_RIGHT, etc in that scenario). Instead, we'll only - * map them if none of the above special number pad mappings applied. */ + * map them if none of the above special number pad mappings applied. + * + * WIN+V (clipboard history feature) can also send Ctrl-V without a scancode value set. + */ if (code == SDL_SCANCODE_UNKNOWN) { code = VKeytoScancodeFallback(wParam); } @@ -638,8 +641,9 @@ WIN_KeyboardHookProc(int nCode, WPARAM wParam, LPARAM lParam) if (nCode < 0 || nCode != HC_ACTION) { return CallNextHookEx(NULL, nCode, wParam, lParam); } + if (hookData->scanCode == 0x21d) { - // Skip fake LCtrl when RAlt is pressed + /* Skip fake LCtrl when RAlt is pressed */ return 1; } @@ -697,36 +701,37 @@ WIN_KeyboardHookProc(int nCode, WPARAM wParam, LPARAM lParam) #endif /*!defined(__XBOXONE__) && !defined(__XBOXSERIES__)*/ -// Return 1 if spruious LCtrl is pressed -// LCtrl is sent when RAltGR is pressed -int skip_bad_lcrtl(WPARAM wParam, LPARAM lParam) +/* Return SDL_TRUE if spurious LCtrl is pressed. LCtrl is sent when RAltGR is pressed. */ +static SDL_bool SkipAltGrLeftControl(WPARAM wParam, LPARAM lParam) { MSG next_msg; DWORD msg_time; + if (wParam != VK_CONTROL) { - return 0; + return SDL_FALSE; } - // Is this an extended key (i.e. right key)? - if (lParam & 0x01000000) - return 0; - // Here is a trick: "Alt Gr" sends LCTRL, then RALT. We only - // want the RALT message, so we try to see if the next message - // is a RALT message. In that case, this is a false LCTRL! + /* Is this an extended key (i.e. right key)? */ + if (lParam & 0x01000000) { + return SDL_FALSE; + } + +#if !defined(__XBOXONE__) && !defined(__XBOXSERIES__) + /* Here is a trick: "Alt Gr" sends LCTRL, then RALT. We only + want the RALT message, so we try to see if the next message + is a RALT message. In that case, this is a false LCTRL! */ msg_time = GetMessageTime(); if (PeekMessage(&next_msg, NULL, 0, 0, PM_NOREMOVE)) { if (next_msg.message == WM_KEYDOWN || next_msg.message == WM_SYSKEYDOWN) { - if (next_msg.wParam == VK_MENU && - (next_msg.lParam & 0x01000000) && - next_msg.time == msg_time) { - // Next message is a RALT down message, which - // means that this is NOT a proper LCTRL message! - return 1; + if (next_msg.wParam == VK_MENU && (next_msg.lParam & 0x01000000) && next_msg.time == msg_time) { + /* Next message is a RALT down message, which means that this is NOT a proper LCTRL message! */ + return SDL_TRUE; } } } - return 0; +#endif // !defined(__XBOXONE__) && !defined(__XBOXSERIES__) + return SDL_FALSE; } LRESULT CALLBACK @@ -1046,7 +1051,7 @@ WIN_WindowProc(HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam) SDL_Scancode code = WindowsScanCodeToSDLScanCode(lParam, wParam); const Uint8 *keyboardState = SDL_GetKeyboardState(NULL); - if (skip_bad_lcrtl(wParam, lParam)) { + if (SkipAltGrLeftControl(wParam, lParam)) { returnCode = 0; break; } @@ -1073,7 +1078,7 @@ WIN_WindowProc(HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam) SDL_Scancode code = WindowsScanCodeToSDLScanCode(lParam, wParam); const Uint8 *keyboardState = SDL_GetKeyboardState(NULL); - if (skip_bad_lcrtl(wParam, lParam)) { + if (SkipAltGrLeftControl(wParam, lParam)) { returnCode = 0; break; } diff --git a/src/video/windows/SDL_windowsmodes.c b/src/video/windows/SDL_windowsmodes.c index 0c4334fb1c2f5..adc3902ce41f0 100644 --- a/src/video/windows/SDL_windowsmodes.c +++ b/src/video/windows/SDL_windowsmodes.c @@ -193,19 +193,8 @@ static SDL_bool WIN_GetDisplayMode(_THIS, LPCWSTR deviceName, DWORD index, SDL_D return SDL_TRUE; } -/* The win32 API calls in this function require Windows Vista or later. */ -/* *INDENT-OFF* */ /* clang-format off */ -typedef LONG (WINAPI *SDL_WIN32PROC_GetDisplayConfigBufferSizes)(UINT32 flags, UINT32* numPathArrayElements, UINT32* numModeInfoArrayElements); -typedef LONG (WINAPI *SDL_WIN32PROC_QueryDisplayConfig)(UINT32 flags, UINT32* numPathArrayElements, DISPLAYCONFIG_PATH_INFO* pathArray, UINT32* numModeInfoArrayElements, DISPLAYCONFIG_MODE_INFO* modeInfoArray, DISPLAYCONFIG_TOPOLOGY_ID* currentTopologyId); -typedef LONG (WINAPI *SDL_WIN32PROC_DisplayConfigGetDeviceInfo)(DISPLAYCONFIG_DEVICE_INFO_HEADER* requestPacket); -/* *INDENT-ON* */ /* clang-format on */ - -static char *WIN_GetDisplayNameVista(const WCHAR *deviceName) +static char *WIN_GetDisplayNameVista(SDL_VideoData *videodata, const WCHAR *deviceName) { - void *dll; - SDL_WIN32PROC_GetDisplayConfigBufferSizes pGetDisplayConfigBufferSizes; - SDL_WIN32PROC_QueryDisplayConfig pQueryDisplayConfig; - SDL_WIN32PROC_DisplayConfigGetDeviceInfo pDisplayConfigGetDeviceInfo; DISPLAYCONFIG_PATH_INFO *paths = NULL; DISPLAYCONFIG_MODE_INFO *modes = NULL; char *retval = NULL; @@ -214,21 +203,12 @@ static char *WIN_GetDisplayNameVista(const WCHAR *deviceName) UINT32 i; LONG rc; - dll = SDL_LoadObject("USER32.DLL"); - if (!dll) { + if (!videodata->GetDisplayConfigBufferSizes || !videodata->QueryDisplayConfig || !videodata->DisplayConfigGetDeviceInfo) { return NULL; } - pGetDisplayConfigBufferSizes = (SDL_WIN32PROC_GetDisplayConfigBufferSizes)SDL_LoadFunction(dll, "GetDisplayConfigBufferSizes"); - pQueryDisplayConfig = (SDL_WIN32PROC_QueryDisplayConfig)SDL_LoadFunction(dll, "QueryDisplayConfig"); - pDisplayConfigGetDeviceInfo = (SDL_WIN32PROC_DisplayConfigGetDeviceInfo)SDL_LoadFunction(dll, "DisplayConfigGetDeviceInfo"); - - if (!pGetDisplayConfigBufferSizes || !pQueryDisplayConfig || !pDisplayConfigGetDeviceInfo) { - goto WIN_GetDisplayNameVista_failed; - } - do { - rc = pGetDisplayConfigBufferSizes(QDC_ONLY_ACTIVE_PATHS, &pathCount, &modeCount); + rc = videodata->GetDisplayConfigBufferSizes(QDC_ONLY_ACTIVE_PATHS, &pathCount, &modeCount); if (rc != ERROR_SUCCESS) { goto WIN_GetDisplayNameVista_failed; } @@ -242,7 +222,7 @@ static char *WIN_GetDisplayNameVista(const WCHAR *deviceName) goto WIN_GetDisplayNameVista_failed; } - rc = pQueryDisplayConfig(QDC_ONLY_ACTIVE_PATHS, &pathCount, paths, &modeCount, modes, 0); + rc = videodata->QueryDisplayConfig(QDC_ONLY_ACTIVE_PATHS, &pathCount, paths, &modeCount, modes, 0); } while (rc == ERROR_INSUFFICIENT_BUFFER); if (rc == ERROR_SUCCESS) { @@ -255,7 +235,7 @@ static char *WIN_GetDisplayNameVista(const WCHAR *deviceName) sourceName.header.type = DISPLAYCONFIG_DEVICE_INFO_GET_SOURCE_NAME; sourceName.header.size = sizeof(sourceName); sourceName.header.id = paths[i].sourceInfo.id; - rc = pDisplayConfigGetDeviceInfo(&sourceName.header); + rc = videodata->DisplayConfigGetDeviceInfo(&sourceName.header); if (rc != ERROR_SUCCESS) { break; } else if (SDL_wcscmp(deviceName, sourceName.viewGdiDeviceName) != 0) { @@ -267,7 +247,7 @@ static char *WIN_GetDisplayNameVista(const WCHAR *deviceName) targetName.header.id = paths[i].targetInfo.id; targetName.header.type = DISPLAYCONFIG_DEVICE_INFO_GET_TARGET_NAME; targetName.header.size = sizeof(targetName); - rc = pDisplayConfigGetDeviceInfo(&targetName.header); + rc = videodata->DisplayConfigGetDeviceInfo(&targetName.header); if (rc == ERROR_SUCCESS) { retval = WIN_StringToUTF8W(targetName.monitorFriendlyDeviceName); /* if we got an empty string, treat it as failure so we'll fallback @@ -283,14 +263,12 @@ static char *WIN_GetDisplayNameVista(const WCHAR *deviceName) SDL_free(paths); SDL_free(modes); - SDL_UnloadObject(dll); return retval; WIN_GetDisplayNameVista_failed: SDL_free(retval); SDL_free(paths); SDL_free(modes); - SDL_UnloadObject(dll); return NULL; } @@ -360,7 +338,7 @@ static void WIN_AddDisplay(_THIS, HMONITOR hMonitor, const MONITORINFOEXW *info, displaydata->IsValid = SDL_TRUE; SDL_zero(display); - display.name = WIN_GetDisplayNameVista(info->szDevice); + display.name = WIN_GetDisplayNameVista(_this->driverdata, info->szDevice); if (!display.name) { DISPLAY_DEVICEW device; SDL_zero(device); diff --git a/src/video/windows/SDL_windowsvideo.c b/src/video/windows/SDL_windowsvideo.c index 7f60dc4eff59f..7c0265805485b 100644 --- a/src/video/windows/SDL_windowsvideo.c +++ b/src/video/windows/SDL_windowsvideo.c @@ -139,6 +139,9 @@ static SDL_VideoDevice *WIN_CreateDevice(void) data->GetDpiForWindow = (UINT (WINAPI *)(HWND))SDL_LoadFunction(data->userDLL, "GetDpiForWindow"); data->AreDpiAwarenessContextsEqual = (BOOL (WINAPI *)(DPI_AWARENESS_CONTEXT, DPI_AWARENESS_CONTEXT))SDL_LoadFunction(data->userDLL, "AreDpiAwarenessContextsEqual"); data->IsValidDpiAwarenessContext = (BOOL (WINAPI *)(DPI_AWARENESS_CONTEXT))SDL_LoadFunction(data->userDLL, "IsValidDpiAwarenessContext"); + data->GetDisplayConfigBufferSizes = (LONG (WINAPI *)(UINT32,UINT32*,UINT32* ))SDL_LoadFunction(data->userDLL, "GetDisplayConfigBufferSizes"); + data->QueryDisplayConfig = (LONG (WINAPI *)(UINT32,UINT32*,DISPLAYCONFIG_PATH_INFO*,UINT32*,DISPLAYCONFIG_MODE_INFO*,DISPLAYCONFIG_TOPOLOGY_ID*))SDL_LoadFunction(data->userDLL, "QueryDisplayConfig"); + data->DisplayConfigGetDeviceInfo = (LONG (WINAPI *)(DISPLAYCONFIG_DEVICE_INFO_HEADER*))SDL_LoadFunction(data->userDLL, "DisplayConfigGetDeviceInfo"); /* *INDENT-ON* */ /* clang-format on */ } else { SDL_ClearError(); diff --git a/src/video/windows/SDL_windowsvideo.h b/src/video/windows/SDL_windowsvideo.h index 617f116a1ec51..1818e79355a45 100644 --- a/src/video/windows/SDL_windowsvideo.h +++ b/src/video/windows/SDL_windowsvideo.h @@ -389,6 +389,10 @@ typedef struct SDL_VideoData UINT (WINAPI *GetDpiForWindow)( HWND ); BOOL (WINAPI *AreDpiAwarenessContextsEqual)(DPI_AWARENESS_CONTEXT, DPI_AWARENESS_CONTEXT); BOOL (WINAPI *IsValidDpiAwarenessContext)(DPI_AWARENESS_CONTEXT); + /* DisplayConfig functions */ + LONG (WINAPI *GetDisplayConfigBufferSizes)( UINT32, UINT32*, UINT32* ); + LONG (WINAPI *QueryDisplayConfig)( UINT32, UINT32*, DISPLAYCONFIG_PATH_INFO*, UINT32*, DISPLAYCONFIG_MODE_INFO*, DISPLAYCONFIG_TOPOLOGY_ID*); + LONG (WINAPI *DisplayConfigGetDeviceInfo)( DISPLAYCONFIG_DEVICE_INFO_HEADER*); /* *INDENT-ON* */ /* clang-format on */ void *shcoreDLL; diff --git a/src/video/winrt/SDL_winrtmessagebox.cpp b/src/video/winrt/SDL_winrtmessagebox.cpp index 7ef54781dac3c..b8469a7227c7e 100644 --- a/src/video/winrt/SDL_winrtmessagebox.cpp +++ b/src/video/winrt/SDL_winrtmessagebox.cpp @@ -35,7 +35,7 @@ using namespace Windows::Foundation; using namespace Windows::UI::Popups; static String ^ WINRT_UTF8ToPlatformString(const char *str) { - wchar_t *wstr = WIN_UTF8ToString(str); + wchar_t *wstr = WIN_UTF8ToStringW(str); String ^ rtstr = ref new String(wstr); SDL_free(wstr); return rtstr; diff --git a/src/video/winrt/SDL_winrtvideo.cpp b/src/video/winrt/SDL_winrtvideo.cpp index e7bdadb29b79b..3edf770caf55d 100644 --- a/src/video/winrt/SDL_winrtvideo.cpp +++ b/src/video/winrt/SDL_winrtvideo.cpp @@ -321,7 +321,7 @@ static int WINRT_AddDisplaysForOutput(_THIS, IDXGIAdapter1 *dxgiAdapter1, int ou WIN_SetErrorFromHRESULT(__FUNCTION__ ", IDXGIOutput::FindClosestMatchingMode failed", hr); goto done; } else { - displayName = WIN_StringToUTF8(dxgiOutputDesc.DeviceName); + displayName = WIN_StringToUTF8W(dxgiOutputDesc.DeviceName); display.name = displayName; WINRT_DXGIModeToSDLDisplayMode(&closestMatch, &display.desktop_mode); display.current_mode = display.desktop_mode; diff --git a/src/video/x11/SDL_x11messagebox.c b/src/video/x11/SDL_x11messagebox.c index 58684930f81cf..9dd2887a865e7 100644 --- a/src/video/x11/SDL_x11messagebox.c +++ b/src/video/x11/SDL_x11messagebox.c @@ -125,12 +125,15 @@ static SDL_INLINE int IntMax(int a, int b) /* Return width and height for a string. */ static void GetTextWidthHeight(SDL_MessageBoxDataX11 *data, const char *str, int nbytes, int *pwidth, int *pheight) { +#ifdef X_HAVE_UTF8_STRING if (SDL_X11_HAVE_UTF8) { XRectangle overall_ink, overall_logical; X11_Xutf8TextExtents(data->font_set, str, nbytes, &overall_ink, &overall_logical); *pwidth = overall_logical.width; *pheight = overall_logical.height; - } else { + } else +#endif + { XCharStruct text_structure; int font_direction, font_ascent, font_descent; X11_XTextExtents(data->font_struct, str, nbytes, @@ -186,6 +189,7 @@ static int X11_MessageBoxInit(SDL_MessageBoxDataX11 *data, const SDL_MessageBoxD return SDL_SetError("Couldn't open X11 display"); } +#ifdef X_HAVE_UTF8_STRING if (SDL_X11_HAVE_UTF8) { char **missing = NULL; int num_missing = 0; @@ -197,7 +201,9 @@ static int X11_MessageBoxInit(SDL_MessageBoxDataX11 *data, const SDL_MessageBoxD if (!data->font_set) { return SDL_SetError("Couldn't load font %s", g_MessageBoxFont); } - } else { + } else +#endif + { data->font_struct = X11_XLoadQueryFont(data->display, g_MessageBoxFontLatin1); if (!data->font_struct) { return SDL_SetError("Couldn't load font %s", g_MessageBoxFontLatin1); @@ -536,11 +542,14 @@ static void X11_MessageBoxDraw(SDL_MessageBoxDataX11 *data, GC ctx) for (i = 0; i < data->numlines; i++) { TextLineData *plinedata = &data->linedata[i]; +#ifdef X_HAVE_UTF8_STRING if (SDL_X11_HAVE_UTF8) { X11_Xutf8DrawString(display, window, data->font_set, ctx, data->xtext, data->ytext + i * data->text_height, plinedata->text, plinedata->length); - } else { + } else +#endif + { X11_XDrawString(display, window, ctx, data->xtext, data->ytext + i * data->text_height, plinedata->text, plinedata->length); @@ -565,12 +574,15 @@ static void X11_MessageBoxDraw(SDL_MessageBoxDataX11 *data, GC ctx) X11_XSetForeground(display, ctx, (data->mouse_over_index == i) ? data->color[SDL_MESSAGEBOX_COLOR_BUTTON_SELECTED] : data->color[SDL_MESSAGEBOX_COLOR_TEXT]); +#ifdef X_HAVE_UTF8_STRING if (SDL_X11_HAVE_UTF8) { X11_Xutf8DrawString(display, window, data->font_set, ctx, buttondatax11->x + offset, buttondatax11->y + offset, buttondata->text, buttondatax11->length); - } else { + } else +#endif + { X11_XDrawString(display, window, ctx, buttondatax11->x + offset, buttondatax11->y + offset, buttondata->text, buttondatax11->length); @@ -604,12 +616,17 @@ static int X11_MessageBoxLoop(SDL_MessageBoxDataX11 *data) SDL_bool has_focus = SDL_TRUE; KeySym last_key_pressed = XK_VoidSymbol; unsigned long gcflags = GCForeground | GCBackground; +#ifdef X_HAVE_UTF8_STRING + const int have_utf8 = SDL_X11_HAVE_UTF8; +#else + const int have_utf8 = 0; +#endif SDL_zero(ctx_vals); ctx_vals.foreground = data->color[SDL_MESSAGEBOX_COLOR_BACKGROUND]; ctx_vals.background = data->color[SDL_MESSAGEBOX_COLOR_BACKGROUND]; - if (!SDL_X11_HAVE_UTF8) { + if (!have_utf8) { gcflags |= GCFont; ctx_vals.font = data->font_struct->fid; } diff --git a/src/video/x11/SDL_x11sym.h b/src/video/x11/SDL_x11sym.h index cc1a658c174a5..2fc12ceefa15e 100644 --- a/src/video/x11/SDL_x11sym.h +++ b/src/video/x11/SDL_x11sym.h @@ -99,7 +99,7 @@ SDL_X11_SYM(Status,XInitThreads,(void),(),return) SDL_X11_SYM(int,XPeekEvent,(Display* a,XEvent* b),(a,b),return) SDL_X11_SYM(int,XPending,(Display* a),(a),return) SDL_X11_SYM(int,XPutImage,(Display* a,Drawable b,GC c,XImage* d,int e,int f,int g,int h,unsigned int i,unsigned int j),(a,b,c,d,e,f,g,h,i,j),return) -SDL_X11_SYM(int,XQueryKeymap,(Display* a,char *b),(a,b),return) +SDL_X11_SYM(int,XQueryKeymap,(Display* a,char b[32]),(a,b),return) SDL_X11_SYM(Bool,XQueryPointer,(Display* a,Window b,Window* c,Window* d,int* e,int* f,int* g,int* h,unsigned int* i),(a,b,c,d,e,f,g,h,i),return) SDL_X11_SYM(int,XRaiseWindow,(Display* a,Window b),(a,b),return) SDL_X11_SYM(int,XReparentWindow,(Display* a,Window b,Window c,int d,int e),(a,b,c,d,e),return) diff --git a/src/video/x11/SDL_x11window.c b/src/video/x11/SDL_x11window.c index a32ea483f70a1..cde53c4a3abfc 100644 --- a/src/video/x11/SDL_x11window.c +++ b/src/video/x11/SDL_x11window.c @@ -285,8 +285,8 @@ static int SetupWindowData(_THIS, SDL_Window *window, Window w, BOOL created) 1) * sizeof(*windowlist)); if (!windowlist) { - SDL_free(data); - return SDL_OutOfMemory(); + SDL_OutOfMemory(); + goto error_cleanup; } windowlist[numwindows] = data; videodata->numwindows++; @@ -331,9 +331,45 @@ static int SetupWindowData(_THIS, SDL_Window *window, Window w, BOOL created) } } +#if defined(SDL_VIDEO_OPENGL_ES) || defined(SDL_VIDEO_OPENGL_ES2) || defined(SDL_VIDEO_OPENGL_EGL) + if ((window->flags & SDL_WINDOW_OPENGL) && + ((_this->gl_config.profile_mask == SDL_GL_CONTEXT_PROFILE_ES) || + SDL_GetHintBoolean(SDL_HINT_VIDEO_X11_FORCE_EGL, SDL_FALSE)) +#ifdef SDL_VIDEO_OPENGL_GLX + && (!_this->gl_data || X11_GL_UseEGL(_this) ) +#endif + ) { +#ifdef SDL_VIDEO_OPENGL_EGL + if (!_this->egl_data) { + goto error_cleanup; + } + + /* Create the GLES window surface */ + data->egl_surface = SDL_EGL_CreateSurface(_this, (NativeWindowType)w); + + if (data->egl_surface == EGL_NO_SURFACE) { + SDL_SetError("Could not create GLES window surface"); + goto error_cleanup; + } +#else + SDL_SetError("Could not create GLES window surface (EGL support not configured)"); + goto error_cleanup; +#endif /* SDL_VIDEO_OPENGL_EGL */ + } +#endif + /* All done! */ window->driverdata = data; return 0; + +error_cleanup: +#ifdef X_HAVE_UTF8_STRING + if (data->ic) { + X11_XDestroyIC(data->ic); + } +#endif + SDL_free(data); + return -1; } static void SetWindowBordered(Display *display, int screen, Window window, SDL_bool border) @@ -634,31 +670,6 @@ int X11_CreateWindow(_THIS, SDL_Window *window) } windowdata = (SDL_WindowData *)window->driverdata; -#if defined(SDL_VIDEO_OPENGL_ES) || defined(SDL_VIDEO_OPENGL_ES2) || defined(SDL_VIDEO_OPENGL_EGL) - if ((window->flags & SDL_WINDOW_OPENGL) && - ((_this->gl_config.profile_mask == SDL_GL_CONTEXT_PROFILE_ES) || - SDL_GetHintBoolean(SDL_HINT_VIDEO_X11_FORCE_EGL, SDL_FALSE)) -#ifdef SDL_VIDEO_OPENGL_GLX - && (!_this->gl_data || X11_GL_UseEGL(_this) ) -#endif - ) { -#ifdef SDL_VIDEO_OPENGL_EGL - if (!_this->egl_data) { - return -1; - } - - /* Create the GLES window surface */ - windowdata->egl_surface = SDL_EGL_CreateSurface(_this, (NativeWindowType)w); - - if (windowdata->egl_surface == EGL_NO_SURFACE) { - return SDL_SetError("Could not create GLES window surface"); - } -#else - return SDL_SetError("Could not create GLES window surface (EGL support not configured)"); -#endif /* SDL_VIDEO_OPENGL_EGL */ - } -#endif - #ifdef X_HAVE_UTF8_STRING if (SDL_X11_HAVE_UTF8 && windowdata->ic) { X11_XGetICValues(windowdata->ic, XNFilterEvents, &fevent, NULL); @@ -861,11 +872,6 @@ void X11_SetWindowMinimumSize(_THIS, SDL_Window *window) X11_XSetWMNormalHints(display, data->xwindow, sizehints); X11_XFree(sizehints); - - /* See comment in X11_SetWindowSize. */ - X11_XResizeWindow(display, data->xwindow, window->w, window->h); - X11_XMoveWindow(display, data->xwindow, window->x - data->border_left, window->y - data->border_top); - X11_XRaiseWindow(display, data->xwindow); } X11_XFlush(display); @@ -889,11 +895,6 @@ void X11_SetWindowMaximumSize(_THIS, SDL_Window *window) X11_XSetWMNormalHints(display, data->xwindow, sizehints); X11_XFree(sizehints); - - /* See comment in X11_SetWindowSize. */ - X11_XResizeWindow(display, data->xwindow, window->w, window->h); - X11_XMoveWindow(display, data->xwindow, window->x - data->border_left, window->y - data->border_top); - X11_XRaiseWindow(display, data->xwindow); } X11_XFlush(display);