eden-emu/SDL
15
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-06-02 01:47:41 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions3

include: Filled in all remaining missing documentation!

Browse source
This commit is contained in:
Ryan C. Gordon 2024-12-22 01:57:07 -05:00
parent 4d8f5758cf
commit f0fad41f2c
No known key found for this signature in database
GPG key ID: FA148B892AB48044
17 changed files with 1874 additions and 142 deletions

115
include/SDL3/SDL_assert.h
View file

@ -156,14 +156,36 @@ extern "C" {
#define SDL_TriggerBreakpoint()
#endif
#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 supports __func__ as a standard. */
#ifdef SDL_WIKI_DOCUMENTATION_SECTION
/**
* A macro that reports the current function being compiled.
*
* If SDL can't figure how the compiler reports this, it will use "???".
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_FUNCTION __FUNCTION__
#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 supports __func__ as a standard. */
# define SDL_FUNCTION __func__
#elif ((defined(__GNUC__) && (__GNUC__ >= 2)) || defined(_MSC_VER) || defined (__WATCOMC__))
# define SDL_FUNCTION __FUNCTION__
#else
# define SDL_FUNCTION "???"
#endif
/**
* A macro that reports the current file being compiled.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_FILE __FILE__
/**
* A macro that reports the current line number of the file being compiled.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_LINE __LINE__
/*
@ -181,14 +203,48 @@ This also solves the problem of...
disable assertions.
*/
#ifdef SDL_WIKI_DOCUMENTATION_SECTION
/**
* A macro for wrapping code in `do {} while (0);` without compiler warnings.
*
* Visual Studio with really aggressive warnings enabled needs this to avoid
* compiler complaints.
*
* the `do {} while (0);` trick is useful for wrapping code in a macro that
* may or may not be a single statement, to avoid various C language accidents.
*
* To use:
*
* ```c
* do { SomethingOnce(); } while (SDL_NULL_WHILE_LOOP_CONDITION (0));
* ```
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_NULL_WHILE_LOOP_CONDITION (0)
#elif defined _MSC_VER /* Avoid /W4 warnings. */
/* "while (0,0)" fools Microsoft's compiler's /W4 warning level into thinking
this condition isn't constant. And looks like an owl's face! */
#ifdef _MSC_VER /* stupid /W4 warnings. */
#define SDL_NULL_WHILE_LOOP_CONDITION (0,0)
#else
#define SDL_NULL_WHILE_LOOP_CONDITION (0)
#endif
/**
* The macro used when an assertion is disabled.
*
* This isn't for direct use by apps, but this is the code that is inserted
* when an SDL_assert is disabled (perhaps in a release build).
*
* The code does nothing, but wraps `condition` in a sizeof operator, which
* generates no code and has no side effects, but avoid compiler warnings
* about unused variables.
*
* \param condition the condition to assert (but not actually run here).
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_disabled_assert(condition) \
do { (void) sizeof ((condition)); } while (SDL_NULL_WHILE_LOOP_CONDITION)
@ -237,7 +293,7 @@ typedef struct SDL_AssertData
/**
* Never call this directly.
*
* Use the SDL_assert* macros instead.
* Use the SDL_assert macros instead.
*
* \param data assert data structure.
* \param func function name.
@ -253,23 +309,48 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
const char *func,
const char *file, int line) SDL_ANALYZER_NORETURN;
/* Define the trigger breakpoint call used in asserts */
#ifndef SDL_AssertBreakpoint
#if defined(ANDROID) && defined(assert)
/* Define this as empty in case assert() is defined as SDL_assert */
#define SDL_AssertBreakpoint()
#else
#ifdef SDL_WIKI_DOCUMENTATION_SECTION
/**
* The macro used when an assertion triggers a breakpoint.
*
* This isn't for direct use by apps; use SDL_assert or SDL_TriggerBreakpoint
* instead.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_AssertBreakpoint() SDL_TriggerBreakpoint()
#endif
#elif !defined(SDL_AssertBreakpoint)
# if defined(ANDROID) && defined(assert)
/* Define this as empty in case assert() is defined as SDL_assert */
# define SDL_AssertBreakpoint()
# else
# define SDL_AssertBreakpoint() SDL_TriggerBreakpoint()
# endif
#endif /* !SDL_AssertBreakpoint */
/* the do {} while(0) avoids dangling else problems:
if (x) SDL_assert(y); else blah();
... without the do/while, the "else" could attach to this macro's "if".
We try to handle just the minimum we need here in a macro...the loop,
the static vars, and break points. The heavy lifting is handled in
SDL_ReportAssertion(), in SDL_assert.c.
*/
/**
* The macro used when an assertion is enabled.
*
* This isn't for direct use by apps, but this is the code that is inserted
* when an SDL_assert is enabled.
*
* The `do {} while(0)` avoids dangling else problems:
*
* ```c
* if (x) SDL_assert(y); else blah();
* ```
*
* ... without the do/while, the "else" could attach to this macro's "if".
* We try to handle just the minimum we need here in a macro...the loop,
* the static vars, and break points. The heavy lifting is handled in
* SDL_ReportAssertion().
*
* \param condition the condition to assert.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_enabled_assert(condition) \
do { \
while ( !(condition) ) { \

82
include/SDL3/SDL_atomic.h
View file

@ -155,6 +155,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockSpinlock(SDL_SpinLock *lock);
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_CompilerBarrier() DoCompilerSpecificReadWriteBarrier()
#elif defined(_MSC_VER) && (_MSC_VER > 1200) && !defined(__clang__)
void _ReadWriteBarrier(void);
#pragma intrinsic(_ReadWriteBarrier)
@ -171,7 +172,49 @@ extern __inline void SDL_CompilerBarrier(void);
#endif
/**
* Insert a memory release barrier.
* Insert a memory release barrier (function version).
*
* Please refer to SDL_MemoryBarrierRelease for details. This is a function
* version, which might be useful if you need to use this functionality from
* a scripting language, etc. Also, some of the macro versions call this
* function behind the scenes, where more heavy lifting can happen inside
* of SDL. Generally, though, an app written in C/C++/etc should use the macro
* version, as it will be more efficient.
*
* \threadsafety Obviously this function is safe to use from any thread at any
* time, but if you find yourself needing this, you are probably
* dealing with some very sensitive code; be careful!
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_MemoryBarrierRelease
*/
extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierReleaseFunction(void);
/**
* Insert a memory acquire barrier (function version).
*
* Please refer to SDL_MemoryBarrierRelease for details. This is a function
* version, which might be useful if you need to use this functionality from
* a scripting language, etc. Also, some of the macro versions call this
* function behind the scenes, where more heavy lifting can happen inside
* of SDL. Generally, though, an app written in C/C++/etc should use the macro
* version, as it will be more efficient.
*
* \threadsafety Obviously this function is safe to use from any thread at any
* time, but if you find yourself needing this, you are probably
* dealing with some very sensitive code; be careful!
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_MemoryBarrierAcquire
*/
extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void);
#ifdef SDL_WIKI_DOCUMENTATION_SECTION
/**
* Insert a memory release barrier (macro version).
*
* Memory barriers are designed to prevent reads and writes from being
* reordered by the compiler and being seen out of order on multi-core CPUs.
@ -191,31 +234,47 @@ extern __inline void SDL_CompilerBarrier(void);
* For more information on these semantics, take a look at the blog post:
* http://preshing.com/20120913/acquire-and-release-semantics
*
* This is the macro version of this functionality; if possible, SDL will
* use compiler intrinsics or inline assembly, but some platforms might
* need to call the function version of this, SDL_MemoryBarrierReleaseFunction
* to do the heavy lifting. Apps that can use the macro should favor it over
* the function.
*
* \threadsafety Obviously this macro is safe to use from any thread at any
* time, but if you find yourself needing this, you are probably
* dealing with some very sensitive code; be careful!
*
* \since This function is available since SDL 3.1.3.
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_MemoryBarrierAcquire
* \sa SDL_MemoryBarrierReleaseFunction
*/
extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierReleaseFunction(void);
#define SDL_MemoryBarrierRelease() SDL_MemoryBarrierReleaseFunction()
/**
* Insert a memory acquire barrier.
* Insert a memory acquire barrier (macro version).
*
* Please refer to SDL_MemoryBarrierReleaseFunction for the details!
* Please see SDL_MemoryBarrierRelease for the details on what memory barriers
* are and when to use them.
*
* \threadsafety Obviously this function is safe to use from any thread at any
* This is the macro version of this functionality; if possible, SDL will
* use compiler intrinsics or inline assembly, but some platforms might
* need to call the function version of this,
* SDL_MemoryBarrierAcquireFunction, to do the heavy lifting. Apps that can
* use the macro should favor it over the function.
*
* \threadsafety Obviously this macro is safe to use from any thread at any
* time, but if you find yourself needing this, you are probably
* dealing with some very sensitive code; be careful!
*
* \since This function is available since SDL 3.1.3.
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_MemoryBarrierReleaseFunction
* \sa SDL_MemoryBarrierRelease
* \sa SDL_MemoryBarrierAcquireFunction
*/
extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void);
#define SDL_MemoryBarrierAcquire() SDL_MemoryBarrierAcquireFunction()
/* !!! FIXME: this should have documentation! */
#if defined(__GNUC__) && (defined(__powerpc__) || defined(__ppc__))
#elif defined(__GNUC__) && (defined(__powerpc__) || defined(__ppc__))
#define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("lwsync" : : : "memory")
#define SDL_MemoryBarrierAcquire() __asm__ __volatile__ ("lwsync" : : : "memory")
#elif defined(__GNUC__) && defined(__aarch64__)
@ -284,6 +343,7 @@ typedef void (*SDL_KernelMemoryBarrierFunc)();
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_CPUPauseInstruction() DoACPUPauseInACompilerAndArchitectureSpecificWay
#elif (defined(__GNUC__) || defined(__clang__)) && (defined(__i386__) || defined(__x86_64__))
#define SDL_CPUPauseInstruction() __asm__ __volatile__("pause\n") /* Some assemblers can't do REP NOP, so go with PAUSE. */
#elif (defined(__arm__) && defined(__ARM_ARCH) && __ARM_ARCH >= 7) || defined(__aarch64__)

69
include/SDL3/SDL_audio.h
View file

@ -141,14 +141,68 @@
extern "C" {
#endif
/* masks for different parts of SDL_AudioFormat. */
/**
* Mask of bits in an SDL_AudioFormat that contains the format bit size.
*
* Generally one should use SDL_AUDIO_BITSIZE instead of this macro directly.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_AUDIO_MASK_BITSIZE (0xFFu)
/**
* Mask of bits in an SDL_AudioFormat that contain the floating point flag.
*
* Generally one should use SDL_AUDIO_ISFLOAT instead of this macro directly.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_AUDIO_MASK_FLOAT (1u<<8)
/**
* Mask of bits in an SDL_AudioFormat that contain the bigendian flag.
*
* Generally one should use SDL_AUDIO_ISBIGENDIAN or SDL_AUDIO_ISLITTLEENDIAN
* instead of this macro directly.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_AUDIO_MASK_BIG_ENDIAN (1u<<12)
/**
* Mask of bits in an SDL_AudioFormat that contain the signed data flag.
*
* Generally one should use SDL_AUDIO_ISSIGNED instead of this macro directly.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_AUDIO_MASK_SIGNED (1u<<15)
#define SDL_DEFINE_AUDIO_FORMAT(signed, bigendian, float, size) \
(((Uint16)(signed) << 15) | ((Uint16)(bigendian) << 12) | ((Uint16)(float) << 8) | ((size) & SDL_AUDIO_MASK_BITSIZE))
/**
* Define an SDL_AudioFormat value.
*
* SDL does not support custom audio formats, so this macro is not of much
* use externally, but it can be illustrative as to what the various bits of
* an SDL_AudioFormat mean.
*
* For example, SDL_AUDIO_S32LE looks like this:
*
* ```c
* SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 32)
* ```
*
* \param signed 1 for signed data, 0 for unsigned data.
* \param bigendian 1 for bigendian data, 0 for littleendian data.
* \param flt 1 for floating point data, 0 for integer data.
* \param size number of bits per sample.
* \returns a format value in the style of SDL_AudioFormat.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_DEFINE_AUDIO_FORMAT(signed, bigendian, flt, size) \
(((Uint16)(signed) << 15) | ((Uint16)(bigendian) << 12) | ((Uint16)(flt) << 8) | ((size) & SDL_AUDIO_MASK_BITSIZE))
/**
* Audio format.
@ -399,14 +453,6 @@ typedef struct SDL_AudioStream SDL_AudioStream;
/* Function prototypes */
/**
* \name Driver discovery functions
*
* These functions return the list of built in audio drivers, in the
* order that they are normally initialized by default.
*/
/* @{ */
/**
* Use this function to get the number of built-in audio drivers.
*
@ -453,7 +499,6 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
* \sa SDL_GetNumAudioDrivers
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index);
/* @} */
/**
* Get the name of the current audio driver.

9
include/SDL3/SDL_begin_code.h
View file

@ -22,9 +22,12 @@
/* WIKI CATEGORY: BeginCode */
/**
* SDL_begin_code.h sets things up for C dynamic library function definitions,
* static inlined functions, and structures aligned at 4-byte alignment.
* If you don't like ugly C preprocessor code, don't look at this file. :)
* # CategoryBeginCode
*
* `SDL_begin_code.h` sets things up for C dynamic library function
* definitions, static inlined functions, and structures aligned at 4-byte
* alignment. If you don't like ugly C preprocessor code, don't look at this
* file. :)
*
* SDL's headers use this; applications generally should not include this
* header directly.

40
include/SDL3/SDL_gpu.h
View file

@ -1504,13 +1504,6 @@ typedef struct SDL_GPUTextureCreateInfo
SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */
} SDL_GPUTextureCreateInfo;
#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_R_FLOAT "SDL.gpu.createtexture.d3d12.clear.r"
#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_G_FLOAT "SDL.gpu.createtexture.d3d12.clear.g"
#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_B_FLOAT "SDL.gpu.createtexture.d3d12.clear.b"
#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_A_FLOAT "SDL.gpu.createtexture.d3d12.clear.a"
#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_DEPTH_FLOAT "SDL.gpu.createtexture.d3d12.clear.depth"
#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_STENCIL_UINT8 "SDL.gpu.createtexture.d3d12.clear.stencil"
/**
* A structure specifying the parameters of a buffer.
*
@ -2239,6 +2232,31 @@ extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader(
* implementation will automatically fall back to the highest available sample
* count.
*
* There are optional properties that can be provided through
* SDL_GPUTextureCreateInfo's `props`. These are the supported properties:
*
* - `SDL_PROP_PROCESS_CREATE_ARGS_POINTER`: an array of strings containing
* the program to run, any arguments, and a NULL pointer, e.g. const char
* *args[] = { "myprogram", "argument", NULL }. This is a required property.
* - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_R_FLOAT`: (Direct3D 12 only)
* if the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the
* texture to a color with this red intensity. Defaults to zero.
* - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_G_FLOAT`: (Direct3D 12 only)
* if the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the
* texture to a color with this green intensity. Defaults to zero.
* - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_B_FLOAT`: (Direct3D 12 only)
* if the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the
* texture to a color with this blue intensity. Defaults to zero.
* - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_A_FLOAT`: (Direct3D 12 only)
* if the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the
* texture to a color with this alpha intensity. Defaults to zero.
* - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_DEPTH_FLOAT`: (Direct3D 12 only)
* if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear
* the texture to a depth of this value. Defaults to zero.
* - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_STENCIL_UINT8`: (Direct3D 12 only)
* if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear
* the texture to a stencil of this value. Defaults to zero.
*
* \param device a GPU Context.
* \param createinfo a struct describing the state of the texture to create.
* \returns a texture object on success, or NULL on failure; call
@ -2261,6 +2279,14 @@ extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_CreateGPUTexture(
SDL_GPUDevice *device,
const SDL_GPUTextureCreateInfo *createinfo);
#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_R_FLOAT "SDL.gpu.createtexture.d3d12.clear.r"
#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_G_FLOAT "SDL.gpu.createtexture.d3d12.clear.g"
#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_B_FLOAT "SDL.gpu.createtexture.d3d12.clear.b"
#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_A_FLOAT "SDL.gpu.createtexture.d3d12.clear.a"
#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_DEPTH_FLOAT "SDL.gpu.createtexture.d3d12.clear.depth"
#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_STENCIL_UINT8 "SDL.gpu.createtexture.d3d12.clear.stencil"
/**
* Creates a buffer object to be used in graphics or compute workflows.
*

14
include/SDL3/SDL_haptic.h
View file

@ -299,12 +299,24 @@ typedef struct SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_LEFTRIGHT (1u<<11)
/**
* Reserved for future use
* Reserved for future use.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_HAPTIC_RESERVED1 (1u<<12)
/**
* Reserved for future use.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_HAPTIC_RESERVED2 (1u<<13)
/**
* Reserved for future use.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_HAPTIC_RESERVED3 (1u<<14)
/**

9
include/SDL3/SDL_hints.h
View file

@ -4021,6 +4021,15 @@ extern "C" {
* \since This hint is available since SDL 3.1.3.
*/
#define SDL_HINT_WINDOWS_INTRESOURCE_ICON "SDL_WINDOWS_INTRESOURCE_ICON"
/**
* A variable to specify custom icon resource id from RC file on Windows
* platform.
*
* This hint should be set before SDL is initialized.
*
* \since This hint is available since SDL 3.1.3.
*/
#define SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL "SDL_WINDOWS_INTRESOURCE_ICON_SMALL"
/**

60
include/SDL3/SDL_init.h
View file

@ -113,11 +113,71 @@ typedef enum SDL_AppResult
SDL_APP_FAILURE /**< Value that requests termination with error from the main callbacks. */
} SDL_AppResult;
/**
* Function pointer typedef for SDL_AppInit.
*
* These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind
* the scenes for apps using the optional main callbacks. Apps that want to use
* this should just implement SDL_AppInit directly.
*
* \param appstate a place where the app can optionally store a pointer for
* future use.
* \param argc the standard ANSI C main's argc; number of elements in `argv`.
* \param argv the standard ANSI C main's argv; array of command line
* arguments.
* \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to
* terminate with success, SDL_APP_CONTINUE to continue.
*
* \since This datatype is available since SDL 3.1.3.
*/
typedef SDL_AppResult (SDLCALL *SDL_AppInit_func)(void **appstate, int argc, char *argv[]);
/**
* Function pointer typedef for SDL_AppIterate.
*
* These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind
* the scenes for apps using the optional main callbacks. Apps that want to use
* this should just implement SDL_AppIterate directly.
*
* \param appstate an optional pointer, provided by the app in SDL_AppInit.
* \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to
* terminate with success, SDL_APP_CONTINUE to continue.
*
* \since This datatype is available since SDL 3.1.3.
*/
typedef SDL_AppResult (SDLCALL *SDL_AppIterate_func)(void *appstate);
/**
* Function pointer typedef for SDL_AppEvent.
*
* These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind
* the scenes for apps using the optional main callbacks. Apps that want to use
* this should just implement SDL_AppEvent directly.
*
* \param appstate an optional pointer, provided by the app in SDL_AppInit.
* \param event the new event for the app to examine.
* \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to
* terminate with success, SDL_APP_CONTINUE to continue.
*
* \since This datatype is available since SDL 3.1.3.
*/
typedef SDL_AppResult (SDLCALL *SDL_AppEvent_func)(void *appstate, SDL_Event *event);
/**
* Function pointer typedef for SDL_AppQuit.
*
* These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind
* the scenes for apps using the optional main callbacks. Apps that want to use
* this should just implement SDL_AppEvent directly.
*
* \param appstate an optional pointer, provided by the app in SDL_AppInit.
* \param result the result code that terminated the app (success or failure).
*
* \since This datatype is available since SDL 3.1.3.
*/
typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate, SDL_AppResult result);
/**
* Initialize the SDL library.
*

66
include/SDL3/SDL_intrin.h
View file

@ -267,7 +267,21 @@ _m_prefetch(void *__P)
#endif
#endif /* compiler version */
#if defined(__clang__) && defined(__has_attribute)
#ifdef SDL_WIKI_DOCUMENTATION_SECTION
/**
* A macro to decide if the compiler supports `__attribute__((target))`.
*
* Even though this is defined in SDL's public headers, it is generally not
* used directly by apps. Apps should probably just use SDL_TARGETING
* directly, instead.
*
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_TARGETING
*/
#define SDL_HAS_TARGET_ATTRIBS
#elif defined(__clang__) && defined(__has_attribute)
# if __has_attribute(target)
# define SDL_HAS_TARGET_ATTRIBS
# endif
@ -277,7 +291,55 @@ _m_prefetch(void *__P)
# define SDL_HAS_TARGET_ATTRIBS
#endif
#ifdef SDL_HAS_TARGET_ATTRIBS
#ifdef SDL_WIKI_DOCUMENTATION_SECTION
/**
* A macro to tag a function as targeting a specific CPU architecture.
*
* This is a hint to the compiler that a function should be built with support
* for a CPU instruction set that might be different than the rest of the
* program.
*
* The particulars of this are explained in the GCC documentation:
*
* https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-target-function-attribute
*
* An example of using this feature is to turn on SSE2 support for a specific
* function, even if the rest of the source code is not compiled to use SSE2
* code:
*
* ```c
* #ifdef SDL_SSE2_INTRINSICS
* static void SDL_TARGETING("sse2") DoSomethingWithSSE2(char *x) {
* ...use SSE2 intrinsic functions, etc...
* }
* #endif
*
* // later...
* #ifdef SDL_SSE2_INTRINSICS
* if (SDL_HasSSE2()) {
* DoSomethingWithSSE2(str);
* }
* #endif
* ```
*
* The application is, on a whole, built without SSE2 instructions, so it
* will run on Intel machines that don't support SSE2. But then at runtime,
* it checks if the system supports the instructions, and then calls into a
* function that uses SSE2 opcodes. The ifdefs make sure that this code isn't
* used on platforms that don't have SSE2 at all.
*
* On compilers without target support, this is defined to nothing.
*
* This symbol is used by SDL internally, but apps and other libraries are
* welcome to use it for their own interfaces as well.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_TARGETING(x) __attribute__((target(x)))
#elif defined(SDL_HAS_TARGET_ATTRIBS)
# define SDL_TARGETING(x) __attribute__((target(x)))
#else
# define SDL_TARGETING(x)

130
include/SDL3/SDL_main.h
View file

@ -28,9 +28,9 @@
* should look like this:
*
* ```c
* int main(int argc, char *argv[])
* {
* }
* int main(int argc, char *argv[])
* {
* }
* ```
*
* SDL will take care of platform specific details on how it gets called.
@ -55,6 +55,84 @@
#include <SDL3/SDL_error.h>
#include <SDL3/SDL_events.h>
#ifdef SDL_WIKI_DOCUMENTATION_SECTION
/**
* Inform SDL that the app is providing an entry point instead of SDL.
*
* SDL does not define this macro, but will check if it is defined when
* including `SDL_main.h`. If defined, SDL will expect the app to provide the
* proper entry point for the platform, and all the other magic details
* needed, like manually calling SDL_SetMainReady.
*
* Please see [README/main-functions](README/main-functions), (or
* docs/README-main-functions.md in the source tree) for a more detailed
* explanation.
*
* \since This macro is used by the headers since SDL 3.1.3.
*/
#define SDL_MAIN_HANDLED 1
/**
* Inform SDL to use the main callbacks instead of main.
*
* SDL does not define this macro, but will check if it is defined when
* including `SDL_main.h`. If defined, SDL will expect the app to provide
* several functions: SDL_AppInit, SDL_AppEvent, SDL_AppIterate, and
* SDL_AppQuit. The app should not provide a `main` function in this case, and
* doing so will likely cause the build to fail.
*
* Please see [README/main-functions](README/main-functions), (or
* docs/README-main-functions.md in the source tree) for a more detailed
* explanation.
*
* \since This macro is used by the headers since SDL 3.1.3.
*
* \sa SDL_AppInit
* \sa SDL_AppEvent
* \sa SDL_AppIterate
* \sa SDL_AppQuit
*/
#define SDL_MAIN_USE_CALLBACKS 1
/**
* Defined if the target platform offers a special mainline through SDL.
*
* This won't be defined otherwise. If defined, SDL's headers will redefine
* `main` to `SDL_main`.
*
* This macro is defined by `SDL_main.h`, which is not automatically included
* by `SDL.h`.
*
* Even if available, an app can define SDL_MAIN_HANDLED and provide their
* own, if they know what they're doing.
*
* This macro is used internally by SDL, and apps probably shouldn't rely on it.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_MAIN_AVAILABLE
/**
* Defined if the target platform _requires_ a special mainline through SDL.
*
* This won't be defined otherwise. If defined, SDL's headers will redefine
* `main` to `SDL_main`.
*
* This macro is defined by `SDL_main.h`, which is not automatically included
* by `SDL.h`.
*
* Even if required, an app can define SDL_MAIN_HANDLED and provide their
* own, if they know what they're doing.
*
* This macro is used internally by SDL, and apps probably shouldn't rely on it.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_MAIN_NEEDED
#endif
#ifndef SDL_MAIN_HANDLED
#if defined(SDL_PLATFORM_PRIVATE_MAIN)
/* Private platforms may have their own ideas about entry points. */
@ -144,7 +222,26 @@
#endif
#endif /* SDL_MAIN_HANDLED */
#ifdef SDL_MAIN_EXPORTED
#ifdef SDL_WIKI_DOCUMENTATION_SECTION
/**
* A macro to tag a main entry point function as exported.
*
* Most platforms don't need this, and the macro will be defined to nothing.
* Some, like Android, keep the entry points in a shared library and need to
* explicitly export the symbols.
*
* External code rarely needs this, and if it needs something, it's almost
* always SDL_DECLSPEC instead.
*
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_DECLSPEC
*/
#define SDLMAIN_DECLSPEC
#elif defined(SDL_MAIN_EXPORTED)
/* We need to export SDL_main so it can be launched from external code,
like SDLActivity.java on Android */
#define SDLMAIN_DECLSPEC SDL_DECLSPEC
@ -153,31 +250,6 @@
#define SDLMAIN_DECLSPEC
#endif /* SDL_MAIN_EXPORTED */
#ifdef SDL_WIKI_DOCUMENTATION_SECTION
/**
* Inform SDL to use the main callbacks instead of main.
*
* SDL does not define this macro, but will check if it is defined when
* including `SDL_main.h`. If defined, SDL will expect the app to provide
* several functions: SDL_AppInit, SDL_AppEvent, SDL_AppIterate, and
* SDL_AppQuit. The app should not provide a `main` function in this case, and
* doing so will likely cause the build to fail.
*
* Please see [README/main-functions](README/main-functions), (or
* docs/README-main-functions.md in the source tree) for a more detailed
* explanation.
*
* \since This macro is used by the headers since SDL 3.1.3.
*
* \sa SDL_AppInit
* \sa SDL_AppEvent
* \sa SDL_AppIterate
* \sa SDL_AppQuit
*/
#define SDL_MAIN_USE_CALLBACKS 1
#endif
#if defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE) || defined(SDL_MAIN_USE_CALLBACKS)
#define main SDL_main
#endif

158
include/SDL3/SDL_mutex.h
View file

@ -33,78 +33,224 @@
#include <SDL3/SDL_error.h>
#include <SDL3/SDL_thread.h>
/******************************************************************************/
/* Enable thread safety attributes only with clang.
#ifdef SDL_WIKI_DOCUMENTATION_SECTION
/**
* Enable thread safety attributes, only with clang.
*
* The attributes can be safely erased when compiling with other compilers.
*
* To enable analysis, set these environment variables before running cmake:
* export CC=clang
* export CFLAGS="-DSDL_THREAD_SAFETY_ANALYSIS -Wthread-safety"
*
* ```bash
* export CC=clang
* export CFLAGS="-DSDL_THREAD_SAFETY_ANALYSIS -Wthread-safety"
* ```
*/
#if defined(SDL_THREAD_SAFETY_ANALYSIS) && \
defined(__clang__) && (!defined(SWIG))
#define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x))
#elif defined(SDL_THREAD_SAFETY_ANALYSIS) && defined(__clang__) && (!defined(SWIG))
#define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x))
#else
#define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x) /* no-op */
#endif
/**
* Wrapper around Clang thread safety analysis annotations.
*
* Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_CAPABILITY(x) \
SDL_THREAD_ANNOTATION_ATTRIBUTE__(capability(x))
/**
* Wrapper around Clang thread safety analysis annotations.
*
* Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_SCOPED_CAPABILITY \
SDL_THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)
/**
* Wrapper around Clang thread safety analysis annotations.
*
* Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_GUARDED_BY(x) \
SDL_THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x))
/**
* Wrapper around Clang thread safety analysis annotations.
*
* Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_PT_GUARDED_BY(x) \
SDL_THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x))
/**
* Wrapper around Clang thread safety analysis annotations.
*
* Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_ACQUIRED_BEFORE(x) \
SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(x))
/**
* Wrapper around Clang thread safety analysis annotations.
*
* Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_ACQUIRED_AFTER(x) \
SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(x))
/**
* Wrapper around Clang thread safety analysis annotations.
*
* Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_REQUIRES(x) \
SDL_THREAD_ANNOTATION_ATTRIBUTE__(requires_capability(x))
/**
* Wrapper around Clang thread safety analysis annotations.
*
* Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_REQUIRES_SHARED(x) \
SDL_THREAD_ANNOTATION_ATTRIBUTE__(requires_shared_capability(x))
/**
* Wrapper around Clang thread safety analysis annotations.
*
* Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_ACQUIRE(x) \
SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquire_capability(x))
/**
* Wrapper around Clang thread safety analysis annotations.
*
* Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_ACQUIRE_SHARED(x) \
SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquire_shared_capability(x))
/**
* Wrapper around Clang thread safety analysis annotations.
*
* Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_RELEASE(x) \
SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_capability(x))
/**
* Wrapper around Clang thread safety analysis annotations.
*
* Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_RELEASE_SHARED(x) \
SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_shared_capability(x))
/**
* Wrapper around Clang thread safety analysis annotations.
*
* Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_RELEASE_GENERIC(x) \
SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_generic_capability(x))
/**
* Wrapper around Clang thread safety analysis annotations.
*
* Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_TRY_ACQUIRE(x, y) \
SDL_THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_capability(x, y))
/**
* Wrapper around Clang thread safety analysis annotations.
*
* Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_TRY_ACQUIRE_SHARED(x, y) \
SDL_THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_shared_capability(x, y))
/**
* Wrapper around Clang thread safety analysis annotations.
*
* Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_EXCLUDES(x) \
SDL_THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(x))
/**
* Wrapper around Clang thread safety analysis annotations.
*
* Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_ASSERT_CAPABILITY(x) \
SDL_THREAD_ANNOTATION_ATTRIBUTE__(assert_capability(x))
/**
* Wrapper around Clang thread safety analysis annotations.
*
* Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_ASSERT_SHARED_CAPABILITY(x) \
SDL_THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_capability(x))
/**
* Wrapper around Clang thread safety analysis annotations.
*
* Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_RETURN_CAPABILITY(x) \
SDL_THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))
/**
* Wrapper around Clang thread safety analysis annotations.
*
* Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_NO_THREAD_SAFETY_ANALYSIS \
SDL_THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis)

424
include/SDL3/SDL_pixels.h
View file

@ -213,25 +213,170 @@ typedef enum SDL_PackedLayout
SDL_PACKEDLAYOUT_1010102
} SDL_PackedLayout;
/**
* A macro for defining custom FourCC pixel formats.
*
* For example, defining SDL_PIXELFORMAT_YV12 looks like this:
*
* ```c
* SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2')
* ```
*
* \param A the first character of the FourCC code.
* \param B the second character of the FourCC code.
* \param C the third character of the FourCC code.
* \param D the fourth character of the FourCC code.
* \returns a format value in the style of SDL_PixelFormat.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_DEFINE_PIXELFOURCC(A, B, C, D) SDL_FOURCC(A, B, C, D)
/**
* A macro for defining custom non-FourCC pixel formats.
*
* For example, defining SDL_PIXELFORMAT_RGBA8888 looks like this:
*
* ```c
* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBA, SDL_PACKEDLAYOUT_8888, 32, 4)
* ```
*
* \param type the type of the new format, probably a SDL_PixelType value.
* \param order the order of the new format, probably a SDL_BitmapOrder, SDL_PackedOrder, or SDL_ArrayOrder value.
* \param layout the layout of the new format, probably an SDL_PackedLayout value or zero.
* \param bits the number of bits per pixel of the new format.
* \param bytes the number of bytes per pixel of the new format.
* \returns a format value in the style of SDL_PixelFormat.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes) \
((1 << 28) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \
((bits) << 8) | ((bytes) << 0))
#define SDL_PIXELFLAG(X) (((X) >> 28) & 0x0F)
#define SDL_PIXELTYPE(X) (((X) >> 24) & 0x0F)
#define SDL_PIXELORDER(X) (((X) >> 20) & 0x0F)
#define SDL_PIXELLAYOUT(X) (((X) >> 16) & 0x0F)
#define SDL_BITSPERPIXEL(X) \
(SDL_ISPIXELFORMAT_FOURCC(X) ? 0 : (((X) >> 8) & 0xFF))
#define SDL_BYTESPERPIXEL(X) \
(SDL_ISPIXELFORMAT_FOURCC(X) ? \
((((X) == SDL_PIXELFORMAT_YUY2) || \
((X) == SDL_PIXELFORMAT_UYVY) || \
((X) == SDL_PIXELFORMAT_YVYU) || \
((X) == SDL_PIXELFORMAT_P010)) ? 2 : 1) : (((X) >> 0) & 0xFF))
/**
* A macro to retrieve the flags of an SDL_PixelFormat.
*
* This macro is generally not needed directly by an app, which should use
* specific tests, like SDL_ISPIXELFORMAT_FOURCC, instead.
*
* \param format an SDL_PixelFormat to check.
* \returns the flags of `format`.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_PIXELFLAG(format) (((format) >> 28) & 0x0F)
/**
* A macro to retrieve the type of an SDL_PixelFormat.
*
* This is usually a value from the SDL_PixelType enumeration.
*
* \param format an SDL_PixelFormat to check.
* \returns the type of `format`.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_PIXELTYPE(format) (((format) >> 24) & 0x0F)
/**
* A macro to retrieve the order of an SDL_PixelFormat.
*
* This is usually a value from the SDL_BitmapOrder, SDL_PackedOrder, or
* SDL_ArrayOrder enumerations, depending on the format type.
*
* \param format an SDL_PixelFormat to check.
* \returns the order of `format`.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_PIXELORDER(format) (((format) >> 20) & 0x0F)
/**
* A macro to retrieve the layout of an SDL_PixelFormat.
*
* This is usually a value from the SDL_PackedLayout enumeration, or zero if
* a layout doesn't make sense for the format type.
*
* \param format an SDL_PixelFormat to check.
* \returns the layout of `format`.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_PIXELLAYOUT(format) (((format) >> 16) & 0x0F)
/**
* A macro to determine an SDL_PixelFormat's bits per pixel.
*
* Note that this macro double-evaluates its parameter, so do not use
* expressions with side-effects here.
*
* FourCC formats will report zero here, as it rarely makes sense to measure
* them per-pixel.
*
* \param format an SDL_PixelFormat to check.
* \returns the bits-per-pixel of `format`.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_BYTESPERPIXEL
*/
#define SDL_BITSPERPIXEL(format) \
(SDL_ISPIXELFORMAT_FOURCC(format) ? 0 : (((format) >> 8) & 0xFF))
/**
* A macro to determine an SDL_PixelFormat's bytes per pixel.
*
* Note that this macro double-evaluates its parameter, so do not use
* expressions with side-effects here.
*
* FourCC formats do their best here, but many of them don't have a meaningful
* measurement of bytes per pixel.
*
* \param format an SDL_PixelFormat to check.
* \returns the bytes-per-pixel of `format`.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_BITSPERPIXEL
*/
#define SDL_BYTESPERPIXEL(format) \
(SDL_ISPIXELFORMAT_FOURCC(format) ? \
((((format) == SDL_PIXELFORMAT_YUY2) || \
((format) == SDL_PIXELFORMAT_UYVY) || \
((format) == SDL_PIXELFORMAT_YVYU) || \
((format) == SDL_PIXELFORMAT_P010)) ? 2 : 1) : (((format) >> 0) & 0xFF))
/**
* A macro to determine if an SDL_PixelFormat is an indexed format.
*
* Note that this macro double-evaluates its parameter, so do not use
* expressions with side-effects here.
*
* \param format an SDL_PixelFormat to check.
* \returns true if the format is indexed, false otherwise.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_ISPIXELFORMAT_INDEXED(format) \
(!SDL_ISPIXELFORMAT_FOURCC(format) && \
((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX1) || \
@ -239,12 +384,38 @@ typedef enum SDL_PackedLayout
(SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX4) || \
(SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX8)))
/**
* A macro to determine if an SDL_PixelFormat is a packed format.
*
* Note that this macro double-evaluates its parameter, so do not use
* expressions with side-effects here.
*
* \param format an SDL_PixelFormat to check.
* \returns true if the format is packed, false otherwise.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_ISPIXELFORMAT_PACKED(format) \
(!SDL_ISPIXELFORMAT_FOURCC(format) && \
((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED8) || \
(SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED16) || \
(SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32)))
/**
* A macro to determine if an SDL_PixelFormat is an array format.
*
* Note that this macro double-evaluates its parameter, so do not use
* expressions with side-effects here.
*
* \param format an SDL_PixelFormat to check.
* \returns true if the format is an array, false otherwise.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_ISPIXELFORMAT_ARRAY(format) \
(!SDL_ISPIXELFORMAT_FOURCC(format) && \
((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU8) || \
@ -253,16 +424,55 @@ typedef enum SDL_PackedLayout
(SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \
(SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32)))
/**
* A macro to determine if an SDL_PixelFormat is a 10-bit format.
*
* Note that this macro double-evaluates its parameter, so do not use
* expressions with side-effects here.
*
* \param format an SDL_PixelFormat to check.
* \returns true if the format is 10-bit, false otherwise.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_ISPIXELFORMAT_10BIT(format) \
(!SDL_ISPIXELFORMAT_FOURCC(format) && \
((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32) && \
(SDL_PIXELLAYOUT(format) == SDL_PACKEDLAYOUT_2101010)))
/**
* A macro to determine if an SDL_PixelFormat is a floating point format.
*
* Note that this macro double-evaluates its parameter, so do not use
* expressions with side-effects here.
*
* \param format an SDL_PixelFormat to check.
* \returns true if the format is 10-bit, false otherwise.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_ISPIXELFORMAT_FLOAT(format) \
(!SDL_ISPIXELFORMAT_FOURCC(format) && \
((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \
(SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32)))
/**
* A macro to determine if an SDL_PixelFormat has an alpha channel.
*
* Note that this macro double-evaluates its parameter, so do not use
* expressions with side-effects here.
*
* \param format an SDL_PixelFormat to check.
* \returns true if the format has alpha, false otherwise.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_ISPIXELFORMAT_ALPHA(format) \
((SDL_ISPIXELFORMAT_PACKED(format) && \
((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \
@ -275,8 +485,23 @@ typedef enum SDL_PackedLayout
(SDL_PIXELORDER(format) == SDL_ARRAYORDER_ABGR) || \
(SDL_PIXELORDER(format) == SDL_ARRAYORDER_BGRA))))
/* The flag is set to 1 because 0x1? is not in the printable ASCII range */
#define SDL_ISPIXELFORMAT_FOURCC(format) \
/**
* A macro to determine if an SDL_PixelFormat is a "FourCC" format.
*
* This covers custom and other unusual formats.
*
* Note that this macro double-evaluates its parameter, so do not use
* expressions with side-effects here.
*
* \param format an SDL_PixelFormat to check.
* \returns true if the format has alpha, false otherwise.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_ISPIXELFORMAT_FOURCC(format) /* The flag is set to 1 because 0x1? is not in the printable ASCII range */ \
((format) && (SDL_PIXELFLAG(format) != 1))
/* Note: If you modify this enum, update SDL_GetPixelFormatName() */
@ -591,22 +816,171 @@ typedef enum SDL_ChromaLocation
/* Colorspace definition */
/**
* A macro for defining custom SDL_Colorspace formats.
*
* For example, defining SDL_COLORSPACE_SRGB looks like this:
*
* ```c
* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_RGB,
* SDL_COLOR_RANGE_FULL,
* SDL_COLOR_PRIMARIES_BT709,
* SDL_TRANSFER_CHARACTERISTICS_SRGB,
* SDL_MATRIX_COEFFICIENTS_IDENTITY,
* SDL_CHROMA_LOCATION_NONE)
* ```
*
* \param type the type of the new format, probably an SDL_ColorType value.
* \param range the range of the new format, probably a SDL_ColorRange value.
* \param primaries the primaries of the new format, probably an SDL_ColorPrimaries value.
* \param transfer the transfer characteristics of the new format, probably an SDL_TransferCharacteristics value.
* \param matrix the matrix coefficients of the new format, probably an SDL_MatrixCoefficients value.
* \param chroma the chroma sample location of the new format, probably an SDL_ChromaLocation value.
* \returns a format value in the style of SDL_Colorspace.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_DEFINE_COLORSPACE(type, range, primaries, transfer, matrix, chroma) \
(((Uint32)(type) << 28) | ((Uint32)(range) << 24) | ((Uint32)(chroma) << 20) | \
((Uint32)(primaries) << 10) | ((Uint32)(transfer) << 5) | ((Uint32)(matrix) << 0))
#define SDL_COLORSPACETYPE(X) (SDL_ColorType)(((X) >> 28) & 0x0F)
#define SDL_COLORSPACERANGE(X) (SDL_ColorRange)(((X) >> 24) & 0x0F)
#define SDL_COLORSPACECHROMA(X) (SDL_ChromaLocation)(((X) >> 20) & 0x0F)
#define SDL_COLORSPACEPRIMARIES(X) (SDL_ColorPrimaries)(((X) >> 10) & 0x1F)
#define SDL_COLORSPACETRANSFER(X) (SDL_TransferCharacteristics)(((X) >> 5) & 0x1F)
#define SDL_COLORSPACEMATRIX(X) (SDL_MatrixCoefficients)((X) & 0x1F)
/**
* A macro to retrieve the type of an SDL_Colorspace.
*
* \param cspace an SDL_Colorspace to check.
* \returns the SDL_ColorType for `cspace`.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_COLORSPACETYPE(cspace) (SDL_ColorType)(((cspace) >> 28) & 0x0F)
#define SDL_ISCOLORSPACE_MATRIX_BT601(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT601 || SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT470BG)
#define SDL_ISCOLORSPACE_MATRIX_BT709(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT709)
#define SDL_ISCOLORSPACE_MATRIX_BT2020_NCL(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT2020_NCL)
#define SDL_ISCOLORSPACE_LIMITED_RANGE(X) (SDL_COLORSPACERANGE(X) != SDL_COLOR_RANGE_FULL)
#define SDL_ISCOLORSPACE_FULL_RANGE(X) (SDL_COLORSPACERANGE(X) == SDL_COLOR_RANGE_FULL)
/**
* A macro to retrieve the range of an SDL_Colorspace.
*
* \param cspace an SDL_Colorspace to check.
* \returns the SDL_ColorRange of `cspace`.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_COLORSPACERANGE(cspace) (SDL_ColorRange)(((cspace) >> 24) & 0x0F)
/**
* A macro to retrieve the chroma sample location of an SDL_Colorspace.
*
* \param cspace an SDL_Colorspace to check.
* \returns the SDL_ChromaLocation of `cspace`.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_COLORSPACECHROMA(cspace) (SDL_ChromaLocation)(((cspace) >> 20) & 0x0F)
/**
* A macro to retrieve the primaries of an SDL_Colorspace.
*
* \param cspace an SDL_Colorspace to check.
* \returns the SDL_ColorPrimaries of `cspace`.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_COLORSPACEPRIMARIES(cspace) (SDL_ColorPrimaries)(((cspace) >> 10) & 0x1F)
/**
* A macro to retrieve the transfer characteristics of an SDL_Colorspace.
*
* \param cspace an SDL_Colorspace to check.
* \returns the SDL_TransferCharacteristics of `cspace`.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_COLORSPACETRANSFER(cspace) (SDL_TransferCharacteristics)(((cspace) >> 5) & 0x1F)
/**
* A macro to retrieve the matrix coefficients of an SDL_Colorspace.
*
* \param cspace an SDL_Colorspace to check.
* \returns the SDL_MatrixCoefficients of `cspace`.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_COLORSPACEMATRIX(cspace) (SDL_MatrixCoefficients)((cspace) & 0x1F)
/**
* A macro to determine if an SDL_Colorspace uses BT601 (or BT470BG) matrix coefficients.
*
* Note that this macro double-evaluates its parameter, so do not use
* expressions with side-effects here.
*
* \param cspace an SDL_Colorspace to check.
* \returns true if BT601 or BT470BG, false otherwise.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_ISCOLORSPACE_MATRIX_BT601(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT601 || SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT470BG)
/**
* A macro to determine if an SDL_Colorspace uses BT709 matrix coefficients.
*
* \param cspace an SDL_Colorspace to check.
* \returns true if BT709, false otherwise.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_ISCOLORSPACE_MATRIX_BT709(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT709)
/**
* A macro to determine if an SDL_Colorspace uses BT2020_NCL matrix coefficients.
*
* \param cspace an SDL_Colorspace to check.
* \returns true if BT709, false otherwise.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_ISCOLORSPACE_MATRIX_BT2020_NCL(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT2020_NCL)
/**
* A macro to determine if an SDL_Colorspace has a limited range.
*
* \param cspace an SDL_Colorspace to check.
* \returns true if limited range, false otherwise.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_ISCOLORSPACE_LIMITED_RANGE(cspace) (SDL_COLORSPACERANGE(cspace) != SDL_COLOR_RANGE_FULL)
/**
* A macro to determine if an SDL_Colorspace has a full range.
*
* \param cspace an SDL_Colorspace to check.
* \returns true if full range, false otherwise.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_ISCOLORSPACE_FULL_RANGE(cspace) (SDL_COLORSPACERANGE(cspace) == SDL_COLOR_RANGE_FULL)
/**
* Colorspace definitions.

10
include/SDL3/SDL_platform_defines.h
View file

@ -357,7 +357,15 @@
#define WINAPI_FAMILY_WINRT 0
#endif /* HAVE_WINAPIFAMILY_H */
#if HAVE_WINAPIFAMILY_H && HAVE_WINAPIFAMILY_H
#ifdef SDL_WIKI_DOCUMENTATION_SECTION
/**
* A preprocessor macro that defined to 1 if compiling for Windows Phone.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP)
#elif HAVE_WINAPIFAMILY_H && HAVE_WINAPIFAMILY_H
#define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP)
#else
#define SDL_WINAPI_FAMILY_PHONE 0

7
include/SDL3/SDL_process.h
View file

@ -54,6 +54,13 @@
extern "C" {
#endif
/**
* An opaque handle representing a system process.
*
* \since This datatype is available since SDL 3.1.3.
*
* \sa SDL_CreateProcess
*/
typedef struct SDL_Process SDL_Process;
/**

674
include/SDL3/SDL_stdinc.h
View file

@ -753,7 +753,288 @@ SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 f
#endif
/* Annotations to help code analysis tools */
#ifdef SDL_DISABLE_ANALYZE_MACROS
#ifdef SDL_WIKI_DOCUMENTATION_SECTION
/**
* Macro that annotates function params with input buffer size.
*
* If we were to annotate `memcpy`:
*
* ```c
* void *memcpy(void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len);
* ```
*
* This notes that `src` should be `len` bytes in size and is only read by the
* function. The compiler or other analysis tools can warn when this doesn't
* appear to be the case.
*
* On compilers without this annotation mechanism, this is defined to nothing.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_IN_BYTECAP(x) _In_bytecount_(x)
/**
* Macro that annotates function params with input/output string buffer size.
*
* If we were to annotate `strlcat`:
*
* ```c
* size_t strlcat(SDL_INOUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen);
* ```
*
* This notes that `dst` is a null-terminated C string, should be `maxlen`
* bytes in size, and is both read from and written to by the function. The
* compiler or other analysis tools can warn when this doesn't appear to be
* the case.
*
* On compilers without this annotation mechanism, this is defined to nothing.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_INOUT_Z_CAP(x) _Inout_z_cap_(x)
/**
* Macro that annotates function params with output string buffer size.
*
* If we were to annotate `snprintf`:
*
* ```c
* int snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, const char *fmt, ...);
* ```
*
* This notes that `text` is a null-terminated C string, should be `maxlen`
* bytes in size, and is only written to by the function. The compiler or
* other analysis tools can warn when this doesn't appear to be the case.
*
* On compilers without this annotation mechanism, this is defined to nothing.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_OUT_Z_CAP(x) _Out_z_cap_(x)
/**
* Macro that annotates function params with output buffer size.
*
* If we were to annotate `wcsncpy`:
*
* ```c
* char *wcscpy(SDL_OUT_CAP(bufsize) wchar_t *dst, const wchar_t *src, size_t bufsize);
* ```
*
* This notes that `dst` should have a capacity of `bufsize` wchar_t in size,
* and is only written to by the function. The compiler or other analysis
* tools can warn when this doesn't appear to be the case.
*
* This operates on counts of objects, not bytes. Use SDL_OUT_BYTECAP for bytes.
*
* On compilers without this annotation mechanism, this is defined to nothing.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_OUT_CAP(x) _Out_cap_(x)
/**
* Macro that annotates function params with output buffer size.
*
* If we were to annotate `memcpy`:
*
* ```c
* void *memcpy(SDL_OUT_BYTECAP(bufsize) void *dst, const void *src, size_t bufsize);
* ```
*
* This notes that `dst` should have a capacity of `bufsize` bytes in size,
* and is only written to by the function. The compiler or other analysis
* tools can warn when this doesn't appear to be the case.
*
* On compilers without this annotation mechanism, this is defined to nothing.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_OUT_BYTECAP(x) _Out_bytecap_(x)
/**
* Macro that annotates function params with output buffer string size.
*
* If we were to annotate `strcpy`:
*
* ```c
* char *strcpy(SDL_OUT_Z_BYTECAP(bufsize) char *dst, const char *src, size_t bufsize);
* ```
*
* This notes that `dst` should have a capacity of `bufsize` bytes in size,
* and a zero-terminated string is written to it by the function. The compiler
* or other analysis tools can warn when this doesn't appear to be the case.
*
* On compilers without this annotation mechanism, this is defined to nothing.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_OUT_Z_BYTECAP(x) _Out_z_bytecap_(x)
/**
* Macro that annotates function params as printf-style format strings.
*
* If we were to annotate `fprintf`:
*
* ```c
* int fprintf(FILE *f, SDL_PRINTF_FORMAT_STRING const char *fmt, ...);
* ```
*
* This notes that `fmt` should be a printf-style format string. The compiler
* or other analysis tools can warn when this doesn't appear to be the case.
*
* On compilers without this annotation mechanism, this is defined to nothing.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_PRINTF_FORMAT_STRING _Printf_format_string_
/**
* Macro that annotates function params as scanf-style format strings.
*
* If we were to annotate `fscanf`:
*
* ```c
* int fscanf(FILE *f, SDL_SCANF_FORMAT_STRING const char *fmt, ...);
* ```
*
* This notes that `fmt` should be a scanf-style format string. The compiler
* or other analysis tools can warn when this doesn't appear to be the case.
*
* On compilers without this annotation mechanism, this is defined to nothing.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_SCANF_FORMAT_STRING _Scanf_format_string_impl_
/**
* Macro that annotates a vararg function that operates like printf.
*
* If we were to annotate `fprintf`:
*
* ```c
* int fprintf(FILE *f, const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
* ```
*
* This notes that the second parameter should be a printf-style format string, followed by `...`.
* The compiler or other analysis tools can warn when this doesn't appear to be the case.
*
* On compilers without this annotation mechanism, this is defined to nothing.
*
* This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which between them
* will cover at least Visual Studio, GCC, and Clang.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __printf__, fmtargnumber, fmtargnumber+1 )))
/**
* Macro that annotates a va_list function that operates like printf.
*
* If we were to annotate `vfprintf`:
*
* ```c
* int vfprintf(FILE *f, const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2);
* ```
*
* This notes that the second parameter should be a printf-style format string, followed by a va_list.
* The compiler or other analysis tools can warn when this doesn't appear to be the case.
*
* On compilers without this annotation mechanism, this is defined to nothing.
*
* This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which between them
* will cover at least Visual Studio, GCC, and Clang.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __printf__, fmtargnumber, 0 )))
/**
* Macro that annotates a vararg function that operates like scanf.
*
* If we were to annotate `fscanf`:
*
* ```c
* int fscanf(FILE *f, const char *fmt, ...) SDL_PRINTF_VARARG_FUNCV(2);
* ```
*
* This notes that the second parameter should be a scanf-style format string, followed by `...`.
* The compiler or other analysis tools can warn when this doesn't appear to be the case.
*
* On compilers without this annotation mechanism, this is defined to nothing.
*
* This can (and should) be used with SDL_SCANF_FORMAT_STRING as well, which between them
* will cover at least Visual Studio, GCC, and Clang.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_SCANF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __scanf__, fmtargnumber, fmtargnumber+1 )))
/**
* Macro that annotates a va_list function that operates like scanf.
*
* If we were to annotate `vfscanf`:
*
* ```c
* int vfscanf(FILE *f, const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2);
* ```
*
* This notes that the second parameter should be a scanf-style format string, followed by a va_list.
* The compiler or other analysis tools can warn when this doesn't appear to be the case.
*
* On compilers without this annotation mechanism, this is defined to nothing.
*
* This can (and should) be used with SDL_SCANF_FORMAT_STRING as well, which between them
* will cover at least Visual Studio, GCC, and Clang.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __scanf__, fmtargnumber, 0 )))
/**
* Macro that annotates a vararg function that operates like wprintf.
*
* If we were to annotate `fwprintf`:
*
* ```c
* int fwprintf(FILE *f, const wchar_t *fmt, ...) SDL_WPRINTF_VARARG_FUNC(2);
* ```
*
* This notes that the second parameter should be a wprintf-style format wide string, followed by `...`.
* The compiler or other analysis tools can warn when this doesn't appear to be the case.
*
* On compilers without this annotation mechanism, this is defined to nothing.
*
* This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which between them
* will cover at least Visual Studio, GCC, and Clang.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, fmtargnumber+1 ))) */
/**
* Macro that annotates a va_list function that operates like wprintf.
*
* If we were to annotate `vfwprintf`:
*
* ```c
* int vfwprintf(FILE *f, const wchar_t *fmt, va_list ap) SDL_WPRINTF_VARARG_FUNC(2);
* ```
*
* This notes that the second parameter should be a wprintf-style format wide string, followed by a va_list.
* The compiler or other analysis tools can warn when this doesn't appear to be the case.
*
* On compilers without this annotation mechanism, this is defined to nothing.
*
* This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which between them
* will cover at least Visual Studio, GCC, and Clang.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, 0 ))) */
#elif defined(SDL_DISABLE_ANALYZE_MACROS)
#define SDL_IN_BYTECAP(x)
#define SDL_INOUT_Z_CAP(x)
#define SDL_OUT_Z_CAP(x)
@ -2295,9 +2576,77 @@ extern SDL_DECLSPEC void * SDLCALL SDL_memset4(void *dst, Uint32 val, size_t dwo
#define SDL_zeroa(x) SDL_memset((x), 0, sizeof((x)))
/**
* Compare two buffers of memory.
*
* \param s1 the first buffer to compare. NULL is not permitted!
* \param s2 the second buffer to compare. NULL is not permitted!
* \param len the number of bytes to compare between the buffers.
* \returns less than zero if s1 is "less than" s2, greater than zero if
* s1 is "greater than" s2, and zero if the buffers match
* exactly for `len` bytes.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*/
extern SDL_DECLSPEC int SDLCALL SDL_memcmp(const void *s1, const void *s2, size_t len);
/**
* This works exactly like wcslen() but doesn't require access to a C runtime.
*
* Counts the number of wchar_t values in `wstr`, excluding the null
* terminator.
*
* Like SDL_strlen only counts bytes and not codepoints in a UTF-8 string,
* this counts wchar_t values in a string, even if the string's encoding is of
* variable width, like UTF-16.
*
* Also be aware that wchar_t is different sizes on different platforms (4
* bytes on Linux, 2 on Windows, etc).
*
* \param wstr The null-terminated wide string to read. Must not be NULL.
* \returns the length (in wchar_t values, excluding the null terminator) of `wstr`.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_wcsnlen
* \sa SDL_utf8strlen
* \sa SDL_utf8strnlen
*/
extern SDL_DECLSPEC size_t SDLCALL SDL_wcslen(const wchar_t *wstr);
/**
* This works exactly like wcsnlen() but doesn't require access to a C
* runtime.
*
* Counts up to a maximum of `maxlen` wchar_t values in `wstr`, excluding the
* null terminator.
*
* Like SDL_strnlen only counts bytes and not codepoints in a UTF-8 string,
* this counts wchar_t values in a string, even if the string's encoding is of
* variable width, like UTF-16.
*
* Also be aware that wchar_t is different sizes on different platforms (4
* bytes on Linux, 2 on Windows, etc).
*
* Also, `maxlen` is a count of wide characters, not bytes!
*
* \param wstr The null-terminated wide string to read. Must not be NULL.
* \param maxlen The maximum amount of wide characters to count.
* \returns the length (in wide characters, excluding the null terminator) of
* `wstr` but never more than `maxlen`.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_wcslen
* \sa SDL_utf8strlen
* \sa SDL_utf8strnlen
*/
extern SDL_DECLSPEC size_t SDLCALL SDL_wcsnlen(const wchar_t *wstr, size_t maxlen);
/**
@ -2316,7 +2665,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_wcsnlen(const wchar_t *wstr, size_t maxle
* \param src The null-terminated wide string to copy. Must not be NULL, and
* must not overlap with `dst`.
* \param maxlen The length (in wide characters) of the destination buffer.
* \returns The length (in wide characters, excluding the null terminator) of
* \returns the length (in wide characters, excluding the null terminator) of
* `src`.
*
* \threadsafety It is safe to call this function from any thread.
@ -2345,7 +2694,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcpy(SDL_OUT_Z_CAP(maxlen) wchar_t *ds
* \param src The second null-terminated wide string. Must not be NULL, and
* must not overlap with `dst`.
* \param maxlen The length (in wide characters) of the destination buffer.
* \returns The length (in wide characters, excluding the null terminator) of
* \returns the length (in wide characters, excluding the null terminator) of
* the string in `dst` plus the length of `src`.
*
* \threadsafety It is safe to call this function from any thread.
@ -2356,8 +2705,63 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcpy(SDL_OUT_Z_CAP(maxlen) wchar_t *ds
*/
extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcat(SDL_INOUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen);
/**
* Allocate a copy of a wide string.
*
* This allocates enough space for a null-terminated copy of `wstr`, using
* SDL_malloc, and then makes a copy of the string into this space.
*
* The returned string is owned by the caller, and should be passed to
* SDL_free when no longer needed.
*
* \param wstr the string to copy.
* \returns a pointer to the newly-allocated wide string.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*/
extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsdup(const wchar_t *wstr);
/**
* Search a wide string for the first instance of a specific substring.
*
* The search ends once it finds the requested substring, or a null
* terminator byte to end the string.
*
* Note that this looks for strings of _wide characters_, not _codepoints_, so
* it's legal to search for malformed and incomplete UTF-16 sequences.
*
* \param haystack the wide string to search. Must not be NULL.
* \param needle the wide string to search for. Must not be NULL.
* \returns a pointer to the first instance of `needle` in the string, or NULL if not found.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*/
extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsstr(const wchar_t *haystack, const wchar_t *needle);
/**
* Search a wide string, up to n wide chars, for the first instance of a specific substring.
*
* The search ends once it finds the requested substring, or a null
* terminator value to end the string, or `maxlen` wide character have been
* examined. It is possible to use this function on a wide string without a
* null terminator.
*
* Note that this looks for strings of _wide characters_, not _codepoints_, so
* it's legal to search for malformed and incomplete UTF-16 sequences.
*
* \param haystack the wide string to search. Must not be NULL.
* \param needle the wide string to search for. Must not be NULL.
* \param maxlen the maximum number of wide characters to search in `haystack`.
* \returns a pointer to the first instance of `needle` in the string, or NULL if not found.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*/
extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsnstr(const wchar_t *haystack, const wchar_t *needle, size_t maxlen);
/**
@ -2499,7 +2903,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcsncasecmp(const wchar_t *str1, const wchar
* to 36 inclusive. If 0, the base will be inferred from the
* number's prefix (0x for hexadecimal, 0 for octal, decimal
* otherwise).
* \returns The parsed `long`, or 0 if no number could be parsed.
* \returns the parsed `long`, or 0 if no number could be parsed.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -2517,7 +2921,7 @@ extern SDL_DECLSPEC long SDLCALL SDL_wcstol(const wchar_t *str, wchar_t **endp,
* If you need the length of a UTF-8 string, consider using SDL_utf8strlen().
*
* \param str The null-terminated string to read. Must not be NULL.
* \returns The length (in bytes, excluding the null terminator) of `src`.
* \returns the length (in bytes, excluding the null terminator) of `src`.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -2540,7 +2944,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_strlen(const char *str);
*
* \param str The null-terminated string to read. Must not be NULL.
* \param maxlen The maximum amount of bytes to count.
* \returns The length (in bytes, excluding the null terminator) of `src` but
* \returns the length (in bytes, excluding the null terminator) of `src` but
* never more than `maxlen`.
*
* \threadsafety It is safe to call this function from any thread.
@ -2570,7 +2974,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_strnlen(const char *str, size_t maxlen);
* \param src The null-terminated string to copy. Must not be NULL, and must
* not overlap with `dst`.
* \param maxlen The length (in characters) of the destination buffer.
* \returns The length (in characters, excluding the null terminator) of
* \returns the length (in characters, excluding the null terminator) of
* `src`.
*
* \threadsafety It is safe to call this function from any thread.
@ -2600,7 +3004,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_strlcpy(SDL_OUT_Z_CAP(maxlen) char *dst,
* must not overlap with `dst`.
* \param dst_bytes The length (in bytes) of the destination buffer. Must not
* be 0.
* \returns The number of bytes written, excluding the null terminator.
* \returns the number of bytes written, excluding the null terminator.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -2627,7 +3031,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlcpy(SDL_OUT_Z_CAP(dst_bytes) char
* \param src The second null-terminated string. Must not be NULL, and must
* not overlap with `dst`.
* \param maxlen The length (in characters) of the destination buffer.
* \returns The length (in characters, excluding the null terminator) of the
* \returns the length (in characters, excluding the null terminator) of the
* string in `dst` plus the length of `src`.
*
* \threadsafety It is safe to call this function from any thread.
@ -2638,8 +3042,68 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlcpy(SDL_OUT_Z_CAP(dst_bytes) char
*/
extern SDL_DECLSPEC size_t SDLCALL SDL_strlcat(SDL_INOUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen);
/**
* Allocate a copy of a string.
*
* This allocates enough space for a null-terminated copy of `str`, using
* SDL_malloc, and then makes a copy of the string into this space.
*
* The returned string is owned by the caller, and should be passed to
* SDL_free when no longer needed.
*
* \param str the string to copy.
* \returns a pointer to the newly-allocated string.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*/
extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strdup(const char *str);
/**
* Allocate a copy of a string, up to n characters.
*
* This allocates enough space for a null-terminated copy of `str`, up to
* `maxlen` bytes, using SDL_malloc, and then makes a copy of the string
* into this space.
*
* If the string is longer than `maxlen` bytes, the returned string will
* be `maxlen` bytes long, plus a null-terminator character that isn't
* included in the count.
*
* The returned string is owned by the caller, and should be passed to
* SDL_free when no longer needed.
*
* \param str the string to copy.
* \param maxlen the maximum length of the copied string, not counting
* the null-terminator character.
* \returns a pointer to the newly-allocated string.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*/
extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strndup(const char *str, size_t maxlen);
/**
* Reverse a string's contents.
*
* This reverses a null-terminated string in-place. Only the content of the
* string is reversed; the null-terminator character remains at the end of the
* reversed string.
*
* **WARNING**: This function reverses the _bytes_ of the string, not the
* codepoints. If `str` is a UTF-8 string with Unicode codepoints > 127, this
* will ruin the string data. You should only use this function on strings
* that are completely comprised of low ASCII characters.
*
* \param str the string to reverse.
* \returns `str`.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*/
extern SDL_DECLSPEC char * SDLCALL SDL_strrev(char *str);
/**
@ -3059,7 +3523,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_ulltoa(unsigned long long value, char *st
* `(int)SDL_strtol(str, NULL, 10)`.
*
* \param str The null-terminated string to read. Must not be NULL.
* \returns The parsed `int`.
* \returns the parsed `int`.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -3082,7 +3546,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_atoi(const char *str);
* NULL)`.
*
* \param str The null-terminated string to read. Must not be NULL.
* \returns The parsed `double`.
* \returns the parsed `double`.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -3114,7 +3578,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_atof(const char *str);
* to 36 inclusive. If 0, the base will be inferred from the
* number's prefix (0x for hexadecimal, 0 for octal, decimal
* otherwise).
* \returns The parsed `long`, or 0 if no number could be parsed.
* \returns the parsed `long`, or 0 if no number could be parsed.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -3148,7 +3612,7 @@ extern SDL_DECLSPEC long SDLCALL SDL_strtol(const char *str, char **endp, int ba
* to 36 inclusive. If 0, the base will be inferred from the
* number's prefix (0x for hexadecimal, 0 for octal, decimal
* otherwise).
* \returns The parsed `unsigned long`, or 0 if no number could be parsed.
* \returns the parsed `unsigned long`, or 0 if no number could be parsed.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -3181,7 +3645,7 @@ extern SDL_DECLSPEC unsigned long SDLCALL SDL_strtoul(const char *str, char **en
* to 36 inclusive. If 0, the base will be inferred from the
* number's prefix (0x for hexadecimal, 0 for octal, decimal
* otherwise).
* \returns The parsed `long long`, or 0 if no number could be parsed.
* \returns the parsed `long long`, or 0 if no number could be parsed.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -3214,7 +3678,7 @@ extern SDL_DECLSPEC long long SDLCALL SDL_strtoll(const char *str, char **endp,
* to 36 inclusive. If 0, the base will be inferred from the
* number's prefix (0x for hexadecimal, 0 for octal, decimal
* otherwise).
* \returns The parsed `unsigned long long`, or 0 if no number could be
* \returns the parsed `unsigned long long`, or 0 if no number could be
* parsed.
*
* \threadsafety It is safe to call this function from any thread.
@ -3241,11 +3705,11 @@ extern SDL_DECLSPEC unsigned long long SDLCALL SDL_strtoull(const char *str, cha
* - Whether or not INF and NAN can be parsed is unspecified.
* - The precision of the result is unspecified.
*
* \param str The null-terminated string to read. Must not be NULL.
* \param endp If not NULL, the address of the first invalid character (i.e.
* \param str the null-terminated string to read. Must not be NULL.
* \param endp if not NULL, the address of the first invalid character (i.e.
* the next character after the parsed number) will be written to
* this pointer.
* \returns The parsed `double`, or 0 if no number could be parsed.
* \returns the parsed `double`, or 0 if no number could be parsed.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -3516,14 +3980,186 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_StepBackUTF8(const char *start, const cha
*/
extern SDL_DECLSPEC char * SDLCALL SDL_UCS4ToUTF8(Uint32 codepoint, char *dst);
/**
* This works exactly like sscanf() but doesn't require access to a C runtime.
*
* Scan a string, matching a format string, converting each '%' item and
* storing it to pointers provided through variable arguments.
*
* \param text the string to scan. Must not be NULL.
* \param fmt a printf-style format string. Must not be NULL.
* \param ... a list of pointers to values to be filled in with scanned items.
* \returns the number of items that matched the format string.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*/
extern SDL_DECLSPEC int SDLCALL SDL_sscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, ...) SDL_SCANF_VARARG_FUNC(2);
/**
* This works exactly like vsscanf() but doesn't require access to a C runtime.
*
* Functions identically to SDL_sscanf(), except it takes a `va_list`
* instead of using `...` variable arguments.
*
* \param text the string to scan. Must not be NULL.
* \param fmt a printf-style format string. Must not be NULL.
* \param ap a `va_list` of pointers to values to be filled in with scanned items.
* \returns the number of items that matched the format string.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*/
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);
/**
* This works exactly like snprintf() but doesn't require access to a C runtime.
*
* Format a string of up to `maxlen`-1 bytes, converting each '%' item with
* values provided through variable arguments.
*
* While some C runtimes differ on how to deal with too-large strings,
* this function null-terminates the output, by treating the null-terminator
* as part of the `maxlen` count. Note that if `maxlen` is zero, however, no
* bytes will be written at all.
*
* This function returns the number of _bytes_ (not _characters_) that should
* be written, excluding the null-terminator character. If this returns a
* number >= `maxlen`, it means the output string was truncated. A negative
* return value means an error occurred.
*
* Referencing the output string's pointer with a format item is undefined
* behavior.
*
* \param text the buffer to write the string into. Must not be NULL.
* \param maxlen the maximum bytes to write, including the null-terminator.
* \param fmt a printf-style format string. Must not be NULL.
* \param ... a list of values to be used with the format string.
* \returns the number of bytes that should be written, not counting the
* null-terminator char, or a negative value on error.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*/
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);
/**
* This works exactly like swprintf() but doesn't require access to a C runtime.
*
* Format a wide string of up to `maxlen`-1 wchar_t values, converting each '%'
* item with values provided through variable arguments.
*
* While some C runtimes differ on how to deal with too-large strings,
* this function null-terminates the output, by treating the null-terminator
* as part of the `maxlen` count. Note that if `maxlen` is zero, however, no
* wide characters will be written at all.
*
* This function returns the number of _wide characters_ (not _codepoints_)
* that should be written, excluding the null-terminator character. If this
* returns a number >= `maxlen`, it means the output string was truncated. A
* negative return value means an error occurred.
*
* Referencing the output string's pointer with a format item is undefined
* behavior.
*
* \param text the buffer to write the wide string into. Must not be NULL.
* \param maxlen the maximum wchar_t values to write, including the null-terminator.
* \param fmt a printf-style format string. Must not be NULL.
* \param ... a list of values to be used with the format string.
* \returns the number of wide characters that should be written, not counting
* the null-terminator char, or a negative value on error.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.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);
/**
* This works exactly like vsnprintf() but doesn't require access to a C runtime.
*
* Functions identically to SDL_snprintf(), except it takes a `va_list`
* instead of using `...` variable arguments.
*
* \param text the buffer to write the string into. Must not be NULL.
* \param maxlen the maximum bytes to write, including the null-terminator.
* \param fmt a printf-style format string. Must not be NULL.
* \param ap a `va_list` values to be used with the format string.
* \returns the number of bytes that should be written, not counting the
* null-terminator char, or a negative value on error.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.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);
/**
* This works exactly like vswprintf() but doesn't require access to a C runtime.
*
* Functions identically to SDL_swprintf(), except it takes a `va_list`
* instead of using `...` variable arguments.
*
* \param text the buffer to write the string into. Must not be NULL.
* \param maxlen the maximum wide characters to write, including the null-terminator.
* \param fmt a printf-style format wide string. Must not be NULL.
* \param ap a `va_list` values to be used with the format string.
* \returns the number of wide characters that should be written, not counting
* the null-terminator char, or a negative value on error.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*/
extern SDL_DECLSPEC int SDLCALL SDL_vswprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, va_list ap) SDL_WPRINTF_VARARG_FUNCV(3);
/**
* This works exactly like asprintf() but doesn't require access to a C runtime.
*
* Functions identically to SDL_snprintf(), except it allocates a buffer large
* enough to hold the output string on behalf of the caller.
*
* On success, this function returns the number of bytes (not characters)
* comprising the output string, not counting the null-terminator character,
* and sets `*strp` to the newly-allocated string.
*
* On error, this function returns a negative number, and the value of `*strp`
* is undefined.
*
* The returned string is owned by the caller, and should be passed to
* SDL_free when no longer needed.
*
* \param strp on output, is set to the new string. Must not be NULL.
* \param fmt a printf-style format string. Must not be NULL.
* \param ... a list of values to be used with the format string.
* \returns the number of bytes in the newly-allocated string, not counting
* the null-terminator char, or a negative value on error.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*/
extern SDL_DECLSPEC int SDLCALL SDL_asprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
/**
* This works exactly like vasprintf() but doesn't require access to a C runtime.
*
* Functions identically to SDL_asprintf(), except it takes a `va_list`
* instead of using `...` variable arguments.
*
* \param strp on output, is set to the new string. Must not be NULL.
* \param fmt a printf-style format string. Must not be NULL.
* \param ap a `va_list` values to be used with the format string.
* \returns the number of bytes in the newly-allocated string, not counting
* the null-terminator char, or a negative value on error.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*/
extern SDL_DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2);
/**

41
include/SDL3/SDL_system.h
View file

@ -129,7 +129,29 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetDXGIOutputInfo(SDL_DisplayID displayID,
* Platform specific functions for UNIX
*/
/* this is defined in Xlib's headers, just need a simple declaration here. */
typedef union _XEvent XEvent;
/**
* A callback to be used with SDL_SetX11EventHook.
*
* This callback may modify the event, and should return true if the event
* should continue to be processed, or false to prevent further processing.
*
* As this is processing an event directly from the X11 event loop, this
* callback should do the minimum required work and return quickly.
*
* \param userdata the app-defined pointer provided to SDL_SetX11EventHook.
* \param xevent a pointer to an Xlib XEvent union to process.
* \returns true to let event continue on, false to drop it.
*
* \threadsafety This may only be called (by SDL) from the thread handling the
* X11 event loop.
*
* \since This datatype is available since SDL 3.1.3.
*
* \sa SDL_SetX11EventHook
*/
typedef bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent);
/**
@ -380,6 +402,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void);
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_ANDROID_EXTERNAL_STORAGE_READ 0x01
/**
* See the official Android developer guide for more information:
* http://developer.android.com/guide/topics/data/data-storage.html
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02
/**
@ -468,7 +497,17 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidExternalStoragePath(void)
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidCachePath(void);
/**
* Callback that presents a response from a SDL_RequestAndroidPermission call.
*
* \param userdata an app-controlled pointer that is passed to the callback.
* \param permission the Android-specific permission name that was requested.
* \param granted true if permission is granted, false if denied.
*
* \since This datatype is available since SDL 3.1.3.
*
* \sa SDL_RequestAndroidPermission
*/
typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, const char *permission, bool granted);
/**

108
include/SDL3/SDL_video.h
View file

@ -112,7 +112,15 @@ typedef enum SDL_SystemTheme
SDL_SYSTEM_THEME_DARK /**< Dark colored system theme */
} SDL_SystemTheme;
/* Internal display mode data */
/**
* Internal display mode data.
*
* This lives as a field in SDL_DisplayMode, as opaque data.
*
* \since This struct is available since SDL 3.1.3.
*
* \sa SDL_DisplayMode
*/
typedef struct SDL_DisplayModeData SDL_DisplayModeData;
/**
@ -206,27 +214,87 @@ typedef Uint64 SDL_WindowFlags;
/**
* Used to indicate that you don't care what the window position is.
* A magic value used with SDL_WINDOWPOS_UNDEFINED.
*
* Generally this macro isn't used directly, but rather through
* SDL_WINDOWPOS_UNDEFINED or SDL_WINDOWPOS_UNDEFINED_DISPLAY.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_WINDOWPOS_UNDEFINED_MASK 0x1FFF0000u
#define SDL_WINDOWPOS_UNDEFINED_DISPLAY(X) (SDL_WINDOWPOS_UNDEFINED_MASK|(X))
#define SDL_WINDOWPOS_UNDEFINED SDL_WINDOWPOS_UNDEFINED_DISPLAY(0)
#define SDL_WINDOWPOS_ISUNDEFINED(X) \
(((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK)
/**
* Used to indicate that the window position should be centered.
* Used to indicate that you don't care what the window position is.
*
* If you _really_ don't care, SDL_WINDOWPOS_UNDEFINED is the same, but always
* uses the primary display instead of specifying one.
*
* \param X the SDL_DisplayID of the display to use.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_WINDOWPOS_UNDEFINED_DISPLAY(X) (SDL_WINDOWPOS_UNDEFINED_MASK|(X))
/**
* Used to indicate that you don't care what the window position/display is.
*
* This always uses the primary display.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_WINDOWPOS_UNDEFINED SDL_WINDOWPOS_UNDEFINED_DISPLAY(0)
/**
* A macro to test if the window position is marked as "undefined."
*
* \param X the window position value.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_WINDOWPOS_ISUNDEFINED(X) (((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK)
/**
* A magic value used with SDL_WINDOWPOS_CENTERED.
*
* Generally this macro isn't used directly, but rather through
* SDL_WINDOWPOS_CENTERED or SDL_WINDOWPOS_CENTERED_DISPLAY.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u
/**
* Used to indicate that the window position should be centered.
*
* SDL_WINDOWPOS_CENTERED is the same, but always uses the primary display
* instead of specifying one.
*
* \param X the SDL_DisplayID of the display to use.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_WINDOWPOS_CENTERED_DISPLAY(X) (SDL_WINDOWPOS_CENTERED_MASK|(X))
/**
* Used to indicate that the window position should be centered.
*
* This always uses the primary display.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_WINDOWPOS_CENTERED SDL_WINDOWPOS_CENTERED_DISPLAY(0)
/**
* A macro to test if the window position is marked as "centered."
*
* \param X the window position value.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_WINDOWPOS_ISCENTERED(X) \
(((X)&0xFFFF0000) == SDL_WINDOWPOS_CENTERED_MASK)
/**
* Window flash operation.
*
@ -249,14 +317,38 @@ typedef enum SDL_FlashOperation
typedef struct SDL_GLContextState *SDL_GLContext;
/**
* Opaque EGL types.
* Opaque type for an EGL display.
*
* \since This datatype is available since SDL 3.1.3.
*/
typedef void *SDL_EGLDisplay;
/**
* Opaque type for an EGL config.
*
* \since This datatype is available since SDL 3.1.3.
*/
typedef void *SDL_EGLConfig;
/**
* Opaque type for an EGL surface.
*
* \since This datatype is available since SDL 3.1.3.
*/
typedef void *SDL_EGLSurface;
/**
* An EGL attribute, used when creating an EGL context.
*
* \since This datatype is available since SDL 3.1.3.
*/
typedef intptr_t SDL_EGLAttrib;
/**
* An EGL integer attribute, used when creating an EGL surface.
*
* \since This datatype is available since SDL 3.1.3.
*/
typedef int SDL_EGLint;
/**