| /* |
| Simple DirectMedia Layer |
| Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org> |
| |
| This software is provided 'as-is', without any express or implied |
| warranty. In no event will the authors be held liable for any damages |
| arising from the use of this software. |
| |
| Permission is granted to anyone to use this software for any purpose, |
| including commercial applications, and to alter it and redistribute it |
| freely, subject to the following restrictions: |
| |
| 1. The origin of this software must not be misrepresented; you must not |
| claim that you wrote the original software. If you use this software |
| in a product, an acknowledgment in the product documentation would be |
| appreciated but is not required. |
| 2. Altered source versions must be plainly marked as such, and must not be |
| misrepresented as being the original software. |
| 3. This notice may not be removed or altered from any source distribution. |
| */ |
| |
| /** |
| * # CategoryStdinc |
| * |
| * This is a general header that includes C language support. It implements a |
| * subset of the C runtime: these should all behave the same way as their C |
| * runtime equivalents, but with an SDL_ prefix. |
| */ |
| |
| #ifndef SDL_stdinc_h_ |
| #define SDL_stdinc_h_ |
| |
| #include <SDL3/SDL_platform_defines.h> |
| |
| #if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L |
| #include <inttypes.h> |
| #endif |
| #include <stdarg.h> |
| #ifndef __cplusplus |
| #include <stdbool.h> |
| #endif |
| #include <stdint.h> |
| #include <string.h> |
| #include <wchar.h> |
| |
| #ifndef SDL_DISABLE_ALLOCA |
| # ifndef alloca |
| # ifdef HAVE_ALLOCA_H |
| # include <alloca.h> |
| # elif defined(SDL_PLATFORM_NETBSD) |
| # if defined(__STRICT_ANSI__) |
| # define SDL_DISABLE_ALLOCA |
| # else |
| # include <stdlib.h> |
| # endif |
| # elif defined(__GNUC__) |
| # define alloca __builtin_alloca |
| # elif defined(_MSC_VER) |
| # include <malloc.h> |
| # define alloca _alloca |
| # elif defined(__WATCOMC__) |
| # include <malloc.h> |
| # elif defined(__BORLANDC__) |
| # include <malloc.h> |
| # elif defined(__DMC__) |
| # include <stdlib.h> |
| # elif defined(SDL_PLATFORM_AIX) |
| # pragma alloca |
| # elif defined(__MRC__) |
| void *alloca(unsigned); |
| # else |
| void *alloca(size_t); |
| # endif |
| # endif |
| #endif |
| |
| #ifdef SIZE_MAX |
| # define SDL_SIZE_MAX SIZE_MAX |
| #else |
| # define SDL_SIZE_MAX ((size_t) -1) |
| #endif |
| |
| /** |
| * Check if the compiler supports a given builtin. |
| * Supported by virtually all clang versions and recent gcc. Use this |
| * instead of checking the clang version if possible. |
| */ |
| #ifdef __has_builtin |
| #define SDL_HAS_BUILTIN(x) __has_builtin(x) |
| #else |
| #define SDL_HAS_BUILTIN(x) 0 |
| #endif |
| |
| /** |
| * The number of elements in an array. |
| * |
| * This macro looks like it double-evaluates the argument, but it does so |
| * inside of `sizeof`, so there are no side-effects here, as expressions do |
| * not actually run any code in these cases. |
| * |
| * \since This macro is available since SDL 3.0.0. |
| */ |
| #define SDL_arraysize(array) (sizeof(array)/sizeof(array[0])) |
| |
| /** |
| * Macro useful for building other macros with strings in them. |
| * |
| * For example: |
| * |
| * ```c |
| * #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n")` |
| * ``` |
| * |
| * \since This macro is available since SDL 3.0.0. |
| */ |
| #define SDL_STRINGIFY_ARG(arg) #arg |
| |
| /** |
| * \name Cast operators |
| * |
| * Use proper C++ casts when compiled as C++ to be compatible with the option |
| * -Wold-style-cast of GCC (and -Werror=old-style-cast in GCC 4.2 and above). |
| */ |
| /* @{ */ |
| #ifdef __cplusplus |
| #define SDL_reinterpret_cast(type, expression) reinterpret_cast<type>(expression) |
| #define SDL_static_cast(type, expression) static_cast<type>(expression) |
| #define SDL_const_cast(type, expression) const_cast<type>(expression) |
| #else |
| #define SDL_reinterpret_cast(type, expression) ((type)(expression)) |
| #define SDL_static_cast(type, expression) ((type)(expression)) |
| #define SDL_const_cast(type, expression) ((type)(expression)) |
| #endif |
| /* @} *//* Cast operators */ |
| |
| /* Define a four character code as a Uint32 */ |
| #define SDL_FOURCC(A, B, C, D) \ |
| ((SDL_static_cast(Uint32, SDL_static_cast(Uint8, (A))) << 0) | \ |
| (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (B))) << 8) | \ |
| (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (C))) << 16) | \ |
| (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (D))) << 24)) |
| |
| #ifdef SDL_WIKI_DOCUMENTATION_SECTION |
| |
| /** |
| * Append the 64 bit integer suffix to a signed integer literal. |
| * |
| * This helps compilers that might believe a integer literal larger than |
| * 0xFFFFFFFF is overflowing a 32-bit value. Use `SDL_SINT64_C(0xFFFFFFFF1)` |
| * instead of `0xFFFFFFFF1` by itself. |
| * |
| * \since This macro is available since SDL 3.0.0. |
| * |
| * \sa SDL_UINT64_C |
| */ |
| #define SDL_SINT64_C(c) c ## LL /* or whatever the current compiler uses. */ |
| |
| /** |
| * Append the 64 bit integer suffix to an unsigned integer literal. |
| * |
| * This helps compilers that might believe a integer literal larger than |
| * 0xFFFFFFFF is overflowing a 32-bit value. Use `SDL_UINT64_C(0xFFFFFFFF1)` |
| * instead of `0xFFFFFFFF1` by itself. |
| * |
| * \since This macro is available since SDL 3.0.0. |
| * |
| * \sa SDL_SINT64_C |
| */ |
| #define SDL_UINT64_C(c) c ## ULL /* or whatever the current compiler uses. */ |
| |
| #elif defined(INT64_C) |
| #define SDL_SINT64_C(c) INT64_C(c) |
| #define SDL_UINT64_C(c) UINT64_C(c) |
| #elif defined(_MSC_VER) |
| #define SDL_SINT64_C(c) c ## i64 |
| #define SDL_UINT64_C(c) c ## ui64 |
| #elif defined(__LP64__) || defined(_LP64) |
| #define SDL_SINT64_C(c) c ## L |
| #define SDL_UINT64_C(c) c ## UL |
| #else |
| #define SDL_SINT64_C(c) c ## LL |
| #define SDL_UINT64_C(c) c ## ULL |
| #endif |
| |
| /** |
| * \name Basic data types |
| */ |
| /* @{ */ |
| |
| /** |
| * A boolean false. |
| * |
| * \since This macro is available since SDL 3.0.0. |
| * |
| * \sa SDL_bool |
| */ |
| #define SDL_FALSE false |
| |
| /** |
| * A boolean true. |
| * |
| * \since This macro is available since SDL 3.0.0. |
| * |
| * \sa SDL_bool |
| */ |
| #define SDL_TRUE true |
| |
| /** |
| * A boolean type: true or false. |
| * |
| * \since This datatype is available since SDL 3.0.0. |
| * |
| * \sa SDL_TRUE |
| * \sa SDL_FALSE |
| */ |
| typedef bool SDL_bool; |
| |
| /** |
| * A signed 8-bit integer type. |
| * |
| * \since This macro is available since SDL 3.0.0. |
| */ |
| typedef int8_t Sint8; |
| #define SDL_MAX_SINT8 ((Sint8)0x7F) /* 127 */ |
| #define SDL_MIN_SINT8 ((Sint8)(~0x7F)) /* -128 */ |
| |
| /** |
| * An unsigned 8-bit integer type. |
| * |
| * \since This macro is available since SDL 3.0.0. |
| */ |
| typedef uint8_t Uint8; |
| #define SDL_MAX_UINT8 ((Uint8)0xFF) /* 255 */ |
| #define SDL_MIN_UINT8 ((Uint8)0x00) /* 0 */ |
| |
| /** |
| * A signed 16-bit integer type. |
| * |
| * \since This macro is available since SDL 3.0.0. |
| */ |
| typedef int16_t Sint16; |
| #define SDL_MAX_SINT16 ((Sint16)0x7FFF) /* 32767 */ |
| #define SDL_MIN_SINT16 ((Sint16)(~0x7FFF)) /* -32768 */ |
| |
| /** |
| * An unsigned 16-bit integer type. |
| * |
| * \since This macro is available since SDL 3.0.0. |
| */ |
| typedef uint16_t Uint16; |
| #define SDL_MAX_UINT16 ((Uint16)0xFFFF) /* 65535 */ |
| #define SDL_MIN_UINT16 ((Uint16)0x0000) /* 0 */ |
| |
| /** |
| * A signed 32-bit integer type. |
| * |
| * \since This macro is available since SDL 3.0.0. |
| */ |
| typedef int32_t Sint32; |
| #define SDL_MAX_SINT32 ((Sint32)0x7FFFFFFF) /* 2147483647 */ |
| #define SDL_MIN_SINT32 ((Sint32)(~0x7FFFFFFF)) /* -2147483648 */ |
| |
| /** |
| * An unsigned 32-bit integer type. |
| * |
| * \since This macro is available since SDL 3.0.0. |
| */ |
| typedef uint32_t Uint32; |
| #define SDL_MAX_UINT32 ((Uint32)0xFFFFFFFFu) /* 4294967295 */ |
| #define SDL_MIN_UINT32 ((Uint32)0x00000000) /* 0 */ |
| |
| /** |
| * A signed 64-bit integer type. |
| * |
| * \since This macro is available since SDL 3.0.0. |
| * |
| * \sa SDL_SINT64_C |
| */ |
| typedef int64_t Sint64; |
| #define SDL_MAX_SINT64 SDL_SINT64_C(0x7FFFFFFFFFFFFFFF) /* 9223372036854775807 */ |
| #define SDL_MIN_SINT64 ~SDL_SINT64_C(0x7FFFFFFFFFFFFFFF) /* -9223372036854775808 */ |
| |
| /** |
| * An unsigned 64-bit integer type. |
| * |
| * \since This macro is available since SDL 3.0.0. |
| * |
| * \sa SDL_UINT64_C |
| */ |
| typedef uint64_t Uint64; |
| #define SDL_MAX_UINT64 SDL_UINT64_C(0xFFFFFFFFFFFFFFFF) /* 18446744073709551615 */ |
| #define SDL_MIN_UINT64 SDL_UINT64_C(0x0000000000000000) /* 0 */ |
| |
| /** |
| * SDL times are signed, 64-bit integers representing nanoseconds since the |
| * Unix epoch (Jan 1, 1970). |
| * |
| * They can be converted between POSIX time_t values with SDL_NS_TO_SECONDS() |
| * and SDL_SECONDS_TO_NS(), and between Windows FILETIME values with |
| * SDL_TimeToWindows() and SDL_TimeFromWindows(). |
| * |
| * \since This macro is available since SDL 3.0.0. |
| * |
| * \sa SDL_MAX_SINT64 |
| * \sa SDL_MIN_SINT64 |
| */ |
| typedef Sint64 SDL_Time; |
| #define SDL_MAX_TIME SDL_MAX_SINT64 |
| #define SDL_MIN_TIME SDL_MIN_SINT64 |
| |
| /* @} *//* Basic data types */ |
| |
| /** |
| * \name Floating-point constants |
| */ |
| /* @{ */ |
| |
| #ifdef FLT_EPSILON |
| #define SDL_FLT_EPSILON FLT_EPSILON |
| #else |
| |
| /** |
| * Epsilon constant, used for comparing floating-point numbers. |
| * |
| * Equals by default to platform-defined `FLT_EPSILON`, or |
| * `1.1920928955078125e-07F` if that's not available. |
| * |
| * \since This macro is available since SDL 3.0.0. |
| */ |
| #define SDL_FLT_EPSILON 1.1920928955078125e-07F /* 0x0.000002p0 */ |
| #endif |
| |
| /* @} *//* Floating-point constants */ |
| |
| /* Make sure we have macros for printing width-based integers. |
| * <stdint.h> should define these but this is not true all platforms. |
| * (for example win32) */ |
| #ifndef SDL_PRIs64 |
| #if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) |
| #define SDL_PRIs64 "I64d" |
| #elif defined(PRIs64) |
| #define SDL_PRIs64 PRIs64 |
| #elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) |
| #define SDL_PRIs64 "ld" |
| #else |
| #define SDL_PRIs64 "lld" |
| #endif |
| #endif |
| #ifndef SDL_PRIu64 |
| #if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) |
| #define SDL_PRIu64 "I64u" |
| #elif defined(PRIu64) |
| #define SDL_PRIu64 PRIu64 |
| #elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) |
| #define SDL_PRIu64 "lu" |
| #else |
| #define SDL_PRIu64 "llu" |
| #endif |
| #endif |
| #ifndef SDL_PRIx64 |
| #if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) |
| #define SDL_PRIx64 "I64x" |
| #elif defined(PRIx64) |
| #define SDL_PRIx64 PRIx64 |
| #elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) |
| #define SDL_PRIx64 "lx" |
| #else |
| #define SDL_PRIx64 "llx" |
| #endif |
| #endif |
| #ifndef SDL_PRIX64 |
| #if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) |
| #define SDL_PRIX64 "I64X" |
| #elif defined(PRIX64) |
| #define SDL_PRIX64 PRIX64 |
| #elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) |
| #define SDL_PRIX64 "lX" |
| #else |
| #define SDL_PRIX64 "llX" |
| #endif |
| #endif |
| #ifndef SDL_PRIs32 |
| #ifdef PRId32 |
| #define SDL_PRIs32 PRId32 |
| #else |
| #define SDL_PRIs32 "d" |
| #endif |
| #endif |
| #ifndef SDL_PRIu32 |
| #ifdef PRIu32 |
| #define SDL_PRIu32 PRIu32 |
| #else |
| #define SDL_PRIu32 "u" |
| #endif |
| #endif |
| #ifndef SDL_PRIx32 |
| #ifdef PRIx32 |
| #define SDL_PRIx32 PRIx32 |
| #else |
| #define SDL_PRIx32 "x" |
| #endif |
| #endif |
| #ifndef SDL_PRIX32 |
| #ifdef PRIX32 |
| #define SDL_PRIX32 PRIX32 |
| #else |
| #define SDL_PRIX32 "X" |
| #endif |
| #endif |
| |
| /* Annotations to help code analysis tools */ |
| #ifdef SDL_DISABLE_ANALYZE_MACROS |
| #define SDL_IN_BYTECAP(x) |
| #define SDL_INOUT_Z_CAP(x) |
| #define SDL_OUT_Z_CAP(x) |
| #define SDL_OUT_CAP(x) |
| #define SDL_OUT_BYTECAP(x) |
| #define SDL_OUT_Z_BYTECAP(x) |
| #define SDL_PRINTF_FORMAT_STRING |
| #define SDL_SCANF_FORMAT_STRING |
| #define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) |
| #define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) |
| #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) |
| #define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) |
| #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) |
| #define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) |
| #else |
| #if defined(_MSC_VER) && (_MSC_VER >= 1600) /* VS 2010 and above */ |
| #include <sal.h> |
| |
| #define SDL_IN_BYTECAP(x) _In_bytecount_(x) |
| #define SDL_INOUT_Z_CAP(x) _Inout_z_cap_(x) |
| #define SDL_OUT_Z_CAP(x) _Out_z_cap_(x) |
| #define SDL_OUT_CAP(x) _Out_cap_(x) |
| #define SDL_OUT_BYTECAP(x) _Out_bytecap_(x) |
| #define SDL_OUT_Z_BYTECAP(x) _Out_z_bytecap_(x) |
| |
| #define SDL_PRINTF_FORMAT_STRING _Printf_format_string_ |
| #define SDL_SCANF_FORMAT_STRING _Scanf_format_string_impl_ |
| #else |
| #define SDL_IN_BYTECAP(x) |
| #define SDL_INOUT_Z_CAP(x) |
| #define SDL_OUT_Z_CAP(x) |
| #define SDL_OUT_CAP(x) |
| #define SDL_OUT_BYTECAP(x) |
| #define SDL_OUT_Z_BYTECAP(x) |
| #define SDL_PRINTF_FORMAT_STRING |
| #define SDL_SCANF_FORMAT_STRING |
| #endif |
| #ifdef __GNUC__ |
| #define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __printf__, fmtargnumber, fmtargnumber+1 ))) |
| #define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __printf__, fmtargnumber, 0 ))) |
| #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __scanf__, fmtargnumber, fmtargnumber+1 ))) |
| #define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __scanf__, fmtargnumber, 0 ))) |
| #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, fmtargnumber+1 ))) */ |
| #define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wscanf__, fmtargnumber, fmtargnumber+1 ))) */ |
| #else |
| #define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) |
| #define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) |
| #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) |
| #define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) |
| #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) |
| #define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) |
| #endif |
| #endif /* SDL_DISABLE_ANALYZE_MACROS */ |
| |
| #ifndef SDL_COMPILE_TIME_ASSERT |
| #if defined(__cplusplus) |
| /* Keep C++ case alone: Some versions of gcc will define __STDC_VERSION__ even when compiling in C++ mode. */ |
| #if (__cplusplus >= 201103L) |
| #define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) |
| #endif |
| #elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 202311L) |
| #define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) |
| #elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 201112L) |
| #define SDL_COMPILE_TIME_ASSERT(name, x) _Static_assert(x, #x) |
| #endif |
| #endif /* !SDL_COMPILE_TIME_ASSERT */ |
| |
| #ifndef SDL_COMPILE_TIME_ASSERT |
| /* universal, but may trigger -Wunused-local-typedefs */ |
| #define SDL_COMPILE_TIME_ASSERT(name, x) \ |
| typedef int SDL_compile_time_assert_ ## name[(x) * 2 - 1] |
| #endif |
| |
| /** \cond */ |
| #ifndef DOXYGEN_SHOULD_IGNORE_THIS |
| SDL_COMPILE_TIME_ASSERT(bool, sizeof(SDL_bool) == 1); |
| SDL_COMPILE_TIME_ASSERT(uint8, sizeof(Uint8) == 1); |
| SDL_COMPILE_TIME_ASSERT(sint8, sizeof(Sint8) == 1); |
| SDL_COMPILE_TIME_ASSERT(uint16, sizeof(Uint16) == 2); |
| SDL_COMPILE_TIME_ASSERT(sint16, sizeof(Sint16) == 2); |
| SDL_COMPILE_TIME_ASSERT(uint32, sizeof(Uint32) == 4); |
| SDL_COMPILE_TIME_ASSERT(sint32, sizeof(Sint32) == 4); |
| SDL_COMPILE_TIME_ASSERT(uint64, sizeof(Uint64) == 8); |
| SDL_COMPILE_TIME_ASSERT(sint64, sizeof(Sint64) == 8); |
| #endif /* DOXYGEN_SHOULD_IGNORE_THIS */ |
| /** \endcond */ |
| |
| /* Check to make sure enums are the size of ints, for structure packing. |
| For both Watcom C/C++ and Borland C/C++ the compiler option that makes |
| enums having the size of an int must be enabled. |
| This is "-b" for Borland C/C++ and "-ei" for Watcom C/C++ (v11). |
| */ |
| |
| /** \cond */ |
| #ifndef DOXYGEN_SHOULD_IGNORE_THIS |
| #if !defined(SDL_PLATFORM_VITA) && !defined(SDL_PLATFORM_3DS) |
| /* TODO: include/SDL_stdinc.h:390: error: size of array 'SDL_dummy_enum' is negative */ |
| typedef enum SDL_DUMMY_ENUM |
| { |
| DUMMY_ENUM_VALUE |
| } SDL_DUMMY_ENUM; |
| |
| SDL_COMPILE_TIME_ASSERT(enum, sizeof(SDL_DUMMY_ENUM) == sizeof(int)); |
| #endif |
| #endif /* DOXYGEN_SHOULD_IGNORE_THIS */ |
| /** \endcond */ |
| |
| #include <SDL3/SDL_begin_code.h> |
| /* Set up for C function definitions, even when using C++ */ |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| #ifndef SDL_DISABLE_ALLOCA |
| #define SDL_stack_alloc(type, count) (type*)alloca(sizeof(type)*(count)) |
| #define SDL_stack_free(data) |
| #else |
| #define SDL_stack_alloc(type, count) (type*)SDL_malloc(sizeof(type)*(count)) |
| #define SDL_stack_free(data) SDL_free(data) |
| #endif |
| |
| extern SDL_DECLSPEC SDL_MALLOC void * SDLCALL SDL_malloc(size_t size); |
| extern SDL_DECLSPEC SDL_MALLOC SDL_ALLOC_SIZE2(1, 2) void * SDLCALL SDL_calloc(size_t nmemb, size_t size); |
| extern SDL_DECLSPEC SDL_ALLOC_SIZE(2) void * SDLCALL SDL_realloc(void *mem, size_t size); |
| extern SDL_DECLSPEC void SDLCALL SDL_free(void *mem); |
| |
| typedef void *(SDLCALL *SDL_malloc_func)(size_t size); |
| typedef void *(SDLCALL *SDL_calloc_func)(size_t nmemb, size_t size); |
| typedef void *(SDLCALL *SDL_realloc_func)(void *mem, size_t size); |
| typedef void (SDLCALL *SDL_free_func)(void *mem); |
| |
| /** |
| * Get the original set of SDL memory functions. |
| * |
| * This is what SDL_malloc and friends will use by default, if there has been |
| * no call to SDL_SetMemoryFunctions. This is not necessarily using the C |
| * runtime's `malloc` functions behind the scenes! Different platforms and |
| * build configurations might do any number of unexpected things. |
| * |
| * \param malloc_func filled with malloc function. |
| * \param calloc_func filled with calloc function. |
| * \param realloc_func filled with realloc function. |
| * \param free_func filled with free function. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| extern SDL_DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func *malloc_func, |
| SDL_calloc_func *calloc_func, |
| SDL_realloc_func *realloc_func, |
| SDL_free_func *free_func); |
| |
| /** |
| * Get the current set of SDL memory functions. |
| * |
| * \param malloc_func filled with malloc function. |
| * \param calloc_func filled with calloc function. |
| * \param realloc_func filled with realloc function. |
| * \param free_func filled with free function. |
| * |
| * \threadsafety This does not hold a lock, so do not call this in the |
| * unlikely event of a background thread calling |
| * SDL_SetMemoryFunctions simultaneously. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_SetMemoryFunctions |
| * \sa SDL_GetOriginalMemoryFunctions |
| */ |
| extern SDL_DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_func, |
| SDL_calloc_func *calloc_func, |
| SDL_realloc_func *realloc_func, |
| SDL_free_func *free_func); |
| |
| /** |
| * Replace SDL's memory allocation functions with a custom set. |
| * |
| * It is not safe to call this function once any allocations have been made, |
| * as future calls to SDL_free will use the new allocator, even if they came |
| * from an SDL_malloc made with the old one! |
| * |
| * If used, usually this needs to be the first call made into the SDL library, |
| * if not the very first thing done at program startup time. |
| * |
| * \param malloc_func custom malloc function. |
| * \param calloc_func custom calloc function. |
| * \param realloc_func custom realloc function. |
| * \param free_func custom free function. |
| * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() |
| * for more information. |
| * |
| * \threadsafety It is safe to call this function from any thread, but one |
| * should not replace the memory functions once any allocations |
| * are made! |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_GetMemoryFunctions |
| * \sa SDL_GetOriginalMemoryFunctions |
| */ |
| extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func, |
| SDL_calloc_func calloc_func, |
| SDL_realloc_func realloc_func, |
| SDL_free_func free_func); |
| |
| /** |
| * Allocate memory aligned to a specific value. |
| * |
| * If `alignment` is less than the size of `void *`, then it will be increased |
| * to match that. |
| * |
| * The returned memory address will be a multiple of the alignment value, and |
| * the amount of memory allocated will be a multiple of the alignment value. |
| * |
| * The memory returned by this function must be freed with SDL_aligned_free(), |
| * and _not_ SDL_free. |
| * |
| * \param alignment the alignment requested. |
| * \param size the size to allocate. |
| * \returns a pointer to the aligned memory. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_aligned_free |
| */ |
| extern SDL_DECLSPEC SDL_MALLOC void * SDLCALL SDL_aligned_alloc(size_t alignment, size_t size); |
| |
| /** |
| * Free memory allocated by SDL_aligned_alloc(). |
| * |
| * The pointer is no longer valid after this call and cannot be dereferenced |
| * anymore. |
| * |
| * \param mem a pointer previously returned by SDL_aligned_alloc. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_aligned_alloc |
| */ |
| extern SDL_DECLSPEC void SDLCALL SDL_aligned_free(void *mem); |
| |
| /** |
| * Get the number of outstanding (unfreed) allocations. |
| * |
| * \returns the number of allocations. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_GetNumAllocations(void); |
| |
| extern SDL_DECLSPEC const char * SDLCALL SDL_getenv(const char *name); |
| extern SDL_DECLSPEC int SDLCALL SDL_setenv(const char *name, const char *value, int overwrite); |
| extern SDL_DECLSPEC int SDLCALL SDL_unsetenv(const char *name); |
| |
| typedef int (SDLCALL *SDL_CompareCallback)(const void *a, const void *b); |
| extern SDL_DECLSPEC void SDLCALL SDL_qsort(void *base, size_t nmemb, size_t size, SDL_CompareCallback compare); |
| extern SDL_DECLSPEC void * SDLCALL SDL_bsearch(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback compare); |
| |
| typedef int (SDLCALL *SDL_CompareCallback_r)(void *userdata, const void *a, const void *b); |
| extern SDL_DECLSPEC void SDLCALL SDL_qsort_r(void *base, size_t nmemb, size_t size, SDL_CompareCallback_r compare, void *userdata); |
| extern SDL_DECLSPEC void * SDLCALL SDL_bsearch_r(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback_r compare, void *userdata); |
| |
| extern SDL_DECLSPEC int SDLCALL SDL_abs(int x); |
| |
| /* NOTE: these double-evaluate their arguments, so you should never have side effects in the parameters */ |
| #define SDL_min(x, y) (((x) < (y)) ? (x) : (y)) |
| #define SDL_max(x, y) (((x) > (y)) ? (x) : (y)) |
| #define SDL_clamp(x, a, b) (((x) < (a)) ? (a) : (((x) > (b)) ? (b) : (x))) |
| |
| /** |
| * Query if a character is alphabetic (a letter). |
| * |
| * **WARNING**: Regardless of system locale, this will only treat ASCII values |
| * for English 'a-z' and 'A-Z' as true. |
| * |
| * \param x character value to check. |
| * \returns non-zero if x falls within the character class, zero otherwise. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_isalpha(int x); |
| |
| /** |
| * Query if a character is alphabetic (a letter) or a number. |
| * |
| * **WARNING**: Regardless of system locale, this will only treat ASCII values |
| * for English 'a-z', 'A-Z', and '0-9' as true. |
| * |
| * \param x character value to check. |
| * \returns non-zero if x falls within the character class, zero otherwise. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_isalnum(int x); |
| |
| /** |
| * Report if a character is blank (a space or tab). |
| * |
| * **WARNING**: Regardless of system locale, this will only treat ASCII values |
| * 0x20 (space) or 0x9 (tab) as true. |
| * |
| * \param x character value to check. |
| * \returns non-zero if x falls within the character class, zero otherwise. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_isblank(int x); |
| |
| /** |
| * Report if a character is a control character. |
| * |
| * **WARNING**: Regardless of system locale, this will only treat ASCII values |
| * 0 through 0x1F, and 0x7F, as true. |
| * |
| * \param x character value to check. |
| * \returns non-zero if x falls within the character class, zero otherwise. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_iscntrl(int x); |
| |
| /** |
| * Report if a character is a numeric digit. |
| * |
| * **WARNING**: Regardless of system locale, this will only treat ASCII values |
| * '0' (0x30) through '9' (0x39), as true. |
| * |
| * \param x character value to check. |
| * \returns non-zero if x falls within the character class, zero otherwise. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_isdigit(int x); |
| |
| /** |
| * Report if a character is a hexadecimal digit. |
| * |
| * **WARNING**: Regardless of system locale, this will only treat ASCII values |
| * 'A' through 'F', 'a' through 'f', and '0' through '9', as true. |
| * |
| * \param x character value to check. |
| * \returns non-zero if x falls within the character class, zero otherwise. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_isxdigit(int x); |
| |
| /** |
| * Report if a character is a punctuation mark. |
| * |
| * **WARNING**: Regardless of system locale, this is equivalent to |
| * `((SDL_isgraph(x)) && (!SDL_isalnum(x)))`. |
| * |
| * \param x character value to check. |
| * \returns non-zero if x falls within the character class, zero otherwise. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_isgraph |
| * \sa SDL_isalnum |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_ispunct(int x); |
| |
| /** |
| * Report if a character is whitespace. |
| * |
| * **WARNING**: Regardless of system locale, this will only treat the |
| * following ASCII values as true: |
| * |
| * - space (0x20) |
| * - tab (0x09) |
| * - newline (0x0A) |
| * - vertical tab (0x0B) |
| * - form feed (0x0C) |
| * - return (0x0D) |
| * |
| * \param x character value to check. |
| * \returns non-zero if x falls within the character class, zero otherwise. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_isspace(int x); |
| |
| /** |
| * Report if a character is upper case. |
| * |
| * **WARNING**: Regardless of system locale, this will only treat ASCII values |
| * 'A' through 'Z' as true. |
| * |
| * \param x character value to check. |
| * \returns non-zero if x falls within the character class, zero otherwise. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_isupper(int x); |
| |
| /** |
| * Report if a character is lower case. |
| * |
| * **WARNING**: Regardless of system locale, this will only treat ASCII values |
| * 'a' through 'z' as true. |
| * |
| * \param x character value to check. |
| * \returns non-zero if x falls within the character class, zero otherwise. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_islower(int x); |
| |
| /** |
| * Report if a character is "printable". |
| * |
| * Be advised that "printable" has a definition that goes back to text |
| * terminals from the dawn of computing, making this a sort of special case |
| * function that is not suitable for Unicode (or most any) text management. |
| * |
| * **WARNING**: Regardless of system locale, this will only treat ASCII values |
| * ' ' (0x20) through '~' (0x7E) as true. |
| * |
| * \param x character value to check. |
| * \returns non-zero if x falls within the character class, zero otherwise. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_isprint(int x); |
| |
| /** |
| * Report if a character is any "printable" except space. |
| * |
| * Be advised that "printable" has a definition that goes back to text |
| * terminals from the dawn of computing, making this a sort of special case |
| * function that is not suitable for Unicode (or most any) text management. |
| * |
| * **WARNING**: Regardless of system locale, this is equivalent to |
| * `(SDL_isprint(x)) && ((x) != ' ')`. |
| * |
| * \param x character value to check. |
| * \returns non-zero if x falls within the character class, zero otherwise. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_isprint |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_isgraph(int x); |
| |
| /** |
| * Convert low-ASCII English letters to uppercase. |
| * |
| * **WARNING**: Regardless of system locale, this will only convert ASCII |
| * values 'a' through 'z' to uppercase. |
| * |
| * This function returns the uppercase equivalent of `x`. If a character |
| * cannot be converted, or is already uppercase, this function returns `x`. |
| * |
| * \param x character value to check. |
| * \returns capitalized version of x, or x if no conversion available. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_toupper(int x); |
| |
| /** |
| * Convert low-ASCII English letters to lowercase. |
| * |
| * **WARNING**: Regardless of system locale, this will only convert ASCII |
| * values 'A' through 'Z' to lowercase. |
| * |
| * This function returns the lowercase equivalent of `x`. If a character |
| * cannot be converted, or is already lowercase, this function returns `x`. |
| * |
| * \param x character value to check. |
| * \returns lowercase version of x, or x if no conversion available. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_tolower(int x); |
| |
| extern SDL_DECLSPEC Uint16 SDLCALL SDL_crc16(Uint16 crc, const void *data, size_t len); |
| extern SDL_DECLSPEC Uint32 SDLCALL SDL_crc32(Uint32 crc, const void *data, size_t len); |
| |
| extern SDL_DECLSPEC void * SDLCALL SDL_memcpy(SDL_OUT_BYTECAP(len) void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len); |
| |
| /* Take advantage of compiler optimizations for memcpy */ |
| #ifndef SDL_SLOW_MEMCPY |
| #ifdef SDL_memcpy |
| #undef SDL_memcpy |
| #endif |
| #define SDL_memcpy memcpy |
| #endif |
| |
| #define SDL_copyp(dst, src) \ |
| { SDL_COMPILE_TIME_ASSERT(SDL_copyp, sizeof (*(dst)) == sizeof (*(src))); } \ |
| SDL_memcpy((dst), (src), sizeof(*(src))) |
| |
| extern SDL_DECLSPEC void * SDLCALL SDL_memmove(SDL_OUT_BYTECAP(len) void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len); |
| |
| /* Take advantage of compiler optimizations for memmove */ |
| #ifndef SDL_SLOW_MEMMOVE |
| #ifdef SDL_memmove |
| #undef SDL_memmove |
| #endif |
| #define SDL_memmove memmove |
| #endif |
| |
| extern SDL_DECLSPEC void * SDLCALL SDL_memset(SDL_OUT_BYTECAP(len) void *dst, int c, size_t len); |
| extern SDL_DECLSPEC void * SDLCALL SDL_memset4(void *dst, Uint32 val, size_t dwords); |
| |
| /* Take advantage of compiler optimizations for memset */ |
| #ifndef SDL_SLOW_MEMSET |
| #ifdef SDL_memset |
| #undef SDL_memset |
| #endif |
| #define SDL_memset memset |
| #endif |
| |
| #define SDL_zero(x) SDL_memset(&(x), 0, sizeof((x))) |
| #define SDL_zerop(x) SDL_memset((x), 0, sizeof(*(x))) |
| #define SDL_zeroa(x) SDL_memset((x), 0, sizeof((x))) |
| |
| extern SDL_DECLSPEC int SDLCALL SDL_memcmp(const void *s1, const void *s2, size_t len); |
| |
| extern SDL_DECLSPEC size_t SDLCALL SDL_wcslen(const wchar_t *wstr); |
| extern SDL_DECLSPEC size_t SDLCALL SDL_wcsnlen(const wchar_t *wstr, size_t maxlen); |
| extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcpy(SDL_OUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen); |
| extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcat(SDL_INOUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen); |
| extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsdup(const wchar_t *wstr); |
| extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsstr(const wchar_t *haystack, const wchar_t *needle); |
| extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsnstr(const wchar_t *haystack, const wchar_t *needle, size_t maxlen); |
| |
| /** |
| * Compare two null-terminated wide strings. |
| * |
| * This only compares wchar_t values until it hits a null-terminating |
| * character; it does not care if the string is well-formed UTF-16 (or UTF-32, |
| * depending on your platform's wchar_t size), or uses valid Unicode values. |
| * |
| * \param str1 the first string to compare. NULL is not permitted! |
| * \param str2 the second string to compare. NULL is not permitted! |
| * \returns less than zero if str1 is "less than" str2, greater than zero if |
| * str1 is "greater than" str2, and zero if the strings match |
| * exactly. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_wcscmp(const wchar_t *str1, const wchar_t *str2); |
| |
| /** |
| * Compare two wide strings up to a number of wchar_t values. |
| * |
| * This only compares wchar_t values; it does not care if the string is |
| * well-formed UTF-16 (or UTF-32, depending on your platform's wchar_t size), |
| * or uses valid Unicode values. |
| * |
| * Note that while this function is intended to be used with UTF-16 (or |
| * UTF-32, depending on your platform's definition of wchar_t), it is |
| * comparing raw wchar_t values and not Unicode codepoints: `maxlen` specifies |
| * a wchar_t limit! If the limit lands in the middle of a multi-wchar UTF-16 |
| * sequence, it will only compare a portion of the final character. |
| * |
| * `maxlen` specifies a maximum number of wchar_t to compare; if the strings |
| * match to this number of wide chars (or both have matched to a |
| * null-terminator character before this count), they will be considered |
| * equal. |
| * |
| * \param str1 the first string to compare. NULL is not permitted! |
| * \param str2 the second string to compare. NULL is not permitted! |
| * \param maxlen the maximum number of wchar_t to compare. |
| * \returns less than zero if str1 is "less than" str2, greater than zero if |
| * str1 is "greater than" str2, and zero if the strings match |
| * exactly. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_wcsncmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen); |
| |
| /** |
| * Compare two null-terminated wide strings, case-insensitively. |
| * |
| * This will work with Unicode strings, using a technique called |
| * "case-folding" to handle the vast majority of case-sensitive human |
| * languages regardless of system locale. It can deal with expanding values: a |
| * German Eszett character can compare against two ASCII 's' chars and be |
| * considered a match, for example. A notable exception: it does not handle |
| * the Turkish 'i' character; human language is complicated! |
| * |
| * Depending on your platform, "wchar_t" might be 2 bytes, and expected to be |
| * UTF-16 encoded (like Windows), or 4 bytes in UTF-32 format. Since this |
| * handles Unicode, it expects the string to be well-formed and not a |
| * null-terminated string of arbitrary bytes. Characters that are not valid |
| * UTF-16 (or UTF-32) are treated as Unicode character U+FFFD (REPLACEMENT |
| * CHARACTER), which is to say two strings of random bits may turn out to |
| * match if they convert to the same amount of replacement characters. |
| * |
| * \param str1 the first string to compare. NULL is not permitted! |
| * \param str2 the second string to compare. NULL is not permitted! |
| * \returns less than zero if str1 is "less than" str2, greater than zero if |
| * str1 is "greater than" str2, and zero if the strings match |
| * exactly. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_wcscasecmp(const wchar_t *str1, const wchar_t *str2); |
| |
| /** |
| * Compare two wide strings, case-insensitively, up to a number of wchar_t. |
| * |
| * This will work with Unicode strings, using a technique called |
| * "case-folding" to handle the vast majority of case-sensitive human |
| * languages regardless of system locale. It can deal with expanding values: a |
| * German Eszett character can compare against two ASCII 's' chars and be |
| * considered a match, for example. A notable exception: it does not handle |
| * the Turkish 'i' character; human language is complicated! |
| * |
| * Depending on your platform, "wchar_t" might be 2 bytes, and expected to be |
| * UTF-16 encoded (like Windows), or 4 bytes in UTF-32 format. Since this |
| * handles Unicode, it expects the string to be well-formed and not a |
| * null-terminated string of arbitrary bytes. Characters that are not valid |
| * UTF-16 (or UTF-32) are treated as Unicode character U+FFFD (REPLACEMENT |
| * CHARACTER), which is to say two strings of random bits may turn out to |
| * match if they convert to the same amount of replacement characters. |
| * |
| * Note that while this function might deal with variable-sized characters, |
| * `maxlen` specifies a _wchar_ limit! If the limit lands in the middle of a |
| * multi-byte UTF-16 sequence, it may convert a portion of the final character |
| * to one or more Unicode character U+FFFD (REPLACEMENT CHARACTER) so as not |
| * to overflow a buffer. |
| * |
| * `maxlen` specifies a maximum number of wchar_t values to compare; if the |
| * strings match to this number of wchar_t (or both have matched to a |
| * null-terminator character before this number of bytes), they will be |
| * considered equal. |
| * |
| * \param str1 the first string to compare. NULL is not permitted! |
| * \param str2 the second string to compare. NULL is not permitted! |
| * \param maxlen the maximum number of wchar_t values to compare. |
| * \returns less than zero if str1 is "less than" str2, greater than zero if |
| * str1 is "greater than" str2, and zero if the strings match |
| * exactly. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_wcsncasecmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen); |
| |
| extern SDL_DECLSPEC long SDLCALL SDL_wcstol(const wchar_t *str, wchar_t **endp, int base); |
| |
| extern SDL_DECLSPEC size_t SDLCALL SDL_strlen(const char *str); |
| extern SDL_DECLSPEC size_t SDLCALL SDL_strnlen(const char *str, size_t maxlen); |
| extern SDL_DECLSPEC size_t SDLCALL SDL_strlcpy(SDL_OUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); |
| extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlcpy(SDL_OUT_Z_CAP(dst_bytes) char *dst, const char *src, size_t dst_bytes); |
| extern SDL_DECLSPEC size_t SDLCALL SDL_strlcat(SDL_INOUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); |
| extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strdup(const char *str); |
| extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strndup(const char *str, size_t maxlen); |
| extern SDL_DECLSPEC char * SDLCALL SDL_strrev(char *str); |
| |
| /** |
| * Convert a string to uppercase. |
| * |
| * **WARNING**: Regardless of system locale, this will only convert ASCII |
| * values 'A' through 'Z' to uppercase. |
| * |
| * This function operates on a null-terminated string of bytes--even if it is |
| * malformed UTF-8!--and converts ASCII characters 'a' through 'z' to their |
| * uppercase equivalents in-place, returning the original `str` pointer. |
| * |
| * \param str the string to convert in-place. Can not be NULL. |
| * \returns the `str` pointer passed into this function. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_strlwr |
| */ |
| extern SDL_DECLSPEC char * SDLCALL SDL_strupr(char *str); |
| |
| /** |
| * Convert a string to lowercase. |
| * |
| * **WARNING**: Regardless of system locale, this will only convert ASCII |
| * values 'A' through 'Z' to lowercase. |
| * |
| * This function operates on a null-terminated string of bytes--even if it is |
| * malformed UTF-8!--and converts ASCII characters 'A' through 'Z' to their |
| * lowercase equivalents in-place, returning the original `str` pointer. |
| * |
| * \param str the string to convert in-place. Can not be NULL. |
| * \returns the `str` pointer passed into this function. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_strupr |
| */ |
| extern SDL_DECLSPEC char * SDLCALL SDL_strlwr(char *str); |
| |
| extern SDL_DECLSPEC char * SDLCALL SDL_strchr(const char *str, int c); |
| extern SDL_DECLSPEC char * SDLCALL SDL_strrchr(const char *str, int c); |
| extern SDL_DECLSPEC char * SDLCALL SDL_strstr(const char *haystack, const char *needle); |
| extern SDL_DECLSPEC char * SDLCALL SDL_strnstr(const char *haystack, const char *needle, size_t maxlen); |
| extern SDL_DECLSPEC char * SDLCALL SDL_strcasestr(const char *haystack, const char *needle); |
| extern SDL_DECLSPEC char * SDLCALL SDL_strtok_r(char *s1, const char *s2, char **saveptr); |
| extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlen(const char *str); |
| extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strnlen(const char *str, size_t bytes); |
| |
| extern SDL_DECLSPEC char * SDLCALL SDL_itoa(int value, char *str, int radix); |
| extern SDL_DECLSPEC char * SDLCALL SDL_uitoa(unsigned int value, char *str, int radix); |
| extern SDL_DECLSPEC char * SDLCALL SDL_ltoa(long value, char *str, int radix); |
| extern SDL_DECLSPEC char * SDLCALL SDL_ultoa(unsigned long value, char *str, int radix); |
| extern SDL_DECLSPEC char * SDLCALL SDL_lltoa(Sint64 value, char *str, int radix); |
| extern SDL_DECLSPEC char * SDLCALL SDL_ulltoa(Uint64 value, char *str, int radix); |
| |
| extern SDL_DECLSPEC int SDLCALL SDL_atoi(const char *str); |
| extern SDL_DECLSPEC double SDLCALL SDL_atof(const char *str); |
| extern SDL_DECLSPEC long SDLCALL SDL_strtol(const char *str, char **endp, int base); |
| extern SDL_DECLSPEC unsigned long SDLCALL SDL_strtoul(const char *str, char **endp, int base); |
| extern SDL_DECLSPEC Sint64 SDLCALL SDL_strtoll(const char *str, char **endp, int base); |
| extern SDL_DECLSPEC Uint64 SDLCALL SDL_strtoull(const char *str, char **endp, int base); |
| extern SDL_DECLSPEC double SDLCALL SDL_strtod(const char *str, char **endp); |
| |
| /** |
| * Compare two null-terminated UTF-8 strings. |
| * |
| * Due to the nature of UTF-8 encoding, this will work with Unicode strings, |
| * since effectively this function just compares bytes until it hits a |
| * null-terminating character. Also due to the nature of UTF-8, this can be |
| * used with SDL_qsort() to put strings in (roughly) alphabetical order. |
| * |
| * \param str1 the first string to compare. NULL is not permitted! |
| * \param str2 the second string to compare. NULL is not permitted! |
| * \returns less than zero if str1 is "less than" str2, greater than zero if |
| * str1 is "greater than" str2, and zero if the strings match |
| * exactly. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_strcmp(const char *str1, const char *str2); |
| |
| /** |
| * Compare two UTF-8 strings up to a number of bytes. |
| * |
| * Due to the nature of UTF-8 encoding, this will work with Unicode strings, |
| * since effectively this function just compares bytes until it hits a |
| * null-terminating character. Also due to the nature of UTF-8, this can be |
| * used with SDL_qsort() to put strings in (roughly) alphabetical order. |
| * |
| * Note that while this function is intended to be used with UTF-8, it is |
| * doing a bytewise comparison, and `maxlen` specifies a _byte_ limit! If the |
| * limit lands in the middle of a multi-byte UTF-8 sequence, it will only |
| * compare a portion of the final character. |
| * |
| * `maxlen` specifies a maximum number of bytes to compare; if the strings |
| * match to this number of bytes (or both have matched to a null-terminator |
| * character before this number of bytes), they will be considered equal. |
| * |
| * \param str1 the first string to compare. NULL is not permitted! |
| * \param str2 the second string to compare. NULL is not permitted! |
| * \param maxlen the maximum number of _bytes_ to compare. |
| * \returns less than zero if str1 is "less than" str2, greater than zero if |
| * str1 is "greater than" str2, and zero if the strings match |
| * exactly. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_strncmp(const char *str1, const char *str2, size_t maxlen); |
| |
| /** |
| * Compare two null-terminated UTF-8 strings, case-insensitively. |
| * |
| * This will work with Unicode strings, using a technique called |
| * "case-folding" to handle the vast majority of case-sensitive human |
| * languages regardless of system locale. It can deal with expanding values: a |
| * German Eszett character can compare against two ASCII 's' chars and be |
| * considered a match, for example. A notable exception: it does not handle |
| * the Turkish 'i' character; human language is complicated! |
| * |
| * Since this handles Unicode, it expects the string to be well-formed UTF-8 |
| * and not a null-terminated string of arbitrary bytes. Bytes that are not |
| * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT |
| * CHARACTER), which is to say two strings of random bits may turn out to |
| * match if they convert to the same amount of replacement characters. |
| * |
| * \param str1 the first string to compare. NULL is not permitted! |
| * \param str2 the second string to compare. NULL is not permitted! |
| * \returns less than zero if str1 is "less than" str2, greater than zero if |
| * str1 is "greater than" str2, and zero if the strings match |
| * exactly. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_strcasecmp(const char *str1, const char *str2); |
| |
| |
| /** |
| * Compare two UTF-8 strings, case-insensitively, up to a number of bytes. |
| * |
| * This will work with Unicode strings, using a technique called |
| * "case-folding" to handle the vast majority of case-sensitive human |
| * languages regardless of system locale. It can deal with expanding values: a |
| * German Eszett character can compare against two ASCII 's' chars and be |
| * considered a match, for example. A notable exception: it does not handle |
| * the Turkish 'i' character; human language is complicated! |
| * |
| * Since this handles Unicode, it expects the string to be well-formed UTF-8 |
| * and not a null-terminated string of arbitrary bytes. Bytes that are not |
| * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT |
| * CHARACTER), which is to say two strings of random bits may turn out to |
| * match if they convert to the same amount of replacement characters. |
| * |
| * Note that while this function is intended to be used with UTF-8, `maxlen` |
| * specifies a _byte_ limit! If the limit lands in the middle of a multi-byte |
| * UTF-8 sequence, it may convert a portion of the final character to one or |
| * more Unicode character U+FFFD (REPLACEMENT CHARACTER) so as not to overflow |
| * a buffer. |
| * |
| * `maxlen` specifies a maximum number of bytes to compare; if the strings |
| * match to this number of bytes (or both have matched to a null-terminator |
| * character before this number of bytes), they will be considered equal. |
| * |
| * \param str1 the first string to compare. NULL is not permitted! |
| * \param str2 the second string to compare. NULL is not permitted! |
| * \param maxlen the maximum number of bytes to compare. |
| * \returns less than zero if str1 is "less than" str2, greater than zero if |
| * str1 is "greater than" str2, and zero if the strings match |
| * exactly. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_strncasecmp(const char *str1, const char *str2, size_t maxlen); |
| |
| /** |
| * The Unicode REPLACEMENT CHARACTER codepoint. |
| * |
| * SDL_StepUTF8() reports this codepoint when it encounters a UTF-8 string |
| * with encoding errors. |
| * |
| * This tends to render as something like a question mark in most places. |
| * |
| * \since This macro is available since SDL 3.0.0. |
| * |
| * \sa SDL_StepUTF8 |
| */ |
| #define SDL_INVALID_UNICODE_CODEPOINT 0xFFFD |
| |
| /** |
| * Decode a UTF-8 string, one Unicode codepoint at a time. |
| * |
| * This will return the first Unicode codepoint in the UTF-8 encoded string in |
| * `*pstr`, and then advance `*pstr` past any consumed bytes before returning. |
| * |
| * It will not access more than `*pslen` bytes from the string. `*pslen` will |
| * be adjusted, as well, subtracting the number of bytes consumed. |
| * |
| * `pslen` is allowed to be NULL, in which case the string _must_ be |
| * NULL-terminated, as the function will blindly read until it sees the NULL |
| * char. |
| * |
| * if `*pslen` is zero, it assumes the end of string is reached and returns a |
| * zero codepoint regardless of the contents of the string buffer. |
| * |
| * If the resulting codepoint is zero (a NULL terminator), or `*pslen` is |
| * zero, it will not advance `*pstr` or `*pslen` at all. |
| * |
| * Generally this function is called in a loop until it returns zero, |
| * adjusting its parameters each iteration. |
| * |
| * If an invalid UTF-8 sequence is encountered, this function returns |
| * SDL_INVALID_UNICODE_CODEPOINT and advances the string/length by one byte |
| * (which is to say, a multibyte sequence might produce several |
| * SDL_INVALID_UNICODE_CODEPOINT returns before it syncs to the next valid |
| * UTF-8 sequence). |
| * |
| * Several things can generate invalid UTF-8 sequences, including overlong |
| * encodings, the use of UTF-16 surrogate values, and truncated data. Please |
| * refer to |
| * [RFC3629](https://www.ietf.org/rfc/rfc3629.txt) |
| * for details. |
| * |
| * \param pstr a pointer to a UTF-8 string pointer to be read and adjusted. |
| * \param pslen a pointer to the number of bytes in the string, to be read and |
| * adjusted. NULL is allowed. |
| * \returns the first Unicode codepoint in the string. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| extern SDL_DECLSPEC Uint32 SDLCALL SDL_StepUTF8(const char **pstr, size_t *pslen); |
| |
| /** |
| * Convert a single Unicode codepoint to UTF-8. |
| * |
| * The buffer pointed to by `dst` must be at least 4 bytes long, as this |
| * function may generate between 1 and 4 bytes of output. |
| * |
| * This function returns the first byte _after_ the newly-written UTF-8 |
| * sequence, which is useful for encoding multiple codepoints in a loop, or |
| * knowing where to write a NULL-terminator character to end the string (in |
| * either case, plan to have a buffer of _more_ than 4 bytes!). |
| * |
| * If `codepoint` is an invalid value (outside the Unicode range, or a UTF-16 |
| * surrogate value, etc), this will use U+FFFD (REPLACEMENT CHARACTER) for the |
| * codepoint instead, and not set an error. |
| * |
| * If `dst` is NULL, this returns NULL immediately without writing to the |
| * pointer and without setting an error. |
| * |
| * \param codepoint a Unicode codepoint to convert to UTF-8. |
| * \param dst the location to write the encoded UTF-8. Must point to at least |
| * 4 bytes! |
| * \returns the first byte past the newly-written UTF-8 sequence. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| extern SDL_DECLSPEC char * SDLCALL SDL_UCS4ToUTF8(Uint32 codepoint, char *dst); |
| |
| |
| extern SDL_DECLSPEC int SDLCALL SDL_sscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, ...) SDL_SCANF_VARARG_FUNC(2); |
| extern SDL_DECLSPEC int SDLCALL SDL_vsscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, va_list ap) SDL_SCANF_VARARG_FUNCV(2); |
| extern SDL_DECLSPEC int SDLCALL SDL_snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, ... ) SDL_PRINTF_VARARG_FUNC(3); |
| extern SDL_DECLSPEC int SDLCALL SDL_swprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, ... ) SDL_WPRINTF_VARARG_FUNC(3); |
| extern SDL_DECLSPEC int SDLCALL SDL_vsnprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3); |
| extern SDL_DECLSPEC int SDLCALL SDL_vswprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, const wchar_t *fmt, va_list ap); |
| extern SDL_DECLSPEC int SDLCALL SDL_asprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); |
| extern SDL_DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); |
| |
| /** |
| * Seeds the pseudo-random number generator. |
| * |
| * Reusing the seed number will cause SDL_rand_*() to repeat the same stream |
| * of 'random' numbers. |
| * |
| * \param seed the value to use as a random number seed, or 0 to use |
| * SDL_GetPerformanceCounter(). |
| * |
| * \threadsafety This should be called on the same thread that calls |
| * SDL_rand*() |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_rand |
| * \sa SDL_rand_bits |
| * \sa SDL_randf |
| */ |
| extern SDL_DECLSPEC void SDLCALL SDL_srand(Uint64 seed); |
| |
| /** |
| * Generate a pseudo-random number less than n for positive n |
| * |
| * The method used is faster and of better quality than `rand() % n`. Odds are |
| * roughly 99.9% even for n = 1 million. Evenness is better for smaller n, and |
| * much worse as n gets bigger. |
| * |
| * Example: to simulate a d6 use `SDL_rand(6) + 1` The +1 converts 0..5 to |
| * 1..6 |
| * |
| * If you want to generate a pseudo-random number in the full range of Sint32, |
| * you should use: (Sint32)SDL_rand_bits() |
| * |
| * If you want reproducible output, be sure to initialize with SDL_srand() |
| * first. |
| * |
| * There are no guarantees as to the quality of the random sequence produced, |
| * and this should not be used for security (cryptography, passwords) or where |
| * money is on the line (loot-boxes, casinos). There are many random number |
| * libraries available with different characteristics and you should pick one |
| * of those to meet any serious needs. |
| * |
| * \param n the number of possible outcomes. n must be positive. |
| * \returns a random value in the range of [0 .. n-1]. |
| * |
| * \threadsafety All calls should be made from a single thread |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_srand |
| * \sa SDL_randf |
| */ |
| extern SDL_DECLSPEC Sint32 SDLCALL SDL_rand(Sint32 n); |
| |
| /** |
| * Generate a uniform pseudo-random floating point number less than 1.0 |
| * |
| * If you want reproducible output, be sure to initialize with SDL_srand() |
| * first. |
| * |
| * There are no guarantees as to the quality of the random sequence produced, |
| * and this should not be used for security (cryptography, passwords) or where |
| * money is on the line (loot-boxes, casinos). There are many random number |
| * libraries available with different characteristics and you should pick one |
| * of those to meet any serious needs. |
| * |
| * \returns a random value in the range of [0.0, 1.0). |
| * |
| * \threadsafety All calls should be made from a single thread |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_srand |
| * \sa SDL_rand |
| */ |
| extern SDL_DECLSPEC float SDLCALL SDL_randf(void); |
| |
| /** |
| * Generate 32 pseudo-random bits. |
| * |
| * You likely want to use SDL_rand() to get a psuedo-random number instead. |
| * |
| * There are no guarantees as to the quality of the random sequence produced, |
| * and this should not be used for security (cryptography, passwords) or where |
| * money is on the line (loot-boxes, casinos). There are many random number |
| * libraries available with different characteristics and you should pick one |
| * of those to meet any serious needs. |
| * |
| * \returns a random value in the range of [0-SDL_MAX_UINT32]. |
| * |
| * \threadsafety All calls should be made from a single thread |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_rand |
| * \sa SDL_randf |
| * \sa SDL_srand |
| */ |
| extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits(void); |
| |
| /** |
| * Generate a pseudo-random number less than n for positive n |
| * |
| * The method used is faster and of better quality than `rand() % n`. Odds are |
| * roughly 99.9% even for n = 1 million. Evenness is better for smaller n, and |
| * much worse as n gets bigger. |
| * |
| * Example: to simulate a d6 use `SDL_rand_r(state, 6) + 1` The +1 converts |
| * 0..5 to 1..6 |
| * |
| * If you want to generate a pseudo-random number in the full range of Sint32, |
| * you should use: (Sint32)SDL_rand_bits_r(state) |
| * |
| * There are no guarantees as to the quality of the random sequence produced, |
| * and this should not be used for security (cryptography, passwords) or where |
| * money is on the line (loot-boxes, casinos). There are many random number |
| * libraries available with different characteristics and you should pick one |
| * of those to meet any serious needs. |
| * |
| * \param state a pointer to the current random number state, this may not be |
| * NULL. |
| * \param n the number of possible outcomes. n must be positive. |
| * \returns a random value in the range of [0 .. n-1]. |
| * |
| * \threadsafety This function is thread-safe, as long as the state pointer |
| * isn't shared between threads. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_rand |
| * \sa SDL_rand_bits_r |
| * \sa SDL_randf_r |
| */ |
| extern SDL_DECLSPEC Sint32 SDLCALL SDL_rand_r(Uint64 *state, Sint32 n); |
| |
| /** |
| * Generate a uniform pseudo-random floating point number less than 1.0 |
| * |
| * If you want reproducible output, be sure to initialize with SDL_srand() |
| * first. |
| * |
| * There are no guarantees as to the quality of the random sequence produced, |
| * and this should not be used for security (cryptography, passwords) or where |
| * money is on the line (loot-boxes, casinos). There are many random number |
| * libraries available with different characteristics and you should pick one |
| * of those to meet any serious needs. |
| * |
| * \param state a pointer to the current random number state, this may not be |
| * NULL. |
| * \returns a random value in the range of [0.0, 1.0). |
| * |
| * \threadsafety This function is thread-safe, as long as the state pointer |
| * isn't shared between threads. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_rand_bits_r |
| * \sa SDL_rand_r |
| * \sa SDL_randf |
| */ |
| extern SDL_DECLSPEC float SDLCALL SDL_randf_r(Uint64 *state); |
| |
| /** |
| * Generate 32 pseudo-random bits. |
| * |
| * You likely want to use SDL_rand_r() to get a psuedo-random number instead. |
| * |
| * There are no guarantees as to the quality of the random sequence produced, |
| * and this should not be used for security (cryptography, passwords) or where |
| * money is on the line (loot-boxes, casinos). There are many random number |
| * libraries available with different characteristics and you should pick one |
| * of those to meet any serious needs. |
| * |
| * \param state a pointer to the current random number state, this may not be |
| * NULL. |
| * \returns a random value in the range of [0-SDL_MAX_UINT32]. |
| * |
| * \threadsafety This function is thread-safe, as long as the state pointer |
| * isn't shared between threads. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_rand_r |
| * \sa SDL_randf_r |
| */ |
| extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits_r(Uint64 *state); |
| |
| |
| #ifndef SDL_PI_D |
| #define SDL_PI_D 3.141592653589793238462643383279502884 /**< pi (double) */ |
| #endif |
| #ifndef SDL_PI_F |
| #define SDL_PI_F 3.141592653589793238462643383279502884F /**< pi (float) */ |
| #endif |
| |
| /** |
| * Compute the arc cosine of `x`. |
| * |
| * The definition of `y = acos(x)` is `x = cos(y)`. |
| * |
| * Domain: `-1 <= x <= 1` |
| * |
| * Range: `0 <= y <= Pi` |
| * |
| * This function operates on double-precision floating point values, use |
| * SDL_acosf for single-precision floats. |
| * |
| * This function may use a different approximation across different versions, |
| * platforms and configurations. i.e, it can return a different value given |
| * the same input on different machines or operating systems, or if SDL is |
| * updated. |
| * |
| * \param x floating point value. |
| * \returns arc cosine of `x`, in radians. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_acosf |
| * \sa SDL_asin |
| * \sa SDL_cos |
| */ |
| extern SDL_DECLSPEC double SDLCALL SDL_acos(double x); |
| |
| /** |
| * Compute the arc cosine of `x`. |
| * |
| * The definition of `y = acos(x)` is `x = cos(y)`. |
| * |
| * Domain: `-1 <= x <= 1` |
| * |
| * Range: `0 <= y <= Pi` |
| * |
| * This function operates on single-precision floating point values, use |
| * SDL_acos for double-precision floats. |
| * |
| * This function may use a different approximation across different versions, |
| * platforms and configurations. i.e, it can return a different value given |
| * the same input on different machines or operating systems, or if SDL is |
| * updated. |
| * |
| * \param x floating point value. |
| * \returns arc cosine of `x`, in radians. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_acos |
| * \sa SDL_asinf |
| * \sa SDL_cosf |
| */ |
| extern SDL_DECLSPEC float SDLCALL SDL_acosf(float x); |
| |
| /** |
| * Compute the arc sine of `x`. |
| * |
| * The definition of `y = asin(x)` is `x = sin(y)`. |
| * |
| * Domain: `-1 <= x <= 1` |
| * |
| * Range: `-Pi/2 <= y <= Pi/2` |
| * |
| * This function operates on double-precision floating point values, use |
| * SDL_asinf for single-precision floats. |
| * |
| * This function may use a different approximation across different versions, |
| * platforms and configurations. i.e, it can return a different value given |
| * the same input on different machines or operating systems, or if SDL is |
| * updated. |
| * |
| * \param x floating point value. |
| * \returns arc sine of `x`, in radians. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_asinf |
| * \sa SDL_acos |
| * \sa SDL_sin |
| */ |
| extern SDL_DECLSPEC double SDLCALL SDL_asin(double x); |
| |
| /** |
| * Compute the arc sine of `x`. |
| * |
| * The definition of `y = asin(x)` is `x = sin(y)`. |
| * |
| * Domain: `-1 <= x <= 1` |
| * |
| * Range: `-Pi/2 <= y <= Pi/2` |
| * |
| * This function operates on single-precision floating point values, use |
| * SDL_asin for double-precision floats. |
| * |
| * This function may use a different approximation across different versions, |
| * platforms and configurations. i.e, it can return a different value given |
| * the same input on different machines or operating systems, or if SDL is |
| * updated. |
| * |
| * \param x floating point value. |
| * \returns arc sine of `x`, in radians. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_asin |
| * \sa SDL_acosf |
| * \sa SDL_sinf |
| */ |
| extern SDL_DECLSPEC float SDLCALL SDL_asinf(float x); |
| |
| /** |
| * Compute the arc tangent of `x`. |
| * |
| * The definition of `y = atan(x)` is `x = tan(y)`. |
| * |
| * Domain: `-INF <= x <= INF` |
| * |
| * Range: `-Pi/2 <= y <= Pi/2` |
| * |
| * This function operates on double-precision floating point values, use |
| * SDL_atanf for single-precision floats. |
| * |
| * To calculate the arc tangent of y / x, use SDL_atan2. |
| * |
| * This function may use a different approximation across different versions, |
| * platforms and configurations. i.e, it can return a different value given |
| * the same input on different machines or operating systems, or if SDL is |
| * updated. |
| * |
| * \param x floating point value. |
| * \returns arc tangent of of `x` in radians, or 0 if `x = 0`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_atanf |
| * \sa SDL_atan2 |
| * \sa SDL_tan |
| */ |
| extern SDL_DECLSPEC double SDLCALL SDL_atan(double x); |
| |
| /** |
| * Compute the arc tangent of `x`. |
| * |
| * The definition of `y = atan(x)` is `x = tan(y)`. |
| * |
| * Domain: `-INF <= x <= INF` |
| * |
| * Range: `-Pi/2 <= y <= Pi/2` |
| * |
| * This function operates on single-precision floating point values, use |
| * SDL_atan for dboule-precision floats. |
| * |
| * To calculate the arc tangent of y / x, use SDL_atan2f. |
| * |
| * This function may use a different approximation across different versions, |
| * platforms and configurations. i.e, it can return a different value given |
| * the same input on different machines or operating systems, or if SDL is |
| * updated. |
| * |
| * \param x floating point value. |
| * \returns arc tangent of of `x` in radians, or 0 if `x = 0`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_atan |
| * \sa SDL_atan2f |
| * \sa SDL_tanf |
| */ |
| extern SDL_DECLSPEC float SDLCALL SDL_atanf(float x); |
| |
| /** |
| * Compute the arc tangent of `y / x`, using the signs of x and y to adjust |
| * the result's quadrant. |
| * |
| * The definition of `z = atan2(x, y)` is `y = x tan(z)`, where the quadrant |
| * of z is determined based on the signs of x and y. |
| * |
| * Domain: `-INF <= x <= INF`, `-INF <= y <= INF` |
| * |
| * Range: `-Pi/2 <= y <= Pi/2` |
| * |
| * This function operates on double-precision floating point values, use |
| * SDL_atan2f for single-precision floats. |
| * |
| * To calculate the arc tangent of a single value, use SDL_atan. |
| * |
| * This function may use a different approximation across different versions, |
| * platforms and configurations. i.e, it can return a different value given |
| * the same input on different machines or operating systems, or if SDL is |
| * updated. |
| * |
| * \param y floating point value of the numerator (y coordinate). |
| * \param x floating point value of the denominator (x coordinate). |
| * \returns arc tangent of of `y / x` in radians, or, if `x = 0`, either |
| * `-Pi/2`, `0`, or `Pi/2`, depending on the value of `y`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_atan2f |
| * \sa SDL_atan |
| * \sa SDL_tan |
| */ |
| extern SDL_DECLSPEC double SDLCALL SDL_atan2(double y, double x); |
| |
| /** |
| * Compute the arc tangent of `y / x`, using the signs of x and y to adjust |
| * the result's quadrant. |
| * |
| * The definition of `z = atan2(x, y)` is `y = x tan(z)`, where the quadrant |
| * of z is determined based on the signs of x and y. |
| * |
| * Domain: `-INF <= x <= INF`, `-INF <= y <= INF` |
| * |
| * Range: `-Pi/2 <= y <= Pi/2` |
| * |
| * This function operates on single-precision floating point values, use |
| * SDL_atan2 for double-precision floats. |
| * |
| * To calculate the arc tangent of a single value, use SDL_atanf. |
| * |
| * This function may use a different approximation across different versions, |
| * platforms and configurations. i.e, it can return a different value given |
| * the same input on different machines or operating systems, or if SDL is |
| * updated. |
| * |
| * \param y floating point value of the numerator (y coordinate). |
| * \param x floating point value of the denominator (x coordinate). |
| * \returns arc tangent of of `y / x` in radians, or, if `x = 0`, either |
| * `-Pi/2`, `0`, or `Pi/2`, depending on the value of `y`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_atan2f |
| * \sa SDL_atan |
| * \sa SDL_tan |
| */ |
| extern SDL_DECLSPEC float SDLCALL SDL_atan2f(float y, float x); |
| |
| /** |
| * Compute the ceiling of `x`. |
| * |
| * The ceiling of `x` is the smallest integer `y` such that `y > x`, i.e `x` |
| * rounded up to the nearest integer. |
| * |
| * Domain: `-INF <= x <= INF` |
| * |
| * Range: `-INF <= y <= INF`, y integer |
| * |
| * This function operates on double-precision floating point values, use |
| * SDL_ceilf for single-precision floats. |
| * |
| * \param x floating point value. |
| * \returns the ceiling of `x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_ceilf |
| * \sa SDL_floor |
| * \sa SDL_trunc |
| * \sa SDL_round |
| * \sa SDL_lround |
| */ |
| extern SDL_DECLSPEC double SDLCALL SDL_ceil(double x); |
| |
| /** |
| * Compute the ceiling of `x`. |
| * |
| * The ceiling of `x` is the smallest integer `y` such that `y > x`, i.e `x` |
| * rounded up to the nearest integer. |
| * |
| * Domain: `-INF <= x <= INF` |
| * |
| * Range: `-INF <= y <= INF`, y integer |
| * |
| * This function operates on single-precision floating point values, use |
| * SDL_ceil for double-precision floats. |
| * |
| * \param x floating point value. |
| * \returns the ceiling of `x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_ceil |
| * \sa SDL_floorf |
| * \sa SDL_truncf |
| * \sa SDL_roundf |
| * \sa SDL_lroundf |
| */ |
| extern SDL_DECLSPEC float SDLCALL SDL_ceilf(float x); |
| |
| /** |
| * Copy the sign of one floating-point value to another. |
| * |
| * The definition of copysign is that ``copysign(x, y) = abs(x) * sign(y)``. |
| * |
| * Domain: `-INF <= x <= INF`, ``-INF <= y <= f`` |
| * |
| * Range: `-INF <= z <= INF` |
| * |
| * This function operates on double-precision floating point values, use |
| * SDL_copysignf for single-precision floats. |
| * |
| * \param x floating point value to use as the magnitude. |
| * \param y floating point value to use as the sign. |
| * \returns the floating point value with the sign of y and the magnitude of |
| * x. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_copysignf |
| * \sa SDL_fabs |
| */ |
| extern SDL_DECLSPEC double SDLCALL SDL_copysign(double x, double y); |
| |
| /** |
| * Copy the sign of one floating-point value to another. |
| * |
| * The definition of copysign is that ``copysign(x, y) = abs(x) * sign(y)``. |
| * |
| * Domain: `-INF <= x <= INF`, ``-INF <= y <= f`` |
| * |
| * Range: `-INF <= z <= INF` |
| * |
| * This function operates on single-precision floating point values, use |
| * SDL_copysign for double-precision floats. |
| * |
| * \param x floating point value to use as the magnitude. |
| * \param y floating point value to use as the sign. |
| * \returns the floating point value with the sign of y and the magnitude of |
| * x. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_copysignf |
| * \sa SDL_fabsf |
| */ |
| extern SDL_DECLSPEC float SDLCALL SDL_copysignf(float x, float y); |
| |
| /** |
| * Compute the cosine of `x`. |
| * |
| * Domain: `-INF <= x <= INF` |
| * |
| * Range: `-1 <= y <= 1` |
| * |
| * This function operates on double-precision floating point values, use |
| * SDL_cosf for single-precision floats. |
| * |
| * This function may use a different approximation across different versions, |
| * platforms and configurations. i.e, it can return a different value given |
| * the same input on different machines or operating systems, or if SDL is |
| * updated. |
| * |
| * \param x floating point value, in radians. |
| * \returns cosine of `x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_cosf |
| * \sa SDL_acos |
| * \sa SDL_sin |
| */ |
| extern SDL_DECLSPEC double SDLCALL SDL_cos(double x); |
| |
| /** |
| * Compute the cosine of `x`. |
| * |
| * Domain: `-INF <= x <= INF` |
| * |
| * Range: `-1 <= y <= 1` |
| * |
| * This function operates on single-precision floating point values, use |
| * SDL_cos for double-precision floats. |
| * |
| * This function may use a different approximation across different versions, |
| * platforms and configurations. i.e, it can return a different value given |
| * the same input on different machines or operating systems, or if SDL is |
| * updated. |
| * |
| * \param x floating point value, in radians. |
| * \returns cosine of `x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_cos |
| * \sa SDL_acosf |
| * \sa SDL_sinf |
| */ |
| extern SDL_DECLSPEC float SDLCALL SDL_cosf(float x); |
| |
| /** |
| * Compute the exponential of `x`. |
| * |
| * The definition of `y = exp(x)` is `y = e^x`, where `e` is the base of the |
| * natural logarithm. The inverse is the natural logarithm, SDL_log. |
| * |
| * Domain: `-INF <= x <= INF` |
| * |
| * Range: `0 <= y <= INF` |
| * |
| * The output will overflow if `exp(x)` is too large to be represented. |
| * |
| * This function operates on double-precision floating point values, use |
| * SDL_expf for single-precision floats. |
| * |
| * This function may use a different approximation across different versions, |
| * platforms and configurations. i.e, it can return a different value given |
| * the same input on different machines or operating systems, or if SDL is |
| * updated. |
| * |
| * \param x floating point value. |
| * \returns value of `e^x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_expf |
| * \sa SDL_log |
| */ |
| extern SDL_DECLSPEC double SDLCALL SDL_exp(double x); |
| |
| /** |
| * Compute the exponential of `x`. |
| * |
| * The definition of `y = exp(x)` is `y = e^x`, where `e` is the base of the |
| * natural logarithm. The inverse is the natural logarithm, SDL_logf. |
| * |
| * Domain: `-INF <= x <= INF` |
| * |
| * Range: `0 <= y <= INF` |
| * |
| * The output will overflow if `exp(x)` is too large to be represented. |
| * |
| * This function operates on single-precision floating point values, use |
| * SDL_exp for double-precision floats. |
| * |
| * This function may use a different approximation across different versions, |
| * platforms and configurations. i.e, it can return a different value given |
| * the same input on different machines or operating systems, or if SDL is |
| * updated. |
| * |
| * \param x floating point value. |
| * \returns value of `e^x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_exp |
| * \sa SDL_logf |
| */ |
| extern SDL_DECLSPEC float SDLCALL SDL_expf(float x); |
| |
| /** |
| * Compute the absolute value of `x` |
| * |
| * Domain: `-INF <= x <= INF` |
| * |
| * Range: `0 <= y <= INF` |
| * |
| * This function operates on double-precision floating point values, use |
| * SDL_copysignf for single-precision floats. |
| * |
| * \param x floating point value to use as the magnitude. |
| * \returns the absolute value of `x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_fabsf |
| */ |
| extern SDL_DECLSPEC double SDLCALL SDL_fabs(double x); |
| |
| /** |
| * Compute the absolute value of `x` |
| * |
| * Domain: `-INF <= x <= INF` |
| * |
| * Range: `0 <= y <= INF` |
| * |
| * This function operates on single-precision floating point values, use |
| * SDL_copysignf for double-precision floats. |
| * |
| * \param x floating point value to use as the magnitude. |
| * \returns the absolute value of `x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_fabs |
| */ |
| extern SDL_DECLSPEC float SDLCALL SDL_fabsf(float x); |
| |
| /** |
| * Compute the floor of `x`. |
| * |
| * The floor of `x` is the largest integer `y` such that `y > x`, i.e `x` |
| * rounded down to the nearest integer. |
| * |
| * Domain: `-INF <= x <= INF` |
| * |
| * Range: `-INF <= y <= INF`, y integer |
| * |
| * This function operates on double-precision floating point values, use |
| * SDL_floorf for single-precision floats. |
| * |
| * \param x floating point value. |
| * \returns the floor of `x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_floorf |
| * \sa SDL_ceil |
| * \sa SDL_trunc |
| * \sa SDL_round |
| * \sa SDL_lround |
| */ |
| extern SDL_DECLSPEC double SDLCALL SDL_floor(double x); |
| |
| /** |
| * Compute the floor of `x`. |
| * |
| * The floor of `x` is the largest integer `y` such that `y > x`, i.e `x` |
| * rounded down to the nearest integer. |
| * |
| * Domain: `-INF <= x <= INF` |
| * |
| * Range: `-INF <= y <= INF`, y integer |
| * |
| * This function operates on single-precision floating point values, use |
| * SDL_floorf for double-precision floats. |
| * |
| * \param x floating point value. |
| * \returns the floor of `x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_floor |
| * \sa SDL_ceilf |
| * \sa SDL_truncf |
| * \sa SDL_roundf |
| * \sa SDL_lroundf |
| */ |
| extern SDL_DECLSPEC float SDLCALL SDL_floorf(float x); |
| |
| /** |
| * Truncate `x` to an integer. |
| * |
| * Rounds `x` to the next closest integer to 0. This is equivalent to removing |
| * the fractional part of `x`, leaving only the integer part. |
| * |
| * Domain: `-INF <= x <= INF` |
| * |
| * Range: `-INF <= y <= INF`, y integer |
| * |
| * This function operates on double-precision floating point values, use |
| * SDL_truncf for single-precision floats. |
| * |
| * \param x floating point value. |
| * \returns `x` truncated to an integer. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_truncf |
| * \sa SDL_fmod |
| * \sa SDL_ceil |
| * \sa SDL_floor |
| * \sa SDL_round |
| * \sa SDL_lround |
| */ |
| extern SDL_DECLSPEC double SDLCALL SDL_trunc(double x); |
| |
| /** |
| * Truncate `x` to an integer. |
| * |
| * Rounds `x` to the next closest integer to 0. This is equivalent to removing |
| * the fractional part of `x`, leaving only the integer part. |
| * |
| * Domain: `-INF <= x <= INF` |
| * |
| * Range: `-INF <= y <= INF`, y integer |
| * |
| * This function operates on single-precision floating point values, use |
| * SDL_truncf for double-precision floats. |
| * |
| * \param x floating point value. |
| * \returns `x` truncated to an integer. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_trunc |
| * \sa SDL_fmodf |
| * \sa SDL_ceilf |
| * \sa SDL_floorf |
| * \sa SDL_roundf |
| * \sa SDL_lroundf |
| */ |
| extern SDL_DECLSPEC float SDLCALL SDL_truncf(float x); |
| |
| /** |
| * Return the floating-point remainder of `x / y` |
| * |
| * Divides `x` by `y`, and returns the remainder. |
| * |
| * Domain: `-INF <= x <= INF`, `-INF <= y <= INF`, `y != 0` |
| * |
| * Range: `-y <= z <= y` |
| * |
| * This function operates on double-precision floating point values, use |
| * SDL_fmodf for single-precision floats. |
| * |
| * \param x the numerator. |
| * \param y the denominator. Must not be 0. |
| * \returns the remainder of `x / y`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_fmodf |
| * \sa SDL_modf |
| * \sa SDL_trunc |
| * \sa SDL_ceil |
| * \sa SDL_floor |
| * \sa SDL_round |
| * \sa SDL_lround |
| */ |
| extern SDL_DECLSPEC double SDLCALL SDL_fmod(double x, double y); |
| |
| /** |
| * Return the floating-point remainder of `x / y` |
| * |
| * Divides `x` by `y`, and returns the remainder. |
| * |
| * Domain: `-INF <= x <= INF`, `-INF <= y <= INF`, `y != 0` |
| * |
| * Range: `-y <= z <= y` |
| * |
| * This function operates on single-precision floating point values, use |
| * SDL_fmod for single-precision floats. |
| * |
| * \param x the numerator. |
| * \param y the denominator. Must not be 0. |
| * \returns the remainder of `x / y`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_fmod |
| * \sa SDL_truncf |
| * \sa SDL_modff |
| * \sa SDL_ceilf |
| * \sa SDL_floorf |
| * \sa SDL_roundf |
| * \sa SDL_lroundf |
| */ |
| extern SDL_DECLSPEC float SDLCALL SDL_fmodf(float x, float y); |
| |
| /** |
| * Return whether the value is infinity. |
| * |
| * \param x double-precision floating point value. |
| * \returns non-zero if the value is infinity, 0 otherwise. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_isinff |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_isinf(double x); |
| |
| /** |
| * Return whether the value is infinity. |
| * |
| * \param x floating point value. |
| * \returns non-zero if the value is infinity, 0 otherwise. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_isinf |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_isinff(float x); |
| |
| /** |
| * Return whether the value is NaN. |
| * |
| * \param x double-precision floating point value. |
| * \returns non-zero if the value is NaN, 0 otherwise. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_isnanf |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_isnan(double x); |
| |
| /** |
| * Return whether the value is NaN. |
| * |
| * \param x floating point value. |
| * \returns non-zero if the value is NaN, 0 otherwise. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_isnan |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_isnanf(float x); |
| |
| /** |
| * Compute the natural logarithm of `x`. |
| * |
| * Domain: `0 < x <= INF` |
| * |
| * Range: `-INF <= y <= INF` |
| * |
| * It is an error for `x` to be less than or equal to 0. |
| * |
| * This function operates on double-precision floating point values, use |
| * SDL_logf for single-precision floats. |
| * |
| * This function may use a different approximation across different versions, |
| * platforms and configurations. i.e, it can return a different value given |
| * the same input on different machines or operating systems, or if SDL is |
| * updated. |
| * |
| * \param x floating point value. Must be greater than 0. |
| * \returns the natural logarithm of `x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_logf |
| * \sa SDL_log10 |
| * \sa SDL_exp |
| */ |
| extern SDL_DECLSPEC double SDLCALL SDL_log(double x); |
| |
| /** |
| * Compute the natural logarithm of `x`. |
| * |
| * Domain: `0 < x <= INF` |
| * |
| * Range: `-INF <= y <= INF` |
| * |
| * It is an error for `x` to be less than or equal to 0. |
| * |
| * This function operates on single-precision floating point values, use |
| * SDL_log for double-precision floats. |
| * |
| * This function may use a different approximation across different versions, |
| * platforms and configurations. i.e, it can return a different value given |
| * the same input on different machines or operating systems, or if SDL is |
| * updated. |
| * |
| * \param x floating point value. Must be greater than 0. |
| * \returns the natural logarithm of `x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_log |
| * \sa SDL_expf |
| */ |
| extern SDL_DECLSPEC float SDLCALL SDL_logf(float x); |
| |
| /** |
| * Compute the base-10 logarithm of `x`. |
| * |
| * Domain: `0 < x <= INF` |
| * |
| * Range: `-INF <= y <= INF` |
| * |
| * It is an error for `x` to be less than or equal to 0. |
| * |
| * This function operates on double-precision floating point values, use |
| * SDL_log10f for single-precision floats. |
| * |
| * This function may use a different approximation across different versions, |
| * platforms and configurations. i.e, it can return a different value given |
| * the same input on different machines or operating systems, or if SDL is |
| * updated. |
| * |
| * \param x floating point value. Must be greater than 0. |
| * \returns the logarithm of `x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_log10f |
| * \sa SDL_log |
| * \sa SDL_pow |
| */ |
| extern SDL_DECLSPEC double SDLCALL SDL_log10(double x); |
| |
| /** |
| * Compute the base-10 logarithm of `x`. |
| * |
| * Domain: `0 < x <= INF` |
| * |
| * Range: `-INF <= y <= INF` |
| * |
| * It is an error for `x` to be less than or equal to 0. |
| * |
| * This function operates on single-precision floating point values, use |
| * SDL_log10 for double-precision floats. |
| * |
| * This function may use a different approximation across different versions, |
| * platforms and configurations. i.e, it can return a different value given |
| * the same input on different machines or operating systems, or if SDL is |
| * updated. |
| * |
| * \param x floating point value. Must be greater than 0. |
| * \returns the logarithm of `x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_log10 |
| * \sa SDL_logf |
| * \sa SDL_powf |
| */ |
| extern SDL_DECLSPEC float SDLCALL SDL_log10f(float x); |
| |
| /** |
| * Split `x` into integer and fractional parts |
| * |
| * This function operates on double-precision floating point values, use |
| * SDL_modff for single-precision floats. |
| * |
| * \param x floating point value. |
| * \param y output pointer to store the integer part of `x`. |
| * \returns the fractional part of `x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_modff |
| * \sa SDL_trunc |
| * \sa SDL_fmod |
| */ |
| extern SDL_DECLSPEC double SDLCALL SDL_modf(double x, double *y); |
| |
| /** |
| * Split `x` into integer and fractional parts |
| * |
| * This function operates on single-precision floating point values, use |
| * SDL_modf for double-precision floats. |
| * |
| * \param x floating point value. |
| * \param y output pointer to store the integer part of `x`. |
| * \returns the fractional part of `x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_modf |
| * \sa SDL_truncf |
| * \sa SDL_fmodf |
| */ |
| extern SDL_DECLSPEC float SDLCALL SDL_modff(float x, float *y); |
| |
| /** |
| * Raise `x` to the power `y` |
| * |
| * Domain: `-INF <= x <= INF`, `-INF <= y <= INF` |
| * |
| * Range: `-INF <= z <= INF` |
| * |
| * If `y` is the base of the natural logarithm (e), consider using SDL_exp |
| * instead. |
| * |
| * This function operates on double-precision floating point values, use |
| * SDL_powf for single-precision floats. |
| * |
| * This function may use a different approximation across different versions, |
| * platforms and configurations. i.e, it can return a different value given |
| * the same input on different machines or operating systems, or if SDL is |
| * updated. |
| * |
| * \param x the base. |
| * \param y the exponent. |
| * \returns `x` raised to the power `y`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_powf |
| * \sa SDL_exp |
| * \sa SDL_log |
| */ |
| extern SDL_DECLSPEC double SDLCALL SDL_pow(double x, double y); |
| |
| /** |
| * Raise `x` to the power `y` |
| * |
| * Domain: `-INF <= x <= INF`, `-INF <= y <= INF` |
| * |
| * Range: `-INF <= z <= INF` |
| * |
| * If `y` is the base of the natural logarithm (e), consider using SDL_exp |
| * instead. |
| * |
| * This function operates on single-precision floating point values, use |
| * SDL_powf for double-precision floats. |
| * |
| * This function may use a different approximation across different versions, |
| * platforms and configurations. i.e, it can return a different value given |
| * the same input on different machines or operating systems, or if SDL is |
| * updated. |
| * |
| * \param x the base. |
| * \param y the exponent. |
| * \returns `x` raised to the power `y`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_pow |
| * \sa SDL_expf |
| * \sa SDL_logf |
| */ |
| extern SDL_DECLSPEC float SDLCALL SDL_powf(float x, float y); |
| |
| /** |
| * Round `x` to the nearest integer. |
| * |
| * Rounds `x` to the nearest integer. Values halfway between integers will be |
| * rounded away from zero. |
| * |
| * Domain: `-INF <= x <= INF` |
| * |
| * Range: `-INF <= y <= INF`, y integer |
| * |
| * This function operates on double-precision floating point values, use |
| * SDL_roundf for single-precision floats. To get the result as an integer |
| * type, use SDL_lround. |
| * |
| * \param x floating point value. |
| * \returns the nearest integer to `x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_roundf |
| * \sa SDL_lround |
| * \sa SDL_floor |
| * \sa SDL_ceil |
| * \sa SDL_trunc |
| */ |
| extern SDL_DECLSPEC double SDLCALL SDL_round(double x); |
| |
| /** |
| * Round `x` to the nearest integer. |
| * |
| * Rounds `x` to the nearest integer. Values halfway between integers will be |
| * rounded away from zero. |
| * |
| * Domain: `-INF <= x <= INF` |
| * |
| * Range: `-INF <= y <= INF`, y integer |
| * |
| * This function operates on double-precision floating point values, use |
| * SDL_roundf for single-precision floats. To get the result as an integer |
| * type, use SDL_lroundf. |
| * |
| * \param x floating point value. |
| * \returns the nearest integer to `x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_round |
| * \sa SDL_lroundf |
| * \sa SDL_floorf |
| * \sa SDL_ceilf |
| * \sa SDL_truncf |
| */ |
| extern SDL_DECLSPEC float SDLCALL SDL_roundf(float x); |
| |
| /** |
| * Round `x` to the nearest integer representable as a long |
| * |
| * Rounds `x` to the nearest integer. Values halfway between integers will be |
| * rounded away from zero. |
| * |
| * Domain: `-INF <= x <= INF` |
| * |
| * Range: `MIN_LONG <= y <= MAX_LONG` |
| * |
| * This function operates on double-precision floating point values, use |
| * SDL_lround for single-precision floats. To get the result as a |
| * floating-point type, use SDL_round. |
| * |
| * \param x floating point value. |
| * \returns the nearest integer to `x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_lroundf |
| * \sa SDL_round |
| * \sa SDL_floor |
| * \sa SDL_ceil |
| * \sa SDL_trunc |
| */ |
| extern SDL_DECLSPEC long SDLCALL SDL_lround(double x); |
| |
| /** |
| * Round `x` to the nearest integer representable as a long |
| * |
| * Rounds `x` to the nearest integer. Values halfway between integers will be |
| * rounded away from zero. |
| * |
| * Domain: `-INF <= x <= INF` |
| * |
| * Range: `MIN_LONG <= y <= MAX_LONG` |
| * |
| * This function operates on single-precision floating point values, use |
| * SDL_lroundf for double-precision floats. To get the result as a |
| * floating-point type, use SDL_roundf, |
| * |
| * \param x floating point value. |
| * \returns the nearest integer to `x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_lround |
| * \sa SDL_roundf |
| * \sa SDL_floorf |
| * \sa SDL_ceilf |
| * \sa SDL_truncf |
| */ |
| extern SDL_DECLSPEC long SDLCALL SDL_lroundf(float x); |
| |
| /** |
| * Scale `x` by an integer power of two. |
| * |
| * Multiplies `x` by the `n`th power of the floating point radix (always 2). |
| * |
| * Domain: `-INF <= x <= INF`, `n` integer |
| * |
| * Range: `-INF <= y <= INF` |
| * |
| * This function operates on double-precision floating point values, use |
| * SDL_scalbnf for single-precision floats. |
| * |
| * \param x floating point value to be scaled. |
| * \param n integer exponent. |
| * \returns `x * 2^n`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_scalbnf |
| * \sa SDL_pow |
| */ |
| extern SDL_DECLSPEC double SDLCALL SDL_scalbn(double x, int n); |
| |
| /** |
| * Scale `x` by an integer power of two. |
| * |
| * Multiplies `x` by the `n`th power of the floating point radix (always 2). |
| * |
| * Domain: `-INF <= x <= INF`, `n` integer |
| * |
| * Range: `-INF <= y <= INF` |
| * |
| * This function operates on single-precision floating point values, use |
| * SDL_scalbn for double-precision floats. |
| * |
| * \param x floating point value to be scaled. |
| * \param n integer exponent. |
| * \returns `x * 2^n`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_scalbn |
| * \sa SDL_powf |
| */ |
| extern SDL_DECLSPEC float SDLCALL SDL_scalbnf(float x, int n); |
| |
| /** |
| * Compute the sine of `x`. |
| * |
| * Domain: `-INF <= x <= INF` |
| * |
| * Range: `-1 <= y <= 1` |
| * |
| * This function operates on double-precision floating point values, use |
| * SDL_sinf for single-precision floats. |
| * |
| * This function may use a different approximation across different versions, |
| * platforms and configurations. i.e, it can return a different value given |
| * the same input on different machines or operating systems, or if SDL is |
| * updated. |
| * |
| * \param x floating point value, in radians. |
| * \returns sine of `x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_sinf |
| * \sa SDL_asin |
| * \sa SDL_cos |
| */ |
| extern SDL_DECLSPEC double SDLCALL SDL_sin(double x); |
| |
| /** |
| * Compute the sine of `x`. |
| * |
| * Domain: `-INF <= x <= INF` |
| * |
| * Range: `-1 <= y <= 1` |
| * |
| * This function operates on single-precision floating point values, use |
| * SDL_sinf for double-precision floats. |
| * |
| * This function may use a different approximation across different versions, |
| * platforms and configurations. i.e, it can return a different value given |
| * the same input on different machines or operating systems, or if SDL is |
| * updated. |
| * |
| * \param x floating point value, in radians. |
| * \returns sine of `x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_sin |
| * \sa SDL_asinf |
| * \sa SDL_cosf |
| */ |
| extern SDL_DECLSPEC float SDLCALL SDL_sinf(float x); |
| |
| /** |
| * Compute the square root of `x`. |
| * |
| * Domain: `0 <= x <= INF` |
| * |
| * Range: `0 <= y <= INF` |
| * |
| * This function operates on double-precision floating point values, use |
| * SDL_sqrtf for single-precision floats. |
| * |
| * This function may use a different approximation across different versions, |
| * platforms and configurations. i.e, it can return a different value given |
| * the same input on different machines or operating systems, or if SDL is |
| * updated. |
| * |
| * \param x floating point value. Must be greater than or equal to 0. |
| * \returns square root of `x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_sqrtf |
| */ |
| extern SDL_DECLSPEC double SDLCALL SDL_sqrt(double x); |
| |
| /** |
| * Compute the square root of `x`. |
| * |
| * Domain: `0 <= x <= INF` |
| * |
| * Range: `0 <= y <= INF` |
| * |
| * This function operates on single-precision floating point values, use |
| * SDL_sqrt for double-precision floats. |
| * |
| * This function may use a different approximation across different versions, |
| * platforms and configurations. i.e, it can return a different value given |
| * the same input on different machines or operating systems, or if SDL is |
| * updated. |
| * |
| * \param x floating point value. Must be greater than or equal to 0. |
| * \returns square root of `x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_sqrt |
| */ |
| extern SDL_DECLSPEC float SDLCALL SDL_sqrtf(float x); |
| |
| /** |
| * Compute the tangent of `x`. |
| * |
| * Domain: `-INF <= x <= INF` |
| * |
| * Range: `-INF <= y <= INF` |
| * |
| * This function operates on double-precision floating point values, use |
| * SDL_tanf for single-precision floats. |
| * |
| * This function may use a different approximation across different versions, |
| * platforms and configurations. i.e, it can return a different value given |
| * the same input on different machines or operating systems, or if SDL is |
| * updated. |
| * |
| * \param x floating point value, in radians. |
| * \returns tangent of `x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_tanf |
| * \sa SDL_sin |
| * \sa SDL_cos |
| * \sa SDL_atan |
| * \sa SDL_atan2 |
| */ |
| extern SDL_DECLSPEC double SDLCALL SDL_tan(double x); |
| |
| /** |
| * Compute the tangent of `x`. |
| * |
| * Domain: `-INF <= x <= INF` |
| * |
| * Range: `-INF <= y <= INF` |
| * |
| * This function operates on single-precision floating point values, use |
| * SDL_tanf for double-precision floats. |
| * |
| * This function may use a different approximation across different versions, |
| * platforms and configurations. i.e, it can return a different value given |
| * the same input on different machines or operating systems, or if SDL is |
| * updated. |
| * |
| * \param x floating point value, in radians. |
| * \returns tangent of `x`. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_tan |
| * \sa SDL_sinf |
| * \sa SDL_cosf |
| * \sa SDL_atanf |
| * \sa SDL_atan2f |
| */ |
| extern SDL_DECLSPEC float SDLCALL SDL_tanf(float x); |
| |
| /* The SDL implementation of iconv() returns these error codes */ |
| #define SDL_ICONV_ERROR (size_t)-1 |
| #define SDL_ICONV_E2BIG (size_t)-2 |
| #define SDL_ICONV_EILSEQ (size_t)-3 |
| #define SDL_ICONV_EINVAL (size_t)-4 |
| |
| typedef struct SDL_iconv_data_t *SDL_iconv_t; |
| |
| /** |
| * This function allocates a context for the specified character set |
| * conversion. |
| * |
| * \param tocode The target character encoding, must not be NULL. |
| * \param fromcode The source character encoding, must not be NULL. |
| * \returns a handle that must be freed with SDL_iconv_close, or |
| * SDL_ICONV_ERROR on failure. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_iconv |
| * \sa SDL_iconv_close |
| * \sa SDL_iconv_string |
| */ |
| extern SDL_DECLSPEC SDL_iconv_t SDLCALL SDL_iconv_open(const char *tocode, |
| const char *fromcode); |
| |
| /** |
| * This function frees a context used for character set conversion. |
| * |
| * \param cd The character set conversion handle. |
| * \returns 0 on success, or -1 on failure. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_iconv |
| * \sa SDL_iconv_open |
| * \sa SDL_iconv_string |
| */ |
| extern SDL_DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd); |
| |
| /** |
| * This function converts text between encodings, reading from and writing to |
| * a buffer. |
| * |
| * It returns the number of succesful conversions. |
| * |
| * \param cd The character set conversion context, created in |
| * SDL_iconv_open(). |
| * \param inbuf Address of variable that points to the first character of the |
| * input sequence. |
| * \param inbytesleft The number of bytes in the input buffer. |
| * \param outbuf Address of variable that points to the output buffer. |
| * \param outbytesleft The number of bytes in the output buffer. |
| * \returns the number of conversions on success, else SDL_ICONV_E2BIG is |
| * returned when the output buffer is too small, or SDL_ICONV_EILSEQ |
| * is returned when an invalid input sequence is encountered, or |
| * SDL_ICONV_EINVAL is returned when an incomplete input sequence is |
| * encountered. |
| * |
| * On exit: |
| * |
| * - inbuf will point to the beginning of the next multibyte |
| * sequence. On error, this is the location of the problematic |
| * input sequence. On success, this is the end of the input |
| * sequence. - inbytesleft will be set to the number of bytes left |
| * to convert, which will be 0 on success. - outbuf will point to |
| * the location where to store the next output byte. - outbytesleft |
| * will be set to the number of bytes left in the output buffer. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_iconv_open |
| * \sa SDL_iconv_close |
| * \sa SDL_iconv_string |
| */ |
| extern SDL_DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf, |
| size_t *inbytesleft, char **outbuf, |
| size_t *outbytesleft); |
| |
| /** |
| * Helper function to convert a string's encoding in one call. |
| * |
| * This function converts a buffer or string between encodings in one pass. |
| * |
| * The string does not need to be NULL-terminated; this function operates on |
| * the number of bytes specified in `inbytesleft` whether there is a NULL |
| * character anywhere in the buffer. |
| * |
| * The returned string is owned by the caller, and should be passed to |
| * SDL_free when no longer needed. |
| * |
| * \param tocode the character encoding of the output string. Examples are |
| * "UTF-8", "UCS-4", etc. |
| * \param fromcode the character encoding of data in `inbuf`. |
| * \param inbuf the string to convert to a different encoding. |
| * \param inbytesleft the size of the input string _in bytes_. |
| * \returns a new string, converted to the new encoding, or NULL on error. |
| * |
| * \since This function is available since SDL 3.0.0. |
| * |
| * \sa SDL_iconv_open |
| * \sa SDL_iconv_close |
| * \sa SDL_iconv |
| */ |
| extern SDL_DECLSPEC char * SDLCALL SDL_iconv_string(const char *tocode, |
| const char *fromcode, |
| const char *inbuf, |
| size_t inbytesleft); |
| |
| /* Some helper macros for common cases... */ |
| #define SDL_iconv_utf8_locale(S) SDL_iconv_string("", "UTF-8", S, SDL_strlen(S)+1) |
| #define SDL_iconv_utf8_ucs2(S) (Uint16 *)SDL_iconv_string("UCS-2", "UTF-8", S, SDL_strlen(S)+1) |
| #define SDL_iconv_utf8_ucs4(S) (Uint32 *)SDL_iconv_string("UCS-4", "UTF-8", S, SDL_strlen(S)+1) |
| #define SDL_iconv_wchar_utf8(S) SDL_iconv_string("UTF-8", "WCHAR_T", (char *)S, (SDL_wcslen(S)+1)*sizeof(wchar_t)) |
| |
| /* force builds using Clang's static analysis tools to use literal C runtime |
| here, since there are possibly tests that are ineffective otherwise. */ |
| #if defined(__clang_analyzer__) && !defined(SDL_DISABLE_ANALYZE_MACROS) |
| |
| /* The analyzer knows about strlcpy even when the system doesn't provide it */ |
| #if !defined(HAVE_STRLCPY) && !defined(strlcpy) |
| size_t strlcpy(char *dst, const char *src, size_t size); |
| #endif |
| |
| /* The analyzer knows about strlcat even when the system doesn't provide it */ |
| #if !defined(HAVE_STRLCAT) && !defined(strlcat) |
| size_t strlcat(char *dst, const char *src, size_t size); |
| #endif |
| |
| #if !defined(HAVE_WCSLCPY) && !defined(wcslcpy) |
| size_t wcslcpy(wchar_t *dst, const wchar_t *src, size_t size); |
| #endif |
| |
| #if !defined(HAVE_WCSLCAT) && !defined(wcslcat) |
| size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size); |
| #endif |
| |
| /* Starting LLVM 16, the analyser errors out if these functions do not have |
| their prototype defined (clang-diagnostic-implicit-function-declaration) */ |
| #include <stdio.h> |
| #include <stdlib.h> |
| #include <strings.h> |
| |
| #define SDL_malloc malloc |
| #define SDL_calloc calloc |
| #define SDL_realloc realloc |
| #define SDL_free free |
| #ifndef SDL_memcpy |
| #define SDL_memcpy memcpy |
| #endif |
| #ifndef SDL_memmove |
| #define SDL_memmove memmove |
| #endif |
| #ifndef SDL_memset |
| #define SDL_memset memset |
| #endif |
| #define SDL_memcmp memcmp |
| #define SDL_strlcpy strlcpy |
| #define SDL_strlcat strlcat |
| #define SDL_strlen strlen |
| #define SDL_wcslen wcslen |
| #define SDL_wcslcpy wcslcpy |
| #define SDL_wcslcat wcslcat |
| #define SDL_strdup strdup |
| #define SDL_wcsdup wcsdup |
| #define SDL_strchr strchr |
| #define SDL_strrchr strrchr |
| #define SDL_strstr strstr |
| #define SDL_wcsstr wcsstr |
| #define SDL_strtok_r strtok_r |
| #define SDL_strcmp strcmp |
| #define SDL_wcscmp wcscmp |
| #define SDL_strncmp strncmp |
| #define SDL_wcsncmp wcsncmp |
| #define SDL_strcasecmp strcasecmp |
| #define SDL_strncasecmp strncasecmp |
| #define SDL_sscanf sscanf |
| #define SDL_vsscanf vsscanf |
| #define SDL_snprintf snprintf |
| #define SDL_vsnprintf vsnprintf |
| #endif |
| |
| /** |
| * Multiply two integers, checking for overflow. |
| * |
| * If `a * b` would overflow, return -1. |
| * |
| * Otherwise store `a * b` via ret and return 0. |
| * |
| * \param a the multiplicand. |
| * \param b the multiplier. |
| * \param ret on non-overflow output, stores the multiplication result. May |
| * not be NULL. |
| * \returns -1 on overflow, 0 if result doesn't overflow. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| SDL_FORCE_INLINE int SDL_size_mul_overflow (size_t a, |
| size_t b, |
| size_t *ret) |
| { |
| if (a != 0 && b > SDL_SIZE_MAX / a) { |
| return -1; |
| } |
| *ret = a * b; |
| return 0; |
| } |
| |
| #ifndef SDL_WIKI_DOCUMENTATION_SECTION |
| #if SDL_HAS_BUILTIN(__builtin_mul_overflow) |
| /* This needs to be wrapped in an inline rather than being a direct #define, |
| * because __builtin_mul_overflow() is type-generic, but we want to be |
| * consistent about interpreting a and b as size_t. */ |
| SDL_FORCE_INLINE int SDL_size_mul_overflow_builtin (size_t a, |
| size_t b, |
| size_t *ret) |
| { |
| return __builtin_mul_overflow(a, b, ret) == 0 ? 0 : -1; |
| } |
| #define SDL_size_mul_overflow(a, b, ret) (SDL_size_mul_overflow_builtin(a, b, ret)) |
| #endif |
| #endif |
| |
| /** |
| * Add two integers, checking for overflow. |
| * |
| * If `a + b` would overflow, return -1. |
| * |
| * Otherwise store `a + b` via ret and return 0. |
| * |
| * \param a the first addend. |
| * \param b the second addend. |
| * \param ret on non-overflow output, stores the addition result. May not be |
| * NULL. |
| * \returns -1 on overflow, 0 if result doesn't overflow. |
| * |
| * \threadsafety It is safe to call this function from any thread. |
| * |
| * \since This function is available since SDL 3.0.0. |
| */ |
| SDL_FORCE_INLINE int SDL_size_add_overflow (size_t a, |
| size_t b, |
| size_t *ret) |
| { |
| if (b > SDL_SIZE_MAX - a) { |
| return -1; |
| } |
| *ret = a + b; |
| return 0; |
| } |
| |
| #ifndef SDL_WIKI_DOCUMENTATION_SECTION |
| #if SDL_HAS_BUILTIN(__builtin_add_overflow) |
| /* This needs to be wrapped in an inline rather than being a direct #define, |
| * the same as the call to __builtin_mul_overflow() above. */ |
| SDL_FORCE_INLINE int SDL_size_add_overflow_builtin (size_t a, |
| size_t b, |
| size_t *ret) |
| { |
| return __builtin_add_overflow(a, b, ret) == 0 ? 0 : -1; |
| } |
| #define SDL_size_add_overflow(a, b, ret) (SDL_size_add_overflow_builtin(a, b, ret)) |
| #endif |
| #endif |
| |
| /* This is a generic function pointer which should be cast to the type you expect */ |
| #ifdef SDL_FUNCTION_POINTER_IS_VOID_POINTER |
| typedef void *SDL_FunctionPointer; |
| #else |
| typedef void (*SDL_FunctionPointer)(void); |
| #endif |
| |
| /* Ends C function definitions when using C++ */ |
| #ifdef __cplusplus |
| } |
| #endif |
| #include <SDL3/SDL_close_code.h> |
| |
| #endif /* SDL_stdinc_h_ */ |
