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.
*
* \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,
* otherwise it returns the initialization status of the specified
* subsystems.
* \returns a mask of all initialized subsystems if `flags` is 0, otherwise it
* returns the initialization status of the specified subsystems.
*
* 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
* 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,
* and for thread B to read the flag and get the data. In this case you
* would insert a release barrier between writing the data and the flag,
* A typical pattern would be for thread A to write some data and a flag, and
* for thread B to read the flag and get the data. In this case you would
* insert a release barrier between writing the data and the flag,
* guaranteeing that the data write completes no later than the flag is
* written, and you would insert an acquire barrier between reading the
* flag and reading the data, to ensure that all the reads associated
* with the flag have completed.
* written, and you would insert an acquire barrier between reading the flag
* and reading the data, to ensure that all the reads associated with the flag
* have completed.
*
* In this pattern you should always see a release barrier paired with
* an acquire barrier and you should gate the data reads/writes with a
* single flag variable.
* In this pattern you should always see a release barrier paired with an
* acquire barrier and you should gate the data reads/writes with a single
* flag variable.
*
* For more information on these semantics, take a look at the blog post:
* http://preshing.com/20120913/acquire-and-release-semantics
@ -238,8 +238,7 @@ typedef void (*SDL_KernelMemoryBarrierFunc)();
typedef struct { int value; } SDL_atomic_t;
/**
* Set an atomic variable to a new value if it is
* currently an old value.
* Set an atomic variable to a new value if it is currently an old value.
*
* ***Note: If you don't know what this function is for, you shouldn't use
* it!***
@ -321,8 +320,7 @@ extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_atomic_t *a, int v);
#endif
/**
* Set a pointer to a new value if it is currently an old
* value.
* Set a pointer to a new value if it is currently an old value.
*
* ***Note: If you don't know what this function is for, you shouldn't use
* it!***

131
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.
*
* \param desired an SDL_AudioSpec structure representing the desired output
* format. Please refer to the SDL_OpenAudioDevice documentation
* for details on how to prepare this structure.
* format. Please refer to the SDL_OpenAudioDevice
* documentation for details on how to prepare this structure.
* \param obtained an SDL_AudioSpec structure filled in with the actual
* parameters, or NULL.
* \returns 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
* function will be guaranteed to be in the requested format, and
* will be automatically converted to the actual hardware audio
* format if necessary. If `obtained` is NULL, `desired` will
* have fields modified.
* format if necessary. If `obtained` is NULL, `desired` will have
* fields modified.
*
* This function returns a negative error code on failure to open the
* audio device or failure to set up the audio thread; call
@ -350,8 +350,8 @@ typedef Uint32 SDL_AudioDeviceID;
* subsystem.
*
* Note that audio capture support is not implemented as of SDL 2.0.4, so the
* `iscapture` parameter is for future expansion and should always be zero
* for now.
* `iscapture` parameter is for future expansion and should always be zero for
* now.
*
* This function will return -1 if an explicit list of devices can't be
* determined. Returning -1 is not an error. For example, if SDL is set up to
@ -463,26 +463,26 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
*
* - `desired->freq` should be the frequency in sample-frames-per-second (Hz).
* - `desired->format` should be the audio format (`AUDIO_S16SYS`, etc).
* - `desired->samples` is the desired size of the audio buffer, in
* _sample frames_ (with stereo output, two samples--left and right--would
* make a single sample frame). This number should be a power of two, and
* may be adjusted by the audio driver to a value more suitable for the
* hardware. Good values seem to range between 512 and 8096 inclusive,
* depending on the application and CPU speed. Smaller values reduce
* latency, but can lead to underflow if the application is doing heavy
* processing and cannot fill the audio buffer in time. Note that the
* number of sample frames is directly related to time by the following
* formula: `ms = (sampleframes*1000)/freq`
* - `desired->samples` is the desired size of the audio buffer, in _sample
* frames_ (with stereo output, two samples--left and right--would make a
* single sample frame). This number should be a power of two, and may be
* adjusted by the audio driver to a value more suitable for the hardware.
* Good values seem to range between 512 and 8096 inclusive, depending on
* the application and CPU speed. Smaller values reduce latency, but can
* lead to underflow if the application is doing heavy processing and cannot
* fill the audio buffer in time. Note that the number of sample frames is
* directly related to time by the following formula: `ms =
* (sampleframes*1000)/freq`
* - `desired->size` is the size in _bytes_ of the audio buffer, and is
* calculated by SDL_OpenAudioDevice(). You don't initialize this.
* - `desired->silence` is the value used to set the buffer to silence,
* and is calculated by SDL_OpenAudioDevice(). You don't initialize this.
* - `desired->callback` should be set to a function that will be called
* when the audio device is ready for more data. It is passed a pointer
* to the audio buffer, and the length in bytes of the audio buffer.
* This function usually runs in a separate thread, and so you should
* protect data structures that it accesses by calling SDL_LockAudioDevice()
* and SDL_UnlockAudioDevice() in your code. Alternately, you may pass a NULL
* - `desired->silence` is the value used to set the buffer to silence, and is
* calculated by SDL_OpenAudioDevice(). You don't initialize this.
* - `desired->callback` should be set to a function that will be called when
* the audio device is ready for more data. It is passed a pointer to the
* audio buffer, and the length in bytes of the audio buffer. This function
* usually runs in a separate thread, and so you should protect data
* structures that it accesses by calling SDL_LockAudioDevice() and
* SDL_UnlockAudioDevice() in your code. Alternately, you may pass a NULL
* pointer here, and call SDL_QueueAudio() with some frequency, to queue
* more audio samples to be played (or for capture devices, call
* SDL_DequeueAudio() with some frequency, to obtain audio samples).
@ -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
* supports int16, SDL will set the hardware to int16. If you had set
* SDL_AUDIO_ALLOW_FORMAT_CHANGE, SDL will change the format in the
* `obtained` structure. If that flag was *not* set, SDL will prepare to
* convert your callback's float32 audio to int16 before feeding it to the
* hardware and will keep the originally requested format in the `obtained`
* structure.
* SDL_AUDIO_ALLOW_FORMAT_CHANGE, SDL will change the format in the `obtained`
* structure. If that flag was *not* set, SDL will prepare to convert your
* callback's float32 audio to int16 before feeding it to the hardware and
* will keep the originally requested format in the `obtained` structure.
*
* If your application can only handle one specific data format, pass a zero
* for `allowed_changes` and let SDL transparently handle any differences.
@ -590,24 +589,24 @@ extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
/**
* Load the audio data of a WAVE file into memory.
*
* Loading a WAVE file requires `src`, `spec`, `audio_buf` and `audio_len`
* to be valid pointers. The entire data portion of the file is then loaded
* into memory and decoded if necessary.
* Loading a WAVE file requires `src`, `spec`, `audio_buf` and `audio_len` to
* be valid pointers. The entire data portion of the file is then loaded into
* memory and decoded if necessary.
*
* If `freesrc` is non-zero, the data source gets automatically closed and
* freed before the function returns.
*
* Supported formats are RIFF WAVE files with the formats PCM (8, 16, 24, and
* 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits),
* and A-law and mu-law (8 bits). Other formats are currently unsupported and
* 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and
* A-law and mu-law (8 bits). Other formats are currently unsupported and
* cause an error.
*
* If this function succeeds, the pointer returned by it is equal to `spec`
* and the pointer to the audio data allocated by the function is written to
* `audio_buf` and its length in bytes to `audio_len`. The SDL_AudioSpec
* members `freq`, `channels`, and `format` are set to the values of the
* audio data in the buffer. The `samples` member is set to a sane default
* and all others are set to zero.
* members `freq`, `channels`, and `format` are set to the values of the audio
* data in the buffer. The `samples` member is set to a sane default and all
* others are set to zero.
*
* It's necessary to use SDL_FreeWAV() to free the audio data returned in
* `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
* provide compatibility with these files, this decoder is lenient in regards
* to the truncation of the file, the fact chunk, and the size of the RIFF
* chunk. The hints `SDL_HINT_WAVE_RIFF_CHUNK_SIZE`, `SDL_HINT_WAVE_TRUNCATION`,
* and `SDL_HINT_WAVE_FACT_CHUNK` can be used to tune the behavior of the
* loading process.
* chunk. The hints `SDL_HINT_WAVE_RIFF_CHUNK_SIZE`,
* `SDL_HINT_WAVE_TRUNCATION`, and `SDL_HINT_WAVE_FACT_CHUNK` can be used to
* tune the behavior of the loading process.
*
* Any file that is invalid (due to truncation, corruption, or wrong values in
* the headers), too big, or unsupported causes an error. Additionally, any
* critical I/O error from the data source will terminate the loading process
* with an error. The function returns NULL on error and in all cases (with the
* exception of `src` being NULL), an appropriate error message will be set.
* with an error. The function returns NULL on error and in all cases (with
* the exception of `src` being NULL), an appropriate error message will be
* set.
*
* It is required that the data source supports seeking.
*
* Example:
*
* ```c++
* 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 spec An SDL_AudioSpec that will be filled in with the wave file's
* format details
* \param audio_buf A pointer filled with the audio data, allocated by the function.
* \param audio_len A pointer filled with the length of the audio data buffer in bytes
* \param audio_buf A pointer filled with the audio data, allocated by the
* function.
* \param audio_len A pointer filled with the length of the audio data buffer
* in bytes
* \returns This function, if successfully called, returns `spec`, which will
* be filled with the audio data format of the wave source data.
* `audio_buf` will be filled with a pointer to an allocated buffer
@ -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
* see SDL_AudioFormat
* \param dst_channels the number of channels in the destination
* \param dst_rate the frequency (sample-frames-per-second) of the
* destination
* \param dst_rate the frequency (sample-frames-per-second) of the destination
* \returns 1 if the audio filter is prepared, 0 if no conversion is needed,
* or a negative error code on failure; call SDL_GetError() for more
* information.
@ -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
* the data during its largest conversion pass. After SDL_BuildAudioCVT()
* returns, the application should set the `cvt->len` field to the size, in
* bytes, of the source data, and allocate a buffer that is
* `cvt->len * cvt->len_mult` bytes long for the `buf` field.
* bytes, of the source data, and allocate a buffer that is `cvt->len *
* cvt->len_mult` bytes long for the `buf` field.
*
* The source data should be copied into this buffer before the call to
* SDL_ConvertAudio(). Upon successful return, this buffer will contain the
@ -838,10 +840,11 @@ extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const vo
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
* 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.
* Get the number of converted/resampled bytes available.
*
* The stream may be 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
* \sa SDL_AudioStreamPut
@ -856,9 +859,9 @@ extern DECLSPEC int SDLCALL SDL_AudioStreamAvailable(SDL_AudioStream *stream);
* Tell the stream that you're done sending data, and anything being buffered
* should be converted/resampled and made available immediately.
*
* It is legal to add more data to a stream after flushing, but there will
* be audio gaps in the output. Generally this is intended to signal the
* end of input, so the complete output becomes available.
* It is legal to add more data to a stream after flushing, but there will be
* audio gaps in the output. Generally this is intended to signal the end of
* input, so the complete output becomes available.
*
* \sa SDL_NewAudioStream
* \sa SDL_AudioStreamPut
@ -920,8 +923,8 @@ extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
/**
* Mix audio data in a specified format.
*
* This takes an audio buffer `src` of `len` bytes of `format` data and
* mixes it into `dst`, performing addition, volume adjustment, and overflow
* This takes an audio buffer `src` of `len` bytes of `format` data and mixes
* it into `dst`, performing addition, volume adjustment, and overflow
* clipping. The buffer pointed to by `dst` must also be `len` bytes of
* `format` data.
*
@ -981,6 +984,11 @@ extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
* You should not call SDL_LockAudio() on the device before queueing; SDL
* 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 data the data to queue to the device for later playback
* \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 data a pointer into where audio data should be copied
* \param len the number of bytes (not samples!) to which (data) points
* \returns the number of bytes dequeued, which could be less than requested; call
* SDL_GetError() for more information.
* \returns the number of bytes dequeued, which could be less than requested;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.5.
*
@ -1045,9 +1053,8 @@ extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *dat
/**
* Get the number of bytes of still-queued audio.
*
* For playback devices: this is the number of bytes that have been queued
* for playback with SDL_QueueAudio(), but have not yet been sent to the
* hardware.
* For playback devices: this is the number of bytes that have been queued for
* playback with SDL_QueueAudio(), but have not yet been sent to the hardware.
*
* 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

12
include/SDL_blendmode.h
View File

@ -109,8 +109,8 @@ typedef enum
* dstA = alphaOperation(srcA * srcAlphaFactor, dstA * dstAlphaFactor);
* ```
*
* Where the functions `colorOperation(src, dst)` and
* `alphaOperation(src, dst)` can return one of the following:
* Where the functions `colorOperation(src, dst)` and `alphaOperation(src,
* dst)` can return one of the following:
*
* - `src + dst`
* - `src - dst`
@ -140,8 +140,8 @@ typedef enum
* factors produce unexpected results with `SDL_BLENDOPERATION_MINIMUM` and
* `SDL_BLENDOPERATION_MAXIMUM`.
* - **opengl**: Supports the `SDL_BLENDOPERATION_ADD` operation with all
* factors. OpenGL versions 1.1, 1.2, and 1.3 do not work correctly with
* SDL 2.0.6.
* factors. OpenGL versions 1.1, 1.2, and 1.3 do not work correctly with SDL
* 2.0.6.
* - **opengles**: Supports the `SDL_BLENDOPERATION_ADD` operation with all
* factors. Color and alpha factors need to be the same. OpenGL ES 1
* implementation specific: May also support `SDL_BLENDOPERATION_SUBTRACT`
@ -149,8 +149,8 @@ typedef enum
* operations being different from each other. May support color and alpha
* factors being different from each other.
* - **opengles2**: Supports the `SDL_BLENDOPERATION_ADD`,
* `SDL_BLENDOPERATION_SUBTRACT`, `SDL_BLENDOPERATION_REV_SUBTRACT` operations
* with all factors.
* `SDL_BLENDOPERATION_SUBTRACT`, `SDL_BLENDOPERATION_REV_SUBTRACT`
* operations with all factors.
* - **psp**: 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.
*
* 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.
*
@ -418,15 +419,16 @@ extern DECLSPEC int SDLCALL SDL_GetSystemRAM(void);
* Report the alignment this system needs for SIMD allocations.
*
* This will return the minimum number of bytes to which a pointer must be
* aligned to be compatible with SIMD instructions on the current machine.
* For example, if the machine supports SSE only, it will return 16, but if
* it supports AVX-512F, it'll return 64 (etc). This only reports values for
* aligned to be compatible with SIMD instructions on the current machine. For
* example, if the machine supports SSE only, it will return 16, but if it
* supports AVX-512F, it'll return 64 (etc). This only reports values for
* instruction sets SDL knows about, so if your SDL build doesn't have
* SDL_HasAVX512F(), then it might return 16 for the SSE support it sees and
* not 64 for the AVX-512 instructions that exist but SDL doesn't know about.
* Plan accordingly.
*
* \returns 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);
@ -434,24 +436,24 @@ extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void);
* Allocate memory in a SIMD-friendly way.
*
* This will allocate a block of memory that is suitable for use with SIMD
* instructions. Specifically, it will be properly aligned and padded for
* the system's supported vector instructions.
* instructions. Specifically, it will be properly aligned and padded for the
* system's supported vector instructions.
*
* The memory returned will be padded such that it is safe to read or write
* an incomplete vector at the end of the memory block. This can be useful
* so you don't have to drop back to a scalar fallback at the end of your
* SIMD processing loop to deal with the final elements without overflowing
* the allocated buffer.
* The memory returned will be padded such that it is safe to read or write an
* incomplete vector at the end of the memory block. This can be useful so you
* don't have to drop back to a scalar fallback at the end of your SIMD
* processing loop to deal with the final elements without overflowing the
* allocated buffer.
*
* You must free this memory with SDL_FreeSIMD(), not free() or SDL_free()
* or delete[], etc.
* You must free this memory with SDL_FreeSIMD(), not free() or SDL_free() or
* delete[], etc.
*
* Note that SDL will only deal with SIMD instruction sets it is aware of;
* for example, SDL 2.0.8 knows that SSE wants 16-byte vectors
* (SDL_HasSSE()), and AVX2 wants 32 bytes (SDL_HasAVX2()), but doesn't
* know that AVX-512 wants 64. To be clear: if you can't decide to use an
* instruction set with an SDL_Has*() function, don't use that instruction
* set with memory allocated through here.
* Note that SDL will only deal with SIMD instruction sets it is aware of; for
* example, SDL 2.0.8 knows that SSE wants 16-byte vectors (SDL_HasSSE()), and
* AVX2 wants 32 bytes (SDL_HasAVX2()), but doesn't know that AVX-512 wants
* 64. To be clear: if you can't decide to use an instruction set with an
* SDL_Has*() function, don't use that instruction set with memory allocated
* through here.
*
* 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
@ -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.
*
* The memory pointed to by `ptr` is no longer valid for access upon return,
* and may be returned to the system or reused by a future allocation.
* The pointer passed to this function is no longer safe to dereference once
* this function returns, and should be discarded.
* and may be returned to the system or reused by a future allocation. The
* pointer passed to this function is no longer safe to dereference once this
* function returns, and should be discarded.
*
* \param ptr The pointer, returned from SDL_SIMDAlloc or SDL_SIMDRealloc,
* to deallocate. NULL is a legal no-op.
* \param ptr The pointer, returned from SDL_SIMDAlloc or SDL_SIMDRealloc, to
* deallocate. NULL is a legal no-op.
*
* \sa SDL_SIMDAlloc
* \sa SDL_SIMDRealloc

35
include/SDL_error.h
View File

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

35
include/SDL_events.h
View File

@ -671,8 +671,8 @@ typedef enum
*
* `action` may be any of the following:
*
* - `SDL_ADDEVENT`: up to `numevents` events will be added to the back of
* the event queue.
* - `SDL_ADDEVENT`: up to `numevents` events will be added to the back 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
* 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.
*
* If `event` is not NULL, the next event is removed from the queue and
* stored in the SDL_Event structure pointed to by `event`. The 1 returned
* refers to this event, immediately stored in the SDL Event structure -- not
* an event to follow.
* If `event` is not NULL, the next event is removed from the queue and stored
* in the SDL_Event structure pointed to by `event`. The 1 returned refers to
* this event, immediately stored in the SDL Event structure -- not an event
* to follow.
*
* If `event` is NULL, it simply returns 1 if there is an event in 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.
*
* If `event` is not NULL, the next event is removed from the queue and
* stored in the SDL_Event structure pointed to by `event`.
* If `event` is not NULL, the next event is removed from the queue and stored
* in the SDL_Event structure pointed to by `event`.
*
* As this function implicitly calls SDL_PumpEvents(), you can only call this
* 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);
/**
* Wait until the specified timeout (in milliseconds) for
* the next available event.
* Wait until the specified timeout (in milliseconds) for the next available
* event.
*
* If `event` is not NULL, the next event is removed from the queue and
* stored in the SDL_Event structure pointed to by `event`.
* If `event` is not NULL, the next event is removed from the queue and stored
* in the SDL_Event structure pointed to by `event`.
*
* As this function implicitly calls SDL_PumpEvents(), you can only call this
* function in the thread that initialized the video subsystem.
@ -935,8 +935,8 @@ typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
*
* There is one caveat when dealing with the ::SDL_QuitEvent event type. The
* event filter is only called when the window manager desires to close the
* application window. If the event filter returns 1, then the window will
* be closed, otherwise the window will remain open if possible.
* application window. If the event filter returns 1, then the window will be
* closed, otherwise the window will remain open if possible.
*
* Note: Disabled events never make it to the event filter function; see
* SDL_EventState().
@ -1004,8 +1004,7 @@ extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter,
void *userdata);
/**
* Remove an event watch callback added with
* SDL_AddEventWatch().
* Remove an event watch callback added with SDL_AddEventWatch().
*
* This function takes the same input as SDL_AddEventWatch() to identify and
* delete the corresponding callback.
@ -1019,8 +1018,8 @@ extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter,
void *userdata);
/**
* Run a specific filter function on the current event
* queue, removing any events for which the filter returns 0.
* Run a specific filter function on the current event queue, removing any
* events for which the filter returns 0.
*
* See SDL_SetEventFilter() for more information. Unlike SDL_SetEventFilter(),
* this function does not change the filter permanently, it only uses the

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

52
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)
/**
* Add support for controllers that SDL is unaware of or
* to cause an existing controller to have a different binding.
* Add support for controllers that SDL is unaware of or to cause an existing
* controller to have a different binding.
*
* The mapping string has the format "GUID,name,mapping", where GUID is the
* 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.
*
* \returns the mapping string. Must be freed with SDL_free().
* Returns NULL if the index is out of range.
* \returns the mapping string. Must be freed with SDL_free(). Returns NULL if
* the index is out of range.
*/
extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForIndex(int mapping_index);
@ -259,8 +259,7 @@ extern DECLSPEC char * SDLCALL SDL_GameControllerMapping(SDL_GameController *gam
extern DECLSPEC SDL_bool SDLCALL SDL_IsGameController(int joystick_index);
/**
* Get the implementation dependent name for the game
* controller.
* Get the implementation dependent name for the game controller.
*
* 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
* SDL_NumJoysticks()-1
* \returns the mapping string. Must be freed with SDL_free(). Returns NULL
* if no mapping is available.
* \returns the mapping string. Must be freed with SDL_free(). Returns NULL if
* no mapping is available.
*/
extern DECLSPEC char *SDLCALL SDL_GameControllerMappingForDeviceIndex(int joystick_index);
@ -341,11 +340,11 @@ extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromInstanceID(SDL
/**
* Get the SDL_GameController associated with a player index.
*
* Please note that the player index is _not_ the device index, nor is it
* the instance id!
* Please note that the player index is _not_ the device index, nor is it the
* instance id!
*
* \param player_index the player index, which is not the device index or
* the instance id!
* \param player_index the player index, which is not the device index or the
* instance id!
* \returns the SDL_GameController associated with a player index.
*
* \sa SDL_GameControllerGetPlayerIndex
@ -433,7 +432,8 @@ extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProductVersion(SDL_GameContr
/**
* Get the serial number of an opened controller, if available.
*
* Returns the serial number of the controller, or NULL if it is not available.
* Returns the serial number of the controller, or NULL if it is not
* available.
*
* \param gamecontroller the game controller object to query.
* \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 axis an axis enum value (one of the SDL_GameControllerAxis values)
* \returns a SDL_GameControllerButtonBind describing the bind. On
* failure (like the given Controller axis doesn't exist on the
* device), its `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
* \returns a SDL_GameControllerButtonBind describing the bind. On failure
* (like the given Controller axis doesn't exist on the device), its
* `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
*
* \since This function is available since SDL 2.0.0.
*
@ -644,7 +644,6 @@ typedef enum
* \param str string representing a SDL_GameController axis
* \returns the SDL_GameControllerButton enum corresponding to the input
* string, or `SDL_CONTROLLER_AXIS_INVALID` if no match was found.
*
*/
extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFromString(const char *str);
@ -669,9 +668,9 @@ extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForButton(SDL_Gam
*
* \param gamecontroller a game controller
* \param button an button enum value (an SDL_GameControllerButton value)
* \returns a SDL_GameControllerButtonBind describing the bind. On
* failure (like the given Controller button doesn't exist on the
* device), its `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
* \returns a SDL_GameControllerButtonBind describing the bind. On failure
* (like the given Controller button doesn't exist on the device),
* its `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
*
* \since This function is available since SDL 2.0.0.
*
@ -715,7 +714,8 @@ extern DECLSPEC Uint8 SDLCALL SDL_GameControllerGetButton(SDL_GameController *ga
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);
@ -729,7 +729,6 @@ extern DECLSPEC int SDLCALL SDL_GameControllerGetTouchpadFinger(SDL_GameControll
*
* \param gamecontroller The controller to query
* \param type The type of sensor to query
*
* \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise.
*/
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 type The type of sensor to enable/disable
* \param enabled Whether data reporting should be enabled
*
* \returns 0 or -1 if an error occurred.
*/
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 type The type of sensor to query
*
* \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise.
*/
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 left_rumble The intensity of the left trigger rumble motor, from 0
* to 0xFFFF
* \param right_rumble The intensity of the right trigger rumble motor, from 0 to 0xFFFF
* \param right_rumble The intensity of the right trigger rumble motor, from 0
* to 0xFFFF
* \param duration_ms The duration of the rumble effect, in milliseconds
*
* \returns 0, or -1 if trigger rumble isn't supported on this controller
*/
extern DECLSPEC int SDLCALL SDL_GameControllerRumbleTriggers(SDL_GameController *gamecontroller, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms);
@ -831,7 +828,8 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSetLED(SDL_GameController *gamecon
* \param gamecontroller The controller to affect
* \param data The data to send to the controller
* \param size The size of the data to send to the controller
* \returns 0, or -1 if this controller or driver doesn't support effect packets
* \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);

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

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

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.
*
* The pointer returned is a pointer to an internal SDL array. It will be
* valid for the whole lifetime of the application and should not be freed
* by the caller.
* valid for the whole lifetime of the application and should not be freed by
* the caller.
*
* 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
@ -118,8 +118,8 @@ extern DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void);
extern DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
/**
* Get the key code corresponding to the given scancode
* according to the current keyboard layout.
* Get the key code corresponding to the given scancode according to the
* current keyboard layout.
*
* See SDL_Keycode for details.
*
@ -132,8 +132,8 @@ extern DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode);
/**
* Get the scancode corresponding to the given key code
* according to the current keyboard layout.
* Get the scancode corresponding to the given key code according to the
* current keyboard layout.
*
* See SDL_Scancode for details.
*
@ -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
* SDL window, and start emitting SDL_TextInputEvent (SDL_TEXTINPUT) and
* SDL_TextEditingEvent (SDL_TEXTEDITING) events. Please use this function
* in pair with SDL_StopTextInput().
* SDL_TextEditingEvent (SDL_TEXTEDITING) events. Please use this function in
* pair with SDL_StopTextInput().
*
* On some platforms using this function activates the screen keyboard.
*

36
include/SDL_locale.h
View File

@ -47,41 +47,41 @@ typedef struct 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.
* When the caller is done with this array, it should call SDL_free() on
* the returned value; all the memory involved is allocated in a single
* block, so a single SDL_free() will suffice.
* When the caller is done with this array, it should call SDL_free() on the
* returned value; all the memory involved is allocated in a single block, so
* a single SDL_free() will suffice.
*
* 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).
* 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
* 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
* 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
* language, generically"). Language strings are never NULL, except to
* terminate the array.
*
* Please note that not all of these strings are 2 characters; some are
* three or more.
* Please note that not all of these strings are 2 characters; some are three
* or more.
*
* The returned list of locales are in the order of the user's preference.
* For example, a German citizen that is fluent in US English and knows
* enough Japanese to navigate around Tokyo might have a list like:
* { "de", "en_US", "jp", NULL }. Someone from England might prefer British
* English (where "color" is spelled "colour", etc), but will settle for
* anything like it: { "en_GB", "en", NULL }.
* The returned list of locales are in the order of the user's preference. For
* example, a German citizen that is fluent in US English and knows enough
* Japanese to navigate around Tokyo might have a list like: { "de", "en_US",
* "jp", NULL }. Someone from England might prefer British English (where
* "color" is spelled "colour", etc), but will settle for anything like it: {
* "en_GB", "en", NULL }.
*
* This function returns NULL on error, including when the platform does not
* supply this information at all.
*
* 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
* change, usually because the user has changed a system preference outside
* of your program; SDL will send an SDL_LOCALECHANGED event in this case,
* if possible, and you can call this function again to get an updated copy
* of preferred locales.
* change, usually because the user has changed a system preference outside of
* your program; SDL will send an SDL_LOCALECHANGED event in this case, if
* possible, and you can call this function again to get an updated copy of
* preferred locales.
*
* \return array of locales, terminated with a locale with a NULL language
* field. Will return NULL on error.

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.
*
= * \param fmt a printf() style message format string
* \param ... additional parameters matching % tokens in the `fmt` string,
* if any
* = * \param fmt a printf() style message format string
*
* \param ... additional parameters matching % tokens in the `fmt` string, if
* any
*
* \sa SDL_LogCritical
* \sa SDL_LogDebug

3
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
* redefine main() as SDL_main(). Thus to ensure that your main() function

39
include/SDL_metal.h
View File

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

13
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.
*
* Note: SDL_GetMouseState() returns the mouse position as SDL understands it
* from the last pump of the event queue. This function, however, queries
* the OS for the current mouse position, and as such, might be a slightly
* less efficient function. Unless you know what you're doing and have a good
* from the last pump of the event queue. This function, however, queries the
* OS for the current mouse position, and as such, might be a slightly less
* efficient function. Unless you know what you're doing and have a good
* reason to use this function, you probably want SDL_GetMouseState() instead.
*
* \param x 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);
/**
* Create a cursor using the specified bitmap data and
* mask (in MSB format).
* Create a cursor using the specified bitmap data and mask (in MSB format).
*
* `mask` has to be in MSB (Most Significant Bit) format.
*
@ -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`
* displays the cursor and passing `SDL_DISABLE` hides it.
*
* The current state of the mouse cursor can be queried by passing `SDL_QUERY`;
* either `SDL_DISABLE` or `SDL_ENABLE` will be returned.
* The current state of the mouse cursor can be queried by passing
* `SDL_QUERY`; either `SDL_DISABLE` or `SDL_ENABLE` will be returned.
*
* \param toggle `SDL_ENABLE` to show the cursor, `SDL_DISABLE` to hide it,
* `SDL_QUERY` to query the current state without changing it.

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 is legal for the owning thread to lock an already-locked mutex. It must
* unlock it the same number of times before it is actually made available
* for other threads in the system (this is known as a "recursive mutex").
* unlock it the same number of times before it is actually made available for
* other threads in the system (this is known as a "recursive mutex").
*
* \param mutex the mutex to lock
* \return 0, or -1 on error.
@ -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.
*
* \param mutex the mutex to try to lock
* \returns 0, `SDL_MUTEX_TIMEDOUT`, or -1 on error; call
* SDL_GetError() for more information.
* \returns 0, `SDL_MUTEX_TIMEDOUT`, or -1 on error; call SDL_GetError() for
* more information.
*
* \sa SDL_CreateMutex
* \sa SDL_DestroyMutex
@ -119,8 +119,8 @@ extern DECLSPEC int SDLCALL SDL_TryLockMutex(SDL_mutex * mutex);
* Unlock the mutex.
*
* It is legal for the owning thread to lock an already-locked mutex. It must
* unlock it the same number of times before it is actually made available
* for other threads in the system (this is known as a "recursive mutex").
* unlock it the same number of times before it is actually made available for
* other threads in the system (this is known as a "recursive mutex").
*
* It is an error to unlock a mutex that has not been locked by the current
* 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);
/**
* Wait until a semaphore has a positive value and then
* decrements it.
* Wait until a semaphore has a positive value and then decrements it.
*
* This function suspends the calling thread until either the semaphore
* pointed to by `sem` has a positive value, 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.
*
* This function unlocks the specified `mutex` and waits for another thread
* to call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable
* `cond`. Once the condition variable is signaled, the mutex is re-locked
* and the function returns.
* This function unlocks the specified `mutex` and waits for another thread to
* call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable
* `cond`. Once the condition variable is signaled, the mutex is re-locked and
* the function returns.
*
* The mutex 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.
*
* This function unlocks the specified `mutex` and waits for another thread
* to call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable
* `cond`, or for the specified time to elapse. Once the condition variable
* is signaled or the time elapsed, the mutex is re-locked and the function
* This function unlocks the specified `mutex` and waits for another thread to
* call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable
* `cond`, or for the specified time to elapse. Once the condition variable is
* signaled or the time elapsed, the mutex is re-locked and the function
* returns.
*
* The mutex must be locked before calling this function.

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.
*
* If `clip` is not NULL then only points inside of the clipping rectangle
* are considered.
* If `clip` is not NULL then only points inside of the clipping rectangle are
* considered.
*
* \param points an array of SDL_Point structures representing points to be
* enclosed

99
include/SDL_render.h
View File

@ -411,8 +411,7 @@ extern DECLSPEC int SDLCALL SDL_SetTextureAlphaMod(SDL_Texture * texture,
Uint8 alpha);
/**
* Get the additional alpha value multiplied into render
* copy operations.
* Get the additional alpha value multiplied into render copy operations.
*
* \param texture the texture to query
* \param alpha a pointer filled in with the current alpha value
@ -426,8 +425,7 @@ extern DECLSPEC int SDLCALL SDL_GetTextureAlphaMod(SDL_Texture * texture,
Uint8 * alpha);
/**
* Set the blend mode for a texture, used by
* SDL_RenderCopy().
* Set the blend mode for a texture, used by SDL_RenderCopy().
*
* If the blend mode is not supported, the closest supported mode is chosen
* 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.
* \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,
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.
* \return 0 on success, or -1 if the texture is not valid.
*
* \sa SDL_SetTextureScaleMode()
* \sa SDL_SetTextureScaleMode
*/
extern DECLSPEC int SDLCALL SDL_GetTextureScaleMode(SDL_Texture * texture,
SDL_ScaleMode *scaleMode);
@ -514,8 +512,8 @@ extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_Texture * texture,
const void *pixels, int pitch);
/**
* Update a rectangle within a planar YV12 or IYUV
* texture with new pixel data.
* Update a rectangle within a planar YV12 or IYUV texture with new pixel
* data.
*
* 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
@ -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
* update the entire texture.
* \param Yplane the raw pixel data for the Y plane.
* \param Ypitch the number of bytes between rows of pixel data for the Y plane.
* \param Ypitch the number of bytes between rows of pixel data for the Y
* plane.
* \param UVplane the raw pixel data for the UV plane.
* \param UVpitch the number of bytes between rows of pixel data for the UV plane.
* \param UVpitch the number of bytes between rows of pixel data for the UV
* plane.
* \return 0 on success, or -1 if the texture is not valid.
*/
extern DECLSPEC int SDLCALL SDL_UpdateNVTexture(SDL_Texture * texture,
@ -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
* with `SDL_TEXTUREACCESS_STREAMING`
*
* \sa SDL_LockTexture()
* \sa SDL_UnlockTexture()
* \sa SDL_LockTexture
* \sa SDL_UnlockTexture
*/
extern DECLSPEC int SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture,
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
* before unlocking it, as the pixels might otherwise be uninitialized memory.
*
* Which is to say: locking and immediately unlocking a texture can result
* in corrupted textures, depending on the renderer in use.
* Which is to say: locking and immediately unlocking a texture can result in
* corrupted textures, depending on the renderer in use.
*
* \param texture a texture locked by SDL_LockTexture()
*
@ -663,8 +663,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_RenderTargetSupported(SDL_Renderer *rendere
* Set a texture as the current rendering target.
*
* Before using this function, you should check the
* `SDL_RENDERER_TARGETTEXTURE` bit in the flags of SDL_RendererInfo to see
* if render targets are supported.
* `SDL_RENDERER_TARGETTEXTURE` bit in the flags of SDL_RendererInfo to see if
* render targets are supported.
*
* 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
@ -672,8 +672,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_RenderTargetSupported(SDL_Renderer *rendere
*
* \param renderer the rendering context
* \param texture the targeted texture, which must be created with the
* `SDL_TEXTUREACCESS_TARGET` flag, or NULL
* to render to the window instead of a texture.
* `SDL_TEXTUREACCESS_TARGET` flag, or NULL to render to the
* window instead of a texture.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
@ -779,8 +779,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_RenderGetIntegerScale(SDL_Renderer * render
/**
* Set the drawing area for rendering on the current target.
*
* When the window is resized, the viewport is reset to fill the entire
* new window size.
* When the window is resized, the viewport is reset to fill the entire new
* window size.
*
* \param renderer the rendering context
* \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 for drawing or filling rectangles, lines, and points,
* and for SDL_RenderClear().
* Set the color for drawing or filling rectangles, lines, and points, and for
* SDL_RenderClear().
*
* \param renderer the rendering context
* \param r the red value used to draw on the rendering target
@ -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
* rotation and flipping.
*
* Copy a portion of the texture to the current rendering
* target, optionally rotating it by angle around the given center and also
* flipping it top-bottom and/or left-right.
* Copy a portion of the texture to the current rendering target, optionally
* rotating it by angle around the given center and also flipping it
* top-bottom and/or left-right.
*
* The texture is blended with the destination based on its blend mode set
* 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.
*
* \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
*/
extern DECLSPEC int SDLCALL SDL_RenderDrawRectF(SDL_Renderer * renderer,
@ -1349,8 +1350,8 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawRectsF(SDL_Renderer * renderer,
int count);
/**
* Fill a rectangle on the current rendering target with the drawing color
* at subpixel precision.
* Fill a rectangle on the current rendering target with the drawing color at
* subpixel precision.
*
* \param renderer The renderer which should fill a rectangle.
* \param rect A pointer to the destination rectangle, or NULL for the entire
@ -1391,8 +1392,8 @@ extern DECLSPEC int SDLCALL SDL_RenderCopyF(SDL_Renderer * renderer,
const SDL_FRect * dstrect);
/**
* Copy a portion of the source texture to the current rendering target,
* with rotation and flipping, at subpixel precision.
* Copy a portion of the source texture to the current rendering target, with
* rotation and flipping, at subpixel precision.
*
* \param renderer The renderer which should copy parts of a texture.
* \param texture The source texture.
@ -1400,10 +1401,13 @@ extern DECLSPEC int SDLCALL SDL_RenderCopyF(SDL_Renderer * renderer,
* texture.
* \param dstrect A pointer to the destination rectangle, or NULL for the
* entire rendering target.
* \param angle An angle in degrees that indicates the rotation that will be applied to dstrect, rotating it in a clockwise direction
* \param center A pointer to a point indicating the point around which dstrect will be rotated (if NULL, rotation will be done around dstrect.w/2, dstrect.h/2).
* \param flip An SDL_RendererFlip value stating which flipping actions should be performed on the texture
*
* \param angle An angle in degrees that indicates the rotation that will be
* applied to dstrect, rotating it in a clockwise direction
* \param center A pointer to a point indicating the point around which
* dstrect will be rotated (if NULL, rotation will be done
* around dstrect.w/2, dstrect.h/2).
* \param flip An SDL_RendererFlip value stating which flipping actions should
* be performed on the texture
* \return 0 on success, or -1 on error
*/
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);
/**
* Update the screen with any rendering performed since
* the previous call.
* Update the screen with any rendering performed since the previous call.
*
* SDL's rendering functions operate on a backbuffer; that is, calling a
* rendering function such as SDL_RenderDrawLine() does not directly put a
@ -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
* rendering API.
*
* You do not need to (and in fact, shouldn't) call this function unless
* you are planning to call into OpenGL/Direct3D/Metal/whatever directly
* in addition to using an SDL_Renderer.
* You do not need to (and in fact, shouldn't) call this function unless you
* are planning to call into OpenGL/Direct3D/Metal/whatever directly in
* addition to using an SDL_Renderer.
*
* This is for a very-specific case: if you are using SDL's render API, you
* asked for a specific renderer backend (OpenGL, Direct3D, etc), you set
@ -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
* will do the right thing, perhaps at a performance loss.
*
* This function is first available in SDL 2.0.10, and is not needed in
* 2.0.9 and earlier, as earlier versions did not queue rendering commands
* at all, instead flushing them to the OS immediately.
* This function is first available in SDL 2.0.10, and is not needed in 2.0.9
* and earlier, as earlier versions did not queue rendering commands at all,
* instead flushing them to the OS immediately.
*
* \param renderer the rendering context
* \returns 0 on success or a negative error code on failure; call
@ -1589,10 +1592,10 @@ extern DECLSPEC int SDLCALL SDL_GL_UnbindTexture(SDL_Texture *texture);
* headers, but it can be safely cast to a `CAMetalLayer *`.
*
* \param renderer The renderer to query
* \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a Metal
* renderer
* \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a
* Metal renderer
*
* \sa SDL_RenderGetMetalCommandEncoder()
* \sa SDL_RenderGetMetalCommandEncoder
*/
extern DECLSPEC void *SDLCALL SDL_RenderGetMetalLayer(SDL_Renderer * renderer);
@ -1603,10 +1606,10 @@ extern DECLSPEC void *SDLCALL SDL_RenderGetMetalLayer(SDL_Renderer * renderer);
* headers, but it can be safely cast to an `id<MTLRenderCommandEncoder>`.
*
* \param renderer The renderer to query
* \returns an `id<MTLRenderCommandEncoder>` on success, or NULL if the renderer
* isn't a Metal renderer.
* \returns an `id<MTLRenderCommandEncoder>` on success, or NULL if the
* renderer isn't a Metal renderer.
*
* \sa SDL_RenderGetMetalLayer()
* \sa SDL_RenderGetMetalLayer
*/
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.
*
* SDL_RWtell is actually a wrapper function that calls the SDL_RWops's
* `seek` method, with an offset of 0 bytes from `RW_SEEK_CUR`, to simplify
* SDL_RWtell is actually a wrapper function that calls the SDL_RWops's `seek`
* method, with an offset of 0 bytes from `RW_SEEK_CUR`, to simplify
* application development.
*
* \param context a SDL_RWops data stream object from which to get the current
@ -284,9 +284,9 @@ extern DECLSPEC size_t SDLCALL SDL_RWread(SDL_RWops *context,
* Write to an SDL_RWops data stream.
*
* This function writes exactly `num` objects each of size `size` from the
* area pointed at by `ptr` to the stream. If this fails for any reason,
* it'll return less than `num` to demonstrate how far the write progressed.
* On success, it returns `num`.
* area pointed at by `ptr` to the stream. If this fails for any reason, it'll
* return less than `num` to demonstrate how far the write progressed. On
* success, it returns `num`.
*
* SDL_RWwrite is actually a function wrapper that calls the SDL_RWops's
* `write` method appropriately, to simplify application development.
@ -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
* an error, but the SDL_RWops is still invalid once this function returns.
*
* SDL_RWclose() is actually a macro that calls the SDL_RWops's `close`
* method appropriately, to simplify application development.
* SDL_RWclose() is actually a macro that calls the SDL_RWops's `close` method
* appropriately, to simplify application development.
*
* \param context SDL_RWops structure to close
* \returns 0 on success or a negative error code on failure; call

6
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
* 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
* the API functions that take a sensor index will be valid, and sensor
* events will not be delivered.
* In particular, you are guaranteed that the sensor list won't change, so the
* API functions that take a sensor index will be valid, and sensor events
* will not be delivered.
*/
extern DECLSPEC void SDLCALL SDL_LockSensors(void);
extern DECLSPEC void SDLCALL SDL_UnlockSensors(void);

47
include/SDL_shape.h
View File

@ -44,7 +44,8 @@ extern "C" {
#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 x The x position of the window, ::SDL_WINDOWPOS_CENTERED, or
@ -53,24 +54,24 @@ extern "C" {
* ::SDL_WINDOWPOS_UNDEFINED.
* \param w The width of the window.
* \param h The height of the window.
* \param flags The flags for the window, a mask of SDL_WINDOW_BORDERLESS with any of the following:
* ::SDL_WINDOW_OPENGL, ::SDL_WINDOW_INPUT_GRABBED,
* ::SDL_WINDOW_HIDDEN, ::SDL_WINDOW_RESIZABLE,
* ::SDL_WINDOW_MAXIMIZED, ::SDL_WINDOW_MINIMIZED,
* ::SDL_WINDOW_BORDERLESS is always set, and ::SDL_WINDOW_FULLSCREEN is always unset.
*
* \param flags The flags for the window, a mask of SDL_WINDOW_BORDERLESS with
* any of the following: ::SDL_WINDOW_OPENGL,
* ::SDL_WINDOW_INPUT_GRABBED, ::SDL_WINDOW_HIDDEN,
* ::SDL_WINDOW_RESIZABLE, ::SDL_WINDOW_MAXIMIZED,
* ::SDL_WINDOW_MINIMIZED, ::SDL_WINDOW_BORDERLESS is always set,
* and ::SDL_WINDOW_FULLSCREEN is always unset.
* \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);
/**
* \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.
*
* \return SDL_TRUE if the window is a window that can be shaped, SDL_FALSE if the window is unshaped or NULL.
* \return SDL_TRUE if the window is a window that can be shaped, SDL_FALSE if
* the window is unshaped or NULL.
*
* \sa SDL_CreateShapedWindow
*/
@ -106,29 +107,31 @@ typedef struct 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 shape A surface encoding the desired shape for the window.
* \param shape_mode The parameters to set for the shaped window.
*
* \return 0 on success, SDL_INVALID_SHAPE_ARGUMENT on an invalid shape argument, or SDL_NONSHAPEABLE_WINDOW
* if the SDL_Window given does not reference a valid shaped window.
* \return 0 on success, SDL_INVALID_SHAPE_ARGUMENT on an invalid shape
* argument, or SDL_NONSHAPEABLE_WINDOW if the SDL_Window given does
* not reference a valid shaped window.
*
* \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);
/**
* \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 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
* data, 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.
* \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 data,
* 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_SetWindowShape

11
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);
/**
* \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,
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);
/**
* \brief 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.
* Replace SDL's memory allocation functions with a custom set
*/
extern DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_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);
/**
* \brief Get the number of outstanding (unfreed) allocations
* Get the number of outstanding (unfreed) allocations
*/
extern DECLSPEC int SDLCALL SDL_GetNumAllocations(void);

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
* existing buffer of data for the surface to use.
*
* No copy is made of the pixel data. Pixel data is not managed
* automatically; you must free the surface before you free the pixel data.
* No copy is made of the pixel data. Pixel data is not managed automatically;
* you must free the surface before you free the pixel data.
*
* \param pixels a pointer to existing pixel data
* \param width the width of the surface
@ -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
* format from SDL_PixelFormatEnum.
*
* No copy is made of the pixel data. Pixel data is not managed
* automatically; you must free the surface before you free the pixel data.
* No copy is made of the pixel data. Pixel data is not managed automatically;
* you must free the surface before you free the pixel data.
*
* \param pixels a pointer to existing pixel data
* \param width the width of the surface
@ -298,7 +298,7 @@ extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface);
*
* \param surface the SDL_Surface structure to be unlocked
*
* \sa SDL_LockSurface()
* \sa SDL_LockSurface
*/
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.
*
* When `surface` is the destination of a blit, only the area within the
* clip rectangle is drawn into.
* When `surface` is the destination of a blit, only the area within the clip
* rectangle is drawn into.
*
* Note that blits are automatically clipped to the edges of the source and
* destination surfaces.
@ -566,8 +566,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface,
/**
* Get the clipping rectangle for a surface.
*
* When `surface` is the destination of a blit, only the area within the
* clip rectangle is drawn into.
* When `surface` is the destination of a blit, only the area within the clip
* rectangle is drawn into.
*
* \param surface the SDL_Surface structure representing the surface to be
* clipped
@ -618,8 +618,8 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface
* Copy an existing surface to a new surface of the specified format enum.
*
* This function operates just like SDL_ConvertSurface(), but accepts an
* SDL_PixelFormatEnum value instead of an SDL_PixelFormat structure. As
* such, it might be easier to call but it doesn't have access to palette
* SDL_PixelFormatEnum value instead of an SDL_PixelFormat structure. As such,
* it might be easier to call but it doesn't have access to palette
* information for the destination surface, in case that would be important.
*
* \param src the existing SDL_Surface structure to convert
@ -768,8 +768,8 @@ extern DECLSPEC int SDLCALL SDL_FillRects
/**
* Perform a fast blit from the source surface to the destination surface.
*
* SDL_UpperBlit() has been replaced by SDL_BlitSurface(), which is merely
* a macro for this function with a less confusing name.
* SDL_UpperBlit() has been replaced by SDL_BlitSurface(), which is merely a
* macro for this function with a less confusing name.
*
* \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);
/**
* 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);

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

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.
*
* The caller must initialize the `info` structure's version by using
* `SDL_VERSION(&info.version)`, and then this function will fill in the
* rest of the structure with information about the given window.
* `SDL_VERSION(&info.version)`, and then this function will fill in the rest
* of the structure with information about the given window.
*
* \param window the window about which information is being requested
* \param info an SDL_SysWMinfo structure filled in with window information

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

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

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