From 1b49f092431379d43649d85c5b35b604d977be11 Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" Date: Fri, 8 Oct 2021 20:22:48 -0400 Subject: [PATCH] include: manually ran wikiheaders.pl and cleaned up the obvious issues. --- include/SDL_audio.h | 239 +++++++++++++++++++++++-- include/SDL_haptic.h | 1 + include/SDL_joystick.h | 1 + include/SDL_rwops.h | 385 ++++++++++++++++++++++++++++++++++++++++- include/SDL_stdinc.h | 15 ++ include/SDL_surface.h | 6 +- include/SDL_system.h | 48 +++++ include/SDL_thread.h | 6 - include/SDL_video.h | 1 + 9 files changed, 681 insertions(+), 21 deletions(-) diff --git a/include/SDL_audio.h b/include/SDL_audio.h index 07ee1a17f..dd815d031 100644 --- a/include/SDL_audio.h +++ b/include/SDL_audio.h @@ -253,7 +253,46 @@ typedef struct SDL_AudioCVT * order that they are normally initialized by default. */ /* @{ */ + +/** + * Use this function to get the number of built-in audio drivers. + * + * This function returns a hardcoded number. This never returns a negative + * value; if there are no drivers compiled into this build of SDL, this + * function returns zero. The presence of a driver in this list does not mean + * it will function, it just means SDL is capable of interacting with that + * interface. For example, a build of SDL might have esound support, but if + * there's no esound server available, SDL's esound driver would fail if used. + * + * By default, SDL tries all drivers, in its preferred order, until one is + * found to be usable. + * + * \returns the number of built-in audio drivers. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetAudioDriver + */ extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void); + +/** + * Use this function to get the name of a built in audio driver. + * + * The list of audio drivers is given in the order that they are normally + * initialized by default; the drivers that seem more reasonable to choose + * first (as far as the SDL developers believe) are earlier in the list. + * + * The names of drivers are all simple, low-ASCII identifiers, like "alsa", + * "coreaudio" or "xaudio2". These never have Unicode characters, and are not + * meant to be proper names. + * + * \param index the index of the audio driver; the value ranges from 0 to + * SDL_GetNumAudioDrivers() - 1 + * \returns the name of the audio driver at the requested index, or NULL if an + * invalid index was specified. + * + * \sa SDL_GetNumAudioDrivers + */ extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index); /* @} */ @@ -265,7 +304,32 @@ extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index); * use. You should normally use SDL_Init() or SDL_InitSubSystem(). */ /* @{ */ + +/** + * Use this function to initialize a particular audio driver. + * + * This function is used internally, and should not be used unless you have a + * specific need to designate the audio driver you want to use. You should + * normally use SDL_Init() or SDL_InitSubSystem(). + * + * \param driver_name the name of the desired audio driver + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \sa SDL_AudioQuit + */ extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name); + +/** + * Use this function to shut down audio if you initialized it with + * SDL_AudioInit(). + * + * This function is used internally, and should not be used unless you have a + * specific need to specify the audio driver you want to use. You should + * normally use SDL_Quit() or SDL_QuitSubSystem(). + * + * \sa SDL_AudioInit + */ extern DECLSPEC void SDLCALL SDL_AudioQuit(void); /* @} */ @@ -296,7 +360,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void); * * This function is roughly equivalent to: * - * ```c++ + * ```c * SDL_OpenAudioDevice(NULL, 0, desired, obtained, SDL_AUDIO_ALLOW_ANY_CHANGE); * ``` * @@ -370,7 +434,7 @@ typedef Uint32 SDL_AudioDeviceID; * should not be called for each iteration of a loop, but rather once at the * start of a loop: * - * ```c++ + * ```c * // Don't do this: * for (int i = 0; i < SDL_GetNumAudioDevices(0); i++) * @@ -577,7 +641,34 @@ typedef enum SDL_AUDIO_PLAYING, SDL_AUDIO_PAUSED } SDL_AudioStatus; + +/** + * This function is a legacy means of querying the audio device. + * + * New programs might want to use SDL_GetAudioDeviceStatus() instead. This + * function is equivalent to calling... + * + * ```c + * SDL_GetAudioDeviceStatus(1); + * ``` + * + * ...and is only useful if you used the legacy SDL_OpenAudio() function. + * + * \returns the SDL_AudioStatus of the audio device opened by SDL_OpenAudio(). + * + * \sa SDL_GetAudioDeviceStatus + */ extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void); + +/** + * Use this function to get the current audio state of an audio device. + * + * \param dev the ID of an audio device previously opened with + * SDL_OpenAudioDevice() + * \returns the SDL_AudioStatus of the specified audio device. + * + * \sa SDL_PauseAudioDevice + */ extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev); /* @} *//* Audio State */ @@ -591,7 +682,52 @@ extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioDeviceStatus(SDL_AudioDevice * Silence will be written to the audio device during the pause. */ /* @{ */ + +/** + * This function is a legacy means of pausing the audio device. + * + * New programs might want to use SDL_PauseAudioDevice() instead. This + * function is equivalent to calling... + * + * ```c + * SDL_PauseAudioDevice(1, pause_on); + * ``` + * + * ...and is only useful if you used the legacy SDL_OpenAudio() function. + * + * \param pause_on non-zero to pause, 0 to unpause + * + * \sa SDL_GetAudioStatus + * \sa SDL_PauseAudioDevice + */ extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on); + +/** + * Use this function to pause and unpause audio playback on a specified + * device. + * + * This function pauses and unpauses the audio callback processing for a given + * device. Newly-opened audio devices start in the paused state, so you must + * call this function with **pause_on**=0 after opening the specified audio + * device to start playing sound. This allows you to safely initialize data + * for your callback function after opening the audio device. Silence will be + * written to the audio device while paused, and the audio callback is + * guaranteed to not be called. Pausing one device does not prevent other + * unpaused devices from running their callbacks. + * + * Pausing state does not stack; even if you pause a device several times, a + * single unpause will start the device playing again, and vice versa. This is + * different from how SDL_LockAudioDevice() works. + * + * If you just need to protect a few variables from race conditions vs your + * callback, you shouldn't pause the audio device, as it will lead to dropouts + * in the audio playback. Instead, you should use SDL_LockAudioDevice(). + * + * \param dev a device opened by SDL_OpenAudioDevice() + * \param pause_on non-zero to pause, 0 to unpause + * + * \sa SDL_LockAudioDevice + */ extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev, int pause_on); /* @} *//* Pause audio functions */ @@ -640,14 +776,14 @@ extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev, * * Example: * - * ```c++ + * ```c * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, &spec, &buf, &len); * ``` * * Note that the SDL_LoadWAV macro does this same thing for you, but in a less * messy way: * - * ```c++ + * ```c * SDL_LoadWAV("sample.wav", &spec, &buf, &len); * ``` * @@ -907,17 +1043,18 @@ extern DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream); extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream); #define SDL_MIX_MAXVOLUME 128 + /** * This function is a legacy means of mixing audio. * - * This function is equivalent to calling + * This function is equivalent to calling... * - * ```c++ + * ```c * SDL_MixAudioFormat(dst, src, format, len, volume); * ``` * - * where `format` is the obtained format of the audio device from the legacy - * SDL_OpenAudio() function. + * ...where `format` is the obtained format of the audio device from the + * legacy SDL_OpenAudio() function. * * \param dst the destination for the mixed audio * \param src the source audio buffer to be mixed @@ -1137,22 +1274,102 @@ extern DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev); * function or you will cause deadlock. */ /* @{ */ + +/** + * This function is a legacy means of locking the audio device. + * + * New programs might want to use SDL_LockAudioDevice() instead. This function + * is equivalent to calling... + * + * ```c + * SDL_LockAudioDevice(1); + * ``` + * + * ...and is only useful if you used the legacy SDL_OpenAudio() function. + * + * \sa SDL_LockAudioDevice + * \sa SDL_UnlockAudio + * \sa SDL_UnlockAudioDevice + */ extern DECLSPEC void SDLCALL SDL_LockAudio(void); + +/** + * Use this function to lock out the audio callback function for a specified + * device. + * + * The lock manipulated by these functions protects the audio callback + * function specified in SDL_OpenAudioDevice(). During a + * SDL_LockAudioDevice()/SDL_UnlockAudioDevice() pair, you can be guaranteed + * that the callback function for that device is not running, even if the + * device is not paused. While a device is locked, any other unpaused, + * unlocked devices may still run their callbacks. + * + * Calling this function from inside your audio callback is unnecessary. SDL + * obtains this lock before calling your function, and releases it when the + * function returns. + * + * You should not hold the lock longer than absolutely necessary. If you hold + * it too long, you'll experience dropouts in your audio playback. Ideally, + * your application locks the device, sets a few variables and unlocks again. + * Do not do heavy work while holding the lock for a device. + * + * It is safe to lock the audio device multiple times, as long as you unlock + * it an equivalent number of times. The callback will not run until the + * device has been unlocked completely in this way. If your application fails + * to unlock the device appropriately, your callback will never run, you might + * hear repeating bursts of audio, and SDL_CloseAudioDevice() will probably + * deadlock. + * + * Internally, the audio device lock is a mutex; if you lock from two threads + * at once, not only will you block the audio callback, you'll block the other + * thread. + * + * \param dev the ID of the device to be locked + * + * \sa SDL_UnlockAudioDevice + */ extern DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev); + +/** + * This function is a legacy means of unlocking the audio device. + * + * New programs might want to use SDL_UnlockAudioDevice() instead. This + * function is equivalent to calling... + * + * ```c + * SDL_UnlockAudioDevice(1); + * ``` + * + * ...and is only useful if you used the legacy SDL_OpenAudio() function. + * + * \sa SDL_LockAudio + * \sa SDL_UnlockAudioDevice + */ extern DECLSPEC void SDLCALL SDL_UnlockAudio(void); + +/** + * Use this function to unlock the audio callback function for a specified + * device. + * + * This function should be paired with a previous SDL_LockAudioDevice() call. + * + * \param dev the ID of the device to be unlocked + * + * \sa SDL_LockAudioDevice + */ extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev); /* @} *//* Audio lock functions */ /** * This function is a legacy means of closing the audio device. * - * This function is equivalent to calling + * This function is equivalent to calling... * - * ```c++ + * ```c * SDL_CloseAudioDevice(1); * ``` * - * and is only useful if you used the legacy SDL_OpenAudio() function. + * ...and is only useful if you used the legacy SDL_OpenAudio() function. * * \sa SDL_OpenAudio */ diff --git a/include/SDL_haptic.h b/include/SDL_haptic.h index bb53ed380..e68da77d3 100644 --- a/include/SDL_haptic.h +++ b/include/SDL_haptic.h @@ -820,6 +820,7 @@ typedef union SDL_HapticEffect /* Function prototypes */ + /** * Count the number of haptic devices attached to the system. * diff --git a/include/SDL_joystick.h b/include/SDL_joystick.h index 76cc9540f..8cc0dbfb7 100644 --- a/include/SDL_joystick.h +++ b/include/SDL_joystick.h @@ -608,6 +608,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state); #define SDL_JOYSTICK_AXIS_MAX 32767 #define SDL_JOYSTICK_AXIS_MIN -32768 + /** * Get the current state of an axis control on a joystick. * diff --git a/include/SDL_rwops.h b/include/SDL_rwops.h index 52b3a6ca0..6f73fcb4c 100644 --- a/include/SDL_rwops.h +++ b/include/SDL_rwops.h @@ -156,25 +156,216 @@ typedef struct SDL_RWops */ /* @{ */ +/** + * Use this function to create a new SDL_RWops structure for reading from + * and/or writing to a named file. + * + * The `mode` string is treated roughly the same as in a call to the C + * library's fopen(), even if SDL doesn't happen to use fopen() behind the + * scenes. + * + * Available `mode` strings: + * + * - "r": Open a file for reading. The file must exist. + * - "w": Create an empty file for writing. If a file with the same name + * already exists its content is erased and the file is treated as a new + * empty file. + * - "a": Append to a file. Writing operations append data at the end of the + * file. The file is created if it does not exist. + * - "r+": Open a file for update both reading and writing. The file must + * exist. + * - "w+": Create an empty file for both reading and writing. If a file with + * the same name already exists its content is erased and the file is + * treated as a new empty file. + * - "a+": Open a file for reading and appending. All writing operations are + * performed at the end of the file, protecting the previous content to be + * overwritten. You can reposition (fseek, rewind) the internal pointer to + * anywhere in the file for reading, but writing operations will move it + * back to the end of file. The file is created if it does not exist. + * + * **NOTE**: In order to open a file as a binary file, a "b" character has to + * be included in the `mode` string. This additional "b" character can either + * be appended at the end of the string (thus making the following compound + * modes: "rb", "wb", "ab", "r+b", "w+b", "a+b") or be inserted between the + * letter and the "+" sign for the mixed modes ("rb+", "wb+", "ab+"). + * Additional characters may follow the sequence, although they should have no + * effect. For example, "t" is sometimes appended to make explicit the file is + * a text file. + * + * This function supports Unicode filenames, but they must be encoded in UTF-8 + * format, regardless of the underlying operating system. + * + * As a fallback, SDL_RWFromFile() will transparently open a matching filename + * in an Android app's `assets`. + * + * Closing the SDL_RWops will close the file handle SDL is holding internally. + * + * \param file a UTF-8 string representing the filename to open + * \param mode an ASCII string representing the mode to be used for opening + * the file. + * \returns a pointer to the SDL_RWops structure that is created, or NULL on + * failure; call SDL_GetError() for more information. + * + * \sa SDL_RWclose + * \sa SDL_RWFromConstMem + * \sa SDL_RWFromFP + * \sa SDL_RWFromMem + * \sa SDL_RWread + * \sa SDL_RWseek + * \sa SDL_RWtell + * \sa SDL_RWwrite + */ extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFile(const char *file, const char *mode); #ifdef HAVE_STDIO_H -extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFP(FILE * fp, - SDL_bool autoclose); + +extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFP(FILE * fp, SDL_bool autoclose); + #else + +/** + * Use this function to create an SDL_RWops structure from a standard I/O file + * pointer (stdio.h's `FILE*`). + * + * This function is not available on Windows, since files opened in an + * application on that platform cannot be used by a dynamically linked + * library. + * + * On some platforms, the first parameter is a `void*`, on others, it's a + * `FILE*`, depending on what system headers are available to SDL. It is + * always intended to be the `FILE*` type from the C runtime's stdio.h. + * + * \param fp the `FILE*` that feeds the SDL_RWops stream + * \param autoclose SDL_TRUE to close the `FILE*` when closing the SDL_RWops, + * SDL_FALSE to leave the `FILE*` open when the RWops is + * closed + * \returns a pointer to the SDL_RWops structure that is created, or NULL on + * failure; call SDL_GetError() for more information. + * + * \sa SDL_RWclose + * \sa SDL_RWFromConstMem + * \sa SDL_RWFromFile + * \sa SDL_RWFromMem + * \sa SDL_RWread + * \sa SDL_RWseek + * \sa SDL_RWtell + * \sa SDL_RWwrite + */ extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFP(void * fp, SDL_bool autoclose); #endif +/** + * Use this function to prepare a read-write memory buffer for use with + * SDL_RWops. + * + * This function sets up an SDL_RWops struct based on a memory area of a + * certain size, for both read and write access. + * + * This memory buffer is not copied by the RWops; the pointer you provide must + * remain valid until you close the stream. Closing the stream will not free + * the original buffer. + * + * If you need to make sure the RWops never writes to the memory buffer, you + * should use SDL_RWFromConstMem() with a read-only buffer of memory instead. + * + * \param mem a pointer to a buffer to feed an SDL_RWops stream + * \param size the buffer size, in bytes + * \returns a pointer to a new SDL_RWops structure, or NULL if it fails; call + * SDL_GetError() for more information. + * + * \sa SDL_RWclose + * \sa SDL_RWFromConstMem + * \sa SDL_RWFromFile + * \sa SDL_RWFromFP + * \sa SDL_RWFromMem + * \sa SDL_RWread + * \sa SDL_RWseek + * \sa SDL_RWtell + * \sa SDL_RWwrite + */ extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromMem(void *mem, int size); + +/** + * Use this function to prepare a read-only memory buffer for use with RWops. + * + * This function sets up an SDL_RWops struct based on a memory area of a + * certain size. It assumes the memory area is not writable. + * + * Attempting to write to this RWops stream will report an error without + * writing to the memory buffer. + * + * This memory buffer is not copied by the RWops; the pointer you provide must + * remain valid until you close the stream. Closing the stream will not free + * the original buffer. + * + * If you need to write to a memory buffer, you should use SDL_RWFromMem() + * with a writable buffer of memory instead. + * + * \param mem a pointer to a read-only buffer to feed an SDL_RWops stream + * \param size the buffer size, in bytes + * \returns a pointer to a new SDL_RWops structure, or NULL if it fails; call + * SDL_GetError() for more information. + * + * \sa SDL_RWclose + * \sa SDL_RWFromConstMem + * \sa SDL_RWFromFile + * \sa SDL_RWFromFP + * \sa SDL_RWFromMem + * \sa SDL_RWread + * \sa SDL_RWseek + * \sa SDL_RWtell + */ extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromConstMem(const void *mem, int size); /* @} *//* RWFrom functions */ +/** + * Use this function to allocate an empty, unpopulated SDL_RWops structure. + * + * Applications do not need to use this function unless they are providing + * their own SDL_RWops implementation. If you just need a SDL_RWops to + * read/write a common data source, you should use the built-in + * implementations in SDL, like SDL_RWFromFile() or SDL_RWFromMem(), etc. + * + * You must free the returned pointer with SDL_FreeRW(). Depending on your + * operating system and compiler, there may be a difference between the + * malloc() and free() your program uses and the versions SDL calls + * internally. Trying to mix the two can cause crashing such as segmentation + * faults. Since all SDL_RWops must free themselves when their **close** + * method is called, all SDL_RWops must be allocated through this function, so + * they can all be freed correctly with SDL_FreeRW(). + * + * \returns a pointer to the allocated memory on success, or NULL on failure; + * call SDL_GetError() for more information. + * + * \sa SDL_FreeRW + */ extern DECLSPEC SDL_RWops *SDLCALL SDL_AllocRW(void); + +/** + * Use this function to free an SDL_RWops structure allocated by + * SDL_AllocRW(). + * + * Applications do not need to use this function unless they are providing + * their own SDL_RWops implementation. If you just need a SDL_RWops to + * read/write a common data source, you should use the built-in + * implementations in SDL, like SDL_RWFromFile() or SDL_RWFromMem(), etc, and + * call the **close** method on those SDL_RWops pointers when you are done + * with them. + * + * Only use SDL_FreeRW() on pointers returned by SDL_AllocRW(). The pointer is + * invalid as soon as this function returns. Any extra memory allocated during + * creation of the SDL_RWops is not freed by SDL_FreeRW(); the programmer must + * be responsible for managing that memory in their **close** method. + * + * \param area the SDL_RWops structure to be freed + * + * \sa SDL_AllocRW + */ extern DECLSPEC void SDLCALL SDL_FreeRW(SDL_RWops * area); #define RW_SEEK_SET 0 /**< Seek from the beginning of data */ @@ -377,12 +568,102 @@ extern DECLSPEC void *SDLCALL SDL_LoadFile(const char *file, size_t *datasize); * Read an item of the specified endianness and return in native format. */ /* @{ */ + +/** + * Use this function to read a byte from an SDL_RWops. + * + * \param src the SDL_RWops to read from + * \returns the read byte on success or 0 on failure; call SDL_GetError() for + * more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_WriteU8 + */ extern DECLSPEC Uint8 SDLCALL SDL_ReadU8(SDL_RWops * src); + +/** + * Use this function to read 16 bits of little-endian data from an SDL_RWops + * and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * \param src the stream from which to read data + * \returns 16 bits of data in the native byte order of the platform. + * + * \sa SDL_ReadBE16 + */ extern DECLSPEC Uint16 SDLCALL SDL_ReadLE16(SDL_RWops * src); + +/** + * Use this function to read 16 bits of big-endian data from an SDL_RWops and + * return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * \param src the stream from which to read data + * \returns 16 bits of data in the native byte order of the platform. + * + * \sa SDL_ReadLE16 + */ extern DECLSPEC Uint16 SDLCALL SDL_ReadBE16(SDL_RWops * src); + +/** + * Use this function to read 32 bits of little-endian data from an SDL_RWops + * and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * \param src the stream from which to read data + * \returns 32 bits of data in the native byte order of the platform. + * + * \sa SDL_ReadBE32 + */ extern DECLSPEC Uint32 SDLCALL SDL_ReadLE32(SDL_RWops * src); + +/** + * Use this function to read 32 bits of big-endian data from an SDL_RWops and + * return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * \param src the stream from which to read data + * \returns 32 bits of data in the native byte order of the platform. + * + * \sa SDL_ReadLE32 + */ extern DECLSPEC Uint32 SDLCALL SDL_ReadBE32(SDL_RWops * src); + +/** + * Use this function to read 64 bits of little-endian data from an SDL_RWops + * and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * \param src the stream from which to read data + * \returns 64 bits of data in the native byte order of the platform. + * + * \sa SDL_ReadBE64 + */ extern DECLSPEC Uint64 SDLCALL SDL_ReadLE64(SDL_RWops * src); + +/** + * Use this function to read 64 bits of big-endian data from an SDL_RWops and + * return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * \param src the stream from which to read data + * \returns 64 bits of data in the native byte order of the platform. + * + * \sa SDL_ReadLE64 + */ extern DECLSPEC Uint64 SDLCALL SDL_ReadBE64(SDL_RWops * src); /* @} *//* Read endian functions */ @@ -392,12 +673,112 @@ extern DECLSPEC Uint64 SDLCALL SDL_ReadBE64(SDL_RWops * src); * Write an item of native format to the specified endianness. */ /* @{ */ + +/** + * Use this function to write a byte to an SDL_RWops. + * + * \param dst the SDL_RWops to write to + * \param value the byte value to write + * \returns 1 on success or 0 on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_ReadU8 + */ extern DECLSPEC size_t SDLCALL SDL_WriteU8(SDL_RWops * dst, Uint8 value); + +/** + * Use this function to write 16 bits in native format to a SDL_RWops as + * little-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in little-endian + * format. + * + * \param dst the stream to which data will be written + * \param value the data to be written, in native format + * \returns 1 on successful write, 0 on error. + * + * \sa SDL_WriteBE16 + */ extern DECLSPEC size_t SDLCALL SDL_WriteLE16(SDL_RWops * dst, Uint16 value); + +/** + * Use this function to write 16 bits in native format to a SDL_RWops as + * big-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in big-endian format. + * + * \param dst the stream to which data will be written + * \param value the data to be written, in native format + * \returns 1 on successful write, 0 on error. + * + * \sa SDL_WriteLE16 + */ extern DECLSPEC size_t SDLCALL SDL_WriteBE16(SDL_RWops * dst, Uint16 value); + +/** + * Use this function to write 32 bits in native format to a SDL_RWops as + * little-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in little-endian + * format. + * + * \param dst the stream to which data will be written + * \param value the data to be written, in native format + * \returns 1 on successful write, 0 on error. + * + * \sa SDL_WriteBE32 + */ extern DECLSPEC size_t SDLCALL SDL_WriteLE32(SDL_RWops * dst, Uint32 value); + +/** + * Use this function to write 32 bits in native format to a SDL_RWops as + * big-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in big-endian format. + * + * \param dst the stream to which data will be written + * \param value the data to be written, in native format + * \returns 1 on successful write, 0 on error. + * + * \sa SDL_WriteLE32 + */ extern DECLSPEC size_t SDLCALL SDL_WriteBE32(SDL_RWops * dst, Uint32 value); + +/** + * Use this function to write 64 bits in native format to a SDL_RWops as + * little-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in little-endian + * format. + * + * \param dst the stream to which data will be written + * \param value the data to be written, in native format + * \returns 1 on successful write, 0 on error. + * + * \sa SDL_WriteBE64 + */ extern DECLSPEC size_t SDLCALL SDL_WriteLE64(SDL_RWops * dst, Uint64 value); + +/** + * Use this function to write 64 bits in native format to a SDL_RWops as + * big-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in big-endian format. + * + * \param dst the stream to which data will be written + * \param value the data to be written, in native format + * \returns 1 on successful write, 0 on error. + * + * \sa SDL_WriteLE64 + */ extern DECLSPEC size_t SDLCALL SDL_WriteBE64(SDL_RWops * dst, Uint64 value); /* @} *//* Write endian functions */ diff --git a/include/SDL_stdinc.h b/include/SDL_stdinc.h index 17edc8511..f43b01399 100644 --- a/include/SDL_stdinc.h +++ b/include/SDL_stdinc.h @@ -575,6 +575,20 @@ extern DECLSPEC int SDLCALL SDL_vasprintf(char **strp, const char *fmt, va_list #endif #endif +/** + * Use this function to compute arc cosine of `x`. + * + * The definition of `y = acos(x)` is `x = cos(y)`. + * + * Domain: `-1 <= x <= 1` + * + * Range: `0 <= y <= Pi` + * + * \param x floating point value, in radians. + * \returns arc cosine of `x`. + * + * \since This function is available since SDL 2.0.2. + */ extern DECLSPEC double SDLCALL SDL_acos(double x); extern DECLSPEC float SDLCALL SDL_acosf(float x); extern DECLSPEC double SDLCALL SDL_asin(double x); @@ -632,6 +646,7 @@ extern DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd); 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. diff --git a/include/SDL_surface.h b/include/SDL_surface.h index cf988a453..3b695a1b5 100644 --- a/include/SDL_surface.h +++ b/include/SDL_surface.h @@ -159,6 +159,7 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface /* !!! FIXME for 2.1: why does this ask for depth? Format provides that. */ + /** * Allocate a new RGB surface with a specific pixel format. * @@ -218,6 +219,7 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels, Uint32 Amask); /* !!! FIXME for 2.1: why does this ask for depth? Format provides that. */ + /** * Allocate a new RGB surface with with a specific pixel format and existing * pixel data. @@ -812,8 +814,8 @@ extern DECLSPEC int SDLCALL SDL_LowerBlit /** - * Perform a fast, low quality, stretch blit between two surfaces of the - * same format. + * Perform a fast, low quality, stretch blit between two surfaces of the same + * format. * * Please use SDL_BlitScaled() instead. */ diff --git a/include/SDL_system.h b/include/SDL_system.h index e48b4245d..433d0bf87 100644 --- a/include/SDL_system.h +++ b/include/SDL_system.h @@ -145,9 +145,57 @@ extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriority(Sint64 threadID, int prio #ifdef __IPHONEOS__ #define SDL_iOSSetAnimationCallback(window, interval, callback, callbackParam) SDL_iPhoneSetAnimationCallback(window, interval, callback, callbackParam) + +/** + * Use this function to set the animation callback on Apple iOS. + * + * The function prototype for `callback` is: + * + * ```c + * void callback(void* callbackParam); + * ``` + * + * Where its parameter, `callbackParam`, is what was passed as `callbackParam` + * to SDL_iPhoneSetAnimationCallback(). + * + * This function is only available on Apple iOS. + * + * For more information see: + * [README-ios.md](https://hg.libsdl.org/SDL/file/default/docs/README-ios.md) + * + * This functions is also accessible using the macro + * SDL_iOSSetAnimationCallback() since SDL 2.0.4. + * + * \param window the window for which the animation callback should be set + * \param interval the number of frames after which **callback** will be + * called + * \param callback the function to call for every frame. + * \param callbackParam a pointer that is passed to `callback`. + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_iPhoneSetEventPump + */ extern DECLSPEC int SDLCALL SDL_iPhoneSetAnimationCallback(SDL_Window * window, int interval, void (*callback)(void*), void *callbackParam); #define SDL_iOSSetEventPump(enabled) SDL_iPhoneSetEventPump(enabled) + +/** + * Use this function to enable or disable the SDL event pump on Apple iOS. + * + * This function is only available on Apple iOS. + * + * This functions is also accessible using the macro SDL_iOSSetEventPump() + * since SDL 2.0.4. + * + * \param enabled SDL_TRUE to enable the event pump, SDL_FALSE to disable it + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_iPhoneSetAnimationCallback + */ extern DECLSPEC void SDLCALL SDL_iPhoneSetEventPump(SDL_bool enabled); #endif /* __IPHONEOS__ */ diff --git a/include/SDL_thread.h b/include/SDL_thread.h index b3441505c..5626447a8 100644 --- a/include/SDL_thread.h +++ b/include/SDL_thread.h @@ -123,9 +123,6 @@ typedef void (__cdecl * pfnSDL_CurrentEndThread) (unsigned code); #define SDL_endthread _endthreadex #endif -/** - * Create a thread. - */ extern DECLSPEC SDL_Thread *SDLCALL SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data, pfnSDL_CurrentBeginThread pfnBeginThread, @@ -138,9 +135,6 @@ SDL_CreateThreadWithStackSize(int (SDLCALL * fn) (void *), pfnSDL_CurrentEndThread pfnEndThread); -/** - * Create a thread. - */ #if defined(SDL_CreateThread) && SDL_DYNAMIC_API #undef SDL_CreateThread #define SDL_CreateThread(fn, name, data) SDL_CreateThread_REAL(fn, name, data, (pfnSDL_CurrentBeginThread)SDL_beginthread, (pfnSDL_CurrentEndThread)SDL_endthread) diff --git a/include/SDL_video.h b/include/SDL_video.h index ac1f85e4d..6cc85ad4b 100644 --- a/include/SDL_video.h +++ b/include/SDL_video.h @@ -1046,6 +1046,7 @@ extern DECLSPEC void SDLCALL SDL_SetWindowResizable(SDL_Window * window, */ extern DECLSPEC void SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window * window, SDL_bool on_top); + /** * Show a window. *