From 1b49f092431379d43649d85c5b35b604d977be11 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
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 07ee1a17f7..dd815d0310 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 bb53ed3804..e68da77d31 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 76cc9540f4..8cc0dbfb78 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 52b3a6ca0e..6f73fcb4c9 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 17edc85112..f43b01399d 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 cf988a453c..3b695a1b59 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 e48b4245d6..433d0bf87a 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 iO
(Patch may be truncated, please check the link at the top of this post.)