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

Sync wiki -> header.

This commit is contained in:
Ryan C. Gordon 2021-07-14 17:07:04 -04:00
parent f8c1fc49d9
commit c88eb7a896
No known key found for this signature in database
GPG Key ID: FA148B892AB48044
31 changed files with 635 additions and 654 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
include/SDL.h
View File

@ -178,9 +178,8 @@ extern DECLSPEC void SDLCALL SDL_QuitSubSystem(Uint32 flags);
* Get a mask of the specified subsystems which are currently initialized. * Get a mask of the specified subsystems which are currently initialized.
* *
* \param flags any of the flags used by SDL_Init(); see SDL_Init for details. * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
* \returns a mask of all initialized subsystems if `flags` is 0, * \returns a mask of all initialized subsystems if `flags` is 0, otherwise it
* otherwise it returns the initialization status of the specified * returns the initialization status of the specified subsystems.
* subsystems.
* *
* The return value does not include SDL_INIT_NOPARACHUTE. * The return value does not include SDL_INIT_NOPARACHUTE.
* *

24
include/SDL_atomic.h
View File

@ -159,17 +159,17 @@ extern _inline void SDL_CompilerBarrier (void);
* Memory barriers are designed to prevent reads and writes from being * Memory barriers are designed to prevent reads and writes from being
* reordered by the compiler and being seen out of order on multi-core CPUs. * reordered by the compiler and being seen out of order on multi-core CPUs.
* *
* A typical pattern would be for thread A to write some data and a flag, * A typical pattern would be for thread A to write some data and a flag, and
* and for thread B to read the flag and get the data. In this case you * for thread B to read the flag and get the data. In this case you would
* would insert a release barrier between writing the data and the flag, * insert a release barrier between writing the data and the flag,
* guaranteeing that the data write completes no later than the flag is * guaranteeing that the data write completes no later than the flag is
* written, and you would insert an acquire barrier between reading the * written, and you would insert an acquire barrier between reading the flag
* flag and reading the data, to ensure that all the reads associated * and reading the data, to ensure that all the reads associated with the flag
* with the flag have completed. * have completed.
* *
* In this pattern you should always see a release barrier paired with * In this pattern you should always see a release barrier paired with an
* an acquire barrier and you should gate the data reads/writes with a * acquire barrier and you should gate the data reads/writes with a single
* single flag variable. * flag variable.
* *
* For more information on these semantics, take a look at the blog post: * For more information on these semantics, take a look at the blog post:
* http://preshing.com/20120913/acquire-and-release-semantics * http://preshing.com/20120913/acquire-and-release-semantics
@ -238,8 +238,7 @@ typedef void (*SDL_KernelMemoryBarrierFunc)();
typedef struct { int value; } SDL_atomic_t; typedef struct { int value; } SDL_atomic_t;
/** /**
* Set an atomic variable to a new value if it is * Set an atomic variable to a new value if it is currently an old value.
* currently an old value.
* *
* ***Note: If you don't know what this function is for, you shouldn't use * ***Note: If you don't know what this function is for, you shouldn't use
* it!*** * it!***
@ -321,8 +320,7 @@ extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_atomic_t *a, int v);
#endif #endif
/** /**
* Set a pointer to a new value if it is currently an old * Set a pointer to a new value if it is currently an old value.
* value.
* *
* ***Note: If you don't know what this function is for, you shouldn't use * ***Note: If you don't know what this function is for, you shouldn't use
* it!*** * it!***

269
include/SDL_audio.h
View File

@ -307,8 +307,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
* means you can only have one device open at a time with this function. * means you can only have one device open at a time with this function.
* *
* \param desired an SDL_AudioSpec structure representing the desired output * \param desired an SDL_AudioSpec structure representing the desired output
* format. Please refer to the SDL_OpenAudioDevice documentation * format. Please refer to the SDL_OpenAudioDevice
* for details on how to prepare this structure. * documentation for details on how to prepare this structure.
* \param obtained an SDL_AudioSpec structure filled in with the actual * \param obtained an SDL_AudioSpec structure filled in with the actual
* parameters, or NULL. * parameters, or NULL.
* \returns 0 if successful, placing the actual hardware parameters in the * \returns 0 if successful, placing the actual hardware parameters in the
@ -317,8 +317,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
* If `obtained` is NULL, the audio data passed to the callback * If `obtained` is NULL, the audio data passed to the callback
* function will be guaranteed to be in the requested format, and * function will be guaranteed to be in the requested format, and
* will be automatically converted to the actual hardware audio * will be automatically converted to the actual hardware audio
* format if necessary. If `obtained` is NULL, `desired` will * format if necessary. If `obtained` is NULL, `desired` will have
* have fields modified. * fields modified.
* *
* This function returns a negative error code on failure to open the * This function returns a negative error code on failure to open the
* audio device or failure to set up the audio thread; call * audio device or failure to set up the audio thread; call
@ -350,8 +350,8 @@ typedef Uint32 SDL_AudioDeviceID;
* subsystem. * subsystem.
* *
* Note that audio capture support is not implemented as of SDL 2.0.4, so the * Note that audio capture support is not implemented as of SDL 2.0.4, so the
* `iscapture` parameter is for future expansion and should always be zero * `iscapture` parameter is for future expansion and should always be zero for
* for now. * now.
* *
* This function will return -1 if an explicit list of devices can't be * This function will return -1 if an explicit list of devices can't be
* determined. Returning -1 is not an error. For example, if SDL is set up to * determined. Returning -1 is not an error. For example, if SDL is set up to
@ -463,31 +463,31 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
* *
* - `desired->freq` should be the frequency in sample-frames-per-second (Hz). * - `desired->freq` should be the frequency in sample-frames-per-second (Hz).
* - `desired->format` should be the audio format (`AUDIO_S16SYS`, etc). * - `desired->format` should be the audio format (`AUDIO_S16SYS`, etc).
* - `desired->samples` is the desired size of the audio buffer, in * - `desired->samples` is the desired size of the audio buffer, in _sample
* _sample frames_ (with stereo output, two samples--left and right--would * frames_ (with stereo output, two samples--left and right--would make a
* make a single sample frame). This number should be a power of two, and * single sample frame). This number should be a power of two, and may be
* may be adjusted by the audio driver to a value more suitable for the * adjusted by the audio driver to a value more suitable for the hardware.
* hardware. Good values seem to range between 512 and 8096 inclusive, * Good values seem to range between 512 and 8096 inclusive, depending on
* depending on the application and CPU speed. Smaller values reduce * the application and CPU speed. Smaller values reduce latency, but can
* latency, but can lead to underflow if the application is doing heavy * lead to underflow if the application is doing heavy processing and cannot
* processing and cannot fill the audio buffer in time. Note that the * fill the audio buffer in time. Note that the number of sample frames is
* number of sample frames is directly related to time by the following * directly related to time by the following formula: `ms =
* formula: `ms = (sampleframes*1000)/freq` * (sampleframes*1000)/freq`
* - `desired->size` is the size in _bytes_ of the audio buffer, and is * - `desired->size` is the size in _bytes_ of the audio buffer, and is
* calculated by SDL_OpenAudioDevice(). You don't initialize this. * calculated by SDL_OpenAudioDevice(). You don't initialize this.
* - `desired->silence` is the value used to set the buffer to silence, * - `desired->silence` is the value used to set the buffer to silence, and is
* and is calculated by SDL_OpenAudioDevice(). You don't initialize this. * calculated by SDL_OpenAudioDevice(). You don't initialize this.
* - `desired->callback` should be set to a function that will be called * - `desired->callback` should be set to a function that will be called when
* when the audio device is ready for more data. It is passed a pointer * the audio device is ready for more data. It is passed a pointer to the
* to the audio buffer, and the length in bytes of the audio buffer. * audio buffer, and the length in bytes of the audio buffer. This function
* This function usually runs in a separate thread, and so you should * usually runs in a separate thread, and so you should protect data
* protect data structures that it accesses by calling SDL_LockAudioDevice() * structures that it accesses by calling SDL_LockAudioDevice() and
* and SDL_UnlockAudioDevice() in your code. Alternately, you may pass a NULL * SDL_UnlockAudioDevice() in your code. Alternately, you may pass a NULL
* pointer here, and call SDL_QueueAudio() with some frequency, to queue * pointer here, and call SDL_QueueAudio() with some frequency, to queue
* more audio samples to be played (or for capture devices, call * more audio samples to be played (or for capture devices, call
* SDL_DequeueAudio() with some frequency, to obtain audio samples). * SDL_DequeueAudio() with some frequency, to obtain audio samples).
* - `desired->userdata` is passed as the first parameter to your callback * - `desired->userdata` is passed as the first parameter to your callback
* function. If you passed a NULL callback, this value is ignored. * function. If you passed a NULL callback, this value is ignored.
* *
* `allowed_changes` can have the following flags OR'd together: * `allowed_changes` can have the following flags OR'd together:
* *
@ -502,11 +502,10 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
* *
* For example, if you ask for float32 audio format, but the sound card only * For example, if you ask for float32 audio format, but the sound card only
* supports int16, SDL will set the hardware to int16. If you had set * supports int16, SDL will set the hardware to int16. If you had set
* SDL_AUDIO_ALLOW_FORMAT_CHANGE, SDL will change the format in the * SDL_AUDIO_ALLOW_FORMAT_CHANGE, SDL will change the format in the `obtained`
* `obtained` structure. If that flag was *not* set, SDL will prepare to * structure. If that flag was *not* set, SDL will prepare to convert your
* convert your callback's float32 audio to int16 before feeding it to the * callback's float32 audio to int16 before feeding it to the hardware and
* hardware and will keep the originally requested format in the `obtained` * will keep the originally requested format in the `obtained` structure.
* structure.
* *
* If your application can only handle one specific data format, pass a zero * If your application can only handle one specific data format, pass a zero
* for `allowed_changes` and let SDL transparently handle any differences. * for `allowed_changes` and let SDL transparently handle any differences.
@ -590,24 +589,24 @@ extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
/** /**
* Load the audio data of a WAVE file into memory. * Load the audio data of a WAVE file into memory.
* *
* Loading a WAVE file requires `src`, `spec`, `audio_buf` and `audio_len` * Loading a WAVE file requires `src`, `spec`, `audio_buf` and `audio_len` to
* to be valid pointers. The entire data portion of the file is then loaded * be valid pointers. The entire data portion of the file is then loaded into
* into memory and decoded if necessary. * memory and decoded if necessary.
* *
* If `freesrc` is non-zero, the data source gets automatically closed and * If `freesrc` is non-zero, the data source gets automatically closed and
* freed before the function returns. * freed before the function returns.
* *
* Supported formats are RIFF WAVE files with the formats PCM (8, 16, 24, and * Supported formats are RIFF WAVE files with the formats PCM (8, 16, 24, and
* 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), * 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and
* and A-law and mu-law (8 bits). Other formats are currently unsupported and * A-law and mu-law (8 bits). Other formats are currently unsupported and
* cause an error. * cause an error.
* *
* If this function succeeds, the pointer returned by it is equal to `spec` * If this function succeeds, the pointer returned by it is equal to `spec`
* and the pointer to the audio data allocated by the function is written to * and the pointer to the audio data allocated by the function is written to
* `audio_buf` and its length in bytes to `audio_len`. The SDL_AudioSpec * `audio_buf` and its length in bytes to `audio_len`. The SDL_AudioSpec
* members `freq`, `channels`, and `format` are set to the values of the * members `freq`, `channels`, and `format` are set to the values of the audio
* audio data in the buffer. The `samples` member is set to a sane default * data in the buffer. The `samples` member is set to a sane default and all
* and all others are set to zero. * others are set to zero.
* *
* It's necessary to use SDL_FreeWAV() to free the audio data returned in * It's necessary to use SDL_FreeWAV() to free the audio data returned in
* `audio_buf` when it is no longer used. * `audio_buf` when it is no longer used.
@ -616,19 +615,21 @@ extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
* problematic files in the wild that cause issues with strict decoders. To * problematic files in the wild that cause issues with strict decoders. To
* provide compatibility with these files, this decoder is lenient in regards * provide compatibility with these files, this decoder is lenient in regards
* to the truncation of the file, the fact chunk, and the size of the RIFF * to the truncation of the file, the fact chunk, and the size of the RIFF
* chunk. The hints `SDL_HINT_WAVE_RIFF_CHUNK_SIZE`, `SDL_HINT_WAVE_TRUNCATION`, * chunk. The hints `SDL_HINT_WAVE_RIFF_CHUNK_SIZE`,
* and `SDL_HINT_WAVE_FACT_CHUNK` can be used to tune the behavior of the * `SDL_HINT_WAVE_TRUNCATION`, and `SDL_HINT_WAVE_FACT_CHUNK` can be used to
* loading process. * tune the behavior of the loading process.
* *
* Any file that is invalid (due to truncation, corruption, or wrong values in * Any file that is invalid (due to truncation, corruption, or wrong values in
* the headers), too big, or unsupported causes an error. Additionally, any * the headers), too big, or unsupported causes an error. Additionally, any
* critical I/O error from the data source will terminate the loading process * critical I/O error from the data source will terminate the loading process
* with an error. The function returns NULL on error and in all cases (with the * with an error. The function returns NULL on error and in all cases (with
* exception of `src` being NULL), an appropriate error message will be set. * the exception of `src` being NULL), an appropriate error message will be
* set.
* *
* It is required that the data source supports seeking. * It is required that the data source supports seeking.
* *
* Example: * Example:
*
* ```c++ * ```c++
* SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, &spec, &buf, &len); * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, &spec, &buf, &len);
* ``` * ```
@ -644,8 +645,10 @@ extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
* \param freesrc If non-zero, SDL will _always_ free the data source * \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 * \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_buf A pointer filled with the audio data, allocated by the
* \param audio_len A pointer filled with the length of the audio data buffer in bytes * function.
* \param audio_len A pointer filled with the length of the audio data buffer
* in bytes
* \returns This function, if successfully called, returns `spec`, which will * \returns This function, if successfully called, returns `spec`, which will
* be filled with the audio data format of the wave source data. * be filled with the audio data format of the wave source data.
* `audio_buf` will be filled with a pointer to an allocated buffer * `audio_buf` will be filled with a pointer to an allocated buffer
@ -713,8 +716,7 @@ extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf);
* \param dst_format the destination format of the audio data; for more info * \param dst_format the destination format of the audio data; for more info
* see SDL_AudioFormat * see SDL_AudioFormat
* \param dst_channels the number of channels in the destination * \param dst_channels the number of channels in the destination
* \param dst_rate the frequency (sample-frames-per-second) of the * \param dst_rate the frequency (sample-frames-per-second) of the destination
* destination
* \returns 1 if the audio filter is prepared, 0 if no conversion is needed, * \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 * or a negative error code on failure; call SDL_GetError() for more
* information. * information.
@ -749,8 +751,8 @@ extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
* in-place, the application must allocate a buffer that will fully contain * in-place, the application must allocate a buffer that will fully contain
* the data during its largest conversion pass. After SDL_BuildAudioCVT() * the data during its largest conversion pass. After SDL_BuildAudioCVT()
* returns, the application should set the `cvt->len` field to the size, in * returns, the application should set the `cvt->len` field to the size, in
* bytes, of the source data, and allocate a buffer that is * bytes, of the source data, and allocate a buffer that is `cvt->len *
* `cvt->len * cvt->len_mult` bytes long for the `buf` field. * cvt->len_mult` bytes long for the `buf` field.
* *
* The source data should be copied into this buffer before the call to * The source data should be copied into this buffer before the call to
* SDL_ConvertAudio(). Upon successful return, this buffer will contain the * SDL_ConvertAudio(). Upon successful return, this buffer will contain the
@ -779,22 +781,22 @@ struct _SDL_AudioStream;
typedef struct _SDL_AudioStream SDL_AudioStream; typedef struct _SDL_AudioStream SDL_AudioStream;
/** /**
* Create a new audio stream. * Create a new audio stream.
* *
* \param src_format The format of the source audio * \param src_format The format of the source audio
* \param src_channels The number of channels 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 src_rate The sampling rate of the source audio
* \param dst_format The format of the desired audio output * \param dst_format The format of the desired audio output
* \param dst_channels The number of channels 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 dst_rate The sampling rate of the desired audio output
* \returns 0 on success, or -1 on error. * \returns 0 on success, or -1 on error.
* *
* \sa SDL_AudioStreamPut * \sa SDL_AudioStreamPut
* \sa SDL_AudioStreamGet * \sa SDL_AudioStreamGet
* \sa SDL_AudioStreamAvailable * \sa SDL_AudioStreamAvailable
* \sa SDL_AudioStreamFlush * \sa SDL_AudioStreamFlush
* \sa SDL_AudioStreamClear * \sa SDL_AudioStreamClear
* \sa SDL_FreeAudioStream * \sa SDL_FreeAudioStream
*/ */
extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioFormat src_format, extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioFormat src_format,
const Uint8 src_channels, const Uint8 src_channels,
@ -804,92 +806,93 @@ extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioForm
const int dst_rate); const int dst_rate);
/** /**
* Add data to be converted/resampled to the stream. * Add data to be converted/resampled to the stream.
* *
* \param stream The stream the audio data is being added to * \param stream The stream the audio data is being added to
* \param buf A pointer to the audio data to add * \param buf A pointer to the audio data to add
* \param len The number of bytes to write to the stream * \param len The number of bytes to write to the stream
* \returns 0 on success, or -1 on error. * \returns 0 on success, or -1 on error.
* *
* \sa SDL_NewAudioStream * \sa SDL_NewAudioStream
* \sa SDL_AudioStreamGet * \sa SDL_AudioStreamGet
* \sa SDL_AudioStreamAvailable * \sa SDL_AudioStreamAvailable
* \sa SDL_AudioStreamFlush * \sa SDL_AudioStreamFlush
* \sa SDL_AudioStreamClear * \sa SDL_AudioStreamClear
* \sa SDL_FreeAudioStream * \sa SDL_FreeAudioStream
*/ */
extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const void *buf, int len); extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const void *buf, int len);
/** /**
* Get converted/resampled data from the stream * Get converted/resampled data from the stream
* *
* \param stream The stream the audio is being requested from * \param stream The stream the audio is being requested from
* \param buf A buffer to fill with audio data * \param buf A buffer to fill with audio data
* \param len The maximum number of bytes to fill * \param len The maximum number of bytes to fill
* \returns the number of bytes read from the stream, or -1 on error * \returns the number of bytes read from the stream, or -1 on error
* *
* \sa SDL_NewAudioStream * \sa SDL_NewAudioStream
* \sa SDL_AudioStreamPut * \sa SDL_AudioStreamPut
* \sa SDL_AudioStreamAvailable * \sa SDL_AudioStreamAvailable
* \sa SDL_AudioStreamFlush * \sa SDL_AudioStreamFlush
* \sa SDL_AudioStreamClear * \sa SDL_AudioStreamClear
* \sa SDL_FreeAudioStream * \sa SDL_FreeAudioStream
*/ */
extern DECLSPEC int SDLCALL SDL_AudioStreamGet(SDL_AudioStream *stream, void *buf, int len); extern DECLSPEC int SDLCALL SDL_AudioStreamGet(SDL_AudioStream *stream, void *buf, int len);
/** /**
* Get the number of converted/resampled bytes available. The stream may be * Get the number of converted/resampled bytes available.
* buffering data behind the scenes until it has enough to resample
* correctly, so this number might be lower than what you expect, or even
* be zero. Add more data or flush the stream if you need the data now.
* *
* \sa SDL_NewAudioStream * The stream may be buffering data behind the scenes until it has enough to
* \sa SDL_AudioStreamPut * resample correctly, so this number might be lower than what you expect, or
* \sa SDL_AudioStreamGet * even be zero. Add more data or flush the stream if you need the data now.
* \sa SDL_AudioStreamFlush *
* \sa SDL_AudioStreamClear * \sa SDL_NewAudioStream
* \sa SDL_FreeAudioStream * \sa SDL_AudioStreamPut
* \sa SDL_AudioStreamGet
* \sa SDL_AudioStreamFlush
* \sa SDL_AudioStreamClear
* \sa SDL_FreeAudioStream
*/ */
extern DECLSPEC int SDLCALL SDL_AudioStreamAvailable(SDL_AudioStream *stream); extern DECLSPEC int SDLCALL SDL_AudioStreamAvailable(SDL_AudioStream *stream);
/** /**
* Tell the stream that you're done sending data, and anything being buffered * Tell the stream that you're done sending data, and anything being buffered
* should be converted/resampled and made available immediately. * should be converted/resampled and made available immediately.
* *
* It is legal to add more data to a stream after flushing, but there will * It is legal to add more data to a stream after flushing, but there will be
* be audio gaps in the output. Generally this is intended to signal the * audio gaps in the output. Generally this is intended to signal the end of
* end of input, so the complete output becomes available. * input, so the complete output becomes available.
* *
* \sa SDL_NewAudioStream * \sa SDL_NewAudioStream
* \sa SDL_AudioStreamPut * \sa SDL_AudioStreamPut
* \sa SDL_AudioStreamGet * \sa SDL_AudioStreamGet
* \sa SDL_AudioStreamAvailable * \sa SDL_AudioStreamAvailable
* \sa SDL_AudioStreamClear * \sa SDL_AudioStreamClear
* \sa SDL_FreeAudioStream * \sa SDL_FreeAudioStream
*/ */
extern DECLSPEC int SDLCALL SDL_AudioStreamFlush(SDL_AudioStream *stream); extern DECLSPEC int SDLCALL SDL_AudioStreamFlush(SDL_AudioStream *stream);
/** /**
* Clear any pending data in the stream without converting it * Clear any pending data in the stream without converting it
* *
* \sa SDL_NewAudioStream * \sa SDL_NewAudioStream
* \sa SDL_AudioStreamPut * \sa SDL_AudioStreamPut
* \sa SDL_AudioStreamGet * \sa SDL_AudioStreamGet
* \sa SDL_AudioStreamAvailable * \sa SDL_AudioStreamAvailable
* \sa SDL_AudioStreamFlush * \sa SDL_AudioStreamFlush
* \sa SDL_FreeAudioStream * \sa SDL_FreeAudioStream
*/ */
extern DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream); extern DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream);
/** /**
* Free an audio stream * Free an audio stream
* *
* \sa SDL_NewAudioStream * \sa SDL_NewAudioStream
* \sa SDL_AudioStreamPut * \sa SDL_AudioStreamPut
* \sa SDL_AudioStreamGet * \sa SDL_AudioStreamGet
* \sa SDL_AudioStreamAvailable * \sa SDL_AudioStreamAvailable
* \sa SDL_AudioStreamFlush * \sa SDL_AudioStreamFlush
* \sa SDL_AudioStreamClear * \sa SDL_AudioStreamClear
*/ */
extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream); extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream);
@ -920,8 +923,8 @@ extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
/** /**
* Mix audio data in a specified format. * Mix audio data in a specified format.
* *
* This takes an audio buffer `src` of `len` bytes of `format` data and * This takes an audio buffer `src` of `len` bytes of `format` data and mixes
* mixes it into `dst`, performing addition, volume adjustment, and overflow * it into `dst`, performing addition, volume adjustment, and overflow
* clipping. The buffer pointed to by `dst` must also be `len` bytes of * clipping. The buffer pointed to by `dst` must also be `len` bytes of
* `format` data. * `format` data.
* *
@ -981,6 +984,11 @@ extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
* You should not call SDL_LockAudio() on the device before queueing; SDL * You should not call SDL_LockAudio() on the device before queueing; SDL
* handles locking internally for this function. * handles locking internally for this function.
* *
* Note that SDL2
* [https://discourse.libsdl.org/t/sdl2-support-for-planar-audio/31263/3 does
* not support planar audio]. You will need to resample 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 dev the device ID to which we will queue audio
* \param data the data to queue to the device for later playback * \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 len the number of bytes (not samples!) to which `data` points
@ -1032,8 +1040,8 @@ extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *da
* \param dev the device ID from which we will dequeue audio * \param dev the device ID from which we will dequeue audio
* \param data a pointer into where audio data should be copied * \param data a pointer into where audio data should be copied
* \param len the number of bytes (not samples!) to which (data) points * \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 * \returns the number of bytes dequeued, which could be less than requested;
* SDL_GetError() for more information. * call SDL_GetError() for more information.
* *
* \since This function is available since SDL 2.0.5. * \since This function is available since SDL 2.0.5.
* *
@ -1045,9 +1053,8 @@ extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *dat
/** /**
* Get the number of bytes of still-queued audio. * Get the number of bytes of still-queued audio.
* *
* For playback devices: this is the number of bytes that have been queued * For playback devices: this is the number of bytes that have been queued for
* for playback with SDL_QueueAudio(), but have not yet been sent to the * playback with SDL_QueueAudio(), but have not yet been sent to the hardware.
* hardware.
* *
* Once we've sent it to the hardware, this function can not decide the exact * Once we've sent it to the hardware, this function can not decide the exact
* byte boundary of what has been played. It's possible that we just gave the * byte boundary of what has been played. It's possible that we just gave the

12
include/SDL_blendmode.h
View File

@ -109,8 +109,8 @@ typedef enum
* dstA = alphaOperation(srcA * srcAlphaFactor, dstA * dstAlphaFactor); * dstA = alphaOperation(srcA * srcAlphaFactor, dstA * dstAlphaFactor);
* ``` * ```
* *
* Where the functions `colorOperation(src, dst)` and * Where the functions `colorOperation(src, dst)` and `alphaOperation(src,
* `alphaOperation(src, dst)` can return one of the following: * dst)` can return one of the following:
* *
* - `src + dst` * - `src + dst`
* - `src - dst` * - `src - dst`
@ -140,8 +140,8 @@ typedef enum
* factors produce unexpected results with `SDL_BLENDOPERATION_MINIMUM` and * factors produce unexpected results with `SDL_BLENDOPERATION_MINIMUM` and
* `SDL_BLENDOPERATION_MAXIMUM`. * `SDL_BLENDOPERATION_MAXIMUM`.
* - **opengl**: Supports the `SDL_BLENDOPERATION_ADD` operation with all * - **opengl**: Supports the `SDL_BLENDOPERATION_ADD` operation with all
* factors. OpenGL versions 1.1, 1.2, and 1.3 do not work correctly with * factors. OpenGL versions 1.1, 1.2, and 1.3 do not work correctly with SDL
* SDL 2.0.6. * 2.0.6.
* - **opengles**: Supports the `SDL_BLENDOPERATION_ADD` operation with all * - **opengles**: Supports the `SDL_BLENDOPERATION_ADD` operation with all
* factors. Color and alpha factors need to be the same. OpenGL ES 1 * factors. Color and alpha factors need to be the same. OpenGL ES 1
* implementation specific: May also support `SDL_BLENDOPERATION_SUBTRACT` * implementation specific: May also support `SDL_BLENDOPERATION_SUBTRACT`
@ -149,8 +149,8 @@ typedef enum
* operations being different from each other. May support color and alpha * operations being different from each other. May support color and alpha
* factors being different from each other. * factors being different from each other.
* - **opengles2**: Supports the `SDL_BLENDOPERATION_ADD`, * - **opengles2**: Supports the `SDL_BLENDOPERATION_ADD`,
* `SDL_BLENDOPERATION_SUBTRACT`, `SDL_BLENDOPERATION_REV_SUBTRACT` operations * `SDL_BLENDOPERATION_SUBTRACT`, `SDL_BLENDOPERATION_REV_SUBTRACT`
* with all factors. * operations with all factors.
* - **psp**: No custom blend mode support. * - **psp**: No custom blend mode support.
* - **software**: No custom blend mode support. * - **software**: No custom blend mode support.
* *

52
include/SDL_cpuinfo.h
View File

@ -171,7 +171,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasRDTSC(void);
/** /**
* Determine whether the CPU has AltiVec features. * Determine whether the CPU has AltiVec features.
* *
* This always returns false on CPUs that aren't using PowerPC instruction sets. * This always returns false on CPUs that aren't using PowerPC instruction
* sets.
* *
* \returns SDL_TRUE if the CPU has AltiVec features or SDL_FALSE if not. * \returns SDL_TRUE if the CPU has AltiVec features or SDL_FALSE if not.
* *
@ -418,15 +419,16 @@ extern DECLSPEC int SDLCALL SDL_GetSystemRAM(void);
* Report the alignment this system needs for SIMD allocations. * Report the alignment this system needs for SIMD allocations.
* *
* This will return the minimum number of bytes to which a pointer must be * This will return the minimum number of bytes to which a pointer must be
* aligned to be compatible with SIMD instructions on the current machine. * aligned to be compatible with SIMD instructions on the current machine. For
* For example, if the machine supports SSE only, it will return 16, but if * example, if the machine supports SSE only, it will return 16, but if it
* it supports AVX-512F, it'll return 64 (etc). This only reports values for * supports AVX-512F, it'll return 64 (etc). This only reports values for
* instruction sets SDL knows about, so if your SDL build doesn't have * instruction sets SDL knows about, so if your SDL build doesn't have
* SDL_HasAVX512F(), then it might return 16 for the SSE support it sees and * SDL_HasAVX512F(), then it might return 16 for the SSE support it sees and
* not 64 for the AVX-512 instructions that exist but SDL doesn't know about. * not 64 for the AVX-512 instructions that exist but SDL doesn't know about.
* Plan accordingly. * Plan accordingly.
* *
* \returns the alignment in bytes needed for available, known SIMD instructions. * \returns the alignment in bytes needed for available, known SIMD
* instructions.
*/ */
extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void); extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void);
@ -434,24 +436,24 @@ extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void);
* Allocate memory in a SIMD-friendly way. * Allocate memory in a SIMD-friendly way.
* *
* This will allocate a block of memory that is suitable for use with SIMD * This will allocate a block of memory that is suitable for use with SIMD
* instructions. Specifically, it will be properly aligned and padded for * instructions. Specifically, it will be properly aligned and padded for the
* the system's supported vector instructions. * system's supported vector instructions.
* *
* The memory returned will be padded such that it is safe to read or write * The memory returned will be padded such that it is safe to read or write an
* an incomplete vector at the end of the memory block. This can be useful * incomplete vector at the end of the memory block. This can be useful so you
* so you don't have to drop back to a scalar fallback at the end of your * don't have to drop back to a scalar fallback at the end of your SIMD
* SIMD processing loop to deal with the final elements without overflowing * processing loop to deal with the final elements without overflowing the
* the allocated buffer. * allocated buffer.
* *
* You must free this memory with SDL_FreeSIMD(), not free() or SDL_free() * You must free this memory with SDL_FreeSIMD(), not free() or SDL_free() or
* or delete[], etc. * delete[], etc.
* *
* Note that SDL will only deal with SIMD instruction sets it is aware of; * Note that SDL will only deal with SIMD instruction sets it is aware of; for
* for example, SDL 2.0.8 knows that SSE wants 16-byte vectors * example, SDL 2.0.8 knows that SSE wants 16-byte vectors (SDL_HasSSE()), and
* (SDL_HasSSE()), and AVX2 wants 32 bytes (SDL_HasAVX2()), but doesn't * AVX2 wants 32 bytes (SDL_HasAVX2()), but doesn't know that AVX-512 wants
* know that AVX-512 wants 64. To be clear: if you can't decide to use an * 64. To be clear: if you can't decide to use an instruction set with an
* instruction set with an SDL_Has*() function, don't use that instruction * SDL_Has*() function, don't use that instruction set with memory allocated
* set with memory allocated through here. * through here.
* *
* SDL_AllocSIMD(0) will return a non-NULL pointer, assuming the system isn't * SDL_AllocSIMD(0) will return a non-NULL pointer, assuming the system isn't
* out of memory, but you are not allowed to dereference it (because you only * out of memory, but you are not allowed to dereference it (because you only
@ -499,12 +501,12 @@ extern DECLSPEC void * SDLCALL SDL_SIMDRealloc(void *mem, const size_t len);
* However, SDL_SIMDFree(NULL) is a legal no-op. * However, SDL_SIMDFree(NULL) is a legal no-op.
* *
* The memory pointed to by `ptr` is no longer valid for access upon return, * The memory pointed to by `ptr` is no longer valid for access upon return,
* and may be returned to the system or reused by a future allocation. * and may be returned to the system or reused by a future allocation. The
* The pointer passed to this function is no longer safe to dereference once * pointer passed to this function is no longer safe to dereference once this
* this function returns, and should be discarded. * function returns, and should be discarded.
* *
* \param ptr The pointer, returned from SDL_SIMDAlloc or SDL_SIMDRealloc, * \param ptr The pointer, returned from SDL_SIMDAlloc or SDL_SIMDRealloc, to
* to deallocate. NULL is a legal no-op. * deallocate. NULL is a legal no-op.
* *
* \sa SDL_SIMDAlloc * \sa SDL_SIMDAlloc
* \sa SDL_SIMDRealloc * \sa SDL_SIMDRealloc

39
include/SDL_error.h
View File

@ -44,8 +44,8 @@ extern "C" {
* *
* Calling this function will replace any previous error message that was set. * Calling this function will replace any previous error message that was set.
* *
* This function always returns -1, since SDL frequently uses -1 to signify * This function always returns -1, since SDL frequently uses -1 to signify an
* an failing result, leading to this idiom: * failing result, leading to this idiom:
* *
* ```c * ```c
* if (error_code) { * if (error_code) {
@ -54,26 +54,27 @@ 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, * \param ... additional parameters matching % tokens in the `fmt` string, if
* if any * any
* \returns always -1. * \returns always -1.
* *
* \sa SDL_ClearError * \sa SDL_ClearError
* \sa SDL_GetError * \sa SDL_GetError
*/ */
extern DECLSPEC int SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); extern DECLSPEC int SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
/** /**
* Retrieve a message about the last error that occurred on the current thread. * Retrieve a message about the last error that occurred on the current
* thread.
* *
* It is possible for multiple errors to occur before calling SDL_GetError(). * It is possible for multiple errors to occur before calling SDL_GetError().
* Only the last error is returned. * Only the last error is returned.
* *
* The message is only applicable when an SDL function has signaled an error. * The message is only applicable when an SDL function has signaled an error.
* You must check the return values of SDL function calls to determine when * You must check the return values of SDL function calls to determine when to
* to appropriately call SDL_GetError(). You should _not_ use the results * appropriately call SDL_GetError(). You should _not_ use the results of
* of SDL_GetError() to decide if an error has occurred! Sometimes SDL will * SDL_GetError() to decide if an error has occurred! Sometimes SDL will set
* set an error string even when reporting success. * an error string even when reporting success.
* *
* SDL will _not_ clear the error string for successful API calls. You _must_ * SDL will _not_ clear the error string for successful API calls. You _must_
* check return values for failure cases before you can assume the error * check return values for failure cases before you can assume the error
@ -87,10 +88,10 @@ extern DECLSPEC int SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fm
* *
* \returns a message with information about the specific error that occurred, * \returns a message with information about the specific error that occurred,
* or an empty string if there hasn't been an error message set since * or an empty string if there hasn't been an error message set since
* the last call to SDL_ClearError(). The message is only applicable when an * the last call to SDL_ClearError(). The message is only applicable
* SDL function has signaled an error. You must check the return * when an SDL function has signaled an error. You must check the
* values of SDL function calls to determine when to appropriately * return values of SDL function calls to determine when to
* call SDL_GetError(). * appropriately call SDL_GetError().
* *
* \sa SDL_ClearError * \sa SDL_ClearError
* \sa SDL_SetError * \sa SDL_SetError
@ -100,11 +101,11 @@ extern DECLSPEC const char *SDLCALL SDL_GetError(void);
/** /**
* Get the last error message that was set for the current thread. * Get the last error message that was set for the current thread.
* *
* This allows the caller to copy the error string into a provided buffer, * This allows the caller to copy the error string into a provided buffer, but
* but otherwise operates exactly the same as SDL_GetError(). * otherwise operates exactly the same as SDL_GetError().
* *
* \param errstr A buffer to fill with the last error message that was set * \param errstr A buffer to fill with the last error message that was set for
* for the current thread * the current thread
* \param maxlen The size of the buffer pointed to by the errstr parameter * \param maxlen The size of the buffer pointed to by the errstr parameter
* \returns the pointer passed in as the `errstr` parameter. * \returns the pointer passed in as the `errstr` parameter.
* *

37
include/SDL_events.h
View File

@ -671,8 +671,8 @@ typedef enum
* *
* `action` may be any of the following: * `action` may be any of the following:
* *
* - `SDL_ADDEVENT`: up to `numevents` events will be added to the back of * - `SDL_ADDEVENT`: up to `numevents` events will be added to the back of the
* the event queue. * event queue.
* - `SDL_PEEKEVENT`: `numevents` events at the front of the event queue, * - `SDL_PEEKEVENT`: `numevents` events at the front of the event queue,
* within the specified minimum and maximum type, will be returned to the * within the specified minimum and maximum type, will be returned to the
* caller and will _not_ be removed from the queue. * caller and will _not_ be removed from the queue.
@ -784,10 +784,10 @@ extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
/** /**
* Poll for currently pending events. * Poll for currently pending events.
* *
* If `event` is not NULL, the next event is removed from the queue and * If `event` is not NULL, the next event is removed from the queue and stored
* stored in the SDL_Event structure pointed to by `event`. The 1 returned * in the SDL_Event structure pointed to by `event`. The 1 returned refers to
* refers to this event, immediately stored in the SDL Event structure -- not * this event, immediately stored in the SDL Event structure -- not an event
* an event to follow. * to follow.
* *
* If `event` is NULL, it simply returns 1 if there is an event in the queue, * If `event` is NULL, it simply returns 1 if there is an event in the queue,
* but will not remove it from the queue. * but will not remove it from the queue.
@ -829,8 +829,8 @@ extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
/** /**
* Wait indefinitely for the next available event. * Wait indefinitely for the next available event.
* *
* If `event` is not NULL, the next event is removed from the queue and * If `event` is not NULL, the next event is removed from the queue and stored
* stored in the SDL_Event structure pointed to by `event`. * in the SDL_Event structure pointed to by `event`.
* *
* As this function implicitly calls SDL_PumpEvents(), you can only call this * As this function implicitly calls SDL_PumpEvents(), you can only call this
* function in the thread that initialized the video subsystem. * function in the thread that initialized the video subsystem.
@ -847,11 +847,11 @@ extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event); extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
/** /**
* Wait until the specified timeout (in milliseconds) for * Wait until the specified timeout (in milliseconds) for the next available
* the next available event. * event.
* *
* If `event` is not NULL, the next event is removed from the queue and * If `event` is not NULL, the next event is removed from the queue and stored
* stored in the SDL_Event structure pointed to by `event`. * in the SDL_Event structure pointed to by `event`.
* *
* As this function implicitly calls SDL_PumpEvents(), you can only call this * As this function implicitly calls SDL_PumpEvents(), you can only call this
* function in the thread that initialized the video subsystem. * function in the thread that initialized the video subsystem.
@ -933,10 +933,10 @@ typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
* interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the * interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the
* application at the next event poll. * 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 * 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 * application window. If the event filter returns 1, then the window will be
* be closed, otherwise the window will remain open if possible. * closed, otherwise the window will remain open if possible.
* *
* Note: Disabled events never make it to the event filter function; see * Note: Disabled events never make it to the event filter function; see
* SDL_EventState(). * SDL_EventState().
@ -1004,8 +1004,7 @@ extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter,
void *userdata); void *userdata);
/** /**
* Remove an event watch callback added with * Remove an event watch callback added with SDL_AddEventWatch().
* SDL_AddEventWatch().
* *
* This function takes the same input as SDL_AddEventWatch() to identify and * This function takes the same input as SDL_AddEventWatch() to identify and
* delete the corresponding callback. * delete the corresponding callback.
@ -1019,8 +1018,8 @@ extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter,
void *userdata); void *userdata);
/** /**
* Run a specific filter function on the current event * Run a specific filter function on the current event queue, removing any
* queue, removing any events for which the filter returns 0. * events for which the filter returns 0.
* *
* See SDL_SetEventFilter() for more information. Unlike SDL_SetEventFilter(), * See SDL_SetEventFilter() for more information. Unlike SDL_SetEventFilter(),
* this function does not change the filter permanently, it only uses the * this function does not change the filter permanently, it only uses the

14
include/SDL_filesystem.h
View File

@ -63,8 +63,8 @@ extern "C" {
* The returned path is guaranteed to end with a path separator ('\' on * The returned path is guaranteed to end with a path separator ('\' on
* Windows, '/' on most other platforms). * Windows, '/' on most other platforms).
* *
* The pointer returned is owned by the caller. Please call SDL_free() on * The pointer returned is owned by the caller. Please call SDL_free() on the
* the pointer when done with it. * pointer when done with it.
* *
* \returns an absolute path in UTF-8 encoding to the application data * \returns an absolute path in UTF-8 encoding to the application data
* directory. NULL will be returned on error or when the platform * directory. NULL will be returned on error or when the platform
@ -84,9 +84,9 @@ extern DECLSPEC char *SDLCALL SDL_GetBasePath(void);
* files (preferences and save games, etc) that are specific to your * files (preferences and save games, etc) that are specific to your
* application. This directory is unique per user, per application. * application. This directory is unique per user, per application.
* *
* This function will decide the appropriate location in the native filesystem, * This function will decide the appropriate location in the native
* create the directory if necessary, and return a string of the absolute * filesystem, create the directory if necessary, and return a string of the
* path to the directory in UTF-8 encoding. * absolute path to the directory in UTF-8 encoding.
* *
* On Windows, the string might look like: * On Windows, the string might look like:
* *
@ -119,8 +119,8 @@ extern DECLSPEC char *SDLCALL SDL_GetBasePath(void);
* The returned path is guaranteed to end with a path separator ('\' on * The returned path is guaranteed to end with a path separator ('\' on
* Windows, '/' on most other platforms). * Windows, '/' on most other platforms).
* *
* The pointer returned is owned by the caller. Please call SDL_free() on * The pointer returned is owned by the caller. Please call SDL_free() on the
* the pointer when done with it. * pointer when done with it.
* *
* \param org the name of your organization * \param org the name of your organization
* \param app the name of your application * \param app the name of your application

60
include/SDL_gamecontroller.h
View File

@ -166,8 +166,8 @@ extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw,
#define SDL_GameControllerAddMappingsFromFile(file) SDL_GameControllerAddMappingsFromRW(SDL_RWFromFile(file, "rb"), 1) #define SDL_GameControllerAddMappingsFromFile(file) SDL_GameControllerAddMappingsFromRW(SDL_RWFromFile(file, "rb"), 1)
/** /**
* Add support for controllers that SDL is unaware of or * Add support for controllers that SDL is unaware of or to cause an existing
* to cause an existing controller to have a different binding. * controller to have a different binding.
* *
* The mapping string has the format "GUID,name,mapping", where GUID is the * The mapping string has the format "GUID,name,mapping", where GUID is the
* string value from SDL_JoystickGetGUIDString(), name is the human readable * string value from SDL_JoystickGetGUIDString(), name is the human readable
@ -202,8 +202,8 @@ extern DECLSPEC int SDLCALL SDL_GameControllerNumMappings(void);
/** /**
* Get the mapping at a particular index. * Get the mapping at a particular index.
* *
* \returns the mapping string. Must be freed with SDL_free(). * \returns the mapping string. Must be freed with SDL_free(). Returns NULL if
* Returns NULL if the index is out of range. * the index is out of range.
*/ */
extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForIndex(int mapping_index); extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForIndex(int mapping_index);
@ -259,8 +259,7 @@ extern DECLSPEC char * SDLCALL SDL_GameControllerMapping(SDL_GameController *gam
extern DECLSPEC SDL_bool SDLCALL SDL_IsGameController(int joystick_index); extern DECLSPEC SDL_bool SDLCALL SDL_IsGameController(int joystick_index);
/** /**
* Get the implementation dependent name for the game * Get the implementation dependent name for the game controller.
* controller.
* *
* This function can be called before any controllers are opened. * This function can be called before any controllers are opened.
* *
@ -298,8 +297,8 @@ extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerTypeForIndex(in
* *
* \param joystick_index the device_index of a device, from zero to * \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 * \returns the mapping string. Must be freed with SDL_free(). Returns NULL if
* if no mapping is available. * no mapping is available.
*/ */
extern DECLSPEC char *SDLCALL SDL_GameControllerMappingForDeviceIndex(int joystick_index); extern DECLSPEC char *SDLCALL SDL_GameControllerMappingForDeviceIndex(int joystick_index);
@ -341,11 +340,11 @@ extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromInstanceID(SDL
/** /**
* Get the SDL_GameController associated with a player index. * Get the SDL_GameController associated with a player index.
* *
* Please note that the player index is _not_ the device index, nor is it * Please note that the player index is _not_ the device index, nor is it the
* the instance id! * instance id!
* *
* \param player_index the player index, which is not the device index or * \param player_index the player index, which is not the device index or the
* the instance id! * instance id!
* \returns the SDL_GameController associated with a player index. * \returns the SDL_GameController associated with a player index.
* *
* \sa SDL_GameControllerGetPlayerIndex * \sa SDL_GameControllerGetPlayerIndex
@ -383,9 +382,9 @@ extern DECLSPEC const char *SDLCALL SDL_GameControllerName(SDL_GameController *g
extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerGetType(SDL_GameController *gamecontroller); extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerGetType(SDL_GameController *gamecontroller);
/** /**
* Get the player index of an opened game controller. * Get the player index of an opened game controller.
* *
* For XInput controllers this returns the XInput user index. * For XInput controllers this returns the XInput user index.
* *
* \param gamecontroller the game controller object to query. * \param gamecontroller the game controller object to query.
* \returns the player index for controller, or -1 if it's not available. * \returns the player index for controller, or -1 if it's not available.
@ -393,7 +392,7 @@ extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerGetType(SDL_Gam
extern DECLSPEC int SDLCALL SDL_GameControllerGetPlayerIndex(SDL_GameController *gamecontroller); extern DECLSPEC int SDLCALL SDL_GameControllerGetPlayerIndex(SDL_GameController *gamecontroller);
/** /**
* Set the player index of an opened game controller. * Set the player index of an opened game controller.
* *
* \param gamecontroller the game controller object to adjust. * \param gamecontroller the game controller object to adjust.
* \param player_index Player index to assign to this controller. * \param player_index Player index to assign to this controller.
@ -432,8 +431,9 @@ extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProductVersion(SDL_GameContr
/** /**
* Get the serial number of an opened controller, if available. * Get the serial number of an opened controller, if available.
* *
* Returns the serial number of the controller, or NULL if it is not available. * Returns the serial number of the controller, or NULL if it is not
* available.
* *
* \param gamecontroller the game controller object to query. * \param gamecontroller the game controller object to query.
* \return the serial number, or NULL if unavailable. * \return the serial number, or NULL if unavailable.
@ -558,9 +558,9 @@ extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForAxis(SDL_GameC
* *
* \param gamecontroller a game controller * \param gamecontroller a game controller
* \param axis an axis enum value (one of the SDL_GameControllerAxis values) * \param axis an axis enum value (one of the SDL_GameControllerAxis values)
* \returns a SDL_GameControllerButtonBind describing the bind. On * \returns a SDL_GameControllerButtonBind describing the bind. On failure
* failure (like the given Controller axis doesn't exist on the * (like the given Controller axis doesn't exist on the device), its
* device), its `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`. * `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
* *
* \since This function is available since SDL 2.0.0. * \since This function is available since SDL 2.0.0.
* *
@ -644,7 +644,6 @@ typedef enum
* \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 * \returns the SDL_GameControllerButton enum corresponding to the input
* string, or `SDL_CONTROLLER_AXIS_INVALID` if no match was found. * string, or `SDL_CONTROLLER_AXIS_INVALID` if no match was found.
*
*/ */
extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFromString(const char *str); extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFromString(const char *str);
@ -669,9 +668,9 @@ extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForButton(SDL_Gam
* *
* \param gamecontroller a game controller * \param gamecontroller a game controller
* \param button an button enum value (an SDL_GameControllerButton value) * \param button an button enum value (an SDL_GameControllerButton value)
* \returns a SDL_GameControllerButtonBind describing the bind. On * \returns a SDL_GameControllerButtonBind describing the bind. On failure
* failure (like the given Controller button doesn't exist on the * (like the given Controller button doesn't exist on the device),
* device), its `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`. * its `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
* *
* \since This function is available since SDL 2.0.0. * \since This function is available since SDL 2.0.0.
* *
@ -715,7 +714,8 @@ extern DECLSPEC Uint8 SDLCALL SDL_GameControllerGetButton(SDL_GameController *ga
extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpads(SDL_GameController *gamecontroller); extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpads(SDL_GameController *gamecontroller);
/** /**
* Get the number of supported simultaneous fingers on a touchpad on a game controller. * Get the number of supported simultaneous fingers on a touchpad on a game
* controller.
*/ */
extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpadFingers(SDL_GameController *gamecontroller, int touchpad); extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpadFingers(SDL_GameController *gamecontroller, int touchpad);
@ -729,7 +729,6 @@ extern DECLSPEC int SDLCALL SDL_GameControllerGetTouchpadFinger(SDL_GameControll
* *
* \param gamecontroller The controller to query * \param gamecontroller The controller to query
* \param type The type of sensor to query * \param type The type of sensor to query
*
* \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise. * \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise.
*/ */
extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasSensor(SDL_GameController *gamecontroller, SDL_SensorType type); extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasSensor(SDL_GameController *gamecontroller, SDL_SensorType type);
@ -740,7 +739,6 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasSensor(SDL_GameController
* \param gamecontroller The controller to update * \param gamecontroller The controller to update
* \param type The type of sensor to enable/disable * \param type The type of sensor to enable/disable
* \param enabled Whether data reporting should be enabled * \param enabled Whether data reporting should be enabled
*
* \returns 0 or -1 if an error occurred. * \returns 0 or -1 if an error occurred.
*/ */
extern DECLSPEC int SDLCALL SDL_GameControllerSetSensorEnabled(SDL_GameController *gamecontroller, SDL_SensorType type, SDL_bool enabled); extern DECLSPEC int SDLCALL SDL_GameControllerSetSensorEnabled(SDL_GameController *gamecontroller, SDL_SensorType type, SDL_bool enabled);
@ -750,7 +748,6 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSetSensorEnabled(SDL_GameControlle
* *
* \param gamecontroller The controller to query * \param gamecontroller The controller to query
* \param type The type of sensor to query * \param type The type of sensor to query
*
* \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise. * \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise.
*/ */
extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerIsSensorEnabled(SDL_GameController *gamecontroller, SDL_SensorType type); extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerIsSensorEnabled(SDL_GameController *gamecontroller, SDL_SensorType type);
@ -798,9 +795,9 @@ extern DECLSPEC int SDLCALL SDL_GameControllerRumble(SDL_GameController *gamecon
* \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 * \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 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 * \param duration_ms The duration of the rumble effect, in milliseconds
*
* \returns 0, or -1 if trigger rumble isn't supported on this controller * \returns 0, or -1 if trigger rumble isn't supported on this controller
*/ */
extern DECLSPEC int SDLCALL SDL_GameControllerRumbleTriggers(SDL_GameController *gamecontroller, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); extern DECLSPEC int SDLCALL SDL_GameControllerRumbleTriggers(SDL_GameController *gamecontroller, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms);
@ -831,7 +828,8 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSetLED(SDL_GameController *gamecon
* \param gamecontroller The controller to affect * \param gamecontroller The controller to affect
* \param data The data to send to the controller * \param data The data to send to the controller
* \param size The size of 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 * \returns 0, or -1 if this controller or driver doesn't support effect
* packets
*/ */
extern DECLSPEC int SDLCALL SDL_GameControllerSendEffect(SDL_GameController *gamecontroller, const void *data, int size); extern DECLSPEC int SDLCALL SDL_GameControllerSendEffect(SDL_GameController *gamecontroller, const void *data, int size);

11
include/SDL_haptic.h
View File

@ -993,8 +993,7 @@ extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic); extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
/** /**
* Get the number of effects a haptic device can play at * Get the number of effects a haptic device can play at the same time.
* the same time.
* *
* This is not supported on all platforms, but will always return a value. * This is not supported on all platforms, but will always return a value.
* *
@ -1038,8 +1037,7 @@ extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic);
extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic); extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic);
/** /**
* Check to see if an effect is supported by a haptic * Check to see if an effect is supported by a haptic device.
* device.
* *
* \param haptic the SDL_Haptic device to query * \param haptic the SDL_Haptic device to query
* \param effect the desired effect to query * \param effect the desired effect to query
@ -1125,7 +1123,9 @@ extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic,
/** /**
* Stop the haptic effect on its associated haptic device. * Stop the haptic effect on its associated haptic device.
*
* * * *
*
* \param haptic the SDL_Haptic device to stop the effect on * \param haptic the SDL_Haptic device to stop the effect on
* \param effect the ID of the haptic effect to stop * \param effect the ID of the haptic effect to stop
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
@ -1156,8 +1156,7 @@ extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic,
int effect); int effect);
/** /**
* Get the status of the current effect on the specified * Get the status of the current effect on the specified haptic device.
* haptic device.
* *
* Device must support the SDL_HAPTIC_STATUS feature. * Device must support the SDL_HAPTIC_STATUS feature.
* *

4
include/SDL_hints.h
View File

@ -1770,7 +1770,7 @@ typedef void (SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const
* *
* \param name the hint to watch * \param name the hint to watch
* \param callback An SDL_HintCallback function that will be called when the * \param callback An SDL_HintCallback function that will be called when the
* hint value changes * hint value changes
* \param userdata a pointer to pass to the callback function * \param userdata a pointer to pass to the callback function
* *
* \since This function is available since SDL 2.0.0. * \since This function is available since SDL 2.0.0.
@ -1786,7 +1786,7 @@ extern DECLSPEC void SDLCALL SDL_AddHintCallback(const char *name,
* *
* \param name the hint being watched * \param name the hint being watched
* \param callback An SDL_HintCallback function that will be called when the * \param callback An SDL_HintCallback function that will be called when the
* hint value changes * hint value changes
* \param userdata a pointer being passed to the callback function * \param userdata a pointer being passed to the callback function
* *
* \since This function is available since SDL 2.0.0. * \since This function is available since SDL 2.0.0.

90
include/SDL_joystick.h
View File

@ -167,14 +167,14 @@ extern DECLSPEC int SDLCALL SDL_NumJoysticks(void);
extern DECLSPEC const char *SDLCALL SDL_JoystickNameForIndex(int device_index); extern DECLSPEC const char *SDLCALL SDL_JoystickNameForIndex(int device_index);
/** /**
* Get the player index of a joystick, or -1 if it's not available * Get the player index of a joystick, or -1 if it's not available This can be
* This can be called before any joysticks are opened. * called before any joysticks are opened.
*/ */
extern DECLSPEC int SDLCALL SDL_JoystickGetDevicePlayerIndex(int device_index); extern DECLSPEC int SDLCALL SDL_JoystickGetDevicePlayerIndex(int device_index);
/** /**
* Get the implementation-dependent GUID for the joystick * Get the implementation-dependent GUID for the joystick at a given device
* at a given device index. * index.
* *
* This function can be called before any joysticks are opened. * This function can be called before any joysticks are opened.
* *
@ -191,8 +191,8 @@ extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetDeviceGUID(int device_in
/** /**
* Get the USB vendor ID of a joystick, if available. * Get the USB vendor ID of a joystick, if available.
* *
* This can be called before any joysticks are opened. * This can be called before any joysticks are opened. If the vendor ID isn't
* If the vendor ID isn't available this function returns 0. * available this function returns 0.
* *
* \param device_index the index of the joystick to query (the N'th joystick * \param device_index the index of the joystick to query (the N'th joystick
* on the system * on the system
@ -204,8 +204,8 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceVendor(int device_index);
/** /**
* Get the USB product ID of a joystick, if available. * Get the USB product ID of a joystick, if available.
* *
* This can be called before any joysticks are opened. * This can be called before any joysticks are opened. If the product ID isn't
* If the product ID isn't available this function returns 0. * available this function returns 0.
* *
* \param device_index the index of the joystick to query (the N'th joystick * \param device_index the index of the joystick to query (the N'th joystick
* on the system * on the system
@ -217,8 +217,8 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProduct(int device_index);
/** /**
* Get the product version of a joystick, if available. * Get the product version of a joystick, if available.
* *
* This can be called before any joysticks are opened. * This can be called before any joysticks are opened. If the product version
* If the product version isn't available this function returns 0. * isn't available this function returns 0.
* *
* \param device_index the index of the joystick to query (the N'th joystick * \param device_index the index of the joystick to query (the N'th joystick
* on the system * on the system
@ -242,8 +242,8 @@ extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetDeviceType(int device_in
/** /**
* Get the instance ID of a joystick. * Get the instance ID of a joystick.
* *
* This can be called before any joysticks are opened. * This can be called before any joysticks are opened. If the index is out of
* If the index is out of range, this function will return -1. * range, this function will return -1.
* *
* \param device_index the index of the joystick to query (the N'th joystick * \param device_index the index of the joystick to query (the N'th joystick
* on the system * on the system
@ -322,12 +322,12 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickIsVirtual(int device_index);
/** /**
* Set values on an opened, virtual-joystick's axis. * Set values on an opened, virtual-joystick's axis.
* *
* Please note that values set here will not be applied until the next * Please note that values set here will not be applied until the next call to
* call to SDL_JoystickUpdate, which can either be called directly, * SDL_JoystickUpdate, which can either be called directly, or can be called
* or can be called indirectly through various other SDL APIs, * indirectly through various other SDL APIs, including, but not limited to
* including, but not limited to the following: SDL_PollEvent, * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout,
* SDL_PumpEvents, SDL_WaitEventTimeout, SDL_WaitEvent. * SDL_WaitEvent.
* *
* \param joystick the virtual joystick on which to set state. * \param joystick the virtual joystick on which to set state.
* \param axis the specific axis on the virtual joystick to set. * \param axis the specific axis on the virtual joystick to set.
* \param value the new value for the specified axis. * \param value the new value for the specified axis.
@ -338,12 +338,12 @@ extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualAxis(SDL_Joystick *joystick, i
/** /**
* Set values on an opened, virtual-joystick's button. * Set values on an opened, virtual-joystick's button.
* *
* Please note that values set here will not be applied until the next * Please note that values set here will not be applied until the next call to
* call to SDL_JoystickUpdate, which can either be called directly, * SDL_JoystickUpdate, which can either be called directly, or can be called
* or can be called indirectly through various other SDL APIs, * indirectly through various other SDL APIs, including, but not limited to
* including, but not limited to the following: SDL_PollEvent, * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout,
* SDL_PumpEvents, SDL_WaitEventTimeout, SDL_WaitEvent. * SDL_WaitEvent.
* *
* \param joystick the virtual joystick on which to set state. * \param joystick the virtual joystick on which to set state.
* \param button the specific button on the virtual joystick to set. * \param button the specific button on the virtual joystick to set.
* \param value the new value for the specified button. * \param value the new value for the specified button.
@ -354,12 +354,12 @@ extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualButton(SDL_Joystick *joystick,
/** /**
* Set values on an opened, virtual-joystick's hat. * Set values on an opened, virtual-joystick's hat.
* *
* Please note that values set here will not be applied until the next * Please note that values set here will not be applied until the next call to
* call to SDL_JoystickUpdate, which can either be called directly, * SDL_JoystickUpdate, which can either be called directly, or can be called
* or can be called indirectly through various other SDL APIs, * indirectly through various other SDL APIs, including, but not limited to
* including, but not limited to the following: SDL_PollEvent, * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout,
* SDL_PumpEvents, SDL_WaitEventTimeout, SDL_WaitEvent. * SDL_WaitEvent.
* *
* \param joystick the virtual joystick on which to set state. * \param joystick the virtual joystick on which to set state.
* \param hat the specific hat on the virtual joystick to set. * \param hat the specific hat on the virtual joystick to set.
* \param value the new value for the specified hat. * \param value the new value for the specified hat.
@ -437,6 +437,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProduct(SDL_Joystick *joystick);
/** /**
* Get the product version of an opened joystick, if available. * Get the product version of an opened joystick, if available.
*
* If the product version isn't available this function returns 0. * 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()
@ -446,11 +447,12 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProductVersion(SDL_Joystick *joyst
/** /**
* Get the serial number of an opened joystick, if available. * Get the serial number of an opened joystick, if available.
* *
* Returns the serial number of the joystick, or NULL if it is not available. * Returns the serial number of the joystick, or NULL if it is not available.
* *
* \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
* \returns the serial number of the selected joystick, or NULL if unavailable. * \returns the serial number of the selected joystick, or NULL if
* unavailable.
*/ */
extern DECLSPEC const char * SDLCALL SDL_JoystickGetSerial(SDL_Joystick *joystick); extern DECLSPEC const char * SDLCALL SDL_JoystickGetSerial(SDL_Joystick *joystick);
@ -609,12 +611,11 @@ extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state);
/** /**
* Get the current state of an axis control on a joystick. * Get the current state of an axis control on a joystick.
* *
* SDL makes no promises about what part of the joystick any given axis * SDL makes no promises about what part of the joystick any given axis refers
* refers to. Your game should have some sort of configuration UI to let * to. Your game should have some sort of configuration UI to let users
* users specify what each axis should be bound to. Alternately, SDL's * specify what each axis should be bound to. Alternately, SDL's higher-level
* higher-level Game Controller API makes a great effort to apply order * Game Controller API makes a great effort to apply order to this lower-level
* to this lower-level interface, so you know that a specific axis is the * interface, so you know that a specific axis is the "left thumb stick," etc.
* "left thumb stick," etc.
* *
* The value returned by SDL_JoystickGetAxis() is a signed integer (-32768 to * The value returned by SDL_JoystickGetAxis() is a signed integer (-32768 to
* 32767) representing the current position of the axis. It may be necessary * 32767) representing the current position of the axis. It may be necessary
@ -688,8 +689,7 @@ extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick *joystick,
* Get the ball axis change since the last poll. * Get the ball axis change since the last poll.
* *
* Trackballs can only return relative motion since the last call to * Trackballs can only return relative motion since the last call to
* SDL_JoystickGetBall(), these motion deltas are placed into `dx` and * SDL_JoystickGetBall(), these motion deltas are placed into `dx` and `dy`.
* `dy`.
* *
* Most joysticks do not have trackballs. * Most joysticks do not have trackballs.
* *
@ -730,7 +730,6 @@ extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick *joystick,
* \param high_frequency_rumble The intensity of the high frequency (right) * \param high_frequency_rumble The intensity of the high frequency (right)
* rumble motor, from 0 to 0xFFFF * rumble motor, from 0 to 0xFFFF
* \param duration_ms The duration of the rumble effect, in milliseconds * \param duration_ms The duration of the rumble effect, in milliseconds
*
* \returns 0, or -1 if rumble isn't supported on this joystick * \returns 0, or -1 if rumble isn't supported on this joystick
*/ */
extern DECLSPEC int SDLCALL SDL_JoystickRumble(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); extern DECLSPEC int SDLCALL SDL_JoystickRumble(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms);
@ -738,12 +737,13 @@ extern DECLSPEC int SDLCALL SDL_JoystickRumble(SDL_Joystick *joystick, Uint16 lo
/** /**
* Start a rumble effect in the joystick's triggers * Start a rumble effect in the joystick's triggers
* *
* Each call to this function cancels any previous trigger rumble effect, * Each call to this function cancels any previous trigger rumble effect, and
* and calling it with 0 intensity stops any rumbling. * calling it with 0 intensity stops any rumbling.
* *
* Note that this function is for _trigger_ rumble; the first joystick to * Note that this function is for _trigger_ rumble; the first joystick to
* support this was the PlayStation 5's DualShock 5 controller. If you want * support this was the PlayStation 5's DualShock 5 controller. If you want
* the (more common) whole-controller rumble, use SDL_JoystickRumble() instead. * 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 * \param left_rumble The intensity of the left trigger rumble motor, from 0
@ -751,7 +751,6 @@ extern DECLSPEC int SDLCALL SDL_JoystickRumble(SDL_Joystick *joystick, Uint16 lo
* \param right_rumble The intensity of the right trigger rumble motor, from 0 * \param right_rumble The intensity of the right trigger rumble motor, from 0
* to 0xFFFF * to 0xFFFF
* \param duration_ms The duration of the rumble effect, in milliseconds * \param duration_ms The duration of the rumble effect, in milliseconds
*
* \returns 0, or -1 if trigger rumble isn't supported on this joystick * \returns 0, or -1 if trigger rumble isn't supported on this joystick
*/ */
extern DECLSPEC int SDLCALL SDL_JoystickRumbleTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); extern DECLSPEC int SDLCALL SDL_JoystickRumbleTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms);
@ -777,7 +776,6 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasLED(SDL_Joystick *joystick);
* \param red The intensity of the red LED * \param red The intensity of the red LED
* \param green The intensity of the green LED * \param green The intensity of the green LED
* \param blue The intensity of the blue LED * \param blue The intensity of the blue LED
*
* \returns 0 on success, -1 if this joystick does not have a modifiable LED * \returns 0 on success, -1 if this joystick does not have a modifiable LED
*/ */
extern DECLSPEC int SDLCALL SDL_JoystickSetLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue); extern DECLSPEC int SDLCALL SDL_JoystickSetLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue);

16
include/SDL_keyboard.h
View File

@ -65,8 +65,8 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void);
* Get a snapshot of the current state of the keyboard. * Get a snapshot of the current state of the keyboard.
* *
* The pointer returned is a pointer to an internal SDL array. It will be * The pointer returned is a pointer to an internal SDL array. It will be
* valid for the whole lifetime of the application and should not be freed * valid for the whole lifetime of the application and should not be freed by
* by the caller. * the caller.
* *
* A array element with a value of 1 means that the key is pressed and a value * A array element with a value of 1 means that the key is pressed and a value
* of 0 means that it is not. Indexes into this array are obtained by using * of 0 means that it is not. Indexes into this array are obtained by using
@ -118,8 +118,8 @@ extern DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void);
extern DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate); extern DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
/** /**
* Get the key code corresponding to the given scancode * Get the key code corresponding to the given scancode according to the
* according to the current keyboard layout. * current keyboard layout.
* *
* See SDL_Keycode for details. * See SDL_Keycode for details.
* *
@ -132,8 +132,8 @@ extern DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode); extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode);
/** /**
* Get the scancode corresponding to the given key code * Get the scancode corresponding to the given key code according to the
* according to the current keyboard layout. * current keyboard layout.
* *
* See SDL_Scancode for details. * See SDL_Scancode for details.
* *
@ -220,8 +220,8 @@ extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name);
* *
* This function will start accepting Unicode text input events in the focused * This function will start accepting Unicode text input events in the focused
* SDL window, and start emitting SDL_TextInputEvent (SDL_TEXTINPUT) and * SDL window, and start emitting SDL_TextInputEvent (SDL_TEXTINPUT) and
* SDL_TextEditingEvent (SDL_TEXTEDITING) events. Please use this function * SDL_TextEditingEvent (SDL_TEXTEDITING) events. Please use this function in
* in pair with SDL_StopTextInput(). * pair with SDL_StopTextInput().
* *
* On some platforms using this function activates the screen keyboard. * On some platforms using this function activates the screen keyboard.
* *

62
include/SDL_locale.h
View File

@ -47,44 +47,44 @@ typedef struct SDL_Locale
} SDL_Locale; } SDL_Locale;
/** /**
* \brief Report the user's preferred locale. * Report the user's preferred locale.
* *
* This returns an array of SDL_Locale structs, the final item zeroed out. * This returns an array of SDL_Locale structs, the final item zeroed out.
* When the caller is done with this array, it should call SDL_free() on * When the caller is done with this array, it should call SDL_free() on the
* the returned value; all the memory involved is allocated in a single * returned value; all the memory involved is allocated in a single block, so
* block, so a single SDL_free() will suffice. * a single SDL_free() will suffice.
* *
* Returned language strings are in the format xx, where 'xx' is an ISO-639 * Returned language strings are in the format xx, where 'xx' is an ISO-639
* language specifier (such as "en" for English, "de" for German, etc). * language specifier (such as "en" for English, "de" for German, etc).
* Country strings are in the format YY, where "YY" is an ISO-3166 country * Country strings are in the format YY, where "YY" is an ISO-3166 country
* code (such as "US" for the United States, "CA" for Canada, etc). Country * code (such as "US" for the United States, "CA" for Canada, etc). Country
* might be NULL if there's no specific guidance on them (so you might get * might be NULL if there's no specific guidance on them (so you might get {
* { "en", "US" } for American English, but { "en", NULL } means "English * "en", "US" } for American English, but { "en", NULL } means "English
* language, generically"). Language strings are never NULL, except to * language, generically"). Language strings are never NULL, except to
* terminate the array. * terminate the array.
* *
* Please note that not all of these strings are 2 characters; some are * Please note that not all of these strings are 2 characters; some are three
* three or more. * or more.
* *
* The returned list of locales are in the order of the user's preference. * The returned list of locales are in the order of the user's preference. For
* For example, a German citizen that is fluent in US English and knows * example, a German citizen that is fluent in US English and knows enough
* enough Japanese to navigate around Tokyo might have a list like: * Japanese to navigate around Tokyo might have a list like: { "de", "en_US",
* { "de", "en_US", "jp", NULL }. Someone from England might prefer British * "jp", NULL }. Someone from England might prefer British English (where
* English (where "color" is spelled "colour", etc), but will settle for * "color" is spelled "colour", etc), but will settle for anything like it: {
* anything like it: { "en_GB", "en", NULL }. * "en_GB", "en", NULL }.
* *
* This function returns NULL on error, including when the platform does not * This function returns NULL on error, including when the platform does not
* supply this information at all. * supply this information at all.
* *
* This might be a "slow" call that has to query the operating system. It's * This might be a "slow" call that has to query the operating system. It's
* best to ask for this once and save the results. However, this list can * best to ask for this once and save the results. However, this list can
* change, usually because the user has changed a system preference outside * change, usually because the user has changed a system preference outside of
* of your program; SDL will send an SDL_LOCALECHANGED event in this case, * your program; SDL will send an SDL_LOCALECHANGED event in this case, if
* if possible, and you can call this function again to get an updated copy * possible, and you can call this function again to get an updated copy of
* of preferred locales. * preferred locales.
* *
* \return array of locales, terminated with a locale with a NULL language * \return array of locales, terminated with a locale with a NULL language
* field. Will return NULL on error. * field. Will return NULL on error.
*/ */
extern DECLSPEC SDL_Locale * SDLCALL SDL_GetPreferredLocales(void); extern DECLSPEC SDL_Locale * SDLCALL SDL_GetPreferredLocales(void);

7
include/SDL_log.h
View File

@ -155,9 +155,10 @@ extern DECLSPEC void SDLCALL SDL_LogResetPriorities(void);
/** /**
* Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO. * Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO.
* *
= * \param fmt a printf() style message format string * = * \param fmt a printf() style message format string
* \param ... additional parameters matching % tokens in the `fmt` string, *
* if any * \param ... additional parameters matching % tokens in the `fmt` string, if
* any
* *
* \sa SDL_LogCritical * \sa SDL_LogCritical
* \sa SDL_LogDebug * \sa SDL_LogDebug

5
include/SDL_main.h
View File

@ -122,7 +122,8 @@ extern SDLMAIN_DECLSPEC int SDL_main(int argc, char *argv[]);
/** /**
* Circumvent failure of SDL_Init() when not using SDL_main() as an entry point. * Circumvent failure of SDL_Init() when not using SDL_main() as an entry
* point.
* *
* This function is defined in SDL_main.h, along with the preprocessor rule to * This function is defined in SDL_main.h, along with the preprocessor rule to
* redefine main() as SDL_main(). Thus to ensure that your main() function * redefine main() as SDL_main(). Thus to ensure that your main() function
@ -136,7 +137,7 @@ extern DECLSPEC void SDLCALL SDL_SetMainReady(void);
#ifdef __WIN32__ #ifdef __WIN32__
/** /**
* This can be called to set the application class at startup * This can be called to set the application class at startup
*/ */
extern DECLSPEC int SDLCALL SDL_RegisterApp(char *name, Uint32 style, void *hInst); extern DECLSPEC int SDLCALL SDL_RegisterApp(char *name, Uint32 style, void *hInst);
extern DECLSPEC void SDLCALL SDL_UnregisterApp(void); extern DECLSPEC void SDLCALL SDL_UnregisterApp(void);

53
include/SDL_metal.h
View File

@ -49,59 +49,46 @@ typedef void *SDL_MetalView;
/* @{ */ /* @{ */
/** /**
* \brief Create a CAMetalLayer-backed NSView/UIView and attach it to the * Create a CAMetalLayer-backed NSView/UIView and attach it to the specified
* specified window. * window.
* *
* On macOS, this does *not* associate a MTLDevice with the CAMetalLayer on its * On macOS, this does *not* associate a MTLDevice with the CAMetalLayer on
* own. It is up to user code to do that. * its own. It is up to user code to do that.
* *
* The returned handle can be casted directly to a NSView or UIView. * The returned handle can be casted directly to a NSView or UIView. To access
* To access the backing CAMetalLayer, call SDL_Metal_GetLayer(). * the backing CAMetalLayer, call SDL_Metal_GetLayer().
* *
* \note \a window must be created with the SDL_WINDOW_METAL flag. * \sa SDL_Metal_DestroyView
* * \sa SDL_Metal_GetLayer
* \sa SDL_Metal_DestroyView
* \sa SDL_Metal_GetLayer
*/ */
extern DECLSPEC SDL_MetalView SDLCALL SDL_Metal_CreateView(SDL_Window * window); extern DECLSPEC SDL_MetalView SDLCALL SDL_Metal_CreateView(SDL_Window * window);
/** /**
* \brief Destroy an existing SDL_MetalView object. * Destroy an existing SDL_MetalView object.
* *
* This should be called before SDL_DestroyWindow, if SDL_Metal_CreateView was * This should be called before SDL_DestroyWindow, if SDL_Metal_CreateView was
* called after SDL_CreateWindow. * called after SDL_CreateWindow.
* *
* \sa SDL_Metal_CreateView * \sa SDL_Metal_CreateView
*/ */
extern DECLSPEC void SDLCALL SDL_Metal_DestroyView(SDL_MetalView view); extern DECLSPEC void SDLCALL SDL_Metal_DestroyView(SDL_MetalView view);
/** /**
* \brief Get a pointer to the backing CAMetalLayer for the given view. * Get a pointer to the backing CAMetalLayer for the given view.
* *
* \sa SDL_MetalCreateView * \sa SDL_MetalCreateView
*/ */
extern DECLSPEC void *SDLCALL SDL_Metal_GetLayer(SDL_MetalView view); extern DECLSPEC void *SDLCALL SDL_Metal_GetLayer(SDL_MetalView view);
/** /**
* \brief Get the size of a window's underlying drawable in pixels (for use * Get the size of a window's underlying drawable in pixels (for use with
* with setting viewport, scissor & etc). * setting viewport, scissor & etc).
* *
* \param window SDL_Window from which the drawable size should be queried * \param window SDL_Window from which the drawable size should be queried
* \param w Pointer to variable for storing the width in pixels, * \param w Pointer to variable for storing the width in pixels, may be NULL
* may be NULL
* \param h Pointer to variable for storing the height in pixels,
* may be NULL
* *
* This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI * \sa SDL_GetWindowSize
* drawable, i.e. the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a * \sa SDL_CreateWindow
* platform with high-DPI support (Apple calls this "Retina"), and not disabled
* by the \c SDL_HINT_VIDEO_HIGHDPI_DISABLED hint.
*
* \note On macOS high-DPI support must be enabled for an application by
* setting NSHighResolutionCapable to true in its Info.plist.
*
* \sa SDL_GetWindowSize()
* \sa SDL_CreateWindow()
*/ */
extern DECLSPEC void SDLCALL SDL_Metal_GetDrawableSize(SDL_Window* window, int *w, extern DECLSPEC void SDLCALL SDL_Metal_GetDrawableSize(SDL_Window* window, int *w,
int *h); int *h);

15
include/SDL_mouse.h
View File

@ -110,9 +110,9 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetMouseState(int *x, int *y);
* window might not be in sync at all times. * window might not be in sync at all times.
* *
* Note: SDL_GetMouseState() returns the mouse position as SDL understands it * Note: SDL_GetMouseState() returns the mouse position as SDL understands it
* from the last pump of the event queue. This function, however, queries * from the last pump of the event queue. This function, however, queries the
* the OS for the current mouse position, and as such, might be a slightly * OS for the current mouse position, and as such, might be a slightly less
* less efficient function. Unless you know what you're doing and have a good * efficient function. Unless you know what you're doing and have a good
* reason to use this function, you probably want SDL_GetMouseState() instead. * 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 * \param x filled in with the current X coord relative to the desktop; can be
@ -245,8 +245,7 @@ extern DECLSPEC int SDLCALL SDL_CaptureMouse(SDL_bool enabled);
extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(void); extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(void);
/** /**
* Create a cursor using the specified bitmap data and * Create a cursor using the specified bitmap data and mask (in MSB format).
* mask (in MSB format).
* *
* `mask` has to be in MSB (Most Significant Bit) format. * `mask` has to be in MSB (Most Significant Bit) format.
* *
@ -328,7 +327,7 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor id);
* the display. SDL_SetCursor(NULL) can be used to force cursor redraw, if * the display. SDL_SetCursor(NULL) can be used to force cursor redraw, if
* this is desired for any reason. * this is desired for any reason.
* *
* \param cursor a cursor to make active * \param cursor a cursor to make active
* *
* \sa SDL_CreateCursor * \sa SDL_CreateCursor
* \sa SDL_GetCursor * \sa SDL_GetCursor
@ -379,8 +378,8 @@ extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor * cursor);
* The cursor starts off displayed but can be turned off. Passing `SDL_ENABLE` * The cursor starts off displayed but can be turned off. Passing `SDL_ENABLE`
* displays the cursor and passing `SDL_DISABLE` hides it. * displays the cursor and passing `SDL_DISABLE` hides it.
* *
* The current state of the mouse cursor can be queried by passing `SDL_QUERY`; * The current state of the mouse cursor can be queried by passing
* either `SDL_DISABLE` or `SDL_ENABLE` will be returned. * `SDL_QUERY`; either `SDL_DISABLE` or `SDL_ENABLE` will be returned.
* *
* \param toggle `SDL_ENABLE` to show the cursor, `SDL_DISABLE` to hide it, * \param toggle `SDL_ENABLE` to show the cursor, `SDL_DISABLE` to hide it,
* `SDL_QUERY` to query the current state without changing it. * `SDL_QUERY` to query the current state without changing it.

31
include/SDL_mutex.h
View File

@ -86,8 +86,8 @@ extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void);
* it. Of all threads waiting to lock the mutex, only one may do so at a time. * it. Of all threads waiting to lock the mutex, only one may do so at a time.
* *
* It is legal for the owning thread to lock an already-locked mutex. It must * It is legal for the owning thread to lock an already-locked mutex. It must
* unlock it the same number of times before it is actually made available * unlock it the same number of times before it is actually made available for
* for other threads in the system (this is known as a "recursive mutex"). * 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. * \return 0, or -1 on error.
@ -105,8 +105,8 @@ extern DECLSPEC int SDLCALL SDL_LockMutex(SDL_mutex * mutex);
* don't want to wait for it, and will return to it to try again later. * 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 * \returns 0, `SDL_MUTEX_TIMEDOUT`, or -1 on error; call SDL_GetError() for
* SDL_GetError() for more information. * more information.
* *
* \sa SDL_CreateMutex * \sa SDL_CreateMutex
* \sa SDL_DestroyMutex * \sa SDL_DestroyMutex
@ -119,8 +119,8 @@ extern DECLSPEC int SDLCALL SDL_TryLockMutex(SDL_mutex * mutex);
* Unlock the mutex. * Unlock the mutex.
* *
* It is legal for the owning thread to lock an already-locked mutex. It must * It is legal for the owning thread to lock an already-locked mutex. It must
* unlock it the same number of times before it is actually made available * unlock it the same number of times before it is actually made available for
* for other threads in the system (this is known as a "recursive mutex"). * other threads in the system (this is known as a "recursive mutex").
* *
* It is an error to unlock a mutex that has not been locked by the current * It is an error to unlock a mutex that has not been locked by the current
* thread, and doing so results in undefined behavior. * thread, and doing so results in undefined behavior.
@ -250,8 +250,7 @@ extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem);
extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem); extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem);
/** /**
* Wait until a semaphore has a positive value and then * Wait until a semaphore has a positive value and then decrements it.
* decrements it.
* *
* This function suspends the calling thread until either the semaphore * This function suspends the calling thread until either the semaphore
* pointed to by `sem` has a positive value, the call is interrupted by a * pointed to by `sem` has a positive value, the call is interrupted by a
@ -371,10 +370,10 @@ extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond);
/** /**
* Wait until a condition variable is signaled. * Wait until a condition variable is signaled.
* *
* This function unlocks the specified `mutex` and waits for another thread * This function unlocks the specified `mutex` and waits for another thread to
* to call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable * call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable
* `cond`. Once the condition variable is signaled, the mutex is re-locked * `cond`. Once the condition variable is signaled, the mutex is re-locked and
* and the function returns. * the function returns.
* *
* The mutex must be locked before calling this function. * The mutex must be locked before calling this function.
* *
@ -397,10 +396,10 @@ extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mutex);
/** /**
* Wait until a condition variable is signaled or a certain time has passed. * Wait until a condition variable is signaled or a certain time has passed.
* *
* This function unlocks the specified `mutex` and waits for another thread * This function unlocks the specified `mutex` and waits for another thread to
* to call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable * call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable
* `cond`, or for the specified time to elapse. Once the condition variable * `cond`, or for the specified time to elapse. Once the condition variable is
* is signaled or the time elapsed, the mutex is re-locked and the function * signaled or the time elapsed, the mutex is re-locked and the function
* returns. * returns.
* *
* The mutex must be locked before calling this function. * The mutex must be locked before calling this function.

4
include/SDL_rect.h
View File

@ -169,8 +169,8 @@ extern DECLSPEC void SDLCALL SDL_UnionRect(const SDL_Rect * A,
/** /**
* Calculate a minimal rectangle enclosing a set of points. * Calculate a minimal rectangle enclosing a set of points.
* *
* If `clip` is not NULL then only points inside of the clipping rectangle * If `clip` is not NULL then only points inside of the clipping rectangle are
* are considered. * considered.
* *
* \param points an array of SDL_Point structures representing points to be * \param points an array of SDL_Point structures representing points to be
* enclosed * enclosed

103
include/SDL_render.h
View File

@ -411,8 +411,7 @@ extern DECLSPEC int SDLCALL SDL_SetTextureAlphaMod(SDL_Texture * texture,
Uint8 alpha); Uint8 alpha);
/** /**
* Get the additional alpha value multiplied into render * Get the additional alpha value multiplied into render copy operations.
* copy operations.
* *
* \param texture the texture to query * \param texture the texture to query
* \param alpha a pointer filled in with the current alpha value * \param alpha a pointer filled in with the current alpha value
@ -426,8 +425,7 @@ extern DECLSPEC int SDLCALL SDL_GetTextureAlphaMod(SDL_Texture * texture,
Uint8 * alpha); Uint8 * alpha);
/** /**
* Set the blend mode for a texture, used by * Set the blend mode for a texture, used by SDL_RenderCopy().
* SDL_RenderCopy().
* *
* If the blend mode is not supported, the closest supported mode is chosen * If the blend mode is not supported, the closest supported mode is chosen
* and this function returns -1. * and this function returns -1.
@ -465,7 +463,7 @@ extern DECLSPEC int SDLCALL SDL_GetTextureBlendMode(SDL_Texture * texture,
* \param scaleMode the SDL_ScaleMode to use for texture scaling. * \param scaleMode the SDL_ScaleMode to use for texture scaling.
* \returns 0 on success, or -1 if the texture is not valid. * \returns 0 on success, or -1 if the texture is not valid.
* *
* \sa SDL_GetTextureScaleMode() * \sa SDL_GetTextureScaleMode
*/ */
extern DECLSPEC int SDLCALL SDL_SetTextureScaleMode(SDL_Texture * texture, extern DECLSPEC int SDLCALL SDL_SetTextureScaleMode(SDL_Texture * texture,
SDL_ScaleMode scaleMode); SDL_ScaleMode scaleMode);
@ -477,7 +475,7 @@ extern DECLSPEC int SDLCALL SDL_SetTextureScaleMode(SDL_Texture * texture,
* \param scaleMode a pointer filled in with the current scale mode. * \param scaleMode a pointer filled in with the current scale mode.
* \return 0 on success, or -1 if the texture is not valid. * \return 0 on success, or -1 if the texture is not valid.
* *
* \sa SDL_SetTextureScaleMode() * \sa SDL_SetTextureScaleMode
*/ */
extern DECLSPEC int SDLCALL SDL_GetTextureScaleMode(SDL_Texture * texture, extern DECLSPEC int SDLCALL SDL_GetTextureScaleMode(SDL_Texture * texture,
SDL_ScaleMode *scaleMode); SDL_ScaleMode *scaleMode);
@ -514,8 +512,8 @@ extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_Texture * texture,
const void *pixels, int pitch); const void *pixels, int pitch);
/** /**
* Update a rectangle within a planar YV12 or IYUV * Update a rectangle within a planar YV12 or IYUV texture with new pixel
* texture with new pixel data. * data.
* *
* You can use SDL_UpdateTexture() as long as your pixel data is a contiguous * You can use SDL_UpdateTexture() as long as your pixel data is a contiguous
* block of Y and U/V planes in the proper order, but this function is * block of Y and U/V planes in the proper order, but this function is
@ -557,9 +555,11 @@ extern DECLSPEC int SDLCALL SDL_UpdateYUVTexture(SDL_Texture * texture,
* \param rect a pointer to the rectangle of pixels to update, or NULL to * \param rect a pointer to the rectangle of pixels to update, or NULL to
* update the entire texture. * update the entire texture.
* \param Yplane the raw pixel data for the Y plane. * \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 Ypitch the number of bytes between rows of pixel data for the Y
* plane.
* \param UVplane the raw pixel data for the UV plane. * \param UVplane the raw pixel data for the UV plane.
* \param UVpitch the number of bytes between rows of pixel data for the UV plane. * \param UVpitch the number of bytes between rows of pixel data for the UV
* plane.
* \return 0 on success, or -1 if the texture is not valid. * \return 0 on success, or -1 if the texture is not valid.
*/ */
extern DECLSPEC int SDLCALL SDL_UpdateNVTexture(SDL_Texture * texture, extern DECLSPEC int SDLCALL SDL_UpdateNVTexture(SDL_Texture * texture,
@ -590,7 +590,7 @@ extern DECLSPEC int SDLCALL SDL_UpdateNVTexture(SDL_Texture * texture,
* or was not created with `SDL_TEXTUREACCESS_STREAMING`; call * or was not created with `SDL_TEXTUREACCESS_STREAMING`; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
* \sa SDL_UnlockTexture * \sa SDL_UnlockTexture
*/ */
extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_Texture * texture, extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_Texture * texture,
const SDL_Rect * rect, const SDL_Rect * rect,
@ -623,8 +623,8 @@ extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_Texture * texture,
* \returns 0 on success, or -1 if the texture is not valid or was not created * \returns 0 on success, or -1 if the texture is not valid or was not created
* with `SDL_TEXTUREACCESS_STREAMING` * with `SDL_TEXTUREACCESS_STREAMING`
* *
* \sa SDL_LockTexture() * \sa SDL_LockTexture
* \sa SDL_UnlockTexture() * \sa SDL_UnlockTexture
*/ */
extern DECLSPEC int SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture, extern DECLSPEC int SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture,
const SDL_Rect *rect, const SDL_Rect *rect,
@ -638,8 +638,8 @@ extern DECLSPEC int SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture,
* be provided. You must fully initialize any area of a texture that you lock * be provided. You must fully initialize any area of a texture that you lock
* before unlocking it, as the pixels might otherwise be uninitialized memory. * before unlocking it, as the pixels might otherwise be uninitialized memory.
* *
* Which is to say: locking and immediately unlocking a texture can result * Which is to say: locking and immediately unlocking a texture can result in
* in corrupted textures, depending on the renderer in use. * corrupted textures, depending on the renderer in use.
* *
* \param texture a texture locked by SDL_LockTexture() * \param texture a texture locked by SDL_LockTexture()
* *
@ -663,8 +663,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_RenderTargetSupported(SDL_Renderer *rendere
* Set a texture as the current rendering target. * Set a texture as the current rendering target.
* *
* Before using this function, you should check the * Before using this function, you should check the
* `SDL_RENDERER_TARGETTEXTURE` bit in the flags of SDL_RendererInfo to see * `SDL_RENDERER_TARGETTEXTURE` bit in the flags of SDL_RendererInfo to see if
* if render targets are supported. * render targets are supported.
* *
* The default render target is the window for which the renderer was created. * 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 * To stop rendering to a texture and render to the window again, call this
@ -672,8 +672,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_RenderTargetSupported(SDL_Renderer *rendere
* *
* \param renderer the rendering context * \param renderer the rendering context
* \param texture the targeted texture, which must be created with the * \param texture the targeted texture, which must be created with the
* `SDL_TEXTUREACCESS_TARGET` flag, or NULL * `SDL_TEXTUREACCESS_TARGET` flag, or NULL to render to the
* to render to the window instead of a texture. * window instead of a texture.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@ -704,7 +704,7 @@ extern DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *renderer
* *
* This function uses the viewport and scaling functionality to allow a fixed * This function uses the viewport and scaling functionality to allow a fixed
* logical resolution for rendering, regardless of the actual output * logical resolution for rendering, regardless of the actual output
* resolution. If the actual output resolution doesn't have the same aspect * resolution. If the actual output resolution doesn't have the same aspect
* ratio the output rendering will be centered within the output display. * ratio the output rendering will be centered within the output display.
* *
* If the output display is a window, mouse and touch events in the window * If the output display is a window, mouse and touch events in the window
@ -779,8 +779,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_RenderGetIntegerScale(SDL_Renderer * render
/** /**
* Set the drawing area for rendering on the current target. * Set the drawing area for rendering on the current target.
* *
* When the window is resized, the viewport is reset to fill the entire * When the window is resized, the viewport is reset to fill the entire new
* new window size. * window size.
* *
* \param renderer the rendering context * \param renderer the rendering context
* \param rect the SDL_Rect structure representing the drawing area, or NULL * \param rect the SDL_Rect structure representing the drawing area, or NULL
@ -891,8 +891,8 @@ extern DECLSPEC void SDLCALL SDL_RenderGetScale(SDL_Renderer * renderer,
/** /**
* Set the color used for drawing operations (Rect, Line and Clear). * Set the color used for drawing operations (Rect, Line and Clear).
* *
* Set the color for drawing or filling rectangles, lines, and points, * Set the color for drawing or filling rectangles, lines, and points, and for
* and for SDL_RenderClear(). * SDL_RenderClear().
* *
* \param renderer the rendering context * \param renderer the rendering context
* \param r the red value used to draw on the rendering target * \param r the red value used to draw on the rendering target
@ -1234,9 +1234,9 @@ extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_Renderer * renderer,
* Copy a portion of the texture to the current rendering, with optional * Copy a portion of the texture to the current rendering, with optional
* rotation and flipping. * rotation and flipping.
* *
* Copy a portion of the texture to the current rendering * Copy a portion of the texture to the current rendering target, optionally
* target, optionally rotating it by angle around the given center and also * rotating it by angle around the given center and also flipping it
* flipping it top-bottom and/or left-right. * top-bottom and/or left-right.
* *
* The texture is blended with the destination based on its blend mode set * The texture is blended with the destination based on its blend mode set
* with SDL_SetTextureBlendMode(). * with SDL_SetTextureBlendMode().
@ -1329,7 +1329,8 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawLinesF(SDL_Renderer * renderer,
* Draw a rectangle on the current rendering target at subpixel precision. * Draw a rectangle on the current rendering target at subpixel precision.
* *
* \param renderer The renderer which should draw a rectangle. * \param renderer The renderer which should draw a rectangle.
* \param rect A pointer to the destination rectangle, or NULL to outline the entire rendering target. * \param 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
*/ */
extern DECLSPEC int SDLCALL SDL_RenderDrawRectF(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderDrawRectF(SDL_Renderer * renderer,
@ -1349,8 +1350,8 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawRectsF(SDL_Renderer * renderer,
int count); int count);
/** /**
* Fill a rectangle on the current rendering target with the drawing color * Fill a rectangle on the current rendering target with the drawing color at
* at subpixel precision. * subpixel precision.
* *
* \param renderer The renderer which should fill a rectangle. * \param renderer The renderer which should fill a rectangle.
* \param rect A pointer to the destination rectangle, or NULL for the entire * \param rect A pointer to the destination rectangle, or NULL for the entire
@ -1391,8 +1392,8 @@ extern DECLSPEC int SDLCALL SDL_RenderCopyF(SDL_Renderer * renderer,
const SDL_FRect * dstrect); const SDL_FRect * dstrect);
/** /**
* Copy a portion of the source texture to the current rendering target, * Copy a portion of the source texture to the current rendering target, with
* with rotation and flipping, at subpixel precision. * rotation and flipping, at subpixel precision.
* *
* \param renderer The renderer which should copy parts of a texture. * \param renderer The renderer which should copy parts of a texture.
* \param texture The source texture. * \param texture The source texture.
@ -1400,10 +1401,13 @@ extern DECLSPEC int SDLCALL SDL_RenderCopyF(SDL_Renderer * renderer,
* texture. * texture.
* \param dstrect A pointer to the destination rectangle, or NULL for the * \param dstrect A pointer to the destination rectangle, or NULL for the
* entire rendering target. * entire rendering target.
* \param angle An angle in degrees that indicates the rotation that will be applied to dstrect, rotating it in a clockwise direction * \param angle An angle in degrees that indicates the rotation that will be
* \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). * applied to dstrect, rotating it in a clockwise direction
* \param flip An SDL_RendererFlip value stating which flipping actions should be performed on the texture * \param center A pointer to a point indicating the point around which
* * dstrect will be rotated (if NULL, rotation will be done
* around dstrect.w/2, dstrect.h/2).
* \param flip An SDL_RendererFlip value stating which flipping actions should
* be performed on the texture
* \return 0 on success, or -1 on error * \return 0 on success, or -1 on error
*/ */
extern DECLSPEC int SDLCALL SDL_RenderCopyExF(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderCopyExF(SDL_Renderer * renderer,
@ -1443,8 +1447,7 @@ extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Renderer * renderer,
void *pixels, int pitch); void *pixels, int pitch);
/** /**
* Update the screen with any rendering performed since * Update the screen with any rendering performed since the previous call.
* the previous call.
* *
* SDL's rendering functions operate on a backbuffer; that is, calling a * SDL's rendering functions operate on a backbuffer; that is, calling a
* rendering function such as SDL_RenderDrawLine() does not directly put a * rendering function such as SDL_RenderDrawLine() does not directly put a
@ -1504,9 +1507,9 @@ extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer * renderer);
* Force the rendering context to flush any pending commands to the underlying * Force the rendering context to flush any pending commands to the underlying
* rendering API. * rendering API.
* *
* You do not need to (and in fact, shouldn't) call this function unless * You do not need to (and in fact, shouldn't) call this function unless you
* you are planning to call into OpenGL/Direct3D/Metal/whatever directly * are planning to call into OpenGL/Direct3D/Metal/whatever directly in
* in addition to using an SDL_Renderer. * addition to using an SDL_Renderer.
* *
* This is for a very-specific case: if you are using SDL's render API, you * This is for a very-specific case: if you are using SDL's render API, you
* asked for a specific renderer backend (OpenGL, Direct3D, etc), you set * asked for a specific renderer backend (OpenGL, Direct3D, etc), you set
@ -1519,9 +1522,9 @@ extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer * renderer);
* maximum performance out of a specific situation. In all other cases, SDL * maximum performance out of a specific situation. In all other cases, SDL
* will do the right thing, perhaps at a performance loss. * will do the right thing, perhaps at a performance loss.
* *
* This function is first available in SDL 2.0.10, and is not needed in * This function is first available in SDL 2.0.10, and is not needed in 2.0.9
* 2.0.9 and earlier, as earlier versions did not queue rendering commands * and earlier, as earlier versions did not queue rendering commands at all,
* at all, instead flushing them to the OS immediately. * 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 * \returns 0 on success or a negative error code on failure; call
@ -1589,10 +1592,10 @@ extern DECLSPEC int SDLCALL SDL_GL_UnbindTexture(SDL_Texture *texture);
* headers, but it can be safely cast to a `CAMetalLayer *`. * 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 * \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a
* renderer * Metal renderer
* *
* \sa SDL_RenderGetMetalCommandEncoder() * \sa SDL_RenderGetMetalCommandEncoder
*/ */
extern DECLSPEC void *SDLCALL SDL_RenderGetMetalLayer(SDL_Renderer * renderer); extern DECLSPEC void *SDLCALL SDL_RenderGetMetalLayer(SDL_Renderer * renderer);
@ -1603,10 +1606,10 @@ extern DECLSPEC void *SDLCALL SDL_RenderGetMetalLayer(SDL_Renderer * renderer);
* headers, but it can be safely cast to an `id<MTLRenderCommandEncoder>`. * headers, but it can be safely cast to an `id<MTLRenderCommandEncoder>`.
* *
* \param renderer The renderer to query * \param renderer The renderer to query
* \returns an `id<MTLRenderCommandEncoder>` on success, or NULL if the renderer * \returns an `id<MTLRenderCommandEncoder>` on success, or NULL if the
* isn't a Metal renderer. * renderer isn't a Metal renderer.
* *
* \sa SDL_RenderGetMetalLayer() * \sa SDL_RenderGetMetalLayer
*/ */
extern DECLSPEC void *SDLCALL SDL_RenderGetMetalCommandEncoder(SDL_Renderer * renderer); extern DECLSPEC void *SDLCALL SDL_RenderGetMetalCommandEncoder(SDL_Renderer * renderer);

14
include/SDL_rwops.h
View File

@ -230,8 +230,8 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWseek(SDL_RWops *context,
/** /**
* Determine the current read/write offset in an SDL_RWops data stream. * Determine the current read/write offset in an SDL_RWops data stream.
* *
* SDL_RWtell is actually a wrapper function that calls the SDL_RWops's * SDL_RWtell is actually a wrapper function that calls the SDL_RWops's `seek`
* `seek` method, with an offset of 0 bytes from `RW_SEEK_CUR`, to simplify * method, with an offset of 0 bytes from `RW_SEEK_CUR`, to simplify
* application development. * application development.
* *
* \param context a SDL_RWops data stream object from which to get the current * \param context a SDL_RWops data stream object from which to get the current
@ -284,9 +284,9 @@ extern DECLSPEC size_t SDLCALL SDL_RWread(SDL_RWops *context,
* Write to an SDL_RWops data stream. * Write to an SDL_RWops data stream.
* *
* This function writes exactly `num` objects each of size `size` from the * This function writes exactly `num` objects each of size `size` from the
* area pointed at by `ptr` to the stream. If this fails for any reason, * area pointed at by `ptr` to the stream. If this fails for any reason, it'll
* it'll return less than `num` to demonstrate how far the write progressed. * return less than `num` to demonstrate how far the write progressed. On
* On success, it returns `num`. * success, it returns `num`.
* *
* SDL_RWwrite is actually a function wrapper that calls the SDL_RWops's * SDL_RWwrite is actually a function wrapper that calls the SDL_RWops's
* `write` method appropriately, to simplify application development. * `write` method appropriately, to simplify application development.
@ -321,8 +321,8 @@ extern DECLSPEC size_t SDLCALL SDL_RWwrite(SDL_RWops *context,
* Note that if this fails to flush the stream to disk, this function reports * Note that if this fails to flush the stream to disk, this function reports
* an error, but the SDL_RWops is still invalid once this function returns. * an error, but the SDL_RWops is still invalid once this function returns.
* *
* SDL_RWclose() is actually a macro that calls the SDL_RWops's `close` * SDL_RWclose() is actually a macro that calls the SDL_RWops's `close` method
* method appropriately, to simplify application development. * appropriately, to simplify application development.
* *
* \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 * \returns 0 on success or a negative error code on failure; call

8
include/SDL_sensor.h
View File

@ -130,9 +130,9 @@ typedef enum
* If you are using the sensor API or handling events from multiple threads * If you are using the sensor API or handling events from multiple threads
* you should use these locking functions to protect access to the sensors. * you should use these locking functions to protect access to the sensors.
* *
* In particular, you are guaranteed that the sensor list won't change, so * In particular, you are guaranteed that the sensor list won't change, so the
* the API functions that take a sensor index will be valid, and sensor * API functions that take a sensor index will be valid, and sensor events
* events will not be delivered. * will not be delivered.
*/ */
extern DECLSPEC void SDLCALL SDL_LockSensors(void); extern DECLSPEC void SDLCALL SDL_LockSensors(void);
extern DECLSPEC void SDLCALL SDL_UnlockSensors(void); extern DECLSPEC void SDLCALL SDL_UnlockSensors(void);
@ -230,7 +230,7 @@ extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetInstanceID(SDL_Sensor *sensor)
/** /**
* Get the current state of an opened sensor. * Get the current state of an opened sensor.
* *
* The number of values and interpretation of the data is sensor dependent. * 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 data A pointer filled with the current sensor state * \param data A pointer filled with the current sensor state

63
include/SDL_shape.h
View File

@ -44,33 +44,34 @@ extern "C" {
#define SDL_WINDOW_LACKS_SHAPE -3 #define SDL_WINDOW_LACKS_SHAPE -3
/** /**
* \brief Create a window that can be shaped with the specified position, dimensions, and flags. * Create a window that can be shaped with the specified position, dimensions,
* and flags.
* *
* \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 * \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 * \param y The y position of the window, ::SDL_WINDOWPOS_CENTERED, or
* ::SDL_WINDOWPOS_UNDEFINED. * ::SDL_WINDOWPOS_UNDEFINED.
* \param w The width of the window. * \param w The width of the window.
* \param h The height 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: * \param flags The flags for the window, a mask of SDL_WINDOW_BORDERLESS with
* ::SDL_WINDOW_OPENGL, ::SDL_WINDOW_INPUT_GRABBED, * any of the following: ::SDL_WINDOW_OPENGL,
* ::SDL_WINDOW_HIDDEN, ::SDL_WINDOW_RESIZABLE, * ::SDL_WINDOW_INPUT_GRABBED, ::SDL_WINDOW_HIDDEN,
* ::SDL_WINDOW_MAXIMIZED, ::SDL_WINDOW_MINIMIZED, * ::SDL_WINDOW_RESIZABLE, ::SDL_WINDOW_MAXIMIZED,
* ::SDL_WINDOW_BORDERLESS is always set, and ::SDL_WINDOW_FULLSCREEN is always unset. * ::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.
* *
* \return the window created, or NULL if window creation failed. * \sa SDL_DestroyWindow
*
* \sa SDL_DestroyWindow()
*/ */
extern DECLSPEC SDL_Window * SDLCALL SDL_CreateShapedWindow(const char *title,unsigned int x,unsigned int y,unsigned int w,unsigned int h,Uint32 flags); extern DECLSPEC SDL_Window * SDLCALL SDL_CreateShapedWindow(const char *title,unsigned int x,unsigned int y,unsigned int w,unsigned int h,Uint32 flags);
/** /**
* \brief Return whether the given window is a shaped window. * Return whether the given window is a shaped window.
* *
* \param window The window to query for being shaped. * \param window The window to query for being shaped.
* * \return SDL_TRUE if the window is a window that can be shaped, SDL_FALSE if
* \return SDL_TRUE if the window is a window that can be shaped, SDL_FALSE if the window is unshaped or NULL. * the window is unshaped or NULL.
* *
* \sa SDL_CreateShapedWindow * \sa SDL_CreateShapedWindow
*/ */
@ -106,29 +107,31 @@ typedef struct SDL_WindowShapeMode {
} SDL_WindowShapeMode; } SDL_WindowShapeMode;
/** /**
* \brief Set the shape and parameters of a shaped window. * Set the shape and parameters of a shaped window.
* *
* \param window The shaped window whose parameters should be set. * \param window The shaped window whose parameters should be set.
* \param shape A surface encoding the desired shape for the window. * \param shape A surface encoding the desired shape for the window.
* \param shape_mode The parameters to set for the shaped window. * \param shape_mode The parameters to set for the shaped window.
* * \return 0 on success, SDL_INVALID_SHAPE_ARGUMENT on an invalid shape
* \return 0 on success, SDL_INVALID_SHAPE_ARGUMENT on an invalid shape argument, or SDL_NONSHAPEABLE_WINDOW * argument, or SDL_NONSHAPEABLE_WINDOW if the SDL_Window given does
* if the SDL_Window given does not reference a valid shaped window. * not reference a valid shaped window.
* *
* \sa SDL_WindowShapeMode * \sa SDL_WindowShapeMode
* \sa SDL_GetShapedWindowMode. * \sa [[SDL_GetShapedWindowMode.]]
*/ */
extern DECLSPEC int SDLCALL SDL_SetWindowShape(SDL_Window *window,SDL_Surface *shape,SDL_WindowShapeMode *shape_mode); extern DECLSPEC int SDLCALL SDL_SetWindowShape(SDL_Window *window,SDL_Surface *shape,SDL_WindowShapeMode *shape_mode);
/** /**
* \brief Get the shape parameters of a shaped window. * Get the shape parameters of a shaped window.
* *
* \param window The shaped window whose parameters should be retrieved. * \param window The shaped window whose parameters should be retrieved.
* \param shape_mode An empty shape-mode structure to fill, or NULL to check whether the window has a shape. * \param shape_mode An empty shape-mode structure to fill, or NULL to check
* * whether the window has a shape.
* \return 0 if the window has a shape and, provided shape_mode was not NULL, shape_mode has been filled with the mode * \return 0 if the window has a shape and, provided shape_mode was not NULL,
* data, SDL_NONSHAPEABLE_WINDOW if the SDL_Window given is not a shaped window, or SDL_WINDOW_LACKS_SHAPE if * shape_mode has been filled with the mode data,
* the SDL_Window given is a shapeable window currently lacking a shape. * SDL_NONSHAPEABLE_WINDOW if the SDL_Window given is not a shaped
* window, or SDL_WINDOW_LACKS_SHAPE if the SDL_Window given is a
* shapeable window currently lacking a shape.
* *
* \sa SDL_WindowShapeMode * \sa SDL_WindowShapeMode
* \sa SDL_SetWindowShape * \sa SDL_SetWindowShape

15
include/SDL_stdinc.h
View File

@ -403,7 +403,7 @@ typedef void *(SDLCALL *SDL_realloc_func)(void *mem, size_t size);
typedef void (SDLCALL *SDL_free_func)(void *mem); typedef void (SDLCALL *SDL_free_func)(void *mem);
/** /**
* \brief Get the current set of SDL memory functions * Get the current set of SDL memory functions
*/ */
extern DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_func, extern DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_func,
SDL_calloc_func *calloc_func, SDL_calloc_func *calloc_func,
@ -411,12 +411,7 @@ extern DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_func
SDL_free_func *free_func); SDL_free_func *free_func);
/** /**
* \brief Replace SDL's memory allocation functions with a custom set * Replace SDL's memory allocation functions with a custom set
*
* \note If you are replacing SDL's memory functions, you should call
* SDL_GetNumAllocations() and be very careful if it returns non-zero.
* That means that your free function will be called with memory
* allocated by the previous memory allocation functions.
*/ */
extern DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func, extern DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func,
SDL_calloc_func calloc_func, SDL_calloc_func calloc_func,
@ -424,7 +419,7 @@ extern DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func,
SDL_free_func free_func); SDL_free_func free_func);
/** /**
* \brief Get the number of outstanding (unfreed) allocations * Get the number of outstanding (unfreed) allocations
*/ */
extern DECLSPEC int SDLCALL SDL_GetNumAllocations(void); extern DECLSPEC int SDLCALL SDL_GetNumAllocations(void);
@ -625,8 +620,8 @@ extern DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf,
size_t * inbytesleft, char **outbuf, size_t * inbytesleft, char **outbuf,
size_t * outbytesleft); size_t * outbytesleft);
/** /**
* This function converts a string between encodings in one pass, returning a * This function converts a string between encodings in one pass, returning a
* string that must be freed with SDL_free() or NULL on error. * string that must be freed with SDL_free() or NULL on error.
*/ */
extern DECLSPEC char *SDLCALL SDL_iconv_string(const char *tocode, extern DECLSPEC char *SDLCALL SDL_iconv_string(const char *tocode,
const char *fromcode, const char *fromcode,

29
include/SDL_surface.h
View File

@ -188,8 +188,8 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceWithFormat
* not allocate memory for the pixel data, instead the caller provides an * not allocate memory for the pixel data, instead the caller provides an
* existing buffer of data for the surface to use. * existing buffer of data for the surface to use.
* *
* No copy is made of the pixel data. Pixel data is not managed * No copy is made of the pixel data. Pixel data is not managed automatically;
* automatically; you must free the surface before you free the pixel data. * you must free the surface before you free the pixel data.
* *
* \param pixels a pointer to existing pixel data * \param pixels a pointer to existing pixel data
* \param width the width of the surface * \param width the width of the surface
@ -226,8 +226,8 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
* instead of providing pixel color masks, you provide it with a predefined * instead of providing pixel color masks, you provide it with a predefined
* format from SDL_PixelFormatEnum. * format from SDL_PixelFormatEnum.
* *
* No copy is made of the pixel data. Pixel data is not managed * No copy is made of the pixel data. Pixel data is not managed automatically;
* automatically; you must free the surface before you free the pixel data. * you must free the surface before you free the pixel data.
* *
* \param pixels a pointer to existing pixel data * \param pixels a pointer to existing pixel data
* \param width the width of the surface * \param width the width of the surface
@ -298,7 +298,7 @@ extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface);
* *
* \param surface the SDL_Surface structure to be unlocked * \param surface the SDL_Surface structure to be unlocked
* *
* \sa SDL_LockSurface() * \sa SDL_LockSurface
*/ */
extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface); extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface);
@ -545,8 +545,8 @@ extern DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface * surface,
/** /**
* Set the clipping rectangle for a surface. * Set the clipping rectangle for a surface.
* *
* When `surface` is the destination of a blit, only the area within the * When `surface` is the destination of a blit, only the area within the clip
* clip rectangle is drawn into. * rectangle is drawn into.
* *
* Note that blits are automatically clipped to the edges of the source and * Note that blits are automatically clipped to the edges of the source and
* destination surfaces. * destination surfaces.
@ -566,8 +566,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface,
/** /**
* Get the clipping rectangle for a surface. * Get the clipping rectangle for a surface.
* *
* When `surface` is the destination of a blit, only the area within the * When `surface` is the destination of a blit, only the area within the clip
* clip rectangle is drawn into. * rectangle is drawn into.
* *
* \param surface the SDL_Surface structure representing the surface to be * \param surface the SDL_Surface structure representing the surface to be
* clipped * clipped
@ -618,8 +618,8 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface
* Copy an existing surface to a new surface of the specified format enum. * Copy an existing surface to a new surface of the specified format enum.
* *
* This function operates just like SDL_ConvertSurface(), but accepts an * This function operates just like SDL_ConvertSurface(), but accepts an
* SDL_PixelFormatEnum value instead of an SDL_PixelFormat structure. As * SDL_PixelFormatEnum value instead of an SDL_PixelFormat structure. As such,
* such, it might be easier to call but it doesn't have access to palette * 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. * 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
@ -768,8 +768,8 @@ extern DECLSPEC int SDLCALL SDL_FillRects
/** /**
* Perform a fast blit from the source surface to the destination surface. * Perform a fast blit from the source surface to the destination surface.
* *
* SDL_UpperBlit() has been replaced by SDL_BlitSurface(), which is merely * SDL_UpperBlit() has been replaced by SDL_BlitSurface(), which is merely a
* a macro for this function with a less confusing name. * macro for this function with a less confusing name.
* *
* \sa SDL_BlitSurface * \sa SDL_BlitSurface
*/ */
@ -868,7 +868,8 @@ extern DECLSPEC void SDLCALL SDL_SetYUVConversionMode(SDL_YUV_CONVERSION_MODE mo
extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionMode(void); extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionMode(void);
/** /**
* Get the YUV conversion mode, returning the correct mode for the resolution when the current conversion mode is SDL_YUV_CONVERSION_AUTOMATIC * Get the YUV conversion mode, returning the correct mode for the resolution
* when the current conversion mode is SDL_YUV_CONVERSION_AUTOMATIC
*/ */
extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionModeForResolution(int width, int height); extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionModeForResolution(int width, int height);

7
include/SDL_system.h
View File

@ -178,8 +178,8 @@ extern DECLSPEC void * SDLCALL SDL_AndroidGetJNIEnv(void);
* return type, even if the implementation returns a jobject. The rationale * return type, even if the implementation returns a jobject. The rationale
* being that the SDL headers can avoid including jni.h. * being that the SDL headers can avoid including jni.h.
* *
* The jobject returned by the function is a local reference and must * The jobject returned by the function is a local reference and must be
* be released by the caller. See the PushLocalFrame() and PopLocalFrame() or * released by the caller. See the PushLocalFrame() and PopLocalFrame() or
* DeleteLocalRef() functions of the Java native interface: * DeleteLocalRef() functions of the Java native interface:
* *
* https://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/functions.html * https://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/functions.html
@ -311,8 +311,7 @@ extern DECLSPEC const char * SDLCALL SDL_AndroidGetExternalStoragePath(void);
/** /**
* Request permissions at runtime. * Request permissions at runtime.
* *
* This blocks the calling thread until the permission is granted or * This blocks the calling thread until the permission is granted or denied.
* denied.
* *
* \param permission The permission to request. * \param permission The permission to request.
* \returns SDL_TRUE if the permission was granted, SDL_FALSE otherwise. * \returns SDL_TRUE if the permission was granted, SDL_FALSE otherwise.

4
include/SDL_syswm.h
View File

@ -351,8 +351,8 @@ typedef struct SDL_SysWMinfo SDL_SysWMinfo;
* You must include SDL_syswm.h for the declaration of SDL_SysWMinfo. * You must include SDL_syswm.h for the declaration of SDL_SysWMinfo.
* *
* The caller must initialize the `info` structure's version by using * The caller must initialize the `info` structure's version by using
* `SDL_VERSION(&info.version)`, and then this function will fill in the * `SDL_VERSION(&info.version)`, and then this function will fill in the rest
* rest of the structure with information about the given window. * of the structure with information about the given window.
* *
* \param window the window about which information is being requested * \param window the window about which information is being requested
* \param info an SDL_SysWMinfo structure filled in with window information * \param info an SDL_SysWMinfo structure filled in with window information

47
include/SDL_thread.h
View File

@ -214,30 +214,29 @@ SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data);
/** /**
* Create a new thread with a specific stack size. * Create a new thread with a specific stack size.
* *
* SDL makes an attempt to report `name` to the system, so that debuggers * SDL makes an attempt to report `name` to the system, so that debuggers can
* can display it. Not all platforms support this. * display it. Not all platforms support this.
* *
* Thread naming is a little complicated: Most systems have very small * Thread naming is a little complicated: Most systems have very small limits
* limits for the string length (Haiku has 32 bytes, Linux currently has 16, * for the string length (Haiku has 32 bytes, Linux currently has 16, Visual
* Visual C++ 6.0 has _nine_!), and possibly other arbitrary rules. You'll * C++ 6.0 has _nine_!), and possibly other arbitrary rules. You'll have to
* have to see what happens with your system's debugger. The name should be * see what happens with your system's debugger. The name should be UTF-8 (but
* UTF-8 (but using the naming limits of C identifiers is a better bet). * using the naming limits of C identifiers is a better bet). There are no
* There are no requirements for thread naming conventions, so long as the * requirements for thread naming conventions, so long as the string is
* string is null-terminated UTF-8, but these guidelines are helpful in * null-terminated UTF-8, but these guidelines are helpful in choosing a name:
* choosing a name:
* *
* https://stackoverflow.com/questions/149932/naming-conventions-for-threads * https://stackoverflow.com/questions/149932/naming-conventions-for-threads
* *
* If a system imposes requirements, SDL will try to munge the string for * If a system imposes requirements, SDL will try to munge the string for it
* it (truncate, etc), but the original string contents will be available * (truncate, etc), but the original string contents will be available from
* from SDL_GetThreadName(). * SDL_GetThreadName().
* *
* The size (in bytes) of the new stack can be specified. Zero means "use * The size (in bytes) of the new stack can be specified. Zero means "use the
* the system default" which might be wildly different between platforms. * system default" which might be wildly different between platforms. x86
* x86 Linux generally defaults to eight megabytes, an embedded device * Linux generally defaults to eight megabytes, an embedded device might be a
* might be a few kilobytes instead. You generally need to specify a stack * few kilobytes instead. You generally need to specify a stack that is a
* that is a multiple of the system's page size (in many cases, this is 4 * multiple of the system's page size (in many cases, this is 4 kilobytes, but
* kilobytes, but check your system documentation). * check your system documentation).
* *
* In SDL 2.1, stack size will be folded into the original SDL_CreateThread * In SDL 2.1, stack size will be folded into the original SDL_CreateThread
* function, but for backwards compatibility, this is currently a separate * function, but for backwards compatibility, this is currently a separate
@ -307,8 +306,8 @@ extern DECLSPEC SDL_threadID SDLCALL SDL_GetThreadID(SDL_Thread * thread);
* Set the priority for the current thread. * Set the priority for the current thread.
* *
* Note that some platforms will not let you alter the priority (or at least, * Note that some platforms will not let you alter the priority (or at least,
* promote the thread to a higher priority) at all, and some require you * promote the thread to a higher priority) at all, and some require you to be
* to be an administrator account. Be prepared for this to fail. * 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 * \returns 0 on success or a negative error code on failure; call
@ -388,8 +387,8 @@ extern DECLSPEC void SDLCALL SDL_DetachThread(SDL_Thread * thread);
/** /**
* Create a piece of thread-local storage. * Create a piece of thread-local storage.
* *
* This creates an identifier that is globally visible to all * This creates an identifier that is globally visible to all threads but
* threads but refers to data that is thread-specific. * refers to data that is thread-specific.
* *
* \returns the newly created thread local storage identifier or 0 on error. * \returns the newly created thread local storage identifier or 0 on error.
* *
@ -440,7 +439,7 @@ extern DECLSPEC void * SDLCALL SDL_TLSGet(SDL_TLSID id);
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, void (SDLCALL *destructor)(void*));
/** /**
* \brief Cleanup all TLS data for this thread. * Cleanup all TLS data for this thread.
*/ */
extern DECLSPEC void SDLCALL SDL_TLSCleanup(void); extern DECLSPEC void SDLCALL SDL_TLSCleanup(void);

123
include/SDL_video.h
View File

@ -443,7 +443,7 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayDPI(int displayIndex, float * ddpi, fl
* \returns The SDL_DisplayOrientation enum value of the display, or * \returns The SDL_DisplayOrientation enum value of the display, or
* `SDL_ORIENTATION_UNKNOWN` if it isn't available. * `SDL_ORIENTATION_UNKNOWN` if it isn't available.
* *
* \sa SDL_GetNumVideoDisplays() * \sa SDL_GetNumVideoDisplays
*/ */
extern DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetDisplayOrientation(int displayIndex); extern DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetDisplayOrientation(int displayIndex);
@ -532,12 +532,12 @@ extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(int displayIndex, SDL_Disp
/** /**
* Get the closest match to the requested display mode. * Get the closest match to the requested display mode.
* *
* The available display modes are scanned and `closest` is filled in with * The available display modes are scanned and `closest` is filled in with the
* the closest mode matching the requested mode and returned. The mode format * closest mode matching the requested mode and returned. The mode format and
* and refresh rate default to the desktop mode if they are set to 0. The * refresh rate default to the desktop mode if they are set to 0. The modes
* modes are scanned with size being first priority, format being second * are scanned with size being first priority, format being second priority,
* priority, and finally checking the refresh rate. If all the available modes * and finally checking the refresh rate. If all the available modes are too
* are too small, then NULL is returned. * 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 * \param mode an SDL_DisplayMode structure containing the desired display
@ -547,8 +547,8 @@ extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(int displayIndex, SDL_Disp
* \returns the passed in value `closest` or NULL if no matching video mode * \returns the passed in value `closest` or NULL if no matching video mode
* was available; call SDL_GetError() for more information. * was available; call SDL_GetError() for more information.
* *
* \sa SDL_GetDisplayMode * \sa SDL_GetDisplayMode
* \sa SDL_GetNumDisplayModes * \sa SDL_GetNumDisplayModes
*/ */
extern DECLSPEC SDL_DisplayMode * SDLCALL SDL_GetClosestDisplayMode(int displayIndex, const SDL_DisplayMode * mode, SDL_DisplayMode * closest); extern DECLSPEC SDL_DisplayMode * SDLCALL SDL_GetClosestDisplayMode(int displayIndex, const SDL_DisplayMode * mode, SDL_DisplayMode * closest);
@ -638,13 +638,13 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window * window);
* *
* If the window is created with the `SDL_WINDOW_ALLOW_HIGHDPI` flag, its size * If the window is created with the `SDL_WINDOW_ALLOW_HIGHDPI` flag, its size
* in pixels may differ from its size in screen coordinates on platforms with * in pixels may differ from its size in screen coordinates on platforms with
* high-DPI support (e.g. iOS and macOS). Use SDL_GetWindowSize() to query * high-DPI support (e.g. iOS and macOS). Use SDL_GetWindowSize() to query the
* the client area's size in screen coordinates, and SDL_GL_GetDrawableSize() * client area's size in screen coordinates, and SDL_GL_GetDrawableSize() or
* or SDL_GetRendererOutputSize() to query the drawable size in pixels. * SDL_GetRendererOutputSize() to query the drawable size in pixels.
* *
* If the window is set fullscreen, the width and height parameters `w` and * If the window is set fullscreen, the width and height parameters `w` and
* `h` will not be used. However, invalid size parameters (e.g. too large) * `h` will not be used. However, invalid size parameters (e.g. too large) may
* may still fail. Window size is actually limited to 16384 x 16384 for all * still fail. Window size is actually limited to 16384 x 16384 for all
* platforms at window creation. * platforms at window creation.
* *
* If the window is created with any of the SDL_WINDOW_OPENGL or * If the window is created with any of the SDL_WINDOW_OPENGL or
@ -722,8 +722,8 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowID(SDL_Window * window);
* these events to specific SDL_Window objects. * 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; * \returns the window associated with `id` or NULL if it doesn't exist; call
* call SDL_GetError() for more information. * SDL_GetError() for more information.
* *
* \sa SDL_GetWindowID * \sa SDL_GetWindowID
*/ */
@ -1083,8 +1083,8 @@ extern DECLSPEC void SDLCALL SDL_MinimizeWindow(SDL_Window * window);
* *
* \param window the window to restore * \param window the window to restore
* *
* \sa SDL_MaximizeWindow * \sa SDL_MaximizeWindow
* \sa SDL_MinimizeWindow * \sa SDL_MinimizeWindow
*/ */
extern DECLSPEC void SDLCALL SDL_RestoreWindow(SDL_Window * window); extern DECLSPEC void SDLCALL SDL_RestoreWindow(SDL_Window * window);
@ -1190,8 +1190,8 @@ extern DECLSPEC void SDLCALL SDL_SetWindowGrab(SDL_Window * window,
/** /**
* Set a window's keyboard grab mode. * Set a window's keyboard grab mode.
* *
* If the caller enables a grab while another window is currently grabbed, * If the caller enables a grab while another window is currently grabbed, the
* the other window loses its grab in favor of the caller's window. * other window loses its grab in favor of the caller's window.
* *
* \param window The window for which the keyboard grab mode should be set. * \param window The window for which the keyboard grab mode should be set.
* \param grabbed This is SDL_TRUE to grab keyboard, and SDL_FALSE to release. * \param grabbed This is SDL_TRUE to grab keyboard, and SDL_FALSE to release.
@ -1207,10 +1207,6 @@ extern DECLSPEC void SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window * window,
* Set a window's mouse grab mode. * Set a window's mouse grab mode.
* *
* \param window The window for which the mouse grab mode should be set. * \param window The window for which the mouse grab mode should be set.
* \param grabbed This is SDL_TRUE to grab mouse, and SDL_FALSE to release.
*
* If the caller enables a grab while another window is currently grabbed,
* the other window loses its grab in favor of the caller's window.
* *
* \sa SDL_GetWindowMouseGrab * \sa SDL_GetWindowMouseGrab
* \sa SDL_SetWindowKeyboardGrab * \sa SDL_SetWindowKeyboardGrab
@ -1513,12 +1509,12 @@ extern DECLSPEC int SDLCALL SDL_SetWindowHitTest(SDL_Window * window,
/** /**
* Request a window to demand attention from the user. * Request a window to demand attention from the user.
* *
* \param window the window to request the flashing for
* \param flash_count number of times the window gets flashed on systems that
* support flashing the window multiple times, like
* Windows, else it is ignored
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
*
* \param window the window to request the flashing for
* \param flash_count number of times the window gets flashed on systems that support flashing the
* window multiple times, like Windows, else it is ignored
*/ */
extern DECLSPEC int SDLCALL SDL_FlashWindow(SDL_Window * window, Uint32 flash_count); extern DECLSPEC int SDLCALL SDL_FlashWindow(SDL_Window * window, Uint32 flash_count);
@ -1615,34 +1611,34 @@ extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path);
* these quirks without any platform-specific code, though: * these quirks without any platform-specific code, though:
* *
* - On Windows, function pointers are specific to the current GL context; * - On Windows, function pointers are specific to the current GL context;
* this means you need to have created a GL context and made it current before * this means you need to have created a GL context and made it current
* calling SDL_GL_GetProcAddress(). If you recreate your context or create a * before calling SDL_GL_GetProcAddress(). If you recreate your context or
* second context, you should assume that any existing function pointers * create a second context, you should assume that any existing function
* aren't valid to use with it. This is (currently) a Windows-specific * pointers aren't valid to use with it. This is (currently) a
* limitation, and in practice lots of drivers don't suffer this limitation, * Windows-specific limitation, and in practice lots of drivers don't suffer
* but it is still the way the wgl API is documented to work and you should * this limitation, but it is still the way the wgl API is documented to
* expect crashes if you don't respect it. Store a copy of the function * work and you should expect crashes if you don't respect it. Store a copy
* pointers that comes and goes with context lifespan. * of the function pointers that comes and goes with context lifespan.
* - On X11, function pointers returned by this function are valid for any * - On X11, function pointers returned by this function are valid for any
* context, and can even be looked up before a context is created at all. This * context, and can even be looked up before a context is created at all.
* means that, for at least some common OpenGL implementations, if you look up * This means that, for at least some common OpenGL implementations, if you
* a function that doesn't exist, you'll get a non-NULL result that is _NOT_ * look up a function that doesn't exist, you'll get a non-NULL result that
* safe to call. You must always make sure the function is actually available * is _NOT_ safe to call. You must always make sure the function is actually
* for a given GL context before calling it, by checking for the existence of * available for a given GL context before calling it, by checking for the
* the appropriate extension with SDL_GL_ExtensionSupported(), or verifying * existence of the appropriate extension with SDL_GL_ExtensionSupported(),
* that the version of OpenGL you're using offers the function as core * or verifying that the version of OpenGL you're using offers the function
* functionality. * as core functionality.
* - Some OpenGL drivers, on all platforms, *will* return NULL if a function * - Some OpenGL drivers, on all platforms, *will* return NULL if a function
* isn't supported, but you can't count on this behavior. Check for extensions * isn't supported, but you can't count on this behavior. Check for
* you use, and if you get a NULL anyway, act as if that extension wasn't * extensions you use, and if you get a NULL anyway, act as if that
* available. This is probably a bug in the driver, but you can code * extension wasn't available. This is probably a bug in the driver, but you
* defensively for this scenario anyhow. * can code defensively for this scenario anyhow.
* - Just because you're on Linux/Unix, don't assume you'll be using X11. * - Just because you're on Linux/Unix, don't assume you'll be using X11.
* Next-gen display servers are waiting to replace it, and may or may not make * Next-gen display servers are waiting to replace it, and may or may not
* the same promises about function pointers. * make the same promises about function pointers.
* - OpenGL function pointers must be declared `APIENTRY` as in the example * - OpenGL function pointers must be declared `APIENTRY` as in the example
* code. This will ensure the proper calling convention is followed on * code. This will ensure the proper calling convention is followed on
* platforms where this matters (Win32) thereby avoiding stack corruption. * 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 * \returns a pointer to the named OpenGL function. The returned pointer
@ -1690,18 +1686,17 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GL_ExtensionSupported(const char
* *
* \sa SDL_GL_GetAttribute * \sa SDL_GL_GetAttribute
* \sa SDL_GL_SetAttribute * \sa SDL_GL_SetAttribute
* \sa <!-- #Remove this section if empty --> * \sa [[<!-- #Remove this section if empty -->]]
*/ */
extern DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void); extern DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void);
/** /**
* Set an OpenGL window attribute before window creation. * Set an OpenGL window attribute before window creation.
* *
* This function sets the OpenGL attribute `attr` to `value`. The * This function sets the OpenGL attribute `attr` to `value`. The requested
* requested attributes should be set before creating an OpenGL window. You * attributes should be set before creating an OpenGL window. You should use
* should use SDL_GL_GetAttribute() to check the values after creating the * SDL_GL_GetAttribute() to check the values after creating the OpenGL
* OpenGL context, since the values obtained can differ from the requested * context, since the values obtained can differ from the requested ones.
* ones.
* *
* \param attr an SDL_GLattr enum value specifying the OpenGL attribute to set * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to set
* \param value the desired value for the attribute * \param value the desired value for the attribute
@ -1738,8 +1733,8 @@ 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. * 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; * \returns the OpenGL context associated with `window` or NULL on error; call
* call SDL_GetError() for more details. * SDL_GetError() for more details.
* *
* \sa SDL_GL_DeleteContext * \sa SDL_GL_DeleteContext
* \sa SDL_GL_MakeCurrent * \sa SDL_GL_MakeCurrent
@ -1813,8 +1808,8 @@ extern DECLSPEC void SDLCALL SDL_GL_GetDrawableSize(SDL_Window * window, int *w,
* Some systems allow specifying -1 for the interval, to enable adaptive * Some systems allow specifying -1 for the interval, to enable adaptive
* vsync. Adaptive vsync works the same as vsync, but if you've already missed * vsync. Adaptive vsync works the same as vsync, but if you've already missed
* the vertical retrace for a given frame, it swaps buffers immediately, which * the vertical retrace for a given frame, it swaps buffers immediately, which
* might be less jarring for the user during occasional framerate drops. If * might be less jarring for the user during occasional framerate drops. If an
* an application requests adaptive vsync and the system does not support it, * application requests adaptive vsync and the system does not support it,
* this function will fail and return -1. In such a case, you should probably * this function will fail and return -1. In such a case, you should probably
* retry the call with 1 for the interval. * retry the call with 1 for the interval.
* *
@ -1863,8 +1858,8 @@ extern DECLSPEC int SDLCALL SDL_GL_GetSwapInterval(void);
* *
* This is used with double-buffered OpenGL contexts, which are the default. * This is used with double-buffered OpenGL contexts, which are the default.
* *
* On macOS, make sure you bind 0 to the draw framebuffer before swapping * On macOS, make sure you bind 0 to the draw framebuffer before swapping the
* the window, otherwise nothing will happen. If you aren't using * window, otherwise nothing will happen. If you aren't using
* glBindFramebuffer(), this is the default and you won't have to do anything * glBindFramebuffer(), this is the default and you won't have to do anything
* extra. * extra.
* *

66
include/SDL_vulkan.h
View File

@ -77,21 +77,21 @@ typedef VkSurfaceKHR SDL_vulkanSurface; /* for compatibility with Tizen */
* application links to a dynamic library and both it and SDL use the same * application links to a dynamic library and both it and SDL use the same
* search path. * search path.
* *
* If you specify a non-NULL `path`, an application should retrieve * If you specify a non-NULL `path`, an application should retrieve all of the
* all of the Vulkan functions it uses from the dynamic library using * Vulkan functions it uses from the dynamic library using
* SDL_Vulkan_GetVkGetInstanceProcAddr unless you can guarantee `path` * SDL_Vulkan_GetVkGetInstanceProcAddr unless you can guarantee `path` points
* points to the same vulkan loader library the application linked to. * to the same vulkan loader library the application linked to.
* *
* On Apple devices, if `path` is NULL, SDL will attempt to find the * On Apple devices, if `path` is NULL, SDL will attempt to find the
* `vkGetInstanceProcAddr` address within all the Mach-O images of the * `vkGetInstanceProcAddr` address within all the Mach-O images of the current
* current process. This is because it is fairly common for Vulkan * process. This is because it is fairly common for Vulkan applications to
* applications to link with libvulkan (and historically MoltenVK was provided * link with libvulkan (and historically MoltenVK was provided as a static
* as a static library). If it is not found, on macOS, SDL will attempt * library). If it is not found, on macOS, SDL will attempt to load
* to load `vulkan.framework/vulkan`, `libvulkan.1.dylib`, * `vulkan.framework/vulkan`, `libvulkan.1.dylib`,
* `MoltenVK.framework/MoltenVK`, and `libMoltenVK.dylib`, in that * `MoltenVK.framework/MoltenVK`, and `libMoltenVK.dylib`, in that order. On
* order. On iOS, SDL will attempt to load `libMoltenVK.dylib`. * iOS, SDL will attempt to load `libMoltenVK.dylib`. Applications using a
* Applications using a dynamic framework or .dylib must ensure it is included * dynamic framework or .dylib must ensure it is included in its application
* in its application bundle. * bundle.
* *
* On non-Apple devices, application linking with a static libvulkan is not * On non-Apple devices, application linking with a static libvulkan is not
* supported. Either do not link to the Vulkan loader or link to a dynamic * supported. Either do not link to the Vulkan loader or link to a dynamic
@ -111,8 +111,8 @@ extern DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path);
/** /**
* Get the address of the `vkGetInstanceProcAddr` function. * Get the address of the `vkGetInstanceProcAddr` function.
* *
* This should be called after either calling SDL_Vulkan_LoadLibrary() * This should be called after either calling SDL_Vulkan_LoadLibrary() or
* or creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag. * creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag.
* *
* \returns the function pointer for `vkGetInstanceProcAddr` or NULL on error. * \returns the function pointer for `vkGetInstanceProcAddr` or NULL on error.
*/ */
@ -128,29 +128,27 @@ extern DECLSPEC void *SDLCALL SDL_Vulkan_GetVkGetInstanceProcAddr(void);
extern DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void); extern DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void);
/** /**
* Get the names of the Vulkan instance extensions needed * Get the names of the Vulkan instance extensions needed to create a surface
* to create a surface with SDL_Vulkan_CreateSurface. * with SDL_Vulkan_CreateSurface.
* *
* If `pNames` is NULL, then the number of required Vulkan instance * If `pNames` is NULL, then the number of required Vulkan instance extensions
* extensions is returned in `pCount`. Otherwise, `pCount` must point * is returned in `pCount`. Otherwise, `pCount` must point to a variable set
* to a variable set to the number of elements in the `pNames` array, and * to the number of elements in the `pNames` array, and on return the variable
* on return the variable is overwritten with the number of names actually * is overwritten with the number of names actually written to `pNames`. If
* written to `pNames`. If `pCount` is less than the number of * `pCount` is less than the number of required extensions, at most `pCount`
* required extensions, at most `pCount` structures will be written. If * structures will be written. If `pCount` is smaller than the number of
* `pCount` is smaller than the number of required extensions, * required extensions, SDL_FALSE will be returned instead of SDL_TRUE, to
* SDL_FALSE will be returned instead of SDL_TRUE, to indicate * indicate that not all the required extensions were returned.
* that not all the required extensions were returned.
* *
* The `window` parameter is currently needed to be valid as of * The `window` parameter is currently needed to be valid as of SDL 2.0.8,
* SDL 2.0.8, however, this parameter will likely be removed in future * however, this parameter will likely be removed in future releases
* releases
* *
* \param window A window for which the required Vulkan instance extensions * \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 * \param pCount A pointer to an unsigned int corresponding to the number of
* number of extensions to be returned * extensions to be returned
* \param pNames NULL or a pointer to an array to be filled with required * \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. * \returns SDL_TRUE on success, SDL_FALSE on error.
* *
* \since This function is available in SDL 2.0.8 * \since This function is available in SDL 2.0.8
@ -187,8 +185,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window,
* Get the size of the window's underlying drawable dimensions in pixels. * Get the size of the window's underlying drawable dimensions in pixels.
* *
* This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI * This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI
* drawable, i.e. the window was created with `SDL_WINDOW_ALLOW_HIGHDPI` * drawable, i.e. the window was created with `SDL_WINDOW_ALLOW_HIGHDPI` on a
* on a platform with high-DPI support (Apple calls this "Retina"), and not * platform with high-DPI support (Apple calls this "Retina"), and not
* disabled by the `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint. * disabled by the `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint.
* *
* \param window an SDL_Window for which the size is to be queried * \param window an SDL_Window for which the size is to be queried