diff --git a/include/SDL.h b/include/SDL.h index 633b5f428..222a8bd99 100644 --- a/include/SDL.h +++ b/include/SDL.h @@ -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. * diff --git a/include/SDL_atomic.h b/include/SDL_atomic.h index df2974bbb..5e1eae773 100644 --- a/include/SDL_atomic.h +++ b/include/SDL_atomic.h @@ -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!*** diff --git a/include/SDL_audio.h b/include/SDL_audio.h index 2d12fca2f..05b482b02 100644 --- a/include/SDL_audio.h +++ b/include/SDL_audio.h @@ -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,31 +463,31 @@ 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->size` is the size in _bytes_ of the audio buffer, and is - * calculated by SDL_OpenAudioDevice(). You don't initialize this. - * - `desired->silence` is the value used to set the buffer to silence, - * and is calculated by SDL_OpenAudioDevice(). You don't initialize this. - * - `desired->callback` should be set to a function that will be called - * when the audio device is ready for more data. It is passed a pointer - * to the audio buffer, and the length in bytes of the audio buffer. - * This function usually runs in a separate thread, and so you should - * protect data structures that it accesses by calling SDL_LockAudioDevice() - * and SDL_UnlockAudioDevice() in your code. Alternately, you may pass a NULL - * pointer here, and call SDL_QueueAudio() with some frequency, to queue - * more audio samples to be played (or for capture devices, call - * SDL_DequeueAudio() with some frequency, to obtain audio samples). - * - `desired->userdata` is passed as the first parameter to your callback - * function. If you passed a NULL callback, this value is ignored. + * - `desired->samples` is the desired size of the audio buffer, in _sample + * frames_ (with stereo output, two samples--left and right--would make a + * single sample frame). This number should be a power of two, and may be + * adjusted by the audio driver to a value more suitable for the hardware. + * Good values seem to range between 512 and 8096 inclusive, depending on + * the application and CPU speed. Smaller values reduce latency, but can + * lead to underflow if the application is doing heavy processing and cannot + * fill the audio buffer in time. Note that the number of sample frames is + * directly related to time by the following formula: `ms = + * (sampleframes*1000)/freq` + * - `desired->size` is the size in _bytes_ of the audio buffer, and is + * calculated by SDL_OpenAudioDevice(). You don't initialize this. + * - `desired->silence` is the value used to set the buffer to silence, and is + * calculated by SDL_OpenAudioDevice(). You don't initialize this. + * - `desired->callback` should be set to a function that will be called when + * the audio device is ready for more data. It is passed a pointer to the + * audio buffer, and the length in bytes of the audio buffer. This function + * usually runs in a separate thread, and so you should protect data + * structures that it accesses by calling SDL_LockAudioDevice() and + * SDL_UnlockAudioDevice() in your code. Alternately, you may pass a NULL + * pointer here, and call SDL_QueueAudio() with some frequency, to queue + * more audio samples to be played (or for capture devices, call + * SDL_DequeueAudio() with some frequency, to obtain audio samples). + * - `desired->userdata` is passed as the first parameter to your callback + * function. If you passed a NULL callback, this value is ignored. * * `allowed_changes` can have the following flags OR'd together: * @@ -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 @@ -779,22 +781,22 @@ struct _SDL_AudioStream; typedef struct _SDL_AudioStream SDL_AudioStream; /** - * Create a new audio stream. + * Create a new audio stream. * - * \param src_format The format of the source audio - * \param src_channels The number of channels of the source audio - * \param src_rate The sampling rate of the source audio - * \param dst_format The format of the desired audio output - * \param dst_channels The number of channels of the desired audio output - * \param dst_rate The sampling rate of the desired audio output - * \returns 0 on success, or -1 on error. + * \param src_format The format of the source audio + * \param src_channels The number of channels of the source audio + * \param src_rate The sampling rate of the source audio + * \param dst_format The format of the desired audio output + * \param dst_channels The number of channels of the desired audio output + * \param dst_rate The sampling rate of the desired audio output + * \returns 0 on success, or -1 on error. * - * \sa SDL_AudioStreamPut - * \sa SDL_AudioStreamGet - * \sa SDL_AudioStreamAvailable - * \sa SDL_AudioStreamFlush - * \sa SDL_AudioStreamClear - * \sa SDL_FreeAudioStream + * \sa SDL_AudioStreamPut + * \sa SDL_AudioStreamGet + * \sa SDL_AudioStreamAvailable + * \sa SDL_AudioStreamFlush + * \sa SDL_AudioStreamClear + * \sa SDL_FreeAudioStream */ extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioFormat src_format, const Uint8 src_channels, @@ -804,92 +806,93 @@ extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioForm const int dst_rate); /** - * Add data to be converted/resampled to the stream. + * Add data to be converted/resampled to the stream. * - * \param stream The stream the audio data is being added to - * \param buf A pointer to the audio data to add - * \param len The number of bytes to write to the stream - * \returns 0 on success, or -1 on error. + * \param stream The stream the audio data is being added to + * \param buf A pointer to the audio data to add + * \param len The number of bytes to write to the stream + * \returns 0 on success, or -1 on error. * - * \sa SDL_NewAudioStream - * \sa SDL_AudioStreamGet - * \sa SDL_AudioStreamAvailable - * \sa SDL_AudioStreamFlush - * \sa SDL_AudioStreamClear - * \sa SDL_FreeAudioStream + * \sa SDL_NewAudioStream + * \sa SDL_AudioStreamGet + * \sa SDL_AudioStreamAvailable + * \sa SDL_AudioStreamFlush + * \sa SDL_AudioStreamClear + * \sa SDL_FreeAudioStream */ extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const void *buf, int len); /** - * Get converted/resampled data from the stream + * Get converted/resampled data from the stream * - * \param stream The stream the audio is being requested from - * \param buf A buffer to fill with audio data - * \param len The maximum number of bytes to fill - * \returns the number of bytes read from the stream, or -1 on error + * \param stream The stream the audio is being requested from + * \param buf A buffer to fill with audio data + * \param len The maximum number of bytes to fill + * \returns the number of bytes read from the stream, or -1 on error * - * \sa SDL_NewAudioStream - * \sa SDL_AudioStreamPut - * \sa SDL_AudioStreamAvailable - * \sa SDL_AudioStreamFlush - * \sa SDL_AudioStreamClear - * \sa SDL_FreeAudioStream + * \sa SDL_NewAudioStream + * \sa SDL_AudioStreamPut + * \sa SDL_AudioStreamAvailable + * \sa SDL_AudioStreamFlush + * \sa SDL_AudioStreamClear + * \sa SDL_FreeAudioStream */ 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. * - * \sa SDL_NewAudioStream - * \sa SDL_AudioStreamPut - * \sa SDL_AudioStreamGet - * \sa SDL_AudioStreamFlush - * \sa SDL_AudioStreamClear - * \sa SDL_FreeAudioStream + * 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 + * \sa SDL_AudioStreamGet + * \sa SDL_AudioStreamFlush + * \sa SDL_AudioStreamClear + * \sa SDL_FreeAudioStream */ 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. + * 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 - * \sa SDL_AudioStreamGet - * \sa SDL_AudioStreamAvailable - * \sa SDL_AudioStreamClear - * \sa SDL_FreeAudioStream + * \sa SDL_NewAudioStream + * \sa SDL_AudioStreamPut + * \sa SDL_AudioStreamGet + * \sa SDL_AudioStreamAvailable + * \sa SDL_AudioStreamClear + * \sa SDL_FreeAudioStream */ extern DECLSPEC int SDLCALL SDL_AudioStreamFlush(SDL_AudioStream *stream); /** - * Clear any pending data in the stream without converting it + * Clear any pending data in the stream without converting it * - * \sa SDL_NewAudioStream - * \sa SDL_AudioStreamPut - * \sa SDL_AudioStreamGet - * \sa SDL_AudioStreamAvailable - * \sa SDL_AudioStreamFlush - * \sa SDL_FreeAudioStream + * \sa SDL_NewAudioStream + * \sa SDL_AudioStreamPut + * \sa SDL_AudioStreamGet + * \sa SDL_AudioStreamAvailable + * \sa SDL_AudioStreamFlush + * \sa SDL_FreeAudioStream */ extern DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream); /** * Free an audio stream * - * \sa SDL_NewAudioStream - * \sa SDL_AudioStreamPut - * \sa SDL_AudioStreamGet - * \sa SDL_AudioStreamAvailable - * \sa SDL_AudioStreamFlush - * \sa SDL_AudioStreamClear + * \sa SDL_NewAudioStream + * \sa SDL_AudioStreamPut + * \sa SDL_AudioStreamGet + * \sa SDL_AudioStreamAvailable + * \sa SDL_AudioStreamFlush + * \sa SDL_AudioStreamClear */ extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream); @@ -920,8 +923,8 @@ extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src, /** * Mix audio data in a specified format. * - * 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 diff --git a/include/SDL_blendmode.h b/include/SDL_blendmode.h index 7627e324c..374f225a0 100644 --- a/include/SDL_blendmode.h +++ b/include/SDL_blendmode.h @@ -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. * diff --git a/include/SDL_cpuinfo.h b/include/SDL_cpuinfo.h index 8fa8a2e8b..4401c3796 100644 --- a/include/SDL_cpuinfo.h +++ b/include/SDL_cpuinfo.h @@ -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 diff --git a/include/SDL_error.h b/include/SDL_error.h index 7085871ab..f61a200cc 100644 --- a/include/SDL_error.h +++ b/include/SDL_error.h @@ -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,26 +54,27 @@ 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 - * \sa SDL_GetError + * \sa SDL_ClearError + * \sa SDL_GetError */ 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. * diff --git a/include/SDL_events.h b/include/SDL_events.h index 8b26982fd..6cdb6625b 100644 --- a/include/SDL_events.h +++ b/include/SDL_events.h @@ -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. @@ -933,10 +933,10 @@ typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event); * interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the * application at the next event poll. * - * There is one caveat when dealing with the ::SDL_QuitEvent event type. The + * There is one caveat when dealing with the ::SDL_QuitEvent event type. The * event filter is only called when the window manager desires to close the - * application window. If the event filter returns 1, then the window will - * be closed, otherwise the window will remain open if possible. + * 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 diff --git a/include/SDL_filesystem.h b/include/SDL_filesystem.h index d06dbe9ed..9dbd28ff8 100644 --- a/include/SDL_filesystem.h +++ b/include/SDL_filesystem.h @@ -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 diff --git a/include/SDL_gamecontroller.h b/include/SDL_gamecontroller.h index e5dbaa545..1108d4a02 100644 --- a/include/SDL_gamecontroller.h +++ b/include/SDL_gamecontroller.h @@ -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 @@ -383,9 +382,9 @@ extern DECLSPEC const char *SDLCALL SDL_GameControllerName(SDL_GameController *g extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerGetType(SDL_GameController *gamecontroller); /** - * Get the player index of an opened game controller. + * Get the player index of an opened game controller. * - * For XInput controllers this returns the XInput user index. + * For XInput controllers this returns the XInput user index. * * \param gamecontroller the game controller object to query. * \returns the player index for controller, or -1 if it's not available. @@ -393,7 +392,7 @@ extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerGetType(SDL_Gam extern DECLSPEC int SDLCALL SDL_GameControllerGetPlayerIndex(SDL_GameController *gamecontroller); /** - * Set the player index of an opened game controller. + * Set the player index of an opened game controller. * * \param gamecontroller the game controller object to adjust. * \param player_index Player index to assign to this controller. @@ -432,8 +431,9 @@ 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); diff --git a/include/SDL_haptic.h b/include/SDL_haptic.h index 424cbd111..bb53ed380 100644 --- a/include/SDL_haptic.h +++ b/include/SDL_haptic.h @@ -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. * diff --git a/include/SDL_hints.h b/include/SDL_hints.h index 08729ef9b..d6a2507bc 100644 --- a/include/SDL_hints.h +++ b/include/SDL_hints.h @@ -1770,7 +1770,7 @@ typedef void (SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const * * \param name the hint to watch * \param callback An SDL_HintCallback function that will be called when the - * hint value changes + * hint value changes * \param userdata a pointer to pass to the callback function * * \since This function is available since SDL 2.0.0. @@ -1786,7 +1786,7 @@ extern DECLSPEC void SDLCALL SDL_AddHintCallback(const char *name, * * \param name the hint being watched * \param callback An SDL_HintCallback function that will be called when the - * hint value changes + * hint value changes * \param userdata a pointer being passed to the callback function * * \since This function is available since SDL 2.0.0. diff --git a/include/SDL_joystick.h b/include/SDL_joystick.h index 56f1c8efd..8be4b732a 100644 --- a/include/SDL_joystick.h +++ b/include/SDL_joystick.h @@ -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,12 +322,12 @@ 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. * \param value the new value for the specified axis. @@ -338,12 +338,12 @@ extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualAxis(SDL_Joystick *joystick, i /** * Set values on an opened, virtual-joystick's button. * - * 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. * \param value the new value for the specified button. @@ -354,12 +354,12 @@ extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualButton(SDL_Joystick *joystick, /** * Set values on an opened, virtual-joystick's hat. * - * 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. * \param value the new value for the specified hat. @@ -437,6 +437,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProduct(SDL_Joystick *joystick); /** * Get the product version of an opened joystick, if available. + * * If the product version isn't available this function returns 0. * * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() @@ -446,11 +447,12 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProductVersion(SDL_Joystick *joyst /** * Get the serial number of an opened joystick, if available. - * + * * 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); diff --git a/include/SDL_keyboard.h b/include/SDL_keyboard.h index 3b14acbf2..4260b5e8d 100644 --- a/include/SDL_keyboard.h +++ b/include/SDL_keyboard.h @@ -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. * diff --git a/include/SDL_locale.h b/include/SDL_locale.h index 8137414fd..cb4b04379 100644 --- a/include/SDL_locale.h +++ b/include/SDL_locale.h @@ -47,44 +47,44 @@ 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. + * 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. * - * 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 - * language, generically"). Language strings are never NULL, except to - * terminate the array. + * 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 + * 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 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. + * 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. * - * \return array of locales, terminated with a locale with a NULL language - * field. Will return NULL on error. + * \return array of locales, terminated with a locale with a NULL language + * field. Will return NULL on error. */ extern DECLSPEC SDL_Locale * SDLCALL SDL_GetPreferredLocales(void); diff --git a/include/SDL_log.h b/include/SDL_log.h index 19b437af6..e85961ace 100644 --- a/include/SDL_log.h +++ b/include/SDL_log.h @@ -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 diff --git a/include/SDL_main.h b/include/SDL_main.h index 020945181..087193b28 100644 --- a/include/SDL_main.h +++ b/include/SDL_main.h @@ -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 @@ -136,7 +137,7 @@ extern DECLSPEC void SDLCALL SDL_SetMainReady(void); #ifdef __WIN32__ /** - * This can be called to set the application class at startup + * This can be called to set the application class at startup */ extern DECLSPEC int SDLCALL SDL_RegisterApp(char *name, Uint32 style, void *hInst); extern DECLSPEC void SDLCALL SDL_UnregisterApp(void); diff --git a/include/SDL_metal.h b/include/SDL_metal.h index 283ab8de2..60bcb6e18 100644 --- a/include/SDL_metal.h +++ b/include/SDL_metal.h @@ -49,59 +49,46 @@ 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(). + * 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. - * - * \sa SDL_Metal_DestroyView - * \sa SDL_Metal_GetLayer + * \sa SDL_Metal_DestroyView + * \sa SDL_Metal_GetLayer */ extern DECLSPEC SDL_MetalView SDLCALL SDL_Metal_CreateView(SDL_Window * window); /** - * \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. + * This should be called before SDL_DestroyWindow, if SDL_Metal_CreateView was + * called after SDL_CreateWindow. * - * \sa SDL_Metal_CreateView + * \sa SDL_Metal_CreateView */ extern DECLSPEC void SDLCALL SDL_Metal_DestroyView(SDL_MetalView view); /** - * \brief Get a pointer to the backing CAMetalLayer for the given view. + * Get a pointer to the backing CAMetalLayer for the given view. * - * \sa SDL_MetalCreateView + * \sa SDL_MetalCreateView */ extern DECLSPEC void *SDLCALL SDL_Metal_GetLayer(SDL_MetalView view); /** - * \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 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 * - * 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); diff --git a/include/SDL_mouse.h b/include/SDL_mouse.h index 2704c0d6e..5919ea197 100644 --- a/include/SDL_mouse.h +++ b/include/SDL_mouse.h @@ -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. * @@ -328,7 +327,7 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor id); * the display. SDL_SetCursor(NULL) can be used to force cursor redraw, if * this is desired for any reason. * - * \param cursor a cursor to make active + * \param cursor a cursor to make active * * \sa SDL_CreateCursor * \sa SDL_GetCursor @@ -379,8 +378,8 @@ extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor * cursor); * The cursor starts off displayed but can be turned off. Passing `SDL_ENABLE` * 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. diff --git a/include/SDL_mutex.h b/include/SDL_mutex.h index 688ab956c..2f27f19ac 100644 --- a/include/SDL_mutex.h +++ b/include/SDL_mutex.h @@ -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. diff --git a/include/SDL_rect.h b/include/SDL_rect.h index ae47298d2..a17ea44f3 100644 --- a/include/SDL_rect.h +++ b/include/SDL_rect.h @@ -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 diff --git a/include/SDL_render.h b/include/SDL_render.h index f0bf8ca56..573270575 100644 --- a/include/SDL_render.h +++ b/include/SDL_render.h @@ -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, @@ -590,7 +590,7 @@ extern DECLSPEC int SDLCALL SDL_UpdateNVTexture(SDL_Texture * texture, * or was not created with `SDL_TEXTUREACCESS_STREAMING`; call * SDL_GetError() for more information. * - * \sa SDL_UnlockTexture + * \sa SDL_UnlockTexture */ extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_Texture * texture, const SDL_Rect * rect, @@ -623,8 +623,8 @@ extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_Texture * texture, * \returns 0 on success, or -1 if the texture is not valid or was not created * 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. * @@ -704,7 +704,7 @@ extern DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *renderer * * This function uses the viewport and scaling functionality to allow a fixed * logical resolution for rendering, regardless of the actual output - * resolution. If the actual output resolution doesn't have the same aspect + * resolution. If the actual output resolution doesn't have the same aspect * ratio the output rendering will be centered within the output display. * * If the output display is a window, mouse and touch events in the window @@ -779,8 +779,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_RenderGetIntegerScale(SDL_Renderer * render /** * Set the drawing area for rendering on the current target. * - * 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`. * * \param renderer The renderer to query - * \returns an `id` on success, or NULL if the renderer - * isn't a Metal renderer. + * \returns an `id` 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); diff --git a/include/SDL_rwops.h b/include/SDL_rwops.h index 09fe33b75..52b3a6ca0 100644 --- a/include/SDL_rwops.h +++ b/include/SDL_rwops.h @@ -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 diff --git a/include/SDL_sensor.h b/include/SDL_sensor.h index 189d5e850..3bab8a4e8 100644 --- a/include/SDL_sensor.h +++ b/include/SDL_sensor.h @@ -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); @@ -230,7 +230,7 @@ extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetInstanceID(SDL_Sensor *sensor) /** * Get the current state of an opened sensor. * - * The number of values and interpretation of the data is sensor dependent. + * The number of values and interpretation of the data is sensor dependent. * * \param sensor The SDL_Sensor object to query * \param data A pointer filled with the current sensor state diff --git a/include/SDL_shape.h b/include/SDL_shape.h index 344d09c06..1f8ca21a2 100644 --- a/include/SDL_shape.h +++ b/include/SDL_shape.h @@ -44,33 +44,34 @@ 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 - * ::SDL_WINDOWPOS_UNDEFINED. - * \param y The y position of the window, ::SDL_WINDOWPOS_CENTERED, or - * ::SDL_WINDOWPOS_UNDEFINED. - * \param w The width of the window. - * \param h The height of the window. - * \param flags The flags for the window, a mask of SDL_WINDOW_BORDERLESS with any of the following: - * ::SDL_WINDOW_OPENGL, ::SDL_WINDOW_INPUT_GRABBED, - * ::SDL_WINDOW_HIDDEN, ::SDL_WINDOW_RESIZABLE, - * ::SDL_WINDOW_MAXIMIZED, ::SDL_WINDOW_MINIMIZED, - * ::SDL_WINDOW_BORDERLESS is always set, and ::SDL_WINDOW_FULLSCREEN is always unset. + * \param title The title of the window, in UTF-8 encoding. + * \param x The x position of the window, ::SDL_WINDOWPOS_CENTERED, or + * ::SDL_WINDOWPOS_UNDEFINED. + * \param y The y position of the window, ::SDL_WINDOWPOS_CENTERED, or + * ::SDL_WINDOWPOS_UNDEFINED. + * \param w The width of the window. + * \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. + * \return the window created, or NULL if window creation failed. * - * \return the window created, or NULL if window creation failed. - * - * \sa SDL_DestroyWindow() + * \sa SDL_DestroyWindow */ extern DECLSPEC SDL_Window * SDLCALL SDL_CreateShapedWindow(const char *title,unsigned int x,unsigned int y,unsigned int w,unsigned int h,Uint32 flags); /** - * \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 diff --git a/include/SDL_stdinc.h b/include/SDL_stdinc.h index 0cbbb436b..f64219df3 100644 --- a/include/SDL_stdinc.h +++ b/include/SDL_stdinc.h @@ -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); @@ -625,8 +620,8 @@ extern DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf, size_t * inbytesleft, char **outbuf, size_t * outbytesleft); /** - * This function converts a string between encodings in one pass, returning a - * string that must be freed with SDL_free() or NULL on error. + * This function converts a string between encodings in one pass, returning a + * string that must be freed with SDL_free() or NULL on error. */ extern DECLSPEC char *SDLCALL SDL_iconv_string(const char *tocode, const char *fromcode, diff --git a/include/SDL_surface.h b/include/SDL_surface.h index d238f1f4f..c79e0de8e 100644 --- a/include/SDL_surface.h +++ b/include/SDL_surface.h @@ -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); diff --git a/include/SDL_system.h b/include/SDL_system.h index 069c3f573..5f12787c0 100644 --- a/include/SDL_system.h +++ b/include/SDL_system.h @@ -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. diff --git a/include/SDL_syswm.h b/include/SDL_syswm.h index 12e86a17c..d2608013a 100644 --- a/include/SDL_syswm.h +++ b/include/SDL_syswm.h @@ -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 diff --git a/include/SDL_thread.h b/include/SDL_thread.h index 513d5dfcb..b3441505c 100644 --- a/include/SDL_thread.h +++ b/include/SDL_thread.h @@ -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); diff --git a/include/SDL_video.h b/include/SDL_video.h index 876c23244..95a535053 100644 --- a/include/SDL_video.h +++ b/include/SDL_video.h @@ -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 @@ -547,8 +547,8 @@ extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(int displayIndex, SDL_Disp * \returns the passed in value `closest` or NULL if no matching video mode * was available; call SDL_GetError() for more information. * - * \sa SDL_GetDisplayMode - * \sa SDL_GetNumDisplayModes + * \sa SDL_GetDisplayMode + * \sa SDL_GetNumDisplayModes */ extern DECLSPEC SDL_DisplayMode * SDLCALL SDL_GetClosestDisplayMode(int displayIndex, const SDL_DisplayMode * mode, SDL_DisplayMode * closest); @@ -638,13 +638,13 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window * window); * * If the window is created with the `SDL_WINDOW_ALLOW_HIGHDPI` flag, its size * 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 */ @@ -1083,8 +1083,8 @@ extern DECLSPEC void SDLCALL SDL_MinimizeWindow(SDL_Window * window); * * \param window the window to restore * - * \sa SDL_MaximizeWindow - * \sa SDL_MinimizeWindow + * \sa SDL_MaximizeWindow + * \sa SDL_MinimizeWindow */ extern DECLSPEC void SDLCALL SDL_RestoreWindow(SDL_Window * window); @@ -1190,8 +1190,8 @@ extern DECLSPEC void SDLCALL SDL_SetWindowGrab(SDL_Window * window, /** * Set a window's keyboard grab mode. * - * 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,34 +1611,34 @@ 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. + * code. This will ensure the proper calling convention is followed on + * platforms where this matters (Win32) thereby avoiding stack corruption. * * \param proc the name of an OpenGL function * \returns a pointer to the named OpenGL function. The returned pointer @@ -1690,18 +1686,17 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GL_ExtensionSupported(const char * * \sa SDL_GL_GetAttribute * \sa SDL_GL_SetAttribute - * \sa + * \sa [[]] */ 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. * diff --git a/include/SDL_vulkan.h b/include/SDL_vulkan.h index b8b58c2b8..006c5aaf8 100644 --- a/include/SDL_vulkan.h +++ b/include/SDL_vulkan.h @@ -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,29 +128,27 @@ 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 + * Vulkan instance extensions * \returns SDL_TRUE on success, SDL_FALSE on error. * * \since This function is available in SDL 2.0.8 @@ -187,8 +185,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window, * Get the size of the window's underlying drawable dimensions in pixels. * * 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