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

include: manually ran wikiheaders.pl and cleaned up the obvious issues.

This commit is contained in:
Ryan C. Gordon 2021-10-08 20:22:48 -04:00
parent 55f60847cb
commit 1b49f09243
No known key found for this signature in database
GPG Key ID: FA148B892AB48044
9 changed files with 681 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

239
include/SDL_audio.h
View File

@ -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
*/

1
include/SDL_haptic.h
View File

@ -820,6 +820,7 @@ typedef union SDL_HapticEffect
/* Function prototypes */
/**
* Count the number of haptic devices attached to the system.
*

1
include/SDL_joystick.h
View File

@ -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.
*

385
include/SDL_rwops.h
View File

@ -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 */

15
include/SDL_stdinc.h
View File

@ -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.

6
include/SDL_surface.h
View File

@ -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.
*/

48
include/SDL_system.h
View File

@ -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__ */

6
include/SDL_thread.h
View File

@ -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)

1
include/SDL_video.h
View File

@ -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.
*